Partager via

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

  • Article

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

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 est la façon dont elles traitent les tables et données 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.

Remarque

L’ingestion à partir d’une requête est une ingestion directe. Par conséquent, il n’inclut pas de nouvelles tentatives automatiques. Les nouvelles tentatives automatiques sont disponibles lors de l’ingestion via le service de gestion des données. Utilisez le document de vue d’ensemble de l’ingestion pour déterminer l’option d’ingestion la plus appropriée pour votre scénario.

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 d’administrateur de table.

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

Syntaxe

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

En savoir plus sur les conventions de syntaxe.

Paramètres

Nom Type Requise Description
async string Si elle est spécifiée, la commande retourne immédiatement et continue l’ingestion en arrière-plan. Utilisez la commande retournée OperationId .show operations pour récupérer l’état et les résultats de l’ingestion.
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. Seules .show les commandes de gestion sont prises en charge.

Astuces pour les performances

  • Définissez la distributed propriété true sur si la quantité de données produites par la requête est volumineuse, 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 être inutile de générer de nombreuses petites partitions de données.
  • L’ingestion de données est une opération gourmande en ressources qui peut affecter les activités simultanées sur la base de données, y compris l’exécution de requêtes. Évitez d’exécuter trop de commandes d’ingestion en même temps.
  • Limitez les données pour l’ingestion à moins de 1 Go par opération d’ingestion. Si nécessaire, utilisez plusieurs commandes d’ingestion.

Propriétés d’ingestion prises en charge

Propriété Type Description
distributed bool Si 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.
creationTime string Valeur DateHeure (sous forme de chaîne ISO8601) à utiliser comme heure de création des étendues de données ingérées. Si aucune valeur n’est spécifiée, 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 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 d’administrateur de table.
recreate_schema bool Si 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 d’administrateur 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 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’étendue créée.
docstring string Description utilisée pour documenter le tableau.
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 détails de l’opération .show. La valeur par défaut est false. with (persistDetails=true)

Considérations relatives au schéma

  • .set-or-replaceconserve le schéma, sauf si l’une des propriétés d’ingestion ou recreate_schema d’ingestion extend_schema est définie truesur .
  • .set-or-append et .append les commandes conservent le schéma, sauf si la extend_schema propriété d’ingestion est définie sur true.
  • La mise en correspondance du schéma du jeu de résultats à celle de la table cible est basée 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 la requête sont dans le même ordre que la table, sinon les données sont ingérées dans les colonnes incorrectes.

Attention

Si le schéma est modifié, il se produit dans une transaction distincte avant l’ingestion réelle des données. Cela signifie que le schéma peut être modifié même en cas de défaillance de l’ingestion des 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és 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 le renommage du projet 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 a une seule colonne, « ExtentId » et contient les ID d’étendue de toutes les étendues de la base de données qui ont été créées il y a plus de 30 jours. La base de données a une table existante nommée « MyExtents ». Étant donné que le jeu de données devrait être supérieur à 1 Go (plus de 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 des étendues sur une 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