Compartir a través de

Exportación de datos al almacenamiento en la nube

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

Ejecuta una consulta y escribe el primer conjunto de resultados en un almacenamiento en la nube externo, especificado por un cadena de conexión de almacenamiento.

Permisos

Debe tener al menos permisos del Visor de base de datos para ejecutar este comando.

Sintaxis

.export[] [async] compressedtoOutputDataFormat( StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] ] )<|Consulta

Obtenga más información sobre las convenciones de sintaxis.

Parámetros

Nombre Type Obligatorio Descripción
async string Si se especifica, el comando se ejecuta en modo asincrónico. Consulte el modo asincrónico.
compressed string Si se especifica, los artefactos de almacenamiento de salida se comprimen como .gz archivos. Consulte la compressionTypepropiedad admitida para comprimir archivos Parquet como snappy.
OutputDataFormat string ✔️ Indica el formato de datos de los artefactos de almacenamiento escritos por el comando . Los valores admitidos son csv, tsv, json y parquet.
StorageConnectionString string Uno o varios cadena de conexión de almacenamiento que indican en qué almacenamiento se van a escribir los datos. Es posible especificar más de una cadena de conexión de almacenamiento para escrituras escalables. Cada uno de estos cadena de conexión debe indicar las credenciales que se usarán al escribir en el almacenamiento. Por ejemplo, al escribir en Azure Blob Storage, las credenciales pueden ser la clave de la cuenta de almacenamiento o una clave de acceso compartido (SAS) con los permisos para leer, escribir y enumerar blobs.
PropertyName, PropertyValue string Lista separada por comas de pares de propiedades clave-valor. Consulte las propiedades admitidas.

Nota:

Se recomienda exportar datos al almacenamiento que se encuentran en la misma región que la propia base de datos. Esto incluye los datos que se exportan para que se puedan transferir a otro servicio en la nube en otras regiones. Las escrituras se deben realizar localmente, mientras que las lecturas pueden producirse de forma remota.

Propiedades admitidas

Propiedad Type Descripción
includeHeaders string Para csv/tsv la salida, controla la generación de encabezados de columna. Puede ser una de (valor predeterminado; sin líneas de encabezado emitidas), none (emita una línea de encabezado en todos los artefactos de almacenamiento) o all (emita una línea de firstFile encabezado solo en el primer artefacto de almacenamiento).
fileExtension string Indica la parte "extension" del artefacto de almacenamiento (por ejemplo, .csv o .tsv). Si se usa la compresión, .gz también se anexa.
namePrefix string Indica un prefijo que se va a agregar a cada nombre de artefacto de almacenamiento generado. Si no se especifica, se usa un prefijo aleatorio.
encoding string Indica cómo codificar el texto: UTF8NoBOM (valor predeterminado) o UTF8BOM.
compressionType string Indica el tipo de compresión que se va a usar. Los valores posibles son gzip o snappy. El valor predeterminado es gzip. snappy se puede usar (opcionalmente) para parquet el formato.
distribution string Sugerencia de distribución (single, per_node, per_shard). Si el valor es igual singlea , un único subproceso escribe en el almacenamiento. De lo contrario, exporte las escrituras de todos los nodos que ejecutan la consulta en paralelo. Consulte evaluate plugin operator (Evaluar operador de complemento). Tiene como valor predeterminado per_shard.
persistDetails bool Indica que el comando debe conservar sus resultados (consulte async la marca ). El valor predeterminado es en ejecuciones asincrónicas true , pero se puede desactivar si el autor de la llamada no requiere los resultados). El valor predeterminado es false en ejecuciones sincrónicas, pero también se puede activar en ellos.
sizeLimit long Límite de tamaño en bytes de un único artefacto de almacenamiento escrito antes de la compresión. Intervalo válido: 100 MB (valor predeterminado) a 4 GB.
parquetRowGroupSize int Solo es relevante cuando el formato de datos es Parquet. Controla el tamaño del grupo de filas en los archivos exportados. El tamaño predeterminado del grupo de filas es de 100 000 registros.
distributed bool Deshabilite o habilite la exportación distribuida. Establecer en false es equivalente a la single sugerencia de distribución. El valor predeterminado es true.
parquetDatetimePrecision string Especifica la precisión que se va a usar al exportar datetime valores a Parquet. Los valores posibles son milisegundos y microsegundos. El valor predeterminado es milisegundos.

Autenticación y autorización

El método de autenticación se basa en el cadena de conexión proporcionado y los permisos necesarios varían en función del método de autenticación.

En la tabla siguiente se enumeran los métodos de autenticación admitidos y los permisos necesarios para exportar datos al almacenamiento externo por tipo de almacenamiento.

Método de autenticación Azure Blob Storage/Data Lake Storage Gen2 Data Lake Storage Gen1
Suplantación Colaborador de datos de blob de almacenamiento Colaborador
Token de acceso compartido (SAS) Escritura Escritura
Token de acceso de Microsoft Entra No se requieren permisos adicionales No se requieren permisos adicionales
Clave de acceso de la cuenta de almacenamiento No se requieren permisos adicionales No se requieren permisos adicionales

Devoluciones

