Classe DataFrameWriterV2

Interface usada para escrever um DataFrame para 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 à propriedade da tabela
• Controlo mais detalhado sobre particionamento
• Capacidades de sobrescrição condicional
• Suporte para clustering
• Semântica mais clara para criar ou substituir operações

Suporta Spark Connect

Sintaxe

Use DataFrame.writeTo(table) para aceder a esta interface.

Methods

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

Exemplos

Criação de 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()

Propriedades da tabela de definição

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

Utilização de 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()

Agrupamento de dados

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

Substituir operações

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

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

Anexar operações

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

Operações de sobrescrição

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()