Cloudflare atualiza a introspecção da SQL API: como descobrir campos JSON sem suposições

Se o esquema de um conjunto de dados analíticos contém uma coluna JSON attributes, mas suas chaves dependem dos dados da conta, agora a Cloudflare permite descobri-las por meio da introspecção. A atualização de 27 de outubro de 2026 adicionou o parâmetro include_attributes=true: a resposta lista as chaves e os tipos encontrados nos dados da conta nos sete dias anteriores.

Para desenvolvedores, isso resolve um problema concreto: antes de criar um filtro, é possível verificar quais campos realmente aparecem no conjunto selecionado. Os nomes antigos include_custom_attributes e custom_attributes ainda funcionam, mas a Cloudflare os marcou como obsoletos. Novas integrações devem ser desenvolvidas com base na introspecção atualizada da SQL API.

O que a introspecção retorna

Alguns conjuntos do Cloudflare Analytics armazenam pares adicionais de chave e valor na coluna attributes. Com o novo parâmetro, a introspecção identifica chaves e tipos com base nos dados dos últimos sete dias e retorna essas informações no campo attributes do objeto do conjunto de dados. Trata-se de um esquema inferido de registros recentes da conta, que ajuda a preparar uma consulta SQL.

No exemplo oficial, a Cloudflare usa a rota /client/v4/analytics/sql/introspection, informa o identificador da conta e o nome do conjunto events.httpRequests e habilita a descoberta de atributos:

curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --data-urlencode "account_tag=$CLOUDFLARE_ACCOUNT_TAG" \
  --data-urlencode "dataset_name=events.httpRequests" \
  --data-urlencode "include_attributes=true"

Antes de executar o comando, defina as variáveis CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_TAG no ambiente. O token é enviado como credencial bearer; os nomes de variáveis do exemplo são configurações locais do comando, não parâmetros separados da Cloudflare.

Da chave encontrada à consulta

Após a introspecção, verifique o campo attributes na descrição do conjunto desejado e escolha uma chave efetivamente listada. A Cloudflare mostra um exemplo de acesso exato a uma chave da coluna JSON: attributes['http.method']. Use no filtro o nome encontrado, e não um nome presumido com base no evento.

Um fluxo de trabalho prático é o seguinte:

1. Consulte a introspecção do conjunto de dados desejado com include_attributes=true.
2. Salve as chaves e os tipos do campo attributes retornado, junto com a data da verificação.
3. Monte a consulta usando o nome exato da chave, por exemplo, attributes['http.method'].
4. Teste a consulta com os dados da sua conta e repita a descoberta quando o esquema ou a natureza dos eventos recebidos mudar.

A data da verificação é útil para garantir a reprodutibilidade: a Cloudflare infere os atributos a partir de uma janela de sete dias, portanto, o conjunto de chaves descobertas reflete dados recentes, não um esquema imutável. Se uma chave desejada não apareceu nessa janela, sua ausência no resultado, por si só, não permite concluir que ela seja universalmente indisponível.

Como migrar dos nomes antigos

No código existente, substitua o parâmetro de consulta include_custom_attributes por include_attributes e troque a leitura do campo de resposta custom_attributes pelo campo attributes. A Cloudflare informa que os nomes anteriores continuam funcionando, então é possível fazer a migração sem precisar restabelecer a integração com urgência.

Para uma transição segura, verifique as duas partes do contrato: o parâmetro de consulta enviado e o caminho do campo na resposta. Em seguida, execute a consulta no mesmo conjunto e compare a lista de chaves. Esse teste detecta um erro comum de migração: a consulta já usa o novo nome do parâmetro, mas o código ainda espera o antigo campo de resposta.

Conclusão para pipelines analíticos

include_attributes=true torna os campos JSON dinâmicos detectáveis por meio do mecanismo oficial de introspecção e fornece os tipos junto com os nomes das chaves. Atualize novas consultas e analisadores para usar include_attributes e o campo de resposta attributes, registre a data da descoberta e crie filtros com base nas chaves realmente encontradas.