expandir json¶

fábrica

achata os campos de uma coluna json/jsonb em novas colunas tipadas, usando caminhos json (json_path) para navegar até cada valor.

quando usar¶

desestruturar uma coluna json vinda de uma fonte mongodb, postgres (jsonb) ou de uma api que retorna objetos aninhados
extrair apenas os campos relevantes de um payload json grande, já convertidos para o tipo correto
preparar dados semiestruturados para uma tabela relacional plana antes do lakehouse writer

configuração¶

campo	tipo	obrigatório	descrição
`source_field`	string	sim	coluna de origem (texto json ou jsonb)
`fields`	lista de `{json_path, alias, type}`	sim	um item por campo a extrair
`keep_source`	bool	não	mantém a coluna json original no resultado · padrão: `false`

cada item de fields:

campo	descrição
`json_path`	caminho até o valor dentro do json, ex: `$.endereco.cidade`
`alias`	nome da nova coluna
`type`	`text`, `integer`, `decimal`, `boolean`, `date`, `datetime`

exemplo¶

dado um campo payload com o conteúdo:

{ "cliente": { "id": 42, "nome": "Ana" }, "valor_total": 199.9, "pago": true }

configuração:

{
  "source_field": "payload",
  "fields": [
    { "json_path": "$.cliente.id", "alias": "cliente_id", "type": "integer" },
    { "json_path": "$.cliente.nome", "alias": "cliente_nome", "type": "text" },
    { "json_path": "$.valor_total", "alias": "valor_total", "type": "decimal" },
    { "json_path": "$.pago", "alias": "pago", "type": "boolean" }
  ],
  "keep_source": false
}

resultado: quatro novas colunas tipadas (cliente_id, cliente_nome, valor_total, pago), e a coluna payload original é removida (porque keep_source = false).

expandir json vs. expandir struct¶

nó	quando usar
expandir json (este nó)	a coluna é um texto json/jsonb e você quer extrair campos específicos por caminho
expandir struct	a coluna já é um tipo estruturado (struct) e você quer expandir todos os campos de uma vez, sem escolher caminho a caminho