Commande .replace extents

Cette commande s’exécute dans le contexte d’une base de données spécifique. Il déplace les étendues spécifiées de leurs tables sources vers la table de destination, puis supprime les étendues spécifiées de la table de destination. Toutes les opérations de suppression et de déplacement sont effectuées dans une seule transaction.

Remarque

Les partitions de données sont appelées étendues, et toutes les commandes utilisent « extent » ou « extents » comme synonyme. Pour plus d’informations sur les étendues, consultez vue d’ensemble des étendues (partitions de données).

autorisations

Vous devez disposer au moins des autorisations d’administrateur de table pour les tables source et de destination.

Restrictions

• Les tables source et de destination doivent se trouver dans la base de données contextuelle.
• Toutes les étendues spécifiées par ExtentsToDropQuery doivent appartenir à la table de destination.
• Toutes les colonnes des tables sources sont censées exister dans la table de destination portant le même nom et le même type de données.
• Si la table de destination est une table source d’une vue matérialisée, la commande peut échouer, car la vue matérialisée ne traite pas les enregistrements dans les étendues déplacées. Pour plus d’informations, consultez la page limitations des vues matérialisées. Vous pouvez contourner cette erreur en définissant un nouveau temps d’ingestion pendant la commande move. Consultez setNewIngestionTime les propriétés prises en charge.

Syntaxe

.replace[async] extents table in DestinationTableName [ with(PropertyName = PropertyValue [, ...]] <|{)ExtentsToDropQuery},{ExtentsToMoveQuery}

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 de manière asynchrone.
DestinationTableName	string	✔️	Nom de la table vers laquelle déplacer les étendues.
FromDate	datetime		Date de début de la fenêtre de requête.
ToDate	datetime		Date de fin de la fenêtre de requête.
PropertyName, PropertyValue	string		Une ou plusieurs propriétés prises en charge.
ExtentsToDropQuery	string	✔️	Les résultats de cette requête spécifient les ID d’étendue qui doivent être supprimés de la table de destination. Doit retourner un jeu d’enregistrements avec une colonne appelée « ExtentId ».
ExtentsToMoveQuery	string	✔️	Les résultats de cette requête Langage de requête Kusto (KQL) spécifient les tables sources et les ID d’étendue à déplacer vers la table de destination. Doit retourner un jeu d’enregistrements avec des colonnes appelées « ExtentId » et « TableName ».

Propriétés prises en charge

Nom de la propriété	Type	Requise	Description
setNewIngestionTime	bool		Si la valeur est définie true, une nouvelle heure d’ingestion est affectée à tous les enregistrements dans les étendues déplacées. Cela est utile lorsque les enregistrements doivent être traités par des charges de travail qui dépendent des curseurs de base de données, tels que les vues matérialisées et l’exportation continue des données.
extentCreatedOnFrom	datetime	✔️	Appliquez les étendues créées après ce point dans le temps.
extentCreatedOnTo	datetime	✔️	Appliquez les étendues créées avant ce point dans le temps.

Remarque

Pour de meilleures performances, définissez les paramètres extentCreatedOnFrom et extentCreatedOnTo sur la plus petite plage possible.

Retours

Lorsque la commande est exécutée de façon synchrone, une table avec le schéma suivant est retournée.

Paramètre de sortie	Type	Description
OriginalExtentId	string	Identificateur unique (GUID) pour l’étendue d’origine dans la table source qui a été déplacée vers la table de destination, ou l’étendue de la table de destination qui a été supprimée.
ResultExtentId	string	Identificateur unique (GUID) pour l’étendue de résultat qui a été déplacée de la table source vers la table de destination. Vide, si l’étendue a été supprimée de la table de destination. En cas d’échec : « Échec ».
Détails	string	Inclut les détails de l’échec en cas d’échec de l’opération.

Lorsque la commande est exécutée de façon asynchrone, un ID d’opération (GUID) est retourné. Surveillez l’état de l’opération avec la commande .show operations et récupérez les résultats d’une exécution réussie avec la commande détails de l’opération .show.

