Como adicionar colunas com withColumn no PySpark

João Barros 04 de July de 2026 4 min de leitura

Adicionar novas colunas a um DataFrame é uma das tarefas mais comuns ao transformar dados em PySpark. O método withColumn permite criar colunas calculadas, converter tipos de dados e aplicar regras condicionais, tudo de forma distribuída e pronta para grandes volumes. A seguir vês, com exemplos simples, como adicionar colunas com withColumn — do caso mais básico ao condicional — e como confirmar que o resultado ficou correto.

Pré-requisitos

Um ambiente com PySpark disponível (por exemplo, Databricks, Microsoft Fabric ou uma instalação local de Spark).
Conhecimentos básicos de Python e familiaridade com o conceito de DataFrame.
Um DataFrame de exemplo para praticar — criamos um no primeiro passo.

Passo 1: Criar um DataFrame de exemplo

Antes de adicionar colunas, precisamos de dados. O código abaixo cria uma SparkSession (o ponto de entrada de qualquer aplicação Spark) e um pequeno DataFrame com três produtos, os seus preços e as quantidades vendidas.

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("colunas").getOrCreate()

dados = [
    ("Teclado", 25.0, 4),
    ("Rato", 15.0, 10),
    ("Monitor", 120.0, 2),
]
df = spark.createDataFrame(dados, ["produto", "preco", "quantidade"])
df.show()

O método show() imprime as primeiras linhas, para confirmares que os dados foram carregados como esperavas.

Passo 2: Adicionar uma coluna calculada

O uso mais frequente de withColumn é criar uma coluna a partir de outras. O método recebe dois argumentos: o nome da nova coluna e a expressão que a calcula. Para nos referirmos a colunas existentes, importamos a função col. No exemplo, multiplicamos o preço pela quantidade para obter o total de cada linha.

from pyspark.sql.functions import col

df = df.withColumn("total", col("preco") * col("quantidade"))
df.show()

Um detalhe importante: withColumn devolve sempre um novo DataFrame em vez de alterar o original. Por isso guardamos o resultado outra vez na variável df. Esta imutabilidade é intencional e ajuda o Spark a otimizar a execução.

Passo 3: Adicionar uma coluna com um valor fixo

Por vezes só precisas de uma coluna constante, como a moeda ou a origem dos dados. Nesse caso, a expressão não pode ser um texto simples — tem de ser um valor literal criado com a função lit.

from pyspark.sql.functions import lit

df = df.withColumn("moeda", lit("EUR"))
df.show()

Se esquecesses o lit e passasses apenas "EUR", o Spark tentaria interpretá-lo como o nome de uma coluna e daria erro.

Passo 4: Criar uma coluna condicional

Para aplicar regras de negócio, combina as funções when e otherwise, que funcionam como um "se… senão". No exemplo, marcamos como "alto" os produtos cujo total ultrapassa 100 e como "normal" todos os outros. Podes encadear vários when antes do otherwise para cobrir mais casos.

from pyspark.sql.functions import when

df = df.withColumn(
    "categoria",
    when(col("total") > 100, "alto").otherwise("normal")
)
df.show()

Passo 5: Converter o tipo de uma coluna

O withColumn também serve para mudar o tipo de dados de uma coluna, usando cast. Aqui convertemos a quantidade de número inteiro para texto.

df = df.withColumn("quantidade", col("quantidade").cast("string"))
df.printSchema()

Como demos à coluna o mesmo nome que já existia (quantidade), o withColumn substitui a coluna original em vez de criar uma nova. É assim que se atualiza uma coluna no sítio.

Dica: para adicionar muitas colunas de uma só vez existe withColumns (no plural), que aceita um dicionário com vários pares nome/expressão. Evita, porém, encadear dezenas de withColumn num ciclo, porque pode tornar o plano de execução mais lento.

Verificar o resultado

Executa df.show() para veres as linhas com as novas colunas e df.printSchema() para confirmares nomes e tipos. Deves ver as colunas total, moeda e categoria, com quantidade agora do tipo string. Se alguma coluna aparecer toda a null, confirma que o nome usado dentro de col("...") existe e está escrito exatamente como no schema — maiúsculas e acentos incluídos.

Conclusão

Já sabes usar withColumn para criar colunas calculadas, constantes e condicionais, e ainda para converter tipos — a base de quase todas as transformações em PySpark. Como próximo passo, tenta combinar estas técnicas para preparar um DataFrame real e guardá-lo em formato Parquet. Qual vai ser a primeira coluna que precisas de criar no teu pipeline?