Classe DataFrameWriterV2

Interface usada para gravar um DataFrame no armazenamento externo usando a API v2.

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

• Melhor suporte à propriedade de tabela
• Controle mais refinado sobre particionamento
• Recursos de substituição condicional
• Suporte para clustering
• Semântica mais clara para criar ou substituir operações

Dá suporte ao Spark Connect

Sintaxe

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

Methods

Método	Descrição
using(provider)	Especifica um provedor para a fonte de dados de saída subjacente.
option(key, value)	Adicione uma opção de gravação. Por exemplo, para criar uma tabela gerenciada: df.writeTo("test").using("delta").option("path", "s3://test").createOrReplace().
options(**options)	Adicionar opções de gravação.
tableProperty(property, value)	Adicionar propriedade de tabela. Por exemplo, use tableProperty("location", "s3://test") para criar uma tabela EXTERNAL (não gerenciada).
partitionedBy(col, *cols)	Particione a tabela de saída criada por create, createOrReplace ou substitua 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 com base no 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()	Acrescente o conteúdo do quadro de dados à tabela de saída.
overwrite(condition)	Substitua as linhas que correspondem à condição de filtro fornecida com o conteúdo do quadro de dados na tabela de saída.
overwritePartitions()	Substitua toda a partição para a qual o quadro de dados contém pelo menos uma linha com o conteúdo do quadro de dados na tabela de saída.

Exemplos

Criando uma nova tabela

# 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

# 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

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

Usando opções

# 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 clustering

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

Operações de substituição

# 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 acréscimo

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

Substituir operações

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

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