Cloudflare actualiza la introspección de SQL API: detecta campos JSON sin conjeturas

Si el esquema de un conjunto de datos analíticos contiene una columna JSON attributes, pero sus claves dependen de los datos de la cuenta, Cloudflare ahora permite detectarlas mediante introspección. La actualización del 27 de octubre de 2026 añadió el parámetro include_attributes=true: la respuesta enumera las claves y los tipos encontrados en los datos de la cuenta durante los siete días anteriores.

Para los desarrolladores, esto resuelve un problema concreto: antes de crear un filtro, pueden comprobar qué campos aparecen realmente en el conjunto seleccionado. Los nombres anteriores include_custom_attributes y custom_attributes siguen funcionando por ahora, pero Cloudflare los ha marcado como obsoletos. Conviene basar las nuevas integraciones en la introspección actualizada de SQL API.

Qué devuelve exactamente la introspección

Algunos conjuntos de Cloudflare Analytics almacenan pares adicionales de clave y valor en la columna attributes. Con el nuevo parámetro, la introspección determina las claves y sus tipos a partir de los datos de los últimos siete días, y devuelve la información en el campo attributes del objeto del conjunto de datos. Se trata de un esquema inferido de los registros recientes de la cuenta que ayuda a preparar una consulta SQL.

En el ejemplo oficial, Cloudflare usa la ruta /client/v4/analytics/sql/introspection, proporciona el identificador de la cuenta y el nombre del conjunto events.httpRequests, y activa la detección 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 ejecutar el comando, define las variables CLOUDFLARE_API_TOKEN y CLOUDFLARE_ACCOUNT_TAG en el entorno. El token se envía como credencial bearer; los nombres de variables del ejemplo son ajustes locales del comando, no parámetros independientes de Cloudflare.

De una clave detectada a una consulta

Después de la introspección, revisa el campo attributes en la descripción del conjunto correspondiente y elige una clave que aparezca en la lista. Cloudflare muestra un ejemplo de acceso exacto a una clave de la columna JSON: attributes['http.method']. Usa en el filtro el nombre detectado, no uno supuesto a partir del nombre del evento.

El flujo de trabajo práctico es el siguiente:

1. Solicita la introspección del conjunto de datos correspondiente con include_attributes=true.
2. Guarda las claves y los tipos del campo attributes devuelto, junto con la fecha de comprobación.
3. Construye la consulta con el nombre exacto de la clave, por ejemplo, attributes['http.method'].
4. Comprueba la consulta con los datos de tu cuenta y repite la detección cuando cambien el esquema o las características de los eventos entrantes.

La fecha de comprobación es útil para poder reproducir los resultados: Cloudflare infiere los atributos a partir de una ventana de siete días, por lo que las claves detectadas reflejan datos recientes, no un esquema inmutable. Si una clave no aparece en esa ventana, su ausencia en el resultado no basta por sí sola para concluir que no está disponible en general.

Cómo migrar desde los nombres anteriores

En el código existente, sustituye el parámetro de consulta include_custom_attributes por include_attributes y cambia la lectura del campo de respuesta de custom_attributes a attributes. Cloudflare indica que los nombres anteriores siguen funcionando, así que puedes realizar la migración sin tener que restablecer urgentemente una integración.

Para migrar de forma segura, comprueba ambos elementos del contrato: el parámetro de consulta enviado y la ruta al campo de la respuesta. Después, ejecuta la consulta en el mismo conjunto y compara la lista de claves. Esta prueba detectará un error de migración habitual: que la consulta ya use el nuevo nombre del parámetro mientras el código aún espera el antiguo campo de respuesta.

Conclusión para las canalizaciones analíticas

include_attributes=true permite detectar campos JSON dinámicos mediante el mecanismo oficial de introspección y ofrece a los desarrolladores los tipos junto con los nombres de las claves. Actualiza las consultas y los analizadores nuevos para usar include_attributes y el campo de respuesta attributes, registra la fecha de detección y crea filtros a partir de las claves encontradas realmente.