Cloudflare aggiorna l’introspection della SQL API: come individuare i campi JSON senza supposizioni

Se lo schema di un dataset analitico contiene una colonna JSON attributes, ma le sue chiavi dipendono dai dati dell’account, Cloudflare ora consente di individuarle tramite introspection. L’aggiornamento del 27 ottobre 2026 ha aggiunto il parametro include_attributes=true: la risposta elenca le chiavi e i tipi rilevati nei dati dell’account nei sette giorni precedenti.

Per gli sviluppatori risolve un problema concreto: prima di costruire un filtro, è possibile verificare quali campi compaiono davvero nel dataset selezionato. I vecchi nomi include_custom_attributes e custom_attributes continuano a funzionare, ma Cloudflare li ha contrassegnati come deprecati. Le nuove integrazioni dovrebbero basarsi sulla nuova introspection della SQL API.

Che cosa restituisce l’introspection

Alcuni dataset di Cloudflare Analytics memorizzano coppie aggiuntive chiave-valore nella colonna attributes. Con il nuovo parametro, l’introspection determina le chiavi e i relativi tipi in base ai dati degli ultimi sette giorni e restituisce le informazioni nel campo attributes dell’oggetto del dataset. Si tratta di uno schema dedotto dai record recenti dell’account, utile per preparare una query SQL.

Nell’esempio ufficiale, Cloudflare usa l’endpoint /client/v4/analytics/sql/introspection, specifica l’identificativo dell’account e il nome del dataset events.httpRequests, quindi abilita il rilevamento degli attributi:

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"

Prima di eseguire il comando, impostate nell’ambiente le variabili CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_TAG. Il token viene passato come credenziale bearer; i nomi delle variabili nell’esempio sono impostazioni locali del comando, non parametri distinti di Cloudflare.

Dalla chiave individuata alla query

Dopo l’introspection, controllate il campo attributes nella descrizione del dataset interessato e scegliete una chiave effettivamente elencata. Cloudflare mostra un esempio di accesso esatto a una chiave della colonna JSON: attributes['http.method']. Nel filtro usate il nome individuato, non uno ipotizzato a partire dal nome dell’evento.

La procedura pratica è la seguente:

1. Eseguite l’introspection del dataset desiderato con include_attributes=true.
2. Salvate le chiavi e i tipi restituiti nel campo attributes, insieme alla data della verifica.
3. Componete la query usando il nome esatto della chiave, per esempio attributes['http.method'].
4. Verificate la query sui dati del vostro account e ripetete il rilevamento quando cambiano lo schema o la natura degli eventi in ingresso.

La data della verifica è utile per la riproducibilità: Cloudflare ricava gli attributi da una finestra di sette giorni, quindi l’insieme delle chiavi individuate rispecchia i dati recenti e non uno schema immutabile. Se una chiave non è comparsa in questa finestra, la sua assenza dal risultato non basta a concludere che sia sempre indisponibile.

Come migrare dai vecchi nomi

Nel codice esistente, sostituite il parametro della query include_custom_attributes con include_attributes e modificate la gestione del campo di risposta da custom_attributes a attributes. Cloudflare segnala che i nomi precedenti continuano a funzionare, quindi la migrazione può essere eseguita senza dover ripristinare con urgenza l’integrazione.

Per una transizione sicura, verificate entrambe le parti del contratto: il parametro di query inviato e il percorso del campo nella risposta. Eseguite quindi la query sullo stesso dataset e confrontate l’elenco delle chiavi. Questo test individua un tipico errore di migrazione: la query usa già il nuovo nome del parametro, ma il codice si aspetta ancora il vecchio campo nella risposta.

In sintesi per le pipeline analitiche

include_attributes=true rende i campi JSON dinamici individuabili tramite il meccanismo ufficiale di introspection e fornisce agli sviluppatori i tipi insieme ai nomi delle chiavi. Aggiornate le nuove query e i parser per usare include_attributes e il campo di risposta attributes, registrate la data del rilevamento e costruite i filtri usando le chiavi effettivamente individuate.