Exporter des données dans une table externe

Vous pouvez exporter des données en définissant une table externe et en les exportant. Les propriétés de la table sont spécifiées lors de la création de la table externe. La commande d’exportation fait référence à la table externe par nom.

autorisations

Vous devez disposer au moins des autorisations d’administrateur de table pour exécuter cette commande.

Syntaxe

.export [async] to table externalTableName
[with (propertyName = propertyValue [, ...]] <| )requête

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom	Type	Requise	Description
externalTableName	string	✔️	Nom de la table externe vers laquelle exporter.
propertyName, propertyValue	string		Liste séparée par des virgules de propriétés facultatives.
query	string	✔️	Requête d’exportation.

Propriétés prises en charge

Les propriétés suivantes sont prises en charge dans le cadre de la commande d’exportation vers une table externe.

Propriété	Type	Description	Default
sizeLimit	long	Limite de taille en octets d’un seul artefact de stockage en cours d’écriture (avant la compression). Un groupe de lignes complet de taille parquetRowGroupSize est écrit avant de vérifier si ce groupe de lignes a atteint la limite de taille et doit démarrer un nouvel artefact. Plage valide : 100 Mo (par défaut) à 1 Go.
distributed	bool	Désactivez/activez l’exportation distribuée. La valeur false équivaut à l’indicateur de single distribution.	La valeur par défaut est true.
distribution	string	Indicateur de distribution (single, per_node, per_shard). Pour plus d’informations, voir les paramètres de distribution	La valeur par défaut est per_node.
distributionKind	string	Vous pouvez éventuellement basculer vers une distribution uniforme lorsque la table externe est partitionnée par partition de chaîne. Les valeurs valides sont uniform ou default. Pour plus d’informations, voir les paramètres de distribution
concurrency	Nombre	Indique au système le nombre de partitions à exécuter en parallèle. Pour plus d’informations, voir les paramètres de distribution	La valeur par défaut est 16.
spread	Nombre	Indique au système comment distribuer les partitions entre les nœuds de cluster. Pour plus d’informations, voir les paramètres de distribution	La valeur par défaut est Min(64, number-of-nodes).
parquetRowGroupSize	int	Pertinent uniquement lorsque le format de données est Parquet. Contrôle la taille du groupe de lignes dans les fichiers exportés. Cette valeur est prioritaire sizeLimit, ce qui signifie qu’un groupe de lignes complet sera exporté avant de vérifier si ce groupe de lignes a atteint la limite de taille et doit démarrer un nouvel artefact.	La taille du groupe de lignes par défaut est de 100 000 enregistrements.

Paramètres de distribution

La distribution d’une exportation vers une opération de table externe indique le nombre de nœuds et de threads qui écrivent dans le stockage simultanément. La distribution par défaut dépend du partitionnement de table externe :

Partitionnement de tables externes	Distribution par défaut
La table externe n’est pas partitionnée ou partitionnée par datetime colonne uniquement	L’exportation est distribuée per_node : tous les nœuds du cluster sont exportés simultanément. Chaque nœud écrit les données affectées à ce nœud. Le nombre de fichiers exportés sizeLimitpar un nœud est supérieur à un seul, uniquement si la taille des données de ce nœud dépasse .
Une table externe est partitionnée par une colonne de chaîne	Les données à exporter sont déplacées entre les nœuds, de sorte que chaque nœud écrit un sous-ensemble des valeurs de partition. Une partition unique est toujours écrite par un seul nœud. Le nombre de fichiers écrits sizeLimitpar partition doit être supérieur à un seul si les données dépassent . Si la table externe comprend plusieurs partitions de chaîne, les données sont partitionnés entre le nœud en fonction de la première partition. Par conséquent, il est recommandé de définir la partition avec la distribution la plus uniforme comme première.

Modifier les paramètres de distribution par défaut

La modification des paramètres de distribution par défaut peut être utile dans les cas suivants :

