Pular para o conteúdo principal
Última atualização em

Substituir seletivamente os dados com o Delta Lake

O Delta Lake oferece as seguintes opções distintas para sobrescritas seletivas:

Opção

Caso de uso

Tipos compute suportados

Versão mínima

REPLACE WHERE

Sobrescrever atomicamente as linhas que correspondem a um predicado. Use para substituições com uma condição de correspondência fixa, como colA = 5 ou int_col IN (1, 2, 3).

Todos os tipos compute .

SQL no Databricks Runtime 12.2 LTS e versões superiores. Python e Scala no Databricks Runtime 9.1 LTS e versões superiores.

REPLACE USING

Sobrescrita dinâmica de dados. Substitui todas as linhas que correspondem às colunas especificadas, com base na comparação da igualdade dos valores das colunas, no conjunto de dados fornecido.

Todos os tipos compute .

SQL no Databricks Runtime 16.3 e versões superiores. Python e Scala no Databricks Runtime 18.2 e versões superiores.

REPLACE ON

Sobrescrita dinâmica de dados por expressão booleana. Use para substituições com uma condição de correspondência complexa ou segura para NULL, como s.colA <=> t.colA AND s.colB <=> t.colB.

Todos os tipos compute .

SQL no Databricks Runtime 17.1 e versões superiores. Python e Scala no Databricks Runtime 18.2 e versões superiores.

partitionOverwriteMode

Sobrescrita dinâmica de partições legada, que sobrescreve todos os dados existentes em cada partição para a qual a gravação irá commit novos dados. Não recomendado para novas cargas de trabalho.

SQL suporta apenas compute clássica. Python e Scala suportam todos os tipos compute .

SQL, Python e Scala no Databricks Runtime 11.3 LTS e versões superiores.

Para a maioria dos casos de uso, a Databricks recomenda o uso de REPLACE USING ou REPLACE WHERE. Use REPLACE ON somente se o seu caso de uso exigir condições de correspondência complexas ou seguras contra NULL.

Para detalhes sobre o comportamento de substituição de cada opção, consulte INSERT. Para uma lista completa das opções Delta Lake DataFrameWriter , consulte Delta Lake e Apache Iceberg.

Em Scala e Python, replaceOn e replaceUsing não podem ser usados em combinação com replaceWhere, partitionOverwriteMode ou overwriteSchema.

Para consultas de origem vazias, tanto REPLACE USING quanto REPLACE ON não excluem dados, no entanto, REPLACE WHERE pode excluir dados.

importante

Se os dados tiverem sido sobrescritos acidentalmente, você poderá usar a restauração para desfazer a alteração.

REPLACE WHERE​

Você pode sobrescrever seletivamente apenas os dados que correspondem a uma expressão arbitrária com REPLACE WHERE.

info

Beta

Para aproveitar a refresh incremental ao executar REPLACE WHERE, use fluxos REPLACE WHERE no pipeline declarativo Spark (SDP). Veja o processamento de lotes com fluxos REPLACE WHERE.

Para substituir atomicamente os eventos de janeiro na tabela de destino, que é particionada por start_date, pelos dados em replace_data:

Python
(replace_data.write
  .mode("overwrite")
  .option("replaceWhere", "start_date >= '2017-01-01' AND end_date <= '2017-01-31'")
  .saveAsTable("events")
)

Este código de exemplo grava os dados em replace_data, valida se todas as linhas correspondem ao predicado e realiza uma substituição atômica usando a semântica overwrite . Se algum valor nas operações estiver fora do predicado, esta operação falhará com um erro por default.

Na compute clássica, para alterar esse comportamento para valores overwrite dentro do intervalo do predicado e registros insert fora do intervalo especificado, remova a verificação de restrição definindo spark.databricks.delta.replaceWhere.constraintCheck.enabled como false:

Python
spark.conf.set("spark.databricks.delta.replaceWhere.constraintCheck.enabled", False)
nota

REPLACE WHERE aceita um boolean_expression com algumas restrições. Consulte INSERT na referência da linguagem SQL.

Para consultas de origem vazias, REPLACE WHERE pode excluir linhas da tabela.

Comportamento legado​

O legado replaceWhere está disponível apenas em compute clássica. Consulte a Visão geral compute clássica.

Se você usar o comportamento legado de replaceWhere, as consultas sobrescreverão os dados que correspondem a um predicado apenas nas colunas de partição. O seguinte comando substituiria atomicamente o mês de janeiro na tabela de destino, que está particionada por date, pelos dados em df:

Python
(df.write
  .mode("overwrite")
  .option("replaceWhere", "birthDate >= '2017-01-01' AND birthDate <= '2017-01-31'")
  .saveAsTable("people10m")
)

Para usar o comportamento antigo, defina spark.databricks.delta.replaceWhere.dataColumns.enabled como false:

Python
spark.conf.set("spark.databricks.delta.replaceWhere.dataColumns.enabled", False)

Sobrescrita dinâmica de dados​

A sobrescrita dinâmica de dados substitui seletivamente os dados que correspondem às colunas key ou à expressão booleana especificadas, deixando todos os outros dados inalterados. Tabelas particionadas, tabelas não particionadas e tabelas com clustering líquido são todas suportadas.

