Compartir a través de

Exportación de datos a una tabla externa

  • Artículo

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

Puede exportar datos definiendo una tabla externa y exportando datos a ellos. Las propiedades de la tabla se especifican al crear la tabla externa. El comando export hace referencia a la tabla externa por nombre.

Permisos

Debe tener al menos permisos de administrador de tablas para ejecutar este comando.

Sintaxis

.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...]] )<|consulta

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

Parámetros

Nombre Type Obligatorio Descripción
externalTableName string ✔️ Nombre de la tabla externa a la que se va a exportar.
propertyName, propertyValue string Lista separada por comas de propiedades opcionales.
query string ✔️ Consulta de exportación.

Propiedades admitidas

Las siguientes propiedades se admiten como parte del comando de exportación a tabla externa.

Propiedad Type Descripción Valor predeterminado
sizeLimit long Límite de tamaño en bytes de un único artefacto de almacenamiento escrito antes de la compresión. Se escribe un grupo de filas completo de tamaño parquetRowGroupSize antes de comprobar si este grupo de filas alcanza el límite de tamaño y debe iniciar un nuevo artefacto. Intervalo válido: 100 MB (valor predeterminado) a 1 GB.
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.
distribution string Sugerencia de distribución (single, per_node, per_shard). Consulte más detalles en Configuración de distribución. El valor predeterminado es per_node.
distributionKind string Opcionalmente, cambia a distribución uniforme cuando la tabla externa tiene particiones por partición de cadena. Los valores válidos son uniform y default. Consulte más detalles en Configuración de distribución.
concurrency Number Indica al sistema cuántas particiones se van a ejecutar en paralelo. Consulte más detalles en Configuración de distribución. El valor predeterminado es 16.
spread Number Indica al sistema cómo distribuir las particiones entre nodos. Consulte más detalles en Configuración de distribución. El valor predeterminado es Min(64, number-of-nodes).
parquetRowGroupSize int Solo es relevante cuando el formato de datos es Parquet. Controla el tamaño del grupo de filas en los archivos exportados. Este valor tiene prioridad sobre sizeLimit, lo que significa que se exportará un grupo de filas completo antes de comprobar si este grupo de filas alcanza el límite de tamaño y debe iniciar un nuevo artefacto. El tamaño predeterminado del grupo de filas es de 100 000 registros.

Configuración de distribución

La distribución de una operación de exportación a tabla externa indica el número de nodos y subprocesos que se escriben en el almacenamiento simultáneamente. La distribución predeterminada depende de la creación de particiones de tablas externas:

Creación de particiones de tablas externas Distribución predeterminada
La tabla externa no está particionada o particionada solo por datetime columna La exportación se distribuye per_node : todos los nodos se exportan simultáneamente. Cada nodo escribe los datos asignados a ese nodo. El número de archivos exportados por un nodo es mayor que uno, solo si el tamaño de los datos de ese nodo supera sizeLimit.
Una columna de cadena particiona una tabla externa Los datos que se van a exportar se mueven entre los nodos, de modo que cada nodo escribe un subconjunto de los valores de partición. Una sola partición siempre está escrita por un solo nodo. El número de archivos escritos por partición debe ser mayor que uno solo si los datos superan sizeLimit. Si la tabla externa incluye varias particiones de cadena, los datos se particionan entre el nodo en función de la primera partición. Por lo tanto, la recomendación es definir la partición con la distribución más uniforme como la primera.

Cambiar la configuración de distribución predeterminada

Cambiar la configuración de distribución predeterminada puede ser útil en los casos siguientes:

Caso de uso Descripción Recomendación
Reducir el número de archivos exportados La exportación está creando demasiados archivos pequeños y le gustaría que creara un número menor de archivos más grandes. Establezca distribution=single o distributed=false (ambos son equivalentes) en las propiedades del comando. Solo un único subproceso realiza la exportación. La desventaja de esto es que la operación de exportación puede ser más lenta, ya que la simultaneidad es mucho menor.
Reducir la duración de la exportación Aumentar la simultaneidad de la operación de exportación para reducir su duración. Establezca distribution=per_shard en las propiedades del comando. Esto significa que la simultaneidad de las operaciones de escritura es por partición de datos, en lugar de por nodo. Esto solo es relevante cuando se exporta a una tabla externa que no tiene particiones por partición de cadena. Esto podría crear demasiada carga en el almacenamiento, lo que podría provocar una limitación. Consulte Errores de almacenamiento.
Reducir la duración de exportación de tablas externas particionadas por una partición de cadena Si las particiones no se distribuyen uniformemente entre los nodos, la exportación puede tardar más tiempo en ejecutarse. Si una partición es mucho mayor que la otra, el nodo asignado a esa partición realiza la mayor parte del trabajo de exportación, mientras que los demás nodos permanecen principalmente inactivos. Para obtener más información, consulte Configuración de distribución. Hay varias opciones de configuración que puede cambiar:
* Si hay más de una partición de cadena, defina la que tiene la mejor distribución primero.

