Comando .replace extents

Este comando se ejecuta en el contexto de una base de datos específica. Mueve las extensiones especificadas de sus tablas de origen a la tabla de destino y, a continuación, quita las extensiones especificadas de la tabla de destino. Todas las operaciones de colocación y movimiento se realizan en una sola transacción.

Nota

Las particiones de datos se denominan extensiones y todos los comandos usan "extent" o "extents" como sinónimo. Para más información sobre las extensiones, consulte Información general sobre extensiones (particiones de datos).

Permisos

Debe tener al menos permisos de table Administración para las tablas de origen y destino.

Restricciones

• Las tablas de origen y destino deben estar en la base de datos de contexto.
• Se espera que todas las extensiones especificadas por ExtentsToDropQuery pertenezcan a la tabla de destino.
• Se espera que todas las columnas de las tablas de origen existan en la tabla de destino con el mismo nombre y tipo de datos.
• Si la tabla de destino es una tabla de origen de una vista materializada, es posible que se produzca un error en el comando, ya que la vista materializada no procesará los registros en las extensiones movidas. Vea más detalles en la página limitaciones de las vistas materializadas . Puede solucionar este error estableciendo un nuevo tiempo de ingesta durante el comando move. Consulte setNewIngestionTime en las propiedades admitidas.

Syntax

.replace [async] extentsintableDestinationTableName [ with(PropertyName=PropertyValue [, ...])] <|{ExtentsToDropQuery},{ExtentsToMoveQuery}

Más información sobre las convenciones de sintaxis.

Parámetros

Nombre	Tipo	Requerido	Descripción
async	string		Si se especifica, el comando se ejecuta de forma asincrónica.
DestinationTableName	string	✔️	Nombre de la tabla a la que se van a mover las extensiones.
FromDate	datetime		Fecha de inicio de la ventana de consulta.
ToDate	datetime		Fecha de finalización de la ventana de consulta.
PropertyName, PropertyValue	string		Una o varias propiedades admitidas.
ExtentsToDropQuery	string	✔️	Los resultados de esta consulta especifican los identificadores de extensión que se deben quitar de la tabla de destino. Debe devolver un conjunto de registros con una columna denominada "ExtentId".
ExtentsToMoveQuery	string	✔️	Los resultados de esta consulta de Lenguaje de consulta Kusto (KQL) especifican las tablas de origen y los identificadores de extensión que se van a mover a la tabla de destino. Debe devolver un conjunto de registros con columnas denominadas "ExtentId" y "TableName".

Propiedades admitidas

Nombre de propiedad	Tipo	Requerido	Descripción
setNewIngestionTime	bool		Si se establece trueen , se asigna un nuevo tiempo de ingesta a todos los registros en extensiones que se mueven. Esto resulta útil cuando las cargas de trabajo que dependen de cursores de base de datos deben procesar registros, como vistas materializadas y exportación continua de datos.
extentCreatedOnFrom	datetime	✔️	Aplique en las extensiones creadas después de este momento dado.
extentCreatedOnTo	datetime	✔️	Aplique en las extensiones creadas antes de este momento dado.

Nota

Para mejorar el rendimiento, establezca los parámetros extentCreatedOnFrom y extentCreatedOnTo en el intervalo más pequeño posible.

Devoluciones

Cuando el comando se ejecuta de forma sincrónica, se devuelve una tabla con el esquema siguiente.

Parámetro de salida	Tipo	Descripción
OriginalExtentId	string	Identificador único (GUID) para la extensión original de la tabla de origen que se ha movido a la tabla de destino o la extensión de la tabla de destino que se ha quitado.
ResultExtentId	string	Identificador único (GUID) para la extensión del resultado que se ha movido de la tabla de origen a la tabla de destino. Vacío, si la extensión se quitó de la tabla de destino. Tras un error: "Error".
Detalles	string	Incluye los detalles del error si se produce un error en la operación.

Cuando el comando se ejecuta de forma asincrónica, se devuelve un identificador de operación (GUID). Supervise el estado de la operación con el comando .show operations y recupere los resultados de una ejecución correcta con el comando .show operation details .

Nota

Se producirá un error en el comando si las extensiones devueltas por la consulta ExtentsToDropQuery no existen en la tabla de destino. Esto puede ocurrir si las extensiones se combinaron antes de que se ejecutara el comando replace. Para asegurarse de que el comando produce un error en las extensiones que faltan, compruebe que la consulta devuelve los valores de ExtentId esperados. Se producirá un error en el ejemplo 1 siguiente si la extensión que se va a quitar no existe en la tabla MyOtherTable. Sin embargo, el ejemplo 2 se realizará correctamente aunque la medida en que se quite no existe, ya que la consulta que se va a quitar no devolvió ningún identificador de extensión.

Ejemplos

Mover todas las extensiones en un intervalo de tiempo de creación especificado de dos tablas

Mueva todas las extensiones de dos tablas específicas (MyTable1, MyTable2) en un intervalo de tiempo de creación especificado a la tabla MyOtherTabley quite todas las extensiones MyOtherTable etiquetadas con 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
    }

Salida de ejemplo

OriginalExtentId	ResultExtentId	Detalles
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

Mover todas las extensiones de un intervalo de tiempo de creación especificado de una tabla a otra, quitar una extensión específica

Mueva todas las extensiones de un intervalo de tiempo de creación especificado de una tabla específica (MyTable1) a la tabla MyOtherTabley quite una extensión específica en MyOtherTable, por su identificador:

.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 
    }

Implementación de una lógica idempotente

Implemente una lógica idempotente para que Kusto quite las extensiones de la tabla t_dest solo si hay extensiones para pasar de la tabla t_source a la tabla 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
}