pivot

fábrica

transforma valores distintos de uma coluna em novas colunas, agregando os valores correspondentes — a operação clássica de "linhas para colunas" usada em relatórios.

---

quando usar

• construir um relatório "wide" com uma coluna por mês, categoria ou região a partir de dados "long"
• montar uma matriz de métricas (ex: vendas por produto x mês) para consumo direto em bi ou planilha
• preparar dados no formato esperado por uma ferramenta de visualização que exige colunas por categoria

---

configuração

campo	tipo	obrigatório	descrição
pivot_col	string	sim	coluna cujos valores distintos viram novas colunas
value_col	string	sim	coluna cujo valor é agregado dentro de cada nova coluna
row_key	string	não	coluna(s) usada(s) para agrupar as linhas do resultado · vazio = sem agrupamento explícito
agg_fn	enum	não	SUM, COUNT, AVG, MAX, MIN · padrão: SUM
pivot_values	lista	não	limita o pivot a valores específicos de pivot_col · vazio = usa todos os valores distintos encontrados

---

exemplo

dado um dataset "long":

regiao	mes	valor
norte	jan	100
norte	fev	150
sul	jan	200
sul	fev	180

configuração:

{
  "pivot_col": "mes",
  "value_col": "valor",
  "row_key": "regiao",
  "agg_fn": "SUM"
}

resultado:

regiao	jan	fev
norte	100	150
sul	200	180

limitando as colunas geradas

{
  "pivot_col": "mes",
  "value_col": "valor",
  "row_key": "regiao",
  "agg_fn": "SUM",
  "pivot_values": ["jan", "fev", "mar"]
}

útil quando a coluna de origem tem muitos valores distintos (ex: centenas de skus) e você quer limitar o pivot a um conjunto conhecido, evitando um resultado com centenas de colunas.

operação inversa: unpivot

para o caminho contrário — transformar colunas em linhas — use o nó unpivot.