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

  • Artigo

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.

Comando Se a tabela existir Se a tabela não existir
.set O comando falha A tabela é criada e os dados são ingeridos
.append Os dados são acrescentados à tabela O comando falha
.set-or-append Os dados são acrescentados à tabela A tabela é criada e os dados são ingeridos
.set-or-replace Os dados substituem os dados da tabela A tabela é criada e os dados são ingeridos

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

Observação

Esse método de ingestão destina-se à exploração e à criação de protótipos. Não o use em cenários de produção ou de alto volume.

Permissões

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

  • Para adicionar linhas a uma tabela existente usando o .append comando , você precisa de um mínimo de permissões de Ingestor de Tabela.
  • 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 Administração de Tabela.

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

Syntax

(.set.append.set-or-append | | | .set-or-replace) [async] tableName [with(propertyName= propertyValue [, ...]] <|)queryOrCommand

Saiba mais sobre as convenções de sintaxe.

Parâmetros

Nome Tipo Obrigatório Descrição
async string Se especificado, o comando retornará e continuará a ingestão em segundo plano. Use o retornado OperationId com o .show operations comando para recuperar a conclusão da ingestão status e os resultados.
tableName string ✔️ O nome da tabela na qual ingerir dados. O tableName está sempre relacionado ao banco de dados no contexto.
propertyName, propertyValue string Uma ou mais propriedades de ingestão com suporte usadas para controlar o processo de ingestão.
queryOrCommand string ✔️ O texto de uma consulta ou um comando de gerenciamento cujos resultados são usados como dados para ingerir.

Observação

Há suporte apenas .show para comandos de gerenciamento.

Propriedades de ingestão compatíveis

Propriedade Tipo Descrição
creationTime string O valor de datetime, formatado como uma cadeia de caracteres ISO8601, a ser usado na hora de criação das extensões dos dados ingeridos. Se não for especificado, now() será usado. Quando especificado, verifique se a propriedade Lookback na Política de mesclagem de extensões efetivas da tabela de destino está alinhada com o valor especificado.
extend_schema bool Se true, o comando poderá estender o esquema da tabela. O padrão é false. Essa opção se aplica somente aos comandos .append, .set-or-append e set-or-replace. Essa opção requer pelo menos permissões de Administração de Tabela.
recreate_schema bool Se true, o comando poderá recriar o esquema da tabela. O padrão é false. Essa opção se aplica somente ao comando .set-or-replace. Essa opção terá precedência sobre a extend_schema propriedade se ambas estiverem definidas. Essa opção requer pelo menos permissões de Administração de Tabela.
folder string A pasta a ser atribuída à tabela. Se a tabela já existir, essa propriedade substituirá a pasta da tabela.
ingestIfNotExists string Se especificado, a ingestão falhará se a tabela já tiver dados marcados com uma ingest-by: marca com o mesmo valor. Para obter mais informações, veja ingest-by: tags.
policy_ingestiontime bool Se true, a Política de Tempo de Ingestão será habilitada na tabela. O padrão é true.
tags string Uma cadeia de caracteres JSON que representa uma lista de marcas a serem associadas à extensão criada.
docstring string Uma descrição usada para documentar a tabela.
distributed bool Se true, o comando ingerirá de todos os nós executando a consulta em paralelo. O padrão é false. Confira dicas de desempenho.
persistDetails Um valor booliano que, se especificado, indica que o comando deve persistir os resultados detalhados para recuperação pelo comando .show operation details . Assume o padrão de false. with (persistDetails=true)

Considerações sobre esquema

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

Cuidado

Se o esquema for modificado, ele ocorrerá em uma transação separada antes da ingestão de dados real. Isso significa que o esquema pode ser modificado mesmo quando há uma falha ao ingerir os dados.

Dicas de desempenho

  • A ingestão de dados é uma operação que faz uso intensivo de recursos, podendo afetar atividades simultâneas no cluster, 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.
  • Defina o distributed sinalizador true como se a quantidade de dados que estão sendo 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.

Limitação de caractere

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 tenha êxito.

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 tabela chamada "OldExtents" no banco de dados, 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. O banco de dados tem uma tabela existente chamada "MyExtents". Como o conjunto de dados deve ser maior que 1 GB (mais de aproximadamente 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, definindo a hora de criação de extensões criadas com um datetime específico 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

ExtentId OriginalSize ExtentSize CompressedSize IndexSize RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10