* Establezca distributionKind=uniform en las propiedades del comando. Esta configuración deshabilita la configuración de distribución predeterminada para las tablas externas con particiones de cadena. La exportación se ejecuta con per-node distribución y cada nodo exporta los datos asignados al nodo. Una sola partición puede escribirse en varios nodos y el número de archivos aumenta en consecuencia. Para aumentar aún más la simultaneidad, establezca distributionKind=uniform junto con distribution=per_shard para la mayor simultaneidad (a costa de potencialmente muchos más archivos escritos).

* Si la causa de la exportación lenta no es atípico en los datos, reduzca la duración aumentando la simultaneidad, sin cambiar la configuración de creación de particiones. Use las hint.spread propiedades y hint.concurrency , que determinan la simultaneidad de la creación de particiones. Consulte el operador de partición. De forma predeterminada, el número de nodos que se exportan simultáneamente (el spread) es el valor mínimo entre 64 y el número de nodos. Si se establece spread en un número mayor que el número de nodos, aumenta la simultaneidad en cada nodo (el valor máximo de spread es 64).

Autenticación y autorización

Para exportar a una tabla externa, debe configurar permisos de escritura. Para más información, consulte Permisos de escritura para la tabla externa de Azure Storage o tabla externa de SQL Server.

Output

Parámetro de salida Type Descripción
ExternalTableName string Nombre de la tabla externa.
Path string Ruta de acceso de salida
NumRecords string Número de registros exportados a la ruta de acceso.

Notas

  • El esquema de salida de la consulta de exportación debe coincidir con el esquema de la tabla externa, incluidas todas las columnas definidas por las particiones. Por ejemplo, si DateTime particiona la tabla, el esquema de salida de la consulta debe tener una columna Timestamp que coincida con TimestampColumnName. Este nombre de columna se define en la definición de creación de particiones de tabla externa.

  • No es posible invalidar las propiedades de la tabla externa mediante el comando export. Por ejemplo, no puede exportar datos en formato Parquet a una tabla externa cuyo formato de datos sea CSV.

  • Si la tabla externa tiene particiones, los artefactos exportados se escriben en sus directorios respectivos según las definiciones de partición. Para obtener un ejemplo, consulte ejemplo de tabla externa con particiones.

    • Si un valor de partición es null/vacío o es un valor de directorio no válido, según las definiciones del almacenamiento de destino, el valor de partición se reemplaza por un valor predeterminado de __DEFAULT_PARTITION__.

  • Para obtener sugerencias para superar los errores de almacenamiento durante los comandos de exportación, consulte errores durante los comandos de exportación.

  • Las columnas de tabla externa se asignan a tipos de datos de formato de destino adecuados, según las reglas de asignación de tipos de datos.

  • La exportación nativa de Parquet es un mecanismo de exportación de recursos ligero más eficaz. Actualmente, synapse SQL COPYno admite una columna de datetime exportada.

Número de archivos

El número de archivos escritos por partición depende de la configuración de distribución de la operación de exportación:

  • Si la tabla externa incluye solo datetime particiones o ninguna partición, el número de archivos escritos para cada partición que existe, debe ser similar al número de nodos (o más, si se alcanza sizeLimit). Cuando se distribuye la operación de exportación, todos los nodos se exportan simultáneamente. Para deshabilitar la distribución, de modo que solo un solo nodo realice las escrituras, establezca en distributed false. Este proceso crea menos archivos, pero reduce el rendimiento de la exportación.

  • Si la tabla externa incluye una partición por una columna de cadena, el número de archivos exportados debe ser un único archivo por partición (o más, si sizeLimit se alcanza). Todos los nodos siguen participando en la exportación (se distribuye la operación), pero cada partición se asigna a un nodo específico. Establecer distributed en false, hace que solo un único nodo realice la exportación, pero el comportamiento sigue siendo el mismo (un único archivo escrito por partición).

Ejemplos

Ejemplo de tabla externa sin particiones

En el ejemplo siguiente se exporta datos de la tabla T a la tabla ExternalBlob. ExternalBlob es una tabla externa sin particiones.

.export to table ExternalBlob <| T

de salida

ExternalTableName Path NumRecords
ExternalBlob http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv 10

Ejemplo de tabla externa con particiones

En el ejemplo siguiente se crea primero una tabla externa con particiones, PartitionedExternalBlob con una ubicación de almacenamiento de blobs especificada. Los datos se almacenan en formato CSV con un formato de ruta de acceso que organiza los datos por nombre y fecha del cliente.

.create external table PartitionedExternalBlob (Timestamp:datetime, CustomerName:string) 
kind=blob
partition by (CustomerName:string=CustomerName, Date:datetime=startofday(Timestamp))   
pathformat = ("CustomerName=" CustomerName "/" datetime_pattern("yyyy/MM/dd", Date))   
dataformat=csv
( 
   h@'http://storageaccount.blob.core.windows.net/container1;secretKey'
)

A continuación, exporta datos de la tabla T a la tabla externa PartitionedExternalBlob.

.export to table PartitionedExternalBlob <| T

de salida

ExternalTableName Path NumRecords
ExternalBlob http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv 10
ExternalBlob http://storageaccount.blob.core.windows.net/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv 10

Si el comando se ejecuta de forma asincrónica mediante la palabra clave async, la salida está disponible mediante el comando mostrar los detalles de la operación.

Contenido relacionado