Ingerir da consulta (.set, .append, .set-or-append, .set-or-replace)

  • Artigo

Estes comandos executam uma consulta ou um comando de gestão e ingerem os resultados da consulta numa tabela. A diferença entre estes comandos é a forma como tratam as tabelas e os 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 anexados à tabela O comando falha
.set-or-append Os dados são anexados à tabela A tabela é criada e os dados são ingeridos
.set-or-replace Os dados substituem os dados na tabela A tabela é criada e os dados são ingeridos

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

Nota

Este método de ingestão destina-se a exploração e prototipagem. Não o utilize em cenários de produção ou de volume elevado.

Permissões

Para efetuar diferentes ações numa tabela, são necessárias permissões específicas:

  • Para adicionar linhas a uma tabela existente com o .append comando, precisa de um mínimo de permissões de Ingestor de Tabelas.
  • Para criar uma nova tabela com os vários .set comandos, precisa de um mínimo de permissões de Utilizador da Base de Dados.
  • Para substituir linhas numa tabela existente com o .set-or-replace comando, precisa de um mínimo de permissões de Administração tabela.

Para obter mais informações sobre permissões, veja Controlo de acesso baseado em funções 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 Necessário Descrição
assíncrona string Se especificado, o comando irá devolver e continuar a ingestão em segundo plano. Utilize o devolvido OperationId com o .show operations comando para obter o estado de conclusão da ingestão e os resultados.
tableName string ✔️ O nome da tabela para ingerir dados. O tableName está sempre relacionado com a base de dados em contexto.
propertyName, propertyValue string Uma ou mais propriedades de ingestão suportadas utilizadas para controlar o processo de ingestão.
queryOrCommand string ✔️ O texto de uma consulta ou de um comando de gestão cujos resultados são utilizados como dados para ingerir.

Nota

Apenas .show os comandos de gestão são suportados.

Propriedades de ingestão suportadas

Propriedade Tipo Description
creationTime string O valor datetime, formatado como uma cadeia de ISO8601, para utilizar no momento de criação das extensões de dados ingeridos. Se não for especificado, now() é utilizado. Quando especificado, certifique-se de que a Lookback propriedade na política de intercalação Extensões efetiva da tabela de destino está alinhada com o valor especificado.
extend_schema bool Se true, o comando poderá expandir o esquema da tabela. A predefinição é false. Esta opção aplica-se apenas a .append, .set-or-appende set-or-replace comandos. Esta 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. A predefinição é false. Esta opção aplica-se apenas ao .set-or-replace comando . Esta opção tem precedência sobre a extend_schema propriedade se ambas estiverem definidas. Esta opção requer, pelo menos, permissões de Administração de Tabela.
folder string A pasta a atribuir à tabela. Se a tabela já existir, esta propriedade substitui a pasta da tabela.
ingestIfNotExists string Se especificado, a ingestão falhará se a tabela já tiver dados marcados com uma ingest-by: etiqueta com o mesmo valor. Para obter mais informações, veja ingestão por: etiquetas.
policy_ingestiontime bool Se true, a Política de Tempo de Ingestão será ativada na tabela. A predefinição é true.
tags string Uma cadeia JSON que representa uma lista de etiquetas a associar à extensão criada.
docstring string Uma descrição utilizada para documentar a tabela.
distributed bool Se true, o comando ingere a partir de todos os nós que executam a consulta em paralelo. A predefinição é false. Veja sugestões de desempenho.
persistDetails Um valor booleano que, se especificado, indica que o comando deve manter os resultados detalhados para obtenção pelo comando .show operation details . Predefinições para false. with (persistDetails=true)

Considerações de esquema

  • .set-or-replace preserva o esquema, a menos que uma das propriedades ou extend_schemarecreate_schema ingestão esteja definida como true.
  • .set-or-append e .append os comandos preservam o esquema, a menos que a extend_schema propriedade 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 existem correspondências de nomes de colunas. Certifique-se de que as colunas de esquema do resultado da consulta estão na mesma ordem que a tabela. Caso contrário, os dados serão ingeridos nas colunas erradas.

Atenção

Se o esquema for modificado, ocorre numa transação separada antes da ingestão de dados real. Isto significa que o esquema pode ser modificado mesmo quando existe uma falha ao ingerir os dados.

Sugestões de desempenho

  • A ingestão de dados é uma operação intensiva em recursos que pode afetar atividades simultâneas no cluster, incluindo a execução de consultas. Evite executar demasiados 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, utilize vários comandos de ingestão.
  • Defina o distributed sinalizador 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 utilize este sinalizador quando os resultados da consulta forem pequenos, uma vez que pode gerar desnecessariamente muitas partições horizontais de dados pequenas.

Limitação de carateres

O comando falhará se a consulta gerar um nome de entidade com o $ caráter. Os nomes das entidades têm de estar em conformidade com as regras de nomenclatura, pelo que o $ caráter tem de ser removido para que o comando ingestão seja bem-sucedido.

Por exemplo, na seguinte consulta, o search operador gera uma coluna $table. Para armazenar os resultados da consulta, utilize o nome do projeto para mudar o nome da coluna.

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

Exemplos

Crie uma nova tabela chamada RecentErrors na base de dados com o mesmo esquema LogsTable que e contém todos os registos de erros da última hora.

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

Crie uma nova tabela denominada "OldExtents" na base de dados que tenha uma única coluna, "ExtentId", e contenha os IDs de extensão de todas as extensões na base de dados que foi criada mais de 30 dias antes. A base de dados tem uma tabela existente chamada "MyExtents". Uma vez que se espera que o conjunto de dados seja superior a 1 GB (mais de ~1 milhão de linhas), utilize o sinalizador distribuído

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

Acrescente dados a uma tabela existente denominada "OldExtents" na base de dados atual que tem uma única coluna, "ExtentId", e contém os IDs de extensão de todas as extensões na base de dados que foram criadas mais de 30 dias antes. Marque a nova extensão com etiquetas tagA e tagB, com base numa tabela existente chamada "MyExtents".

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

Acrescente dados à tabela "OldExtents" na base de dados atual ou crie a tabela se ainda não existir. Marque a nova extensão com ingest-by:myTag. Faça-o apenas se a tabela ainda não contiver uma extensão etiquetada com ingest-by:myTag, com base numa tabela existente denominada "MyExtents".

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

Substitua os dados na tabela "OldExtents" na base de dados atual ou crie a tabela se 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" na base de dados atual, ao mesmo tempo que define a hora de criação da extensão criada para 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

Devolver saída

Devolve informações sobre as extensões criadas devido ao .set comando ou .append .

Saída de exemplo

ExtentId OriginalSize Extensão Comprimir Indexar RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10