Classe DataFrame

Uma coleção distribuída de dados agrupados em colunas nomeadas.

Um DataFrame é equivalente a uma tabela relacional no Spark SQL e pode ser criado usando várias funções no SparkSession.

Importante

Um DataFrame não deve ser criado diretamente usando o construtor.

Dá suporte ao Spark Connect

Propriedades

Propriedade	Descrição
sparkSession	Retorna SparkSession que criou esse DataFrame.
rdd	Retorna o conteúdo como um RDD de Linha (somente modo clássico).
na	Retorna um DataFrameNaFunctions para lidar com valores ausentes.
stat	Retorna um DataFrameStatFunctions para funções de estatística.
write	Interface para salvar o conteúdo do DataFrame sem streaming no armazenamento externo.
writeStream	Interface para salvar o conteúdo do DataFrame de streaming no armazenamento externo.
schema	Retorna o esquema deste DataFrame como um StructType.
dtypes	Retorna todos os nomes de coluna e seus tipos de dados como uma lista.
columns	Recupera os nomes de todas as colunas no DataFrame como uma lista.
storageLevel	Obtenha o nível de armazenamento atual do DataFrame.
isStreaming	Retorna True se esse DataFrame contiver uma ou mais fontes que retornam dados continuamente à medida que chegam.
executionInfo	Retorna um objeto ExecutionInfo depois que a consulta foi executada.
plot	Retorna um PySparkPlotAccessor para plotar funções.

Methods

Exibição e inspeção de dados

Método	Descrição
toJSON(use_unicode)	Converte um DataFrame em um RDD de cadeia de caracteres ou DataFrame.
printSchema(level)	Imprime o esquema no formato de árvore.
explain(extended, mode)	Imprime os planos (lógicos e físicos) no console para fins de depuração.
show(n, truncate, vertical)	Imprime as primeiras n linhas do DataFrame no console.
collect()	Retorna todos os registros no DataFrame como uma lista de Linha.
toLocalIterator(prefetchPartitions)	Retorna um iterador que contém todas as linhas neste DataFrame.
take(num)	Retorna as primeiras linhas num como uma lista de Linha.
tail(num)	Retorna as últimas linhas num como uma lista de Linha.
head(n)	Retorna as primeiras n linhas.
first()	Retorna a primeira linha como uma linha.
count()	Retorna o número de linhas neste DataFrame.
isEmpty()	Verifica se o DataFrame está vazio e retorna um valor booliano.
describe(*cols)	Calcula estatísticas básicas para colunas numéricas e de cadeia de caracteres.
summary(*statistics)	Calcula estatísticas especificadas para colunas numéricas e de cadeia de caracteres.

Visões temporárias

Método	Descrição
createTempView(name)	Cria uma exibição temporária local com esse DataFrame.
createOrReplaceTempView(name)	Cria ou substitui uma exibição temporária local por este DataFrame.
createGlobalTempView(name)	Cria uma exibição temporária global com esse DataFrame.
createOrReplaceGlobalTempView(name)	Cria ou substitui uma exibição temporária global usando o nome fornecido.

Seleção e projeção

Método	Descrição
select(*cols)	Projeta um conjunto de expressões e retorna um novo DataFrame.
selectExpr(*expr)	Projeta um conjunto de expressões SQL e retorna um novo DataFrame.
filter(condition)	Filtra linhas usando a condição fornecida.
where(condition)	Alias para filtro.
drop(*cols)	Retorna um novo DataFrame sem colunas especificadas.
toDF(*cols)	Retorna um novo DataFrame com novos nomes de coluna especificados.
withColumn(colName, col)	Retorna um novo DataFrame adicionando uma coluna ou substituindo a coluna existente que tem o mesmo nome.
withColumns(*colsMap)	Retorna um novo DataFrame adicionando várias colunas ou substituindo as colunas existentes que têm os mesmos nomes.
withColumnRenamed(existing, new)	Retorna um novo DataFrame renomeando uma coluna existente.
withColumnsRenamed(colsMap)	Retorna um novo DataFrame renomeando várias colunas.
withMetadata(columnName, metadata)	Retorna um novo DataFrame atualizando uma coluna existente com metadados.
metadataColumn(colName)	Seleciona uma coluna de metadados com base em seu nome de coluna lógica e a retorna como uma Coluna.
colRegex(colName)	Seleciona a coluna com base no nome da coluna especificado como um regex e a retorna como Coluna.

Classificação e ordenação

Método	Descrição
sort(*cols, **kwargs)	Retorna um novo DataFrame classificado pelas colunas especificadas.
orderBy(*cols, **kwargs)	Alias para classificação.
sortWithinPartitions(*cols, **kwargs)	Retorna um novo DataFrame com cada partição classificada pelas colunas especificadas.