Cas d’usage	Description	Recommandation
Réduire le nombre de fichiers exportés	L’exportation crée trop de petits fichiers et vous souhaitez qu’il crée un plus petit nombre de fichiers plus volumineux.	Définissez distribution=single ou distributed=false (les deux sont équivalents) dans les propriétés de commande. Un seul thread effectue l’exportation. L’inconvénient est que l’opération d’exportation peut être plus lente, car la concurrence est beaucoup réduite.
Réduire la durée d’exportation	Augmentation de la concurrence de l’opération d’exportation, afin de réduire sa durée.	Définir distribution=per_shard dans les propriétés de commande. Cela signifie que l’accès concurrentiel des opérations d’écriture est par partition de données, au lieu d’un nœud. Cela s’applique uniquement lors de l’exportation vers une table externe qui n’est pas partitionnée par partition de chaîne. Cela peut créer trop de charge sur le stockage, ce qui peut entraîner une limitation. Consultez les échecs de stockage.
Réduire la durée d’exportation des tables externes partitionnés par une partition de chaîne	Si les partitions ne sont pas réparties uniformément entre les nœuds, l’exportation peut prendre plus de temps pour s’exécuter. Par exemple, s’il existe une partition unique qui est beaucoup plus grande que d’autres, la plupart du travail d’exportation est effectué par le nœud unique affecté à cette partition, tandis que d’autres nœuds seront principalement inactifs. Consultez les paramètres de distribution.	Vous pouvez modifier plusieurs paramètres : * S’il existe plusieurs partitions de chaîne, définissez-en une avec la meilleure distribution. * Définir distributionKind=uniform dans les propriétés de commande. Ce paramètre désactive les paramètres de distribution par défaut pour les tables externes partitionnée par chaîne. L’exportation s’exécute avec per-node la distribution et chaque nœud exporte les données affectées au nœud. Une partition unique peut être écrite par plusieurs nœuds et le nombre de fichiers augmente en conséquence. Pour augmenter encore davantage la concurrence, définissez distributionKind=uniform avec distribution=per_shard la concurrence la plus élevée (au coût d’un nombre potentiellement plus élevé de fichiers écrits) * Si la cause de l’exportation lente n’est pas hors norme dans les données, réduisez la durée en augmentant la concurrence, sans modifier les paramètres de partitionnement. Utilisez les propriétés et hint.concurrency les hint.spread propriétés, qui déterminent l’accès concurrentiel du partitionnement. Voir l’opérateur de partition. Par défaut, le nombre de nœuds exportés simultanément (le spread) est la valeur minimale comprise entre 64 et le nombre de nœuds de cluster. La définition spread d’un nombre supérieur au nombre de nœuds augmente la concurrence sur chaque nœud (la valeur maximale est spread de 64).

Authentification et autorisation

Pour exporter vers une table externe, vous devez configurer des autorisations d’écriture. Pour plus d’informations, consultez les autorisations d’écriture pour Stockage Azure table externe ou une table externe SQL Server.

Sortie

Paramètre de sortie	Type	Description
ExternalTableName	string	Nom de la table externe.
Chemin d’accès	string	Chemin d’accès de sortie.
NumRecords	string	Nombre d’enregistrements exportés vers le chemin d’accès.

Notes

• Le schéma de sortie de requête d’exportation doit correspondre au schéma de la table externe, y compris toutes les colonnes définies par les partitions. Par exemple, si la table est partitionnée par DateTime, le schéma de sortie de requête doit avoir une colonne Timestamp correspondant à TimestampColumnName. Ce nom de colonne est défini dans la définition de partitionnement de table externe.

• Il n’est pas possible de remplacer les propriétés de table externe à l’aide de la commande d’exportation. Par exemple, vous ne pouvez pas exporter de données au format Parquet vers une table externe dont le format de données est CSV.

• Si la table externe est partitionnée, les artefacts exportés sont écrits dans leurs répertoires respectifs en fonction des définitions de partition, comme indiqué dans l’exemple de table externe partitionnée.

  • Si une valeur de partition est null/vide ou est une valeur de répertoire non valide, conformément aux définitions du stockage cible, la valeur de partition est remplacée par une valeur par défaut de __DEFAULT_PARTITION__.

• Pour obtenir des suggestions pour surmonter les erreurs de stockage pendant les commandes d’exportation, consultez les échecs lors des commandes d’exportation.

• Les colonnes de table externe sont mappées aux types de données de format cible appropriés, en fonction des règles de mappage des types de données.

• L’exportation native Parquet est un mécanisme d’exportation de lumière de ressource plus performant. Une colonne « datetime » exportée n’est actuellement pas prise en charge par Synapse SQL « COPY ».

Nombre de fichiers

Le nombre de fichiers écrits par partition dépend des paramètres de distribution de l’opération d’exportation :

• Si la table externe inclut uniquement des partitions datetime ou aucune partition, le nombre de fichiers écrits (pour chaque partition, le cas échéant) doit être similaire au nombre de nœuds dans le cluster (ou plus, le cas sizeLimit échéant). Lorsque l’opération d’exportation est distribuée, tous les nœuds du cluster sont exportés simultanément. Pour désactiver la distribution, de sorte qu’un seul nœud effectue les écritures, défini sur distributed false. Ce processus crée moins de fichiers, mais réduit les performances d’exportation.

• Si la table externe inclut une partition par une colonne de chaîne, le nombre de fichiers exportés doit être un seul fichier par partition (ou plus, s’il sizeLimit est atteint). Tous les nœuds participent toujours à l’exportation (l’opération est distribuée), mais chaque partition est affectée à un nœud spécifique. La valeur distributed false entraîne l’exportation d’un seul nœud, mais le comportement reste le même (un seul fichier écrit par partition).

Exemples

Exemple de table externe non partitionnée

ExternalBlob est une table externe non partitionnée.

.export to table ExternalBlob <| T

ExternalTableName	Chemin d’accès	NumRecords
ExternalBlob	http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv	10

Exemple de table externe partitionnée

PartitionedExternalBlob est une table externe, définie comme suit :

.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	Chemin d’accès	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 la commande est exécutée de manière asynchrone (à l’aide du async mot clé), la sortie est disponible à l’aide de la commande Afficher les détails de l’opération.