Ingestion à partir d’une requête (.set, .append, .set-or-append, .set-or-replace)

Article
01/18/2024

Ces commandes exécutent une requête ou une commande de gestion et ingèrent les résultats de la requête dans une table. La différence entre ces commandes réside dans la façon dont elles traitent les données et les tables existantes ou inexistantes.

Commande	Si la table existe	Si la table n’existe pas
`.set`	La commande échoue	La table est créée et les données sont ingérées
`.append`	Les données sont ajoutées à la table	La commande échoue
`.set-or-append`	Les données sont ajoutées à la table	La table est créée et les données sont ingérées
`.set-or-replace`	Les données remplacent les données de la table	La table est créée et les données sont ingérées

Pour annuler une ingestion à partir de la commande de requête, consultez cancel operation.

Notes

Cette méthode d’ingestion est destinée à l’exploration et au prototypage. Ne l’utilisez pas dans des scénarios de production ou de volume élevé.

Autorisations

Pour effectuer différentes actions sur une table, des autorisations spécifiques sont requises :

Pour ajouter des lignes à une table existante à l’aide de la .append commande , vous avez besoin d’un minimum d’autorisations d’ingestion de table.
Pour créer une table à l’aide des différentes .set commandes, vous avez besoin d’un minimum d’autorisations Utilisateur de base de données.
Pour remplacer les lignes d’une table existante à l’aide de la .set-or-replace commande , vous avez besoin d’un minimum d’autorisations de Administration de table.

Pour plus d’informations sur les autorisations, consultez Contrôle d’accès en fonction du rôle Kusto.

Syntax

(.set | .set-or-append.set-or-replace.append | | ) [async] tableName [with(propertyName= propertyValue [, ...]] <|)queryOrCommand

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	Description
async	`string`		Si elle est spécifiée, la commande retourne et continue l’ingestion en arrière-plan. Utilisez le retourné `OperationId` avec la `.show operations` commande pour récupérer l’achèvement de l’ingestion status et les résultats.
tableName	`string`	✔️	Nom de la table dans laquelle ingérer des données. TableName est toujours lié à la base de données dans le contexte.
propertyName, propertyValue	`string`		Une ou plusieurs propriétés d’ingestion prises en charge utilisées pour contrôler le processus d’ingestion.
queryOrCommand	`string`	✔️	Texte d’une requête ou d’une commande de gestion dont les résultats sont utilisés comme données à ingérer.

Notes

Seules les .show commandes de gestion sont prises en charge.

Propriétés d’ingestion prises en charge

Propriété	Type	Description
`creationTime`	`string`	Valeur DateHeure (sous forme de chaîne ISO8601) à utiliser comme heure de création des étendues de données ingérées. S’il n’est pas spécifié, `now()` est utilisé. Lorsqu’elle est spécifiée, assurez-vous que la propriété `Lookback` de la stratégie de fusion des étendues effective de la table cible est alignée sur la valeur spécifiée.
`extend_schema`	`bool`	Si `true`la valeur est , la commande peut étendre le schéma de la table. La valeur par défaut est `false`. Cette option s’applique uniquement aux commandes `.append`, `.set-or-append` et `set-or-replace`. Cette option nécessite au moins des autorisations de Administration de table.
`recreate_schema`	`bool`	Si la valeur est `true`, la commande peut recréer le schéma de la table. La valeur par défaut est `false`. Cette option s’applique uniquement à la commande `.set-or-replace`. Cette option est prioritaire sur la `extend_schema` propriété si les deux sont définies. Cette option nécessite au moins des autorisations de Administration de table.
`folder`	`string`	Dossier à assigner à la table. Si la table existe déjà, cette propriété remplace le dossier de la table.
`ingestIfNotExists`	`string`	Si elle est spécifiée, l’ingestion échoue si la table a déjà des données marquées avec une `ingest-by:` balise avec la même valeur. Pour plus d’informations, consultez Étiquettes ingest-by:.
`policy_ingestiontime`	`bool`	Si `true`la valeur est , la stratégie de temps d’ingestion est activée sur la table. Par défaut, il s’agit de `true`.
`tags`	`string`	Chaîne JSON qui représente une liste de balises à associer à l’extension créée.
`docstring`	`string`	Description utilisée pour documenter le tableau.
`distributed`	`bool`	Si la valeur est `true`, la commande ingère à partir de tous les nœuds exécutant la requête en parallèle. La valeur par défaut est `false`. Consultez les conseils sur les performances.
`persistDetails`	Valeur booléenne qui, si elle est spécifiée, indique que la commande doit conserver les résultats détaillés pour la récupération par la commande .show operation details . La valeur par défaut est `false`.	`with (persistDetails=true)`

