Partager via

Exporter des données vers le stockage cloud

  • Article

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

Exécute une requête et écrit le premier jeu de résultats dans un stockage cloud externe, spécifié par un chaîne de connexion de stockage.

autorisations

Vous devez disposer au moins des autorisations de visionneuse de base de données pour exécuter cette commande.

Syntaxe

.export[] [asynccompressed] toOutputDataFormat( StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] ] )<|Requête

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom Type Requise Description
async string Si elle est spécifiée, la commande s’exécute en mode asynchrone. Voir le mode asynchrone.
compressed string Si spécifié, les artefacts de stockage de sortie sont compressés sous forme .gz de fichiers. Consultez la compressionTypepropriété prise en charge pour compresser les fichiers Parquet en tant que composant logiciel enfichable.
OutputDataFormat string ✔️ Indique le format des données des artefacts de stockage écrits par la commande. Les valeurs prises en charge sont csv, tsv, json et parquet.
StorageConnectionString string Un ou plusieurs chaîne de connexion de stockage qui indiquent le stockage dans lequel écrire les données. Plusieurs chaînes de connexion de stockage peuvent être spécifiées pour les écritures évolutives. Chaque chaîne de connexion doit indiquer les informations d’identification à utiliser lors de l’écriture dans le stockage. Par exemple, lors de l’écriture dans Stockage Blob Azure, les informations d’identification peuvent être la clé du compte de stockage ou une clé d’accès partagé (SAP) avec les autorisations de lecture, d’écriture et de liste des objets blob.
PropertyName, PropertyValue string Liste séparée par des virgules de paires de propriétés clé-valeur. Consultez les propriétés prises en charge.

Remarque

Nous vous recommandons vivement d’exporter des données vers le stockage qui se trouve dans la même région que la base de données elle-même. Cela inclut les données exportées afin qu’elles puissent être transférées vers un autre service cloud dans d’autres régions. Les écritures doivent être effectuées localement, tandis que les lectures peuvent se produire à distance.

Propriétés prises en charge

Propriété Type Description
includeHeaders string Pour csv/tsv la sortie, contrôle la génération d’en-têtes de colonne. Il peut s’agir de l’une ( none valeur par défaut ; aucune ligne d’en-tête émise), all (émettre une ligne d’en-tête dans chaque artefact de stockage) ou firstFile (émettre une ligne d’en-tête dans le premier artefact de stockage uniquement).
fileExtension string Indique la partie « extension » de l’artefact de stockage (par exemple, .csv ou .tsv). Si la compression est utilisée, .gz elle est également ajoutée.
namePrefix string Indique un préfixe à ajouter à chaque nom d’artefact de stockage généré. Un préfixe aléatoire est utilisé s’il n’est pas spécifié.
encoding string Indique comment encoder le texte : UTF8NoBOM (par défaut) ou UTF8BOM.
compressionType string Indique le type de compression à utiliser. Les valeurs possibles sont gzip ou snappy. La valeur par défaut est gzip. snappy peut (éventuellement) être utilisé pour parquet le format.
distribution string Indicateur de distribution (single, per_node, per_shard). Si la valeur est singleégale, un thread unique écrit dans le stockage. Sinon, exportez les écritures à partir de tous les nœuds exécutant la requête en parallèle. Voir évaluer l’opérateur de plug-in. La valeur par défaut est per_shard.
persistDetails bool Indique que la commande doit conserver ses résultats (voir async l’indicateur). Les valeurs par défaut dans les exécutions asynchrones, mais peuvent être désactivées true si l’appelant ne nécessite pas les résultats). La valeur par défaut est false dans les exécutions synchrones, mais peut également être activée dans celles-ci.
sizeLimit long Limite de taille en octets d’un seul artefact de stockage écrit avant la compression. Plage valide : 100 Mo (par défaut) à 4 Go.
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. La taille du groupe de lignes par défaut est de 100 000 enregistrements.
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.
parquetDatetimePrecision string Spécifie la précision à utiliser lors de l’exportation datetime de valeurs vers Parquet. Les valeurs possibles sont millisecondes et microsecondes. La valeur par défaut est milliseconde.

Authentification et autorisation

La méthode d’authentification est basée sur la chaîne de connexion fournie, et les autorisations requises varient en fonction de la méthode d’authentification.

Le tableau suivant répertorie les méthodes d’authentification prises en charge et les autorisations nécessaires pour exporter des données vers un stockage externe par type de stockage.

Méthode d'authentification Stockage Blob Azure / Data Lake Storage Gen2 Data Lake Storage Gen 1
Emprunt d'identité Contributeur aux données Blob du stockage Contributeur
Jeton d’accès partagé (SAS) Écrire Écrire
Jeton d’accès Microsoft Entra Aucune autorisation supplémentaire requise Aucune autorisation supplémentaire requise
Clé d’accès au compte de stockage Aucune autorisation supplémentaire requise Aucune autorisation supplémentaire requise

Retours

Les commandes retournent une table qui décrit les artefacts de stockage générés. Chaque enregistrement décrit un seul artefact et inclut le chemin de stockage de l’artefact et le nombre d’enregistrements qu’il contient.

Chemin d’accès NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv 10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv 15

Mode Asynchrone

Si l’indicateur async est spécifié, la commande s’exécute en mode asynchrone. Dans ce mode, la commande retourne immédiatement avec un ID d’opération et l’exportation de données se poursuit en arrière-plan jusqu’à l’achèvement. L’ID d’opération retourné par la commande peut être utilisé pour suivre sa progression et finalement ses résultats via les commandes suivantes :

Par exemple, après une réussite, vous pouvez récupérer les résultats à l’aide des éléments suivants :

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Exemples

Dans cet exemple, Kusto exécute la requête, puis exporte le premier jeu d’enregistrements produit par la requête vers un ou plusieurs objets blob CSV compressés, jusqu’à 1 Go avant la compression. Les étiquettes de nom de colonne sont ajoutées en tant que première ligne pour chaque objet blob.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Échecs pendant les commandes d’exportation

Les commandes d’exportation peuvent échouer temporairement pendant l’exécution. exportation continue retente automatiquement la commande. Les commandes d’exportation régulières (exporter vers le stockage, exporter vers une table externe) n’effectuent aucune nouvelle tentative.

  • Lorsque la commande d’exportation échoue, les artefacts qui ont déjà été écrits dans le stockage ne sont pas supprimés. Ces artefacts restent dans le stockage. Si la commande échoue, supposons que l’exportation est incomplète, même si certains artefacts ont été écrits.
  • La meilleure façon de suivre à la fois l’achèvement de la commande et les artefacts exportés lors de l’achèvement réussi consiste à utiliser les commandes et .show operations les .show operation details commandes.

Échecs de stockage

Par défaut, les commandes d’exportation sont distribuées de sorte qu’il peut y avoir de nombreuses écritures simultanées dans le stockage. Le niveau de distribution dépend du type de commande d’exportation :

  • La distribution par défaut pour la commande régulière .export est per_shard, ce qui signifie toutes les étendues qui contiennent des données à exporter en écriture dans le stockage simultanément.

  • La distribution par défaut pour l’exportation vers des commandes de table externe est per_node, ce qui signifie que la concurrence est le nombre de nœuds.

Lorsque le nombre d’étendues/nœuds est important, cela peut entraîner une charge élevée sur le stockage qui entraîne une limitation de stockage ou des erreurs de stockage temporaires. Les suggestions suivantes peuvent surmonter ces erreurs (par ordre de priorité) :

  • Augmentez le nombre de comptes de stockage fournis à la commande d’exportation ou à la définition de table externe . La charge est répartie uniformément entre les comptes.

  • Réduisez la concurrence en définissant l’indicateur per_node de distribution sur (voir les propriétés de commande).

  • Réduisez la concurrence du nombre de nœuds exportés en définissant la propriétéquery_fanout_nodes_percent de requête du client sur la concurrence souhaitée (pourcentage de nœuds). La propriété peut être définie dans le cadre de la requête d’exportation. Par exemple, la commande suivante limite le nombre de nœuds écrits simultanément dans le stockage à 50 % des nœuds :

    .export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery

  • Réduisez la concurrence du nombre de threads exportés dans chaque nœud lors de l’utilisation par exportation de partitions, en définissant la propriétéquery_fanout_threads_percent de demande cliente sur la concurrence souhaitée (pourcentage de threads). La propriété peut être définie dans le cadre de la requête d’exportation. Par exemple, la commande suivante limite le nombre de threads écrits simultanément dans le stockage à 50 % sur chacun des nœuds :

    .export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery

  • Si vous exportez vers une table externe partitionnée, la définition des propriétés peut réduire la spread/concurrency concurrence (consultez les détails des propriétés de commande.

  • Si aucune des recommandations précédentes ne fonctionne, vous pouvez désactiver complètement la distribution en définissant la propriété distributed sur false. Toutefois, nous vous déconseillons de le faire, car cela peut affecter considérablement les performances de la commande.

Échecs d’autorisation

Les échecs d’authentification ou d’autorisation pendant les commandes d’exportation peuvent se produire lorsque les informations d’identification fournies dans le chaîne de connexion de stockage ne sont pas autorisées à écrire dans le stockage. Si vous utilisez ou si vous utilisez impersonate un jeton SAP délégué par l’utilisateur pour la commande d’exportation, le rôle Contributeur aux données blob de stockage est requis pour écrire dans le compte de stockage. Pour plus d’informations, veuillez consulter la page Chaînes de connexion de stockage.

Mappage de types de données

Mappage des types de données Parquet

Lors de l’exportation, les types de données Kusto sont mappés aux types de données Parquet à l’aide des règles suivantes :

Type de données Kusto Type de données Parquet Parquet Annotation Commentaires
bool BOOLEAN
datetime INT64 TIMESTAMP_MICROS
dynamic BYTE_ARRAY UTF-8 Sérialisé en tant que chaîne JSON
guid BYTE_ARRAY UTF-8
int INT32
long INT64
real DOUBLE
string BYTE_ARRAY UTF-8
timespan INT64 Stocké sous forme de graduations (nombre de 100 nanosecondes)
decimal FIXED_LENGTH_BYTE_ARRAY DECIMAL

Contenu connexe