Exportación de datos al almacenamiento en la nube

Artículo
01/18/2024

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 bases de datos para ejecutar este comando.

Syntax

.export[] [compressedasync] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|Consulta

Más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Tipo	Requerido	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 `compressionType`propiedad 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`		Una o varias cadenas de conexión de almacenamiento que indican en qué almacenamiento se van a escribir los datos. Se puede especificar más de un cadena de conexión de almacenamiento para escrituras escalables. Cada cadena de conexión de este tipo debe indicar las credenciales que se van a usar al escribir en el almacenamiento. Por ejemplo, al escribir en Azure Blob Storage, las credenciales pueden ser la clave de 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 encarecidamente exportar datos al almacenamiento que se encuentran en la misma región que el propio clúster. 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 se pueden realizar de forma remota.

Propiedades admitidas

Propiedad	Tipo	Descripción
`includeHeaders`	`string`	Para `csv`/`tsv` la salida, controla la generación de encabezados de columna. Puede ser una de `none` (valor predeterminado; sin líneas de encabezado emitidas), `all` (emita una línea de encabezado en cada artefacto de almacenamiento) o `firstFile` (emita una línea de encabezado solo en el primer artefacto de almacenamiento).
`fileExtension`	`string`	Indica la parte "extensión" 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 `single`igual a , un único subproceso escribe en el almacenamiento. De lo contrario, exporta escrituras de todos los nodos que ejecutan la consulta en paralelo. Consulte Evaluate plugin operator (Evaluar operador de complementos). 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 que se escribe (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 blobs 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 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.

Ruta de acceso	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:

.show operations: realiza un seguimiento del progreso.
.show operation details: obtiene los resultados de finalización.

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 errores transitorios durante la ejecución. La exportación continua reintentará 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 escribieron en el almacenamiento no se eliminarán. 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 la exportación a comandos de tabla externa es per_node, lo que significa que la simultaneidad es el número de nodos del clúster.

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 distribuirá uniformemente entre las cuentas).
Reduzca la simultaneidad estableciendo la sugerencia per_node de distribución en (vea las propiedades del comando).
Reduzca la simultaneidad del número de nodos que exportan estableciendo la propiedad query_fanout_nodes_percentde 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 comando siguiente limita el número de nodos que escriben en el almacenamiento simultáneamente al 50 % de los nodos del clúster:
```
.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 se exportan en cada nodo al usar la exportación de particiones estableciendo la propiedad query_fanout_threads_percentde 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 comando siguiente limita el número de subprocesos que escriben en el almacenamiento simultáneamente al 50 % en cada uno de los nodos del clúster:
```
.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 ninguno de los trabajos anteriores, puede deshabilitar completamente la distribución estableciendo la distributed propiedad en false. Sin embargo, no se recomienda hacerlo, ya que puede 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 más información, consulte Cadenas de conexión de almacenamiento.

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 reglas siguientes:

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