Considérations relatives au schéma

.set-or-replace conserve le schéma, sauf si l’une des propriétés d’ingestion extend_schema ou recreate_schema est définie sur true.
.set-or-append les commandes et .append conservent le schéma, sauf si la extend_schema propriété d’ingestion a la valeur true.
Le fait de faire correspondre le schéma du jeu de résultats à celui de la table cible est basé sur les types de colonnes. Il n’y a aucune correspondance avec les noms de colonnes. Assurez-vous que les colonnes de schéma de résultat de requête sont dans le même ordre que la table, sinon les données seront ingérées dans les colonnes incorrectes.

Attention

Si le schéma est modifié, cela se produit dans une transaction distincte avant l’ingestion des données réelle. Cela signifie que le schéma peut être modifié même en cas d’échec de l’ingestion des données.

Conseils sur les performances

L’ingestion de données est une opération gourmande en ressources qui peut affecter les activités simultanées sur le cluster, notamment les requêtes en cours d’exécution. Évitez d’exécuter trop de commandes d’ingestion en même temps.
Limitez les données d’ingestion à moins de 1 Go par opération d’ingestion. Si nécessaire, utilisez plusieurs commandes d’ingestion.
Définissez l’indicateur distributedtrue sur si la quantité de données produites par la requête est importante, dépasse 1 Go et ne nécessite pas de sérialisation. Ensuite, plusieurs nœuds peuvent produire une sortie en parallèle. N’utilisez pas cet indicateur lorsque les résultats de la requête sont petits, car il peut générer inutilement de nombreuses petites partitions de données.

Limitation des caractères

La commande échoue si la requête génère un nom d’entité avec le $ caractère . Les noms d’entité doivent respecter les règles d’affectation de noms. Le caractère doit donc $ être supprimé pour que la commande d’ingestion réussisse.

Par exemple, dans la requête suivante, l’opérateur search génère une colonne $table. Pour stocker les résultats de la requête, utilisez project-rename pour renommer la colonne.

.set Texas <| search State has 'Texas' | project-rename tableName=$table

Exemples

Créez une table nommée RecentErrors dans la base de données qui a le même schéma que LogsTable et qui contient tous les enregistrements d’erreur de la dernière heure.

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

Créez une table appelée « OldExtents » dans la base de données qui comporte une seule colonne, « ExtentId », et qui contient les ID d’étendue de toutes les étendues de la base de données qui ont été créées plus de 30 jours plus tôt. La base de données a une table existante nommée « MyExtents ». Étant donné que le jeu de données doit être supérieur à 1 Go (plus d’environ 1 million de lignes), utilisez l’indicateur distribué

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Ajoutez des données à une table existante appelée « OldExtents » dans la base de données active qui contient une seule colonne, « ExtentId », et qui contient les ID d’étendue de toutes les étendues de la base de données qui ont été créées plus de 30 jours plus tôt. Marquez la nouvelle étendue avec des balises tagA et tagB, en fonction d’une table existante nommée « MyExtents ».

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Ajoutez des données à la table « OldExtents » de la base de données active ou créez la table si elle n’existe pas déjà. Balisez la nouvelle étendue avec ingest-by:myTag. Procédez ainsi uniquement si la table ne contient pas déjà une extension marquée avec ingest-by:myTag, en fonction d’une table existante nommée « MyExtents ».

.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
   MyExtents
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Remplacez les données de la table « OldExtents » de la base de données active ou créez la table si elle n’existe pas déjà. Balisez la nouvelle étendue avec ingest-by:myTag.

.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Ajoutez des données à la table « OldExtents » dans la base de données active, tout en définissant l’heure de création de l’étendue créée sur une valeur DateTime spécifique dans le passé.

.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Sortie de retour

Retourne des informations sur les étendues créées en raison de la commande .set ou .append.

Exemple de sortie

ExtentId	OriginalSize	ExtentSize	CompressedSize	IndexSize	RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563	1291	5882	1568	4314	10