Partager via


Commande des étendues .replace

S’applique à : ✅Azure Data Explorer

Cette commande supprime et déplace les étendues dans une transaction unique dans le contexte d’une base de données spécifique. La commande supprime toutes les étendues spécifiées de la table de destination et déplace les étendues spécifiées des tables sources vers la table de destination.

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 peut pas traiter 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 une nouvelle heure 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 doivent inclure la ExtentId colonne, qui contient les ID d’étendue à supprimer de la table de destination.
ExtentsToMoveQuery string ✔️ Les résultats de cette requête doivent inclure les ExtentId colonnes, TableName qui contiennent les tables sources et les ID d’étendue à déplacer vers la table de destination.

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 sont 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 supprimée.
ResultExtentId string Identificateur unique (GUID) pour l’étendue du résultat 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. Le premier exemple échoue si l’étendue à supprimer n’existe pas dans la table MyOtherTable. Toutefois, le deuxième exemple 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
}