Ingestão de consulta (.set, .append, .set-or-append, .set-or-replace)

Aplica-se a: ✅Microsoft Fabric✅Azure Data Explorer

Esses comandos executam uma consulta ou um comando de gerenciamento e ingerem os resultados da consulta em uma tabela. A diferença entre esses comandos é como eles tratam tabelas e dados existentes ou inexistentes.

Para cancelar um comando de ingestão de consulta, consulte cancel operation.

Permissões

Para executar ações diferentes em uma tabela, são necessárias permissões específicas:

• Para adicionar linhas a uma tabela existente usando o .append comando, você precisa de um mínimo de permissões do Table Ingestor.
• Para criar uma nova tabela usando os vários .set comandos, você precisa de um mínimo de permissões de usuário do banco de dados.
• Para substituir linhas em uma tabela existente usando o .set-or-replace comando, você precisa de um mínimo de permissões de administrador de tabela.

Para obter mais informações sobre permissões, consulte Controle de acesso baseado em função Kusto.

Sintaxe

(.set.set-or-append | .set-or-replace | .append | ) [async] nome_da_tabela [with( nome_da_propriedade valor_da_ = propriedade [, ...]])<| queryOrCommand

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Dicas de desempenho

• Defina a distributed propriedade como true se a quantidade de dados produzidos pela consulta for grande, exceder 1 GB e não exigir serialização. Em seguida, vários nós podem produzir saída em paralelo. Não use esse sinalizador quando os resultados da consulta forem pequenos, pois ele pode gerar desnecessariamente muitos fragmentos de dados pequenos.
• A ingestão de dados é uma operação com uso intensivo de recursos que pode afetar atividades simultâneas no banco de dados, incluindo a execução de consultas. Evite executar muitos comandos de ingestão ao mesmo tempo.
• Limite os dados para ingestão a menos de 1 GB por operação de ingestão. Se necessário, use vários comandos de ingestão.

Propriedades de ingestão compatíveis

Considerações sobre o esquema

• .set-or-replace Preserva o esquema, a menos que uma das propriedades de ingestão OR extend_schema recreate_schema seja definida como true.
• .set-or-append e .append preservam o esquema, a menos que a extend_schema propriedade de ingestão seja definida como true.
• A correspondência do esquema do conjunto de resultados com o da tabela de destino é baseada nos tipos de coluna. Não há correspondência de nomes de coluna. Verifique se as colunas do esquema de resultado da consulta estão na mesma ordem que a tabela, caso contrário, os dados serão ingeridos nas colunas erradas.

Limitação de caracteres

O comando falhará se a consulta gerar um nome de entidade com o $ caractere. Os nomes de entidade devem estar em conformidade com as regras de nomenclatura, portanto, o $ caractere deve ser removido para que o comando de ingestão seja bem-sucedido.

Por exemplo, na consulta a seguir, o search operador gera uma coluna $table. Para armazenar os resultados da consulta, use project-rename para renomear a coluna.

.set Texas <| search State has 'Texas' | project-rename tableName=$table

Exemplos

Crie uma tabela chamada RecentErrors no banco de dados que tenha o mesmo esquema que LogsTable e que contenha todos os registros de erro da última hora.

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

Crie uma nova tabela chamada "OldExtents" no banco de dados que tenha uma única coluna, "ExtentId", e contenha as IDs de extensão de todas as extensões no banco de dados que foram criadas há mais de 30 dias. O banco de dados tem uma tabela existente chamada "MyExtents". Como se espera que o conjunto de dados seja maior que 1 GB (mais de ~ 1 milhão de linhas), use o sinalizador distribuído

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Acrescente dados a uma tabela existente chamada "OldExtents" no banco de dados atual, que tenha uma única coluna, "ExtentId", e que contenha as IDs de extensão de todas as extensões no banco de dados que foram criadas há mais de 30 dias. Marque a nova extensão com as marcas tagA e tagB, com base em uma tabela existente denominada "MyExtents".

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Acrescente dados à tabela "OldExtents" no banco de dados atual ou crie a tabela se ela ainda não existir. Marque a nova extensão com ingest-by:myTag. Faça isso somente se a tabela ainda não contiver uma extensão marcada com ingest-by:myTag, com base em uma tabela existente chamada "MyExtents".

.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
   MyExtents
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Substitua os dados da tabela "OldExtents" no banco de dados atual ou crie a tabela se ela ainda não existir. Marque a nova extensão com ingest-by:myTag.

.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Acrescente dados à tabela "OldExtents" no banco de dados atual, enquanto define a hora de criação das extensões para uma data e hora específica no passado.

.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId     

Saída de retorno

Retorna informações sobre as extensões criadas pelo comando .set ou .append.

Saída de exemplo