Exportación de datos a una tabla externa

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 table Administración para ejecutar este comando.

Syntax

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

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

Parámetros

Nombre	Tipo	Requerido	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.
consulta	string	✔️	Consulta de exportación.

Propiedades admitidas

Las propiedades siguientes se admiten como parte del comando exportar a tabla externa.

Propiedad	Tipo	Descripción	Default
sizeLimit	long	Límite de tamaño en bytes de un único artefacto de almacenamiento que se escribe (antes de la compresión). Se escribirá un grupo de filas completo de tamaño parquetRowGroupSize antes de comprobar si este grupo de filas ha alcanzado 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 equivale 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 una 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 los nodos del clúster. 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 ha alcanzado 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 tabla externa:

Creación de particiones de tablas externas	Distribución predeterminada
La tabla externa no está particionada ni particionada solo por datetime columna	La exportación se distribuye per_node : todos los nodos del clúster se exportan simultáneamente. Cada nodo escribe los datos asignados a ese nodo. El número de archivos exportados por un nodo será 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 se escribe mediante un único 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, se recomienda 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 se reduce mucho.
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 las tablas externas con particiones mediante 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. Por ejemplo, si hay una sola partición que es mucho mayor que otras, la mayoría del trabajo de exportación se realiza mediante el nodo único asignado a esa partición, mientras que otros nodos estarán principalmente inactivos. 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 primero la que tiene la mejor distribución. * Se establece 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 ejecutará con per-node distribución y cada nodo exportará 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 valores atípicos 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) será el valor mínimo entre 64 y el número de nodos del clúster. 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 la tabla externa de Azure Storagepermisos de escritura o SQL Server tabla externa.

Output

Parámetro de salida	Tipo	Descripción
ExternalTableName	string	Nombre de la tabla externa.
Ruta de acceso	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 se pueden 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 respectivos directorios según las definiciones de partición, como se muestra en el ejemplo de tabla externa con particiones.

  • Si un valor de partición es nulo o está 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 los 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 luz de recursos más eficaz. La columna 'datetime' exportada no es compatible actualmente con Synapse SQL 'COPY'.

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 solo incluye particiones datetime, o no hay particiones en absoluto, el número de archivos escritos (para cada partición, si existe) debe ser similar al número de nodos del clúster (o más, si sizeLimit se alcanza). Cuando se distribuye la operación de exportación, todos los nodos del clúster exportan simultáneamente. Para deshabilitar la distribución, de modo que solo un nodo realice las escrituras, establezca en distributed false. Este proceso crea menos archivos, pero reducirá 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. Si se establece distributed en false, solo se producirá un nodo único para realizar la exportación, pero el comportamiento seguirá siendo el mismo (un único archivo escrito por partición).

Ejemplos

Ejemplo de tabla externa sin particiones

ExternalBlob es una tabla externa sin particiones.

.export to table ExternalBlob <| T

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

Ejemplo de tabla externa con particiones

PartitionedExternalBlob es una tabla externa, definida de la siguiente manera:

.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'
)

.export to table PartitionedExternalBlob <| T

ExternalTableName	Ruta de acceso	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 async palabra clave ), la salida está disponible mediante el comando mostrar detalles de la operación.