A sobrescrita dinâmica de partições é um subconjunto do comportamento de sobrescrita dinâmica de dados. A sobrescrita dinâmica de partições substitui todos os dados existentes em cada partição para a qual a gravação irá commit novos dados, deixando todas as outras partições inalteradas. Somente tabelas particionadas são suportadas.

REPLACE USING​

SQL é suportado no Databricks Runtime 16.3 e versões superiores. Python e Scala são suportados no Databricks Runtime 18.2 e versões superiores. Para diferenças de comportamento entre o Databricks Runtime 16.3 e o 17.1, consulte Comportamento Legado.

REPLACE USING Permite um comportamento de sobrescrita atômica e independente de compute , que funciona em data warehouses Databricks SQL , compute serverless e compute clássica. REPLACE USING não exige que você defina uma configuração de sessão Spark.

REPLACE USING Substitui as linhas quando as colunas especificadas são iguais em relação à igualdade. Todos os outros dados permanecem inalterados.

Use a sobrescrita de dados dinâmicos com REPLACE USING:

Python
(sourceDataDF.write
  .mode("overwrite")
  .option("replaceUsing", "event_id, start_date")
  .saveAsTable("events")
)

Para consultas de origem vazias, REPLACE USING não exclui nenhuma linha da tabela.

Para condições de correspondência complexas ou seguras contra valores NULL, use REPLACE ON em vez disso. Veja REPLACE ON.

Consulte INSERT na referência da linguagem SQL.

Comportamento legado​

No Databricks Runtime 16.3 a 17.1, REPLACE USING usa comportamento legado e permite apenas sobrescritas dinâmicas de partições, enquanto Databricks Runtime 17.2 e versões superiores permitem sobrescritas dinâmicas de dados.

Tenha em mente as seguintes restrições e comportamentos para o comportamento legado REPLACE USING :

  • Você deve especificar o conjunto completo das colunas de partição da tabela na cláusula USING.
  • Sempre valide se os dados gravados tocam somente nas partições esperadas. Uma única linha na partição errada pode, sem querer, sobrescrever a partição inteira.

REPLACE ON​

SQL é suportado no Databricks Runtime 17.1 e versões superiores. Python e Scala são suportados no Databricks Runtime 18.2 e versões superiores.

REPLACE ON substitui linhas quando elas correspondem a uma condição definida pelo usuário, diferentemente de REPLACE USING, que substitui linhas quando as colunas especificadas são iguais sob a condição de igualdade. Use REPLACE ON quando você precisar de lógica de correspondência que REPLACE USING não suporta, como tratar valores NULL como iguais.

Opcionalmente, use a opção targetAlias para especificar um alias para a tabela de destino e as APIs .as() ou .alias() para especificar um alias para os dados de origem.

Para sintaxe SQL, veja INSERT.

Python
(sourceDataDF.alias("s")
  .write
  .mode("overwrite")
  .option("targetAlias", "t")
  .option("replaceOn", "s.event_id <=> t.event_id AND s.start_date <=> t.start_date")
  .saveAsTable("events")
)

Para consultas de origem vazias, REPLACE ON não exclui nenhuma linha da tabela.

Sobrescritas de partição dinâmica com partitionOverwriteMode (legado)​

info

Visualização

Esse recurso está em Public Preview.

Databricks Runtime 11.3 O LTS e acima suportam sobrescritas dinâmicas de partições para tabelas particionadas usando o modo de sobrescrita: INSERT OVERWRITE em SQL ou uma gravação DataFrame com df.write.mode("overwrite"). Este tipo de substituição está disponível apenas para armazéns clássicos compute, não para armazéns Databricks SQL ou serverless compute.

atenção

Quando possível, use INSERT REPLACE USING em vez de sobrescrever a partição INSERT OVERWRITE PARTITION e spark.sql.sources.partitionOverwriteMode=dynamic. A sobrescrita de partições pode usar dados obsoletos quando as configurações de particionamento são alteradas.

Para usar o modo de sobrescrita de partição dinâmica, defina a configuração da sessão Spark de spark.sql.sources.partitionOverwriteMode para dynamic. Alternativamente, você pode definir a opção DataFrameWriter partitionOverwriteMode para dynamic. Caso esteja presente, a opção específica da consulta substitui o modo definido na configuração da sessão. O valor default para spark.sql.sources.partitionOverwriteMode é static.

O exemplo a seguir usa partitionOverwriteMode:

SQL
SET spark.sql.sources.partitionOverwriteMode=dynamic;
INSERT OVERWRITE TABLE default.people10m SELECT * FROM morePeople;

Lembre-se das seguintes restrições e comportamentos para partitionOverwriteMode:

  • Você não pode definir overwriteSchema como true.
  • Não é possível especificar partitionOverwriteMode e replaceWhere nas mesmas operações DataFrameWriter.
  • Se você especificar uma condição replaceWhere usando uma opção DataFrameWriter, o Delta Lake aplicará essa condição para controlar quais dados serão sobrescritos. Essa opção tem precedência sobre a configuração partitionOverwriteMode em nível de sessão.
  • Sempre valide se os dados gravados tocam somente nas partições esperadas. Uma única linha na partição errada pode, sem querer, sobrescrever a partição inteira.
Nesta página