Sobrescrever dados seletivamente com o Delta Lake

O Delta Lake tem as seguintes opções específicas para sobrescrições seletivas:

Option Caso de uso Tipos de computação suportados Versão mínima
REPLACE WHERE Sobrescreve atómicamente linhas que correspondem a um predicado. Use para substituições com condição fixa de correspondência, como colA = 5 ou int_col IN (1, 2, 3). Todos os tipos de computação. SQL no Databricks Runtime 12.2 LTS e superiores. Python e Scala no Databricks Runtime 9.1 LTS e em versões posteriores.
REPLACE USING Substituição de dados dinâmicos. Substitui todas as linhas que correspondem às colunas especificadas, com base na comparação de igualdade dos valores das colunas, no conjunto de dados fornecido. Todos os tipos de computação. SQL no Databricks Runtime 16.3 e versões posteriores. Python e Scala no Databricks Runtime 18.2 e posteriores.
REPLACE ON Sobrescrever dados dinâmicos por expressão booleana. Utilize para substituições com uma condição de correspondência complexa ou segura em relação a NULL, como s.colA <=> t.colA AND s.colB <=> t.colB. Todos os tipos de computação. SQL no Databricks Runtime 17.1 e superiores. Python e Scala no Databricks Runtime 18.2 e versões superiores.
partitionOverwriteMode Sobrescrita dinâmica de partições antiga, que sobrescreve todos os dados existentes em cada partição na qual a operação de escrita irá confirmar novos dados. Não recomendado para novas cargas de trabalho. SQL suporta apenas computação clássica. Python e Scala suportam todos os tipos de computação. SQL, Python e Scala no Databricks Runtime 11.3 LTS e superiores.

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

Para detalhes sobre o comportamento de substituição de cada opção, veja INSERT. Para uma lista completa das DataFrameWriter opções de Delta Lake, veja 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 vazia, tanto REPLACE USING como REPLACE ON não eliminam dados, no entanto, REPLACE WHERE podem apagar dados.

Important

Se os dados tiverem sido substituídos acidentalmente, você poderá usar restaurar para desfazer a alteração.

REPLACE WHERE

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

Important

Para tirar partido da atualização incremental ao executar REPLACE WHERE, utilize fluxos REPLACE WHERE em Pipelines Declarativos do Spark (SDP). Consulte o processamento em lote com fluxos REPLACE WHERE.

Para substituir atomicamente os eventos de janeiro na tabela de destino, que está 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")
)

Scala

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

SQL

INSERT INTO TABLE events REPLACE WHERE start_date >= '2017-01-01' AND end_date <= '2017-01-31' SELECT * FROM replace_data

Este código de exemplo grava os dados em replace_data, valida que todas as linhas correspondem ao predicado, e executa uma substituição atómica usando a semântica de overwrite. Se algum valor na operação ficar fora do predicado, esta operação falha com um erro por defeito.

No cálculo clássico, para alterar este comportamento para overwrite valores dentro do intervalo de predicados e insert registos fora do intervalo especificado, remova a verificação de restrições definindo spark.databricks.delta.replaceWhere.constraintCheck.enabled para false:

Python

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

Scala

spark.conf.set("spark.databricks.delta.replaceWhere.constraintCheck.enabled", false)

SQL

SET spark.databricks.delta.replaceWhere.constraintCheck.enabled=false

Note

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

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

Comportamento herdado

O Legacy replaceWhere só está disponível em computação clássica. Consulte Visão geral da computação clássica.

Se usar o comportamento legado de replaceWhere, as consultas sobrescrevem dados que correspondem a um predicado apenas sobre colunas de partição. O comando seguinte substituiria atomicamente o mês de janeiro na tabela alvo, que é particionada por date, com os dados em df:

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

Para usar o comportamento legado, defina spark.databricks.delta.replaceWhere.dataColumns.enabled para false:

Python
spark.conf.set("spark.databricks.delta.replaceWhere.dataColumns.enabled", False)
Scala
spark.conf.set("spark.databricks.delta.replaceWhere.dataColumns.enabled", false)
SQL
SET spark.databricks.delta.replaceWhere.dataColumns.enabled=false

Sobrescrita de dados dinâmicos

As substituições dinâmicas de dados substituem seletivamente os dados que correspondam às colunas-chave especificadas ou à expressão booleana, deixando todos os outros dados inalterados. Tabelas particionadas, tabelas não particionadas e tabelas com clustering líquido são todas suportadas.

As sobrescrições dinâmicas de partições são um subconjunto do comportamento dinâmico de sobrescrição de dados. As substituições dinâmicas de partições substituem todos os dados existentes em cada partição na qual a operação de escrita irá gravar novos dados, mantendo todas as outras partições inalteradas. Apenas as tabelas particionadas são suportadas.

