Exporter des données dans une table externe
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] to table externalTableName
[with (propertyName = propertyValue [, ...]] <| )requête
En savoir plus sur les conventions de syntaxe.
Paramètres
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. 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 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. 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__.
- 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
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 pas de partitions du tout, le nombre de fichiers écrits (pour chaque partition, le cas échéant) doit être similaire au nombre de nœuds (ou plus, s’il
sizeLimitest 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 surdistributedfalse. 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
sizeLimitest 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 valeurdistributedfalse 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.