Agregação e agrupamento

Método	Descrição
groupBy(*cols)	Agrupa o DataFrame pelas colunas especificadas para que a agregação possa ser executada nelas.
rollup(*cols)	Crie um rollup multidimensional para o DataFrame atual usando as colunas especificadas.
cube(*cols)	Crie um cubo multidimensional para o DataFrame atual usando as colunas especificadas.
groupingSets(groupingSets, *cols)	Crie agregação multidimensional para o DataFrame atual usando os conjuntos de agrupamento especificados.
agg(*exprs)	Agregar em todo o DataFrame sem grupos (abreviação para df.groupBy().agg()).
observe(observation, *exprs)	Defina as métricas (nomeadas) a serem observadas no DataFrame.

Joins

Método	Descrição
join(other, on, how)	Une-se a outro DataFrame, usando a expressão de junção fornecida.
crossJoin(other)	Retorna o produto cartesiano com outro DataFrame.
lateralJoin(other, on, how)	Junções laterais com outro DataFrame, usando a expressão de junção fornecida.

Definir operações

Método	Descrição
union(other)	Retorne um novo DataFrame que contém a união de linhas neste e em outro DataFrame.
unionByName(other, allowMissingColumns)	Retorna um novo DataFrame que contém a união de linhas neste e em outro DataFrame.
intersect(other)	Retornar um novo DataFrame que contém linhas somente neste DataFrame e em outro DataFrame.
intersectAll(other)	Retorne um novo DataFrame que contém linhas neste DataFrame e em outro DataFrame, preservando duplicatas.
subtract(other)	Retorne um novo DataFrame que contém linhas neste DataFrame, mas não em outro DataFrame.
exceptAll(other)	Retorne um novo DataFrame que contém linhas neste DataFrame, mas não em outro DataFrame, preservando duplicatas.

Deduplicação

Método	Descrição
distinct()	Retorna um novo DataFrame que contém as linhas distintas neste DataFrame.
dropDuplicates(subset)	Retorne um novo DataFrame com linhas duplicadas removidas, opcionalmente considerando apenas determinadas colunas.
dropDuplicatesWithinWatermark(subset)	Retorne um novo DataFrame com linhas duplicadas removidas, opcionalmente considerando apenas determinadas colunas, dentro da marca d'água.

Amostragem e divisão

Método	Descrição
sample(withReplacement, fraction, seed)	Retorna um subconjunto amostrado deste DataFrame.
sampleBy(col, fractions, seed)	Retorna uma amostra estratificada sem substituição com base na fração fornecida em cada estrato.
randomSplit(weights, seed)	Divide aleatoriamente esse DataFrame com os pesos fornecidos.

Partitioning

Método	Descrição
coalesce(numPartitions)	Retorna um novo DataFrame que tem exatamente partições numPartitions.
repartition(numPartitions, *cols)	Retorna um novo DataFrame particionado pelas expressões de particionamento fornecidas.
repartitionByRange(numPartitions, *cols)	Retorna um novo DataFrame particionado pelas expressões de particionamento fornecidas.
repartitionById(numPartitions, partitionIdCol)	Retorna um novo DataFrame particionado pela expressão de ID de partição fornecida.

Remodelagem

Método	Descrição
unpivot(ids, values, variableColumnName, valueColumnName)	Despivote um DataFrame de formato largo para formato longo.
melt(ids, values, variableColumnName, valueColumnName)	Alias para unpivot.
transpose(indexColumn)	Transpõe um DataFrame de modo que os valores na coluna de índice especificada se tornem as novas colunas.

Tratamento de dados ausentes

Método	Descrição
dropna(how, thresh, subset)	Retorna um novo DataFrame omitindo linhas com valores nulos ou NaN.
fillna(value, subset)	Retorna um novo DataFrame que os valores nulos são preenchidos com o novo valor.
replace(to_replace, value, subset)	Retorna um novo DataFrame substituindo um valor por outro valor.

Funções estatísticas

Método	Descrição
approxQuantile(col, probabilities, relativeError)	Calcula os quantiles aproximados de colunas numéricas de um DataFrame.
corr(col1, col2, method)	Calcula a correlação de duas colunas de um DataFrame como um valor duplo.
cov(col1, col2)	Calcule a covariância de exemplo para as colunas fornecidas, especificadas por seus nomes.
crosstab(col1, col2)	Calcula uma tabela de frequência em termos de par das colunas fornecidas.
freqItems(cols, support)	Localizando itens frequentes para colunas, possivelmente com falsos positivos.

Operações de esquema

Método	Descrição
to(schema)	Retorna um novo DataFrame em que cada linha é reconciliada para corresponder ao esquema especificado.
alias(alias)	Retorna um novo DataFrame com um conjunto de alias.

Iteração