REPLACE USING

SQL suportado no Databricks Runtime 16.3 e posterior. Python e Scala suportados no Databricks Runtime 18.2 e superiores. Para diferenças de comportamento nos Databricks Runtime 16.3 a 17.1, veja Comportamento legado.

REPLACE USING permite um comportamento de substituição atómica independente de computação, que funciona em armazéns de dados SQL do Databricks, em computação sem servidor e em computação clássica. REPLACE USING não exige que definas uma configuração de sessão Spark.

REPLACE USING substitui as linhas quando as colunas especificadas se comparam iguais sob igualdade. Todos os outros dados mantêm-se inalterados.

Utilize a substituição de dados dinâmicos com REPLACE USING:

Python

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

Scala

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

SQL

INSERT INTO TABLE events
  REPLACE USING (event_id, start_date)
  SELECT * FROM source_data

Para consultas de origem vazias, REPLACE USING não apaga linhas de tabela.

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

Consulte INSERT na referência da linguagem SQL.

Comportamento herdado

No Databricks Runtime 16.3 a 17.1, REPLACE USING utiliza comportamento legado e só permite sobrescrições dinâmicas de partições, enquanto o Databricks Runtime 17.2 e superiores permite sobrescrições dinâmicas de dados.

Tenha em mente as seguintes restrições e comportamentos relativamente ao comportamento legado de REPLACE USING:

  • Você deve especificar o conjunto completo das colunas de partição da tabela na USING cláusula.
  • Verifique sempre que os dados escritos abrangem apenas as partições esperadas. Uma única linha na partição errada pode sobrepor involuntariamente toda a partição.

REPLACE ON

SQL suportado no Databricks Runtime 17.1 e posteriores. Python e Scala suportados no Databricks Runtime 18.2 e superiores.

REPLACE ON substitui linhas quando satisfazem uma condição definida pelo utilizador, ao contrário de REPLACE USING, que substitui linhas quando as colunas especificadas são consideradas iguais segundo o operador de igualdade. Use REPLACE ON quando precisar de lógica correspondente que REPLACE USING não suporta, como tratar NULL os valores como iguais.

Opcionalmente, utilize 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 a 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")
)

Scala

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

SQL

INSERT INTO TABLE events AS t
  REPLACE ON (s.event_id <=> t.event_id AND s.start_date <=> t.start_date)
  (SELECT * FROM source_data) AS s

Para consultas de origem vazias, REPLACE ON não apaga linhas de tabela.

Partição dinâmica sobreescreve com partitionOverwriteMode (legacy)

Important

Este recurso está no Public Preview.

O Databricks Runtime 11.3 LTS e superior suporta a substituição dinâmica de partições para tabelas particionadas usando o modo de substituição: INSERT OVERWRITE em SQL ou em uma escrita de DataFrame com df.write.mode("overwrite"). Esse tipo de substituição só está disponível para computação clássica, não para armazéns SQL Databricks ou computação sem servidor.

Advertência

Sempre que possível, use INSERT REPLACE USING em vez de sobrescrever INSERT OVERWRITE PARTITION partições e spark.sql.sources.partitionOverwriteMode=dynamic. A sobreposição de partições pode usar dados obsoletos quando há alterações na partição.

Para usar o modo de sobrescrição dinâmica de partições, defina a configuração spark.sql.sources.partitionOverwriteMode da sessão Spark para dynamic. Como alternativa, você pode definir a DataFrameWriter opção partitionOverwriteMode como dynamic. Se presente, a opção específica da consulta substitui o modo definido na configuração da sessão. O valor padrão 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;

Python

(df.write
  .mode("overwrite")
  .option("partitionOverwriteMode", "dynamic")
  .saveAsTable("default.people10m")
)

Scala

df.write
  .mode("overwrite")
  .option("partitionOverwriteMode", "dynamic")
  .saveAsTable("default.people10m")

Tenha em mente as seguintes restrições e comportamentos para partitionOverwriteMode:

  • Não é possível definir overwriteSchema como true.
  • Não é possível especificar ambos partitionOverwriteMode e replaceWhere na mesma DataFrameWriter operação.
  • Se você especificar uma replaceWhere condição usando uma DataFrameWriter opção, o Delta Lake aplicará essa condição para controlar quais dados serão substituídos. Esta opção tem precedência sobre a configuração a nível de sessão partitionOverwriteMode.
  • Verifique sempre que os dados escritos abrangem apenas as partições esperadas. Uma única linha na partição errada pode sobrepor involuntariamente toda a partição.
  • Last updated on