Cloudflare oppdaterer SQL API-introspeksjon: Slik finner du JSON-felt uten gjetting

Hvis skjemaet for et analysedatasett inneholder JSON-kolonnen attributes, men nøklene avhenger av kontodataene, kan Cloudflare nå finne dem gjennom introspeksjon. Oppdateringen fra 27. oktober 2026 la til parameteren include_attributes=true: Svaret lister opp nøkler og typer som er funnet i kontodata fra de foregående sju dagene.

For utviklere løser dette en konkret oppgave: Før du lager et filter, kan du kontrollere hvilke felt som faktisk finnes i det valgte datasettet. De gamle navnene include_custom_attributes og custom_attributes fungerer fortsatt, men Cloudflare har merket dem som utdaterte. Nye integrasjoner bør bygges på den oppdaterte SQL API-introspeksjonen.

Hva introspeksjonen returnerer

Noen av Cloudflares Analytics-datasett lagrer ekstra nøkkel–verdi-par i kolonnen attributes. Med den nye parameteren finner introspeksjonen nøkler og typene deres basert på data fra sju dager, og returnerer informasjonen i feltet attributes i datasettobjektet. Dette er et skjema utledet fra nylige kontodata, som kan hjelpe deg med å klargjøre en SQL-spørring.

I det offisielle eksempelet bruker Cloudflare endepunktet /client/v4/analytics/sql/introspection, angir konto-ID-en og datasettets navn events.httpRequests, og slår på attributtoppdagelse:

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"

Før du kjører kommandoen, må du sette variablene CLOUDFLARE_API_TOKEN og CLOUDFLARE_ACCOUNT_TAG i miljøet. Tokenet sendes som bearer-legitimasjon; variabelnavnene i eksempelet er lokale innstillinger for kommandoen, ikke egne Cloudflare-parametere.

Fra funnet nøkkel til spørring

Etter introspeksjonen kontrollerer du feltet attributes i beskrivelsen av det aktuelle datasettet og velger en nøkkel som faktisk er oppført. Cloudflare viser et eksempel på hvordan du slår opp en bestemt nøkkel i JSON-kolonnen: attributes['http.method']. Bruk navnet du fant i filteret, ikke et navn du antar ut fra hendelsen.

En praktisk arbeidsflyt ser slik ut:

1. Kjør introspeksjon for det aktuelle datasettet med include_attributes=true.
2. Lagre nøklene og typene fra det returnerte feltet attributes sammen med datoen for kontrollen.
3. Sett sammen spørringen med det nøyaktige nøkkelnavnet, for eksempel attributes['http.method'].
4. Test spørringen mot kontodataene dine, og gjenta oppdagelsen når skjemaet eller innkommende hendelser endrer seg.

Kontrolldatoen er nyttig for reproduksjon: Cloudflare utleder attributtene fra et sjudagersvindu, så listen over oppdagede nøkler gjenspeiler nylige data, ikke et uforanderlig skjema. Hvis en nøkkel ikke forekom i dette tidsrommet, betyr ikke fraværet i resultatet i seg selv at den generelt er utilgjengelig.

Slik går du over fra de gamle navnene

I eksisterende kode bytter du ut spørringsparameteren include_custom_attributes med include_attributes, og endrer behandlingen av svarfeltet fra custom_attributes til attributes. Cloudflare opplyser at de gamle navnene fortsatt fungerer, så migreringen kan gjøres uten at du må gjenopprette integrasjonen umiddelbart.

For en trygg overgang kontrollerer du begge delene av grensesnittet: spørringsparameteren som sendes, og feltbanen i svaret. Kjør deretter spørringen på det samme datasettet og sammenlign listen over nøkler. Denne testen avdekker en vanlig migreringsfeil: Spørringen bruker det nye parameternavnet, mens koden fortsatt forventer det gamle svarfeltet.

Konsekvenser for datapipelines

include_attributes=true gjør dynamiske JSON-felt synlige gjennom den offisielle introspeksjonsmekanismen og gir utviklere typene sammen med nøkkelnavnene. Oppdater nye spørringer og parsere til å bruke include_attributes og svarfeltet attributes, lagre datoen for oppdagelsen, og lag filtre basert på nøkler som faktisk er funnet.