Los comandos devuelven una tabla que describe los artefactos de almacenamiento generados. Cada registro describe un único artefacto e incluye la ruta de acceso de almacenamiento al artefacto y cuántos registros contiene.

Path NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv 10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv 15

Modo asincrónico

Si se especifica la async marca, el comando se ejecuta en modo asincrónico. En este modo, el comando devuelve inmediatamente con un identificador de operación y la exportación de datos continúa en segundo plano hasta la finalización. El identificador de operación devuelto por el comando se puede usar para realizar un seguimiento de su progreso y, en última instancia, sus resultados a través de los siguientes comandos:

Por ejemplo, después de una finalización correcta, puede recuperar los resultados mediante:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Ejemplos

En este ejemplo, Kusto ejecuta la consulta y, a continuación, exporta el primer conjunto de registros generado por la consulta a uno o varios blobs CSV comprimidos, hasta 1 GB antes de la compresión. Las etiquetas de nombre de columna se agregan como primera fila para cada blob.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Errores durante los comandos de exportación

Los comandos de exportación pueden producir un error transitorio durante la ejecución. exportación continua reintenta automáticamente el comando. Los comandos de exportación normales (exportar al almacenamiento, exportar a una tabla externa) no realizan ningún reintento.

  • Cuando se produce un error en el comando de exportación, los artefactos que ya se han escrito en el almacenamiento no se eliminan. Estos artefactos permanecen en el almacenamiento. Si se produce un error en el comando, suponga que la exportación está incompleta, incluso si se escribieron algunos artefactos.
  • La mejor manera de realizar un seguimiento de la finalización del comando y de los artefactos exportados tras la finalización correcta es mediante los .show operations comandos y .show operation details .

Errores de almacenamiento

De forma predeterminada, los comandos de exportación se distribuyen de forma que puede haber muchas escrituras simultáneas en el almacenamiento. El nivel de distribución depende del tipo de comando de exportación:

  • La distribución predeterminada para el comando regular .export es per_shard, lo que significa que todas las extensiones que contienen datos que se van a exportar escritura al almacenamiento simultáneamente.

  • La distribución predeterminada para exportar a comandos de tabla externa es per_node, lo que significa que la simultaneidad es el número de nodos.

Cuando el número de extensiones o nodos es grande, esto puede provocar una carga elevada en el almacenamiento que da lugar a una limitación de almacenamiento o errores transitorios de almacenamiento. Las siguientes sugerencias pueden superar estos errores (por orden de prioridad):

  • Aumente el número de cuentas de almacenamiento proporcionadas al comando de exportación o a la definición de tabla externa . La carga se distribuye uniformemente entre las cuentas.

  • Reduzca la simultaneidad estableciendo la sugerencia de distribución en per_node (consulte las propiedades del comando).

  • Reduzca la simultaneidad del número de nodos que exportan estableciendo la propiedadquery_fanout_nodes_percent de solicitud de cliente en la simultaneidad deseada (porcentaje de nodos). La propiedad se puede establecer como parte de la consulta de exportación. Por ejemplo, el siguiente comando limita el número de nodos que escriben en el almacenamiento simultáneamente al 50 % de los nodos:

    .export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery

  • Reduzca la simultaneidad del número de subprocesos que exportan en cada nodo al usar la exportación de particiones estableciendo la propiedadquery_fanout_threads_percent de solicitud de cliente en la simultaneidad deseada (porcentaje de subprocesos). La propiedad se puede establecer como parte de la consulta de exportación. Por ejemplo, el siguiente comando limita el número de subprocesos que escriben en el almacenamiento simultáneamente al 50 % en cada uno de los nodos:

    .export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery

  • Si se exporta a una tabla externa con particiones, establecer las propiedades puede reducir la spread/concurrency simultaneidad (vea los detalles de las propiedades del comando.

  • Si ninguna de las recomendaciones anteriores funciona, puede deshabilitar completamente la distribución estableciendo la propiedad distributed en false. Sin embargo, no se recomienda hacerlo, ya que podría afectar significativamente al rendimiento del comando.

Errores de autorización

Los errores de autenticación o autorización durante los comandos de exportación pueden producirse cuando las credenciales proporcionadas en el cadena de conexión de almacenamiento no pueden escribir en el almacenamiento. Si usa impersonate o un token de SAS delegado por el usuario para el comando de exportación, se requiere el rol Colaborador de datos de Storage Blob para escribir en la cuenta de almacenamiento. Para obtener más información, consulte Cadenas de conexión de Storage.

Asignación de tipos de datos

Asignación de tipos de datos de Parquet

En la exportación, los tipos de datos de Kusto se asignan a los tipos de datos parquet mediante las siguientes reglas:

Tipo de datos kusto Tipo de datos de Parquet Anotación de Parquet Comentarios
bool BOOLEAN
datetime INT64 TIMESTAMP_MICROS
dynamic BYTE_ARRAY UTF-8 Serializado como cadena JSON
guid BYTE_ARRAY UTF-8
int INT32
long INT64
real DOUBLE
string BYTE_ARRAY UTF-8
timespan INT64 Almacenado como tics (unidades de 100 nanosegundos)
decimal FIXED_LENGTH_BYTE_ARRAY DECIMAL

Contenido relacionado