Classe DataFrameWriterV2

Interface utilizada para gravar um DataFrame em armazenamento externo usando a API v2.

Para a maioria dos casos de uso com tabelas Databricks e Delta Lake, o DataFrameWriterV2 oferece opções mais poderosas e flexíveis do que o DataFrameWriter original:

• Melhor suporte para propriedades de tabela
• Controle mais preciso sobre o particionamento
• Capacidades de sobrescrita condicional
• Suporte para clustering
• Semântica mais clara para operações de criação ou substituição

Compatível com Spark Connect

Sintaxe

Use DataFrame.writeTo(table) para acessar esta interface.

Métodos

Método	Descrição
using(provider)	Especifica um provedor para a fonte de dados de saída subjacente.
option(key, value)	Adicionar uma opção de escrita. Por exemplo, para criar uma tabela de gerenciamento: df.writeTo("test").using("delta").option("path", "s3://test").createOrReplace().
options(**options)	Adicionar opções de escrita.
tableProperty(property, value)	Adicionar propriedade à tabela. Por exemplo, use tableProperty("location", "s3://test") para criar uma tabela EXTERNA (não gerenciada).
partitionedBy(col, *cols)	Particione a tabela de saída criada por create, createOrReplace ou replace usando as colunas ou transformações fornecidas.
clusterBy(col, *cols)	Agrupa os dados pelas colunas fornecidas para otimizar o desempenho da consulta.
create()	Crie uma nova tabela a partir do conteúdo do quadro de dados.
replace()	Substitua uma tabela existente pelo conteúdo do quadro de dados.
createOrReplace()	Crie uma nova tabela ou substitua uma tabela existente pelo conteúdo do quadro de dados.
append()	Anexe o conteúdo do quadro de dados à tabela de saída.
overwrite(condition)	Substitua as linhas que correspondem à condição de filtro fornecida pelo conteúdo do quadro de dados na tabela de saída.
overwritePartitions()	Sobrescreva todas as partições para as quais o quadro de dados contenha pelo menos uma linha com o conteúdo do quadro de dados na tabela de saída.

Exemplos

Criando uma nova tabela

Python

# Create a new table with DataFrame contents
df = spark.createDataFrame([{"name": "Alice", "age": 30}])
df.writeTo("my_table").create()

# Create with a specific provider
df.writeTo("my_table").using("parquet").create()

Particionamento de dados

Python

# Partition by single column
df.writeTo("my_table") \
    .partitionedBy("year") \
    .create()

# Partition by multiple columns
df.writeTo("my_table") \
    .partitionedBy("year", "month") \
    .create()

# Partition using transform functions
from pyspark.sql.functions import years, months, days

df.writeTo("my_table") \
    .partitionedBy(years("date"), months("date")) \
    .create()

Definindo propriedades da tabela

Python

# Add table properties
df.writeTo("my_table") \
    .tableProperty("key1", "value1") \
    .tableProperty("key2", "value2") \
    .create()

Usando opções

Python

# Add write options
df.writeTo("my_table") \
    .option("compression", "snappy") \
    .option("maxRecordsPerFile", "10000") \
    .create()

# Add multiple options at once
df.writeTo("my_table") \
    .options(compression="snappy", maxRecordsPerFile="10000") \
    .create()

dados de agrupamento

Python

# Cluster by columns for query optimization
df.writeTo("my_table") \
    .clusterBy("user_id", "timestamp") \
    .create()

Substituir operações

Python

# Replace existing table
df.writeTo("my_table") \
    .using("parquet") \
    .replace()

# Create or replace (safe operation)
df.writeTo("my_table") \
    .using("parquet") \
    .createOrReplace()

Operações de anexo

Python

# Append to existing table
df.writeTo("my_table").append()

Operações de sobrescrita

Python

from pyspark.sql.functions import col

# Overwrite specific rows based on condition
df.writeTo("my_table") \
    .overwrite(col("date") == "2025-01-01")

# Overwrite entire partitions
df.writeTo("my_table") \
    .overwritePartitions()

Encadeamento de métodos

Python

# Combine multiple configurations
df.writeTo("my_table") \
    .using("parquet") \
    .option("compression", "snappy") \
    .tableProperty("description", "User data table") \
    .partitionedBy("year", "month") \
    .clusterBy("user_id") \
    .createOrReplace()