Compartilhar via

Comando .update table

  • Artigo

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

O .update table comando executa atualizações de dados em uma tabela especificada excluindo e anexando registros atomicamente.

Aviso

Este comando é irrecuperável.

Observação

Quando você executa o .update table comando em uma tabela que é a origem de uma política de atualização, o comando aciona .update table essas políticas de atualização para as quais a tabela que está sendo modificada é a origem da política de atualização.

Você pode excluir até 5 milhões de registros em um único comando.

Permissões

Você deve ter pelo menos permissões de Administrador de Tabela para executar este comando.

Sintaxe

Observação

A sintaxe simplificada , que estava disponível durante a versão prévia, foi preterida.

Saiba mais sobre as convenções de sintaxe.

.update[async] table TableName delete DeleteIdentifier append AppendIdentifier [ ( with propertyName = propertyValue ] )<|
letDeleteIdentifier= ExcluirPredicado;
letIdentificador de Apêndice= AppendPredicate;

Parâmetros

Nome Digitar Obrigatória Descrição
async string Se especificado, indica que o comando é executado no modo assíncrono.
TableName string ✔️ O nome da tabela a ser atualizada.
DeleteIdentifier string ✔️ O nome do identificador usado para especificar o predicado de exclusão aplicado à tabela atualizada.
ExcluirPredicado string ✔️ O texto de uma consulta cujos resultados são usados como dados a serem excluídos. O predicado tem as mesmas limitações que o predicado de exclusão reversível.
Identificador de Apêndice string ✔️ O nome do identificador usado para especificar o predicado de acréscimo aplicado à tabela atualizada.
AppendPredicate string ✔️ O texto de uma consulta cujos resultados são usados como dados a serem acrescentados.

Importante

  • Os predicados de exclusão e acréscimo não podem usar entidades remotas, entidades entre bancos de dados e entre clusters. Os predicados não podem fazer referência a uma tabela externa nem usar o externaldata operador.
  • Espera-se que as consultas de acréscimo e exclusão produzam resultados determinísticos. Consultas não determinísticas podem levar a resultados inesperados. Uma consulta é determinística se e somente se retornaria os mesmos dados se executada várias vezes.
  • As consultas podem ser executadas mais de uma vez na update execução. Se os resultados intermediários da consulta forem inconsistentes, o comando update poderá produzir resultados inesperados.

Propriedades com suporte

Nome Tipo Descrição
e se bool Se true, retorna o número de registros que serão anexados/excluídos em cada fragmento, sem anexar/excluir nenhum registro. O padrão é false.
Distribuído 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.

Importante

É recomendável executar no whatif modo antes de executar a atualização para validar os predicados antes de excluir ou acrescentar dados.

Devoluções

O resultado do comando é uma tabela em que cada registro representa uma extensão que foi criada com novos dados ou teve registros excluídos.

Nome Tipo Descrição
Tabela string A tabela na qual a extensão foi criada ou excluída.
Ação string Crie ou Exclua dependendo da ação executada na extensão.
ExtentId guid O identificador exclusivo para a extensão criada ou excluída pelo comando.
RowCount long O número de linhas criadas ou excluídas na extensão especificada pelo comando.

Escolher entre .update table e exibições materializadas

Há cenários em que você pode usar o .update table comando ou uma exibição materializada para atingir o mesmo objetivo em uma tabela. Por exemplo, uma exibição materializada pode ser usada para manter a versão mais recente de cada registro ou uma atualização pode ser usada para atualizar registros quando uma nova versão estiver disponível.

Use as seguintes diretrizes para decidir qual método usar:

  • Se o padrão de atualização não for compatível com exibições materializadas, use o comando update.
  • Se a tabela de origem tiver um alto volume de ingestão, mas apenas algumas atualizações, o uso do comando update poderá ter mais desempenho e consumir menos cache ou armazenamento do que as exibições materializadas. Isso ocorre porque as exibições materializadas precisam reprocessar todos os dados ingeridos, o que é menos eficiente do que identificar os registros individuais a serem atualizados com base nos predicados de acréscimo ou exclusão.
  • As exibições materializadas são uma solução totalmente gerenciada. A visão materializada é definida uma vez e a materialização ocorre em segundo plano pelo sistema. O comando de atualização requer um processo orquestrado (por exemplo, Azure Data Factory, Aplicativos Lógicos, Power Automate e outros) que executa explicitamente o comando de atualização sempre que há atualizações. Se as exibições materializadas funcionarem o suficiente para seu caso de uso, o uso de exibições materializadas exigirá menos gerenciamento e manutenção.

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. Recomendamos que você evite as seguintes ações com uso intensivo de recursos: executar muitos .update comandos ao mesmo tempo e uso intensivo da propriedade distribuída.
  • Limite os dados de acréscimo a menos de 1 GB por operação. Se necessário, use vários comandos de atualização.
  • Defina o distributed sinalizador como true somente se a quantidade de dados que está sendo produzida pela consulta for grande, exceder 1 GB e não exigir serialização: 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.