Remarque

La commande échoue si les étendues retournées par la requête ExtentsToDropQuery n’existent pas dans la table de destination. Cela peut se produire si les étendues ont été fusionnées avant l’exécution de la commande replace. Pour vous assurer que la commande échoue sur les étendues manquantes, vérifiez que la requête retourne les ExtentIds attendus. L’exemple n°1 ci-dessous échoue si l’étendue à supprimer n’existe pas dans la table MyOtherTable. Toutefois, l’exemple n° 2 réussit même si l’étendue à supprimer n’existe pas, car la requête à supprimer n’a retourné aucun ID d’étendue.

Exemples

Déplacer toutes les étendues dans un intervalle de temps de création spécifié à partir de deux tables

Déplacez toutes les étendues de deux tables spécifiques (MyTable1, MyTable2) dans une plage de temps de création spécifiée vers la table MyOtherTable, puis supprimez toutes les étendues marquées MyOtherTable avec drop-by:MyTag:

.replace extents in table MyOtherTable with (extentCreatedOnFrom=datetime(2023-03-10), extentCreatedOnTo=datetime(2023-03-12)) <|
    {
        .show table MyOtherTable extents where tags has 'drop-by:MyTag'
    },
    {
        .show tables (MyTable1,MyTable2) extents
    }

Exemple de sortie

OriginalExtentId	ResultExtentId	Détails
e133f050-a1e2-4dad-8552-1f5cf47cab69	0d96ab2d-9dd2-4d2c-a45e-b24c65aa6687
cdbeb35b-87ea-499f-b545-defbae091b57	a90a303c-8a14-4207-8f35-d8ea94ca45be
4fcb4598-9a31-4614-903c-0c67c286da8c	97aafea1-59ff-4312-b06b-08f42187872f
2dfdef64-62a3-4950-a130-96b5b1083b5a	0fb7f3da-5e28-4f09-a000-e62eb41592df

Déplacer toutes les étendues d’une plage de temps de création spécifiée d’une table à une autre, supprimer une extension spécifique

Déplacez toutes les étendues d’une plage de temps de création spécifiée d’une table spécifique (MyTable1) vers la table MyOtherTableet supprimez une extension spécifique en MyOtherTable, par son ID :

.replace extents in table MyOtherTable with (extentCreatedOnFrom=datetime(2023-03-10), extentCreatedOnTo=datetime(2023-03-12)) <|
    {
        print ExtentId = "2cca5844-8f0d-454e-bdad-299e978be5df"
    },
    {
        .show table MyTable1 extents 
    }

.replace extents in table MyOtherTable with (extentCreatedOnFrom=datetime(2023-03-10), extentCreatedOnTo=datetime(2023-03-12)) <|
    {
        .show table MyOtherTable extents
        | where ExtentId == guid(2cca5844-8f0d-454e-bdad-299e978be5df) 
    },
    {
        .show table MyTable1 extents 
    }

Implémenter une logique idempotente

Implémentez une logique idempotente afin que Kusto supprime les étendues de la table t_dest uniquement s’il existe des étendues à déplacer d’une table t_source à l’autre t_dest:

.replace async extents in table t_dest with (extentCreatedOnFrom=datetime(2023-03-10), extentCreatedOnTo=datetime(2023-03-12)) <|
{
    let any_extents_to_move = toscalar( 
        t_source
        | where extent_tags() has 'drop-by:blue'
        | summarize count() > 0
    );
    let extents_to_drop =
        t_dest
        | where any_extents_to_move and extent_tags() has 'drop-by:blue'
        | summarize by ExtentId = extent_id()
    ;
    extents_to_drop
},
{
    let extents_to_move = 
        t_source
        | where extent_tags() has 'drop-by:blue'
        | summarize by ExtentId = extent_id(), TableName = 't_source'
    ;
    extents_to_move
}