Partager via

Exporter des données dans une table externe

  • Article

S’applique à : ✅Microsoft Fabric✅Azure Data Explorer

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] totableexternalTableName
[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 écrit avant la compression. Un groupe de lignes complet de taille parquetRowGroupSize est écrit avant de vérifier si ce groupe de lignes 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 ou 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. 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 sur sizeLimit, ce qui signifie qu’un groupe de lignes complet est exporté avant de vérifier si ce groupe de lignes 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 sont exportés simultanément. Chaque nœud écrit les données affectées à ce nœud. Le nombre de fichiers exportés par un nœud est supérieur à un, uniquement si la taille des données de ce nœud dépasse sizeLimit.
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, la recommandation consiste à définir la partition avec la distribution la plus uniforme comme la 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. Si une partition est beaucoup plus grande que les autres, le nœud affecté à cette partition effectue la plupart du travail d’exportation, tandis que les autres nœuds restent principalement inactifs. Pour plus d’informations, consultez 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 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.spread les hint.concurrency 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. 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. Pour obtenir un exemple, consultez 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 de 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 datetime partitions uniquement, ou pas de partitions du tout, le nombre de fichiers écrits pour chaque partition qui existe doit être similaire au nombre de nœuds (ou plus, si sizeLimit est atteint). Lorsque l’opération d’exportation est distribuée, tous les nœuds s’exportent 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 définition de distributed sur 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

L’exemple suivant exporte des données de la table T vers la table ExternalBlob. ExternalBlob est une table externe non partitionnée.

.export to table ExternalBlob <| T

de sortie

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

Exemple de table externe partitionnée

L’exemple suivant crée d’abord une table externe partitionnée, PartitionedExternalBlob avec un emplacement de stockage d’objets blob spécifié. Les données sont stockées au format CSV avec un format de chemin d’accès qui organise les données par nom et date du client.

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

Il exporte ensuite les données de la table T vers la table externe PartitionedExternalBlob.

.export to table PartitionedExternalBlob <| T

de sortie

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 mot clé async, la sortie est disponible à l’aide du afficher les détails de l’opération commande.

Contenu connexe