Compartilhar via

Comando .update table (versão prévia)

  • Artigo

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

Aviso

Esse 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 .update table comando dispara 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 Administração tabela para executar esse comando.

Syntax

Há duas opções de sintaxe, sintaxe simplificada e sintaxe expandida.

Saiba mais sobre as convenções de sintaxe.

Sintaxe expandida

A sintaxe expandida oferece a flexibilidade de definir uma consulta para excluir linhas e uma consulta diferente para acrescentar linhas:

.updatetableTablenamedeleteDeleteIdentifierappendAppendIdentifier [with(propertyName=propertyValue)] <|
letDeleteIdentifier=DeletePredicate;
letAppendIdentifier=AppendPredicate;

Parâmetros para sintaxe expandida

Nome Tipo Obrigatório Descrição
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.
DeletePredicate string ✔️ O texto de uma consulta cujos resultados são usados como dados para excluir. O predicado delete deve incluir pelo menos um where operador e só pode usar os seguintes operadores: extend, where, projectjoin e lookup.
AppendIdentifier 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 para acrescentar.

Importante

  • Os predicados delete e append não podem usar entidades remotas, entre bancos de dados e entidades entre clusters. Os predicados não podem referenciar 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 retornar os mesmos dados se executada várias vezes.
  • As consultas podem ser executadas mais de uma vez dentro da update execução. Se os resultados da consulta intermediária forem inconsistentes, o comando update poderá produzir resultados inesperados.

Sintaxe simplificada

A sintaxe simplificada requer uma consulta acréscimo, bem como uma chave. A chave é uma coluna na tabela que representa valores exclusivos na tabela. Essa coluna é usada para definir quais linhas devem ser excluídas da tabela. Uma junção é executada entre a tabela original e a consulta de acréscimo, para identificar linhas que concordam com seu valor em relação a essa coluna.

.updatetableTableName em IDColumnName [with(propertyName=propertyValue)] <|
appendQuery

Parâmetros para sintaxe simplificada

Nome Tipo Obrigatório Descrição
TableName string ✔️ O nome da tabela a ser atualizada.
IDColumnName string ✔️ O nome da coluna que identifica linhas. A coluna deve estar presente na tabela e appendQuery.
appendQuery string ✔️ O texto de uma consulta ou um comando de gerenciamento cujos resultados são usados como dados para acrescentar. O esquema da consulta deve ser o mesmo que o esquema da tabela.

Importante

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

Propriedades com suporte

Nome Tipo Descrição
Whatif bool Se true, retornará o número de registros que serão acrescentados/excluídos em cada fragmento, sem acrescentar/excluir nenhum registro. O padrão é false.

Importante

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

Retornos

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 que foi 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 exibições materializadas e

Há cenários em que você pode usar o .update table comando ou uma exibição materializada para atingir a mesma meta 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 de atualização poderá ser mais eficaz 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.
  • Exibições materializadas são uma solução totalmente gerenciada. A exibiçã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 bem o suficiente para seu caso de uso, o uso de exibições materializadas exigirá menos gerenciamento e manutenção.

Exemplos – Sintaxe simplificada

Os exemplos a seguir usam a sintaxe simplificada.

Exemplo geral

A tabela a seguir é criada.

.set-or-replace People <|
datatable(Name:string, Address:string)[
  "Alice", "221B Baker street",
  "Bob", "1600 Pennsylvania Avenue",
  "Carl", "11 Wall Street New York"
]
Nome Endereço
Alice Rua Baker, 221B
Roberto Avenida Pensilvânia, 1600
Carl 11 Wall Street Nova York

Em seguida, o seguinte comando de atualização é executado:

.update table People on Name <|
  datatable(Name:string, Address:string)[
  "Alice", "2 Macquarie Street",
  "Diana", "350 Fifth Avenue" ]

Em que appendQuery produz o seguinte conjunto de resultados:

Nome Endereço
Alice Rua Macquarie 2
Diana 350 Quinta Avenida

Como atualizamos naName coluna, a linha Alice será excluída e a tabela após a atualização terá esta aparência:

Nome Endereço
Alice Rua Macquarie 2
Roberto Avenida Pensilvânia, 1600
Carl 11 Wall Street Nova York
Diana 350 Quinta Avenida

Observe que Diana não foi encontrada na tabela original. Isso é válido e nenhuma linha correspondente foi excluída.

Da mesma forma, se houvesse várias linhas com o nome Alice na tabela original, todas elas teriam sido excluídas e substituídas pela única linha Alice que temos no final.

Exemplo de tabela

Os próximos exemplos são baseados na tabela a seguir:

.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 Cliente Cinza
3 Employee Vermelho
4 Cliente Azul
5 Employee Cinza
6 Cliente Vermelho
6 Employee Azul

Atualizar uma única coluna em uma linha

O exemplo a seguir usa a sintaxe simplificada para atualizar uma única coluna em uma única linha que corresponde ao predicado de acréscimo:

.update table Employees on Id with(whatif=true) <|
    Employees
    | where Id==3
    | extend Color="Orange"

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

O seguinte comando realmente executa a atualização:

.update table Employees on Id <|
  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 Verde nessas linhas que correspondem ao predicado de acréscimo.

.update table Employees on Id <|
  Employees
  | where Code=="Employee"
  | where Color=="Blue"
  | extend Color="Green"

Atualizar várias colunas em várias linhas

O exemplo a seguir atualiza várias colunas em todas as linhas que correspondem ao predicado de acréscimo.

.update table Employees on Id <|
  Employees
  | where Color=="Gray"
  | extend Code=strcat("ex-", Code)
  | extend Color=""

Atualizar linhas usando outra tabela

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 com base no predicado de acréscimo e na "Nova Cor" correspondente:

.update table Employees on Id <|
  Employees
  | where Code=="Customer"
  | lookup ColorMapping on $left.Color==$right.OldColor
  | project Id, Code, Color=NewColor

Atualizar linhas com uma tabela de preparo

Um padrão popular é primeiro obter dados em uma tabela de preparo antes de atualizar a tabela main.

O primeiro comando cria uma tabela de preparo:

.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 main com os dados na tabela de preparo:

.update table Employees on Id <|
  MyStagingTable

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

Exemplos – Sintaxe expandida

Os exemplos a seguir usam a sintaxe Expandida.

Chave composta

A sintaxe simplificada pressupõe que uma única coluna possa corresponder a linhas no appendQuery para inferir linhas a serem excluídas. Mais de uma coluna pode ser usada, por exemplo, usando chaves compostas.

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";

Controle completo

No exemplo a seguir, todas as linhas com CodeEmployee são excluídas e as linhas com CodeEmployeeeColor purple são acrescentadas. Mais linhas são excluídas do que inseridas.

.update table Employees delete D append A <|
  let D = Employees
    | where Code=="Employee";
  let A = Employees
    | where Code=="Employee"
    | where Color=="Purple"
    | extend Code="Corporate"
    | extend Color="Mauve";

Esse tipo de ação só é possível usando a sintaxe expandida, que controla independentemente as operações de exclusão e acréscimo.

Conteúdo relacionado