Compartilhar via

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

  • Artigo

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.

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 um comando de ingestão de consulta, consulte cancel operation.

Observação

A ingestão da consulta é uma ingestão direta. Como tal, não inclui novas tentativas automáticas. As repetições automáticas estão disponíveis ao ingerir por meio do serviço de gerenciamento de dados. Use o documento de visão geral da ingestão para decidir qual é a opção de ingestão mais adequada para seu cenário.

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

Nome Digitar Obrigatória Descrição
async string Se especificado, o comando retorna imediatamente e continua a ingestão em segundo plano. Use o comando returned OperationId with para recuperar o status e os .show operations resultados da conclusão da ingestão.
tableName string ✔️ O nome da tabela na qual os dados devem ser assimilados. O tableName está sempre relacionado ao banco de dados no contexto.
propertyName, propertyValue string Uma ou mais propriedades de assimilação com suporte usadas para controlar o processo de assimilação.
queryOrCommand string ✔️ O texto de uma consulta ou de um comando de gerenciamento cujos resultados são usados como dados a serem ingeridos. Somente .show comandos de gerenciamento são suportados.

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

Propriedade Type Descrição
distributed bool Se true, o comando ingere de todos os nós que executam a consulta em paralelo. O padrão é false. Veja dicas de desempenho.
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 especificado, será usado now(). 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 pode 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 administrador de tabela.
recreate_schema bool Se true, o comando pode 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 administrador 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: tag 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á ativada na tabela. O padrão é true.
tags string Uma cadeia de caracteres JSON que representa uma lista de tags a serem associadas à extensão criada.
docstring string Uma descrição usada para documentar a tabela.
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 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.

Cuidado

Se o esquema for modificado, isso 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 na ingestão dos dados.

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

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