Exporter des données vers le stockage cloud

Article
01/23/2024

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 d’au moins les autorisations De visionneuse de base de données pour exécuter cette commande.

Syntax

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

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	Description
`async`	`string`		Si elle est spécifiée, la commande s’exécute en mode asynchrone. Consultez Mode asynchrone.
`compressed`	`string`		Si spécifié, les artefacts de stockage de sortie sont compressés sous forme de `.gz` fichiers. Consultez la `compressionType`propriété prise en charge pour la compression des fichiers Parquet en tant que snappy.
OutputDataFormat	`string`	✔️	Indique le format de données des artefacts de stockage écrits par la commande . Les valeurs prises en charge sont `csv`, `tsv`, `json` et `parquet`.
StorageConnectionString	`string`		Une ou plusieurs chaînes de connexion de stockage qui indiquent le stockage dans lequel écrire les données. Plusieurs chaîne de connexion de stockage peuvent être spécifiés 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é de 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 propriétés prises en charge.

Notes

Nous vous recommandons vivement d’exporter des données vers un stockage colocalisé dans la même région que le cluster lui-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 `none` (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` est également ajouté.
`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 égale `single`à , un thread unique écrit dans le stockage. Sinon, exportez les écritures de tous les nœuds exécutant la requête en parallèle. Consultez é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` indicateur). La valeur par défaut est dans les exécutions asynchrones `true` , mais peut être désactivée si l’appelant n’a pas besoin des 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 artefact de stockage unique en cours d’écriture (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ésactiver/activer l’exportation distribuée. La définition de la valeur false équivaut à un indicateur de `single` distribution. La valeur par défaut est true.
`parquetDatetimePrecision`	`string`	Spécifie la précision à utiliser lors de l’exportation de `datetime` valeurs vers Parquet. Les valeurs possibles sont milliseconde et microseconde. La valeur par défaut est milliseconde.

Authentification et autorisation

La méthode d’authentification est basée sur les chaîne de connexion fournies 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)	Write	Write
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 artefact unique 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 des 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 :

.show operations: suivez la progression.
.show operation details: obtenir les résultats de l’achèvement.

Par exemple, après une exécution réussie, vous pouvez récupérer les résultats à l’aide de :

.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 comme 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 lors des commandes d’exportation

Les commandes d’exportation peuvent échouer temporairement pendant l’exécution. L’exportation continue retenter 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 une fois l’exécution réussie consiste à utiliser les .show operations commandes et .show operation details .

Échecs de stockage

Par défaut, les commandes d’exportation sont distribuées de telle 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 l’accès concurrentiel correspond au nombre de nœuds dans le cluster.

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

Augmentez le nombre de comptes de stockage fournis à la commande export ou à la définition de table externe (la charge sera répartie uniformément entre les comptes).
Réduisez l’accès concurrentiel en définissant l’indicateur de distribution sur per_node (voir 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 demande cliente sur l’accès concurrentiel souhaité (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 qui écrivent simultanément dans le stockage à 50 % des nœuds de cluster :
```
.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 de chaque exportation de partition, en définissant la propriété query_fanout_threads_percent de demande cliente sur l’accès concurrentiel souhaité (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 qui écrivent simultanément dans le stockage à 50 % sur chacun des nœuds de cluster :
```
.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 dans les propriétés de commande.
Si aucun des éléments ci-dessus ne fonctionne, vous pouvez désactiver complètement la distribution en définissant la distributed propriété sur false. Toutefois, nous vous déconseillons de le faire, car cela peut affecter considérablement les performances de la commande.

Échecs d’autorisation

Des é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 impersonate ou 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, consultez Chaînes de connexion de stockage.

Mappage des 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ée en tant que chaîne JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Nombre stocké sous forme de tiques (100 nanosecondes)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Partager via