comando .replace extents

Esse comando é executado no contexto de um banco de dados específico. Ele move as extensões especificadas de suas tabelas de origem para a tabela de destino e, em seguida, descarta as extensões especificadas da tabela de destino. Todas as operações de drop e move são feitas em uma única transação.

Observação

Os fragmentos de dados são chamados de extensões, e todos os comandos usam "extensão" ou "extensões" como sinônimo. Para obter mais informações sobre extensões, consulte Visão geral sobre extensões (fragmentos de dados).

Permissões

Você deve ter pelo menos permissões de administrador de tabela para as tabelas de origem e destino.

Restrições

• As tabelas de origem e de destino devem estar no banco de dados de contexto.
• Espera-se que todas as extensões especificadas pelo ExtentsToDropQuery pertençam à tabela de destino.
• Espera-se que todas as colunas nas tabelas de origem existam na tabela de destino com o mesmo nome e tipo de dados.
• Se a tabela de destino for uma tabela de origem de uma exibição materializada, o comando poderá falhar, pois a exibição materializada não processará os registros nas extensões movidas. Veja mais detalhes na página de limitações de visualizações materializadas. Você pode contornar esse erro definindo um novo tempo de ingestão durante o comando mover. Consulte setNewIngestionTime em propriedades suportadas.

Sintaxe

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

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome	Digitar	Obrigatória	Descrição
async	string		Se especificado, o comando é executado de forma assíncrona.
DestinationTableName	string	✔️	O nome da tabela para a qual mover as extensões.
FromDate	datetime		A data de início da janela de consulta.
Até o momento	datetime		A data de término da janela de consulta.
PropertyName, PropertyValue	string		Uma ou mais propriedades com suporte.
ExtentsToDropQuery	string	✔️	Os resultados dessa consulta especificam as IDs de extensão que devem ser descartadas da tabela de destino. Deve retornar um conjunto de registros com uma coluna chamada "ExtentId".
ExtentsToMoveQuery	string	✔️	Os resultados dessa consulta KQL (Kusto Query Language) especificam as tabelas de origem e as IDs de extensão a serem movidas para a tabela de destino. Deve retornar um conjunto de registros com colunas chamadas "ExtentId" e "TableName".

Propriedades com suporte

Nome da propriedade	Tipo	Obrigatória	Descrição
setNewIngestionTime	bool		Se definido como true, um novo tempo de ingestão é atribuído a todos os registros em extensões que estão sendo movidas. Isso é útil quando os registros devem ser processados por cargas de trabalho que dependem de cursores de banco de dados, como exibições materializadas e exportação contínua de dados.
extentCreatedOnFrom	datetime	✔️	Aplicar em extensões criadas após esse point-in-time.
extentCreatedOnTo	datetime	✔️	Aplicar em extensões criadas antes deste momento.

Observação

Para obter melhor desempenho, defina os parâmetros extentCreatedOnFrom e extentCreatedOnTo para o menor intervalo possível.

Devoluções

Quando o comando é executado de forma síncrona, uma tabela com o seguinte esquema é retornada.

Parâmetro de saída	Tipo	Descrição
OriginalExtentId	string	Um identificador exclusivo (GUID) para a extensão original na tabela de origem que foi movida para a tabela de destino ou a extensão na tabela de destino que foi descartada.
ResultExtentId	string	Um identificador exclusivo (GUID) para a extensão de resultado que foi movida da tabela de origem para a tabela de destino. Vazio, se a extensão foi descartada da tabela de destino. Em caso de falha: "Falhou".
Detalhes	string	Inclui os detalhes da falha se a operação falhar.

Quando o comando é executado de forma assíncrona, um GUID (ID de operação) é retornado. Monitore o status da operação com o comando .show operations e recupere os resultados de uma execução bem-sucedida com o comando .show operation details .

Observação

O comando falhará se as extensões retornadas pela consulta ExtentsToDropQuery não existirem na tabela de destino. Isso pode acontecer se as extensões foram mescladas antes da execução do comando substituto. Para garantir que o comando falhe em extensões ausentes, verifique se a consulta retorna os ExtentIds esperados. O exemplo #1 abaixo falhará se a extensão a ser descartada não existir na tabela MyOtherTable. O exemplo #2, no entanto, será bem-sucedido mesmo que a extensão a ser descartada não exista, já que a consulta a ser descartada não retornou nenhum IDs de extensão.

Exemplos

Mover todas as extensões em um intervalo de tempo de criação especificado de duas tabelas

Mova todas as extensões de duas tabelas específicas (MyTable1, MyTable2) em um intervalo de tempo de criação especificado para a tabela MyOtherTablee solte todas as extensões marcadas MyOtherTable com 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
    }

Saída de exemplo

OriginalExtentId	ResultExtentId	Detalhes
e133f050-a1e2-4dad-8552-1f5cf47cab69	0d96ab2d-9dd2-4d2c-a45e-b24c65aa6687
CDBEB35B-87EA-499F-B545-DEFPAE091B57	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 as extensões em um intervalo de tempo de criação especificado de uma tabela para outra, descartar extensão específica

Mova todas as extensões em um intervalo de tempo de criação especificado de uma tabela específica (MyTable1) para uma tabela MyOtherTablee solte uma extensão específica em MyOtherTable, por sua 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 
    }

Implementar uma lógica idempotente

Implemente uma lógica idempotente para que o Kusto descarta extensões da tabela t_dest somente se houver extensões para mover de tabela t_source para tabela 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
}