Método	Descrição
foreach(f)	Aplica a função f a todas as linhas deste DataFrame.
foreachPartition(f)	Aplica a função f a cada partição deste DataFrame.

Cache e persistência

Método	Descrição
cache()	Persiste o DataFrame com o nível de armazenamento padrão (MEMORY_AND_DISK_DESER).
persist(storageLevel)	Define o nível de armazenamento para persistir o conteúdo do DataFrame entre operações.
unpersist(blocking)	Marca o DataFrame como não persistente e remove todos os blocos para ele da memória e do disco.

Definindo o ponto de verificação

Método	Descrição
checkpoint(eager)	Retorna uma versão com ponto de verificação deste DataFrame.
localCheckpoint(eager, storageLevel)	Retorna uma versão com ponto de verificação local deste DataFrame.

Operações de streaming

Método	Descrição
withWatermark(eventTime, delayThreshold)	Define uma marca d'água de hora do evento para este DataFrame.

Dicas de otimização

Método	Descrição
hint(name, *parameters)	Especifica alguma dica sobre o DataFrame atual.

Limites e deslocamentos

Método	Descrição
limit(num)	Limita a contagem de resultados ao número especificado.
offset(num)	Retorna um novo DataFrame ignorando as primeiras n linhas.

Transformações avançadas

Método	Descrição
transform(func, *args, **kwargs)	Retorna um novo DataFrame. Sintaxe concisa para encadear transformações personalizadas.

Métodos de conversão

Método	Descrição
toPandas()	Retorna o conteúdo deste DataFrame como pandas pandas. DataFrame.
toArrow()	Retorna o conteúdo deste DataFrame como pyarrow PyArrow. Tabela.
pandas_api(index_col)	Converte o DataFrame existente em um DataFrame pandas-on-Spark.
mapInPandas(func, schema, barrier, profile)	Mapeia um iterador de lotes no DataFrame atual usando uma função nativa do Python.
mapInArrow(func, schema, barrier, profile)	Mapeia um iterador de lotes no DataFrame atual usando uma função nativa do Python que é executada em pyarrow. RecordBatch.

Gravação de dados

Método	Descrição
writeTo(table)	Crie um construtor de configuração de gravação para fontes v2.
mergeInto(table, condition)	Mescla um conjunto de atualizações, inserções e exclusões com base em uma tabela de origem em uma tabela de destino.

Comparação de DataFrame

Método	Descrição
sameSemantics(other)	Retorna True quando os planos de consulta lógica dentro de ambos os DataFrames são iguais.
semanticHash()	Retorna um código hash do plano de consulta lógica em relação a esse DataFrame.

Metadados e informações de arquivo

Método	Descrição
inputFiles()	Retorna um instantâneo de melhor esforço dos arquivos que compõem esse DataFrame.

Recursos avançados do SQL

Método	Descrição
isLocal()	Retorna True se os métodos collect e take podem ser executados localmente.
asTable()	Converte o DataFrame em um objeto TableArg, que pode ser usado como um argumento de tabela em um TVF.
scalar()	Retornar um objeto Column para uma subconsulta SCALAR que contém exatamente uma linha e uma coluna.
exists()	Retornar um objeto Column para uma Subconsulta EXISTS.

Exemplos

Operações básicas do DataFrame

# Create a DataFrame
people = spark.createDataFrame([
    {"deptId": 1, "age": 40, "name": "Alice", "gender": "M", "salary": 50},
    {"deptId": 1, "age": 50, "name": "Bob", "gender": "M", "salary": 100},
    {"deptId": 2, "age": 60, "name": "Sue", "gender": "F", "salary": 150},
    {"deptId": 3, "age": 20, "name": "Tom", "gender": "M", "salary": 200}
])

# Select columns
people.select("name", "age").show()

# Filter rows
people.filter(people.age > 30).show()

# Add a new column
people.withColumn("age_plus_10", people.age + 10).show()

Agregação e agrupamento

# Group by and aggregate
people.groupBy("gender").agg({"salary": "avg", "age": "max"}).show()

# Multiple aggregations
from pyspark.sql import functions as F
people.groupBy("deptId").agg(
    F.avg("salary").alias("avg_salary"),
    F.max("age").alias("max_age")
).show()

Joins

# Create another DataFrame
department = spark.createDataFrame([
    {"id": 1, "name": "PySpark"},
    {"id": 2, "name": "ML"},
    {"id": 3, "name": "Spark SQL"}
])

# Join DataFrames
people.join(department, people.deptId == department.id).show()

Transformações complexas

# Chained operations
result = people.filter(people.age > 30) \\
    .join(department, people.deptId == department.id) \\
    .groupBy(department.name, "gender") \\
    .agg({"salary": "avg", "age": "max"}) \\
    .sort("max(age)")
result.show()