Exemplos

Para os exemplos, vamos usar a seguinte tabela:

.set-or-replace Employees <|
  range i from 1 to 100 step 1
  | project Id=i
  | extend Code = tostring(dynamic(["Customer", "Employee"])[Id %2])
  | extend Color = tostring(dynamic(["Red", "Blue", "Gray"])[Id %3])

Este comando cria uma tabela com 100 registros começando com:

ID Código Color
1 Employee Azul
2 Customer Cinza
3 Employee Vermelho
4 Customer Azul
5 Employee Cinza
6 Customer Vermelho
6 Employee Azul

Atualizar uma única coluna em uma linha

O exemplo a seguir atualiza uma única coluna em uma única linha:

.update table Employees delete D append A with(whatif=true) <|
    let D = Employees
      | where Id==3;
    let A = Employees
      | where Id==3
      | extend Color="Orange";

Observe que whatif está definido como true. Após essa consulta, a tabela permanece inalterada, mas o comando retorna que haveria uma extensão com uma linha excluída e uma nova extensão com uma linha.

O comando a seguir realmente executa a atualização:

.update table Employees delete D append A <|
    let D = Employees
      | where Id==3;
    let A = Employees
      | where Id==3
      | extend Color="Orange";

Atualizar uma única coluna em várias linhas

O exemplo a seguir é atualizado em uma única coluna Color para o valor de Green nas linhas que têm o valor blue.

.update table Employees delete D append A <|
    let D = Employees
        | where Code=="Employee"
        | where Color=="Blue";
    let A = D
      | extend Color="Green";

Aqui, reutilizamos o identificador de exclusão na definição do predicado de acréscimo.

Atualizar várias colunas em várias linhas

O exemplo a seguir atualiza várias colunas em todas as linhas com a cor cinza.

.update table Employees delete D append A <|
    let D = Employees
      | where Color=="Gray";
    let A = D
      | extend Code=strcat("ex-", Code)
      | extend Color="";

Atualizar linhas usando outra tabela (valores de referência)

Neste exemplo, a primeira etapa é criar a seguinte tabela de mapeamento:

.set-or-replace ColorMapping <|
  datatable(OldColor:string, NewColor:string)[
    "Red", "Pink",
    "Blue", "Purple",
    "Gray", "LightGray",
    "Orange", "Yellow",
    "Green", "AppleGreen"
  ]

Essa tabela de mapeamento é usada para atualizar algumas cores na tabela original:

.update table Employees delete D append A <|
  let D = Employees
    | where Code=="Customer";
  let A = D
    | lookup ColorMapping on $left.Color==$right.OldColor
    | project Id, Code, Color=NewColor

Atualizar linhas com uma tabela de dados

Às vezes, os valores a serem atualizados são conhecidos sem serem armazenados em uma tabela, e o operador datatable pode ser útil:

.update table Employees delete D append A <|
  let A = datatable(Id:long, Code:string, Color:string)[
    1, "Customer", "Purple",
    2, "Customer", "Magenta",
    3, "Customer", "Turquoise",
  ];
  let D = Employees
      | join kind=leftsemi A on Id
      | where true;

Atualizar linhas com uma tabela de preparo

Um padrão popular é primeiro colocar os dados em uma tabela de preparo antes de atualizar a tabela principal.

O primeiro comando cria uma tabela de preparação:

.set-or-replace MyStagingTable <|
    range i from 70 to 130 step 5
    | project Id=i
    | extend Code = tostring(dynamic(["Customer", "Employee"])[Id %2])
    | extend Color = tostring(dynamic(["Red", "Blue", "Gray"])[Id %3])

O próximo comando atualiza a tabela principal com os dados na tabela de preparação:

.update table Employees delete D append A <|
    let A = MyStagingTable;
    let D = Employees
        | join kind=leftsemi MyStagingTable on Id
        | where true;

Alguns registros na tabela de preparo não existiam na tabela principal (ou seja, tinham Id>100), mas ainda eram inseridos na tabela principal (comportamento de upsert).

Padrão

O primeiro comando cria uma tabela com chaves compostas:

.set-or-replace VersionedArticle <|
  datatable(ArticleId:string, Version:int, Detail:string)[
    "A", 1, "Early version",
    "B", 1, "News about mobiles",
    "C", 1, "Opinion article",
    "B", 2, "Revision about brand X",
    "B", 3, "Revision about brand Y",
    "C", 2, "Fact check"
  ]

O próximo comando atualiza um registro específico usando a sintaxe expandida:

.update table VersionedArticle delete D append A <|
  let D = VersionedArticle
    | where ArticleId=="B"
    | where Version==3;
  let A = VersionedArticle
    | where ArticleId=="B"
    | where Version==3
    | extend Detail = "Revision about brand Z";

Conteúdo relacionado