Cloudflare vernieuwt SQL API-introspectie: JSON-velden ontdekken zonder giswerk

Als het schema van een analytische dataset een JSON-kolom attributes bevat waarvan de sleutels afhankelijk zijn van de accountgegevens, kun je die nu via introspectie ontdekken. De update van 27 oktober 2026 voegde de parameter include_attributes=true toe: het antwoord somt sleutels en typen op die in de accountgegevens van de voorafgaande zeven dagen zijn aangetroffen.

Voor ontwikkelaars lost dit een concreet probleem op: voordat je een filter opstelt, kun je controleren welke velden daadwerkelijk in de gekozen dataset voorkomen. De oude namen include_custom_attributes en custom_attributes werken nog, maar Cloudflare heeft ze als verouderd aangemerkt. Nieuwe integraties kun je het best baseren op de vernieuwde SQL API-introspectie.

Wat de introspectie precies teruggeeft

Sommige Cloudflare Analytics-datasets slaan aanvullende sleutel-waardeparen op in de kolom attributes. Met de nieuwe parameter bepaalt introspectie de sleutels en hun typen op basis van gegevens uit zeven dagen en geeft de informatie terug in het veld attributes van het datasetobject. Dit is een schema dat is afgeleid van recente accountgegevens en helpt bij het voorbereiden van een SQL-query.

In het officiële voorbeeld van Cloudflare wordt de route /client/v4/analytics/sql/introspection gebruikt, samen met de account-ID en de datasetnaam events.httpRequests, en wordt attribuutdetectie ingeschakeld:

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"

Stel vóór uitvoering de omgevingsvariabelen CLOUDFLARE_API_TOKEN en CLOUDFLARE_ACCOUNT_TAG in. Het token wordt als bearer-credential meegestuurd; de variabelenamen in het voorbeeld zijn lokale instellingen voor de opdracht en geen afzonderlijke Cloudflare-parameters.

Van gevonden sleutel naar query

Controleer na de introspectie het veld attributes in de beschrijving van de gewenste dataset en kies een sleutel die daadwerkelijk wordt vermeld. Cloudflare geeft een voorbeeld van directe toegang tot een sleutel in een JSON-kolom: attributes['http.method']. Gebruik in het filter de gevonden naam, niet een naam die je op basis van de gebeurtenisnaam vermoedt.

De praktische werkwijze ziet er als volgt uit:

1. Vraag introspectie op voor de gewenste dataset met include_attributes=true.
2. Sla de sleutels en typen uit het geretourneerde veld attributes op, samen met de controledatum.
3. Stel de query op met de exacte sleutelnaam, bijvoorbeeld attributes['http.method'].
4. Test de query met gegevens uit je account en voer de detectie opnieuw uit wanneer het schema of de aard van binnenkomende gebeurtenissen verandert.

De controledatum is nuttig voor reproduceerbaarheid: Cloudflare leidt attributen af uit een periode van zeven dagen, waardoor de gevonden sleutels de recente gegevens weerspiegelen en geen onveranderlijk schema vormen. Als een gewenste sleutel in die periode niet is voorgekomen, betekent het ontbreken ervan in het resultaat op zichzelf niet dat de sleutel algemeen ontoegankelijk is.

Overstappen vanaf de oude namen

Vervang in bestaande code de queryparameter include_custom_attributes door include_attributes en pas de verwerking van het antwoord aan zodat het veld attributes wordt gelezen in plaats van custom_attributes. Cloudflare meldt dat de oude namen blijven werken, zodat je de migratie los van een dringende integratieherstelactie kunt uitvoeren.

Controleer voor een veilige overstap beide onderdelen van het contract: de meegestuurde queryparameter en het pad naar het veld in het antwoord. Voer de query vervolgens uit op dezelfde dataset en vergelijk de lijst met sleutels. Zo spoor je een veelvoorkomende migratiefout op: de query gebruikt al de nieuwe parameternaam, maar de code verwacht nog het oude antwoordveld.

Conclusie voor analytische pipelines

include_attributes=true maakt dynamische JSON-velden vindbaar via het officiële introspectiemechanisme en geeft ontwikkelaars naast de sleutelnamen ook de typen. Stap voor nieuwe queries en parsers over op include_attributes en het antwoordveld attributes, bewaar de detectiedatum en stel filters op aan de hand van daadwerkelijk gevonden sleutels.