Add `analytics_engine` service exposing the Workers Analytics Engine SQL API

[jeffreyaven]

Summary

The Cloudflare provider does not currently expose the Workers Analytics Engine (WAE) SQL API. The endpoint has recently been added to the upstream Cloudflare OpenAPI schemas, and the GET variant maps cleanly to a StackQL select method. Adding it would allow WAE datasets to be queried directly from StackQL, e.g. for release download analytics stored in Analytics Engine.

Current state

• Provider version v26.07.00424 (109 services) has no analytics_engine service.
• The closest existing resource, cloudflare.workers.queries, is the Workers Observability saved-queries CRUD and is unrelated to WAE query execution.

Upstream change

cloudflare/api-schemas (openapi.json) now includes the path /accounts/{account_id}/analytics_engine/sql with two operations:

operationId	Method	Query passed as
analytics-engine-sql-query-get	GET	required query query-string parameter
analytics-engine-sql-query-post	POST	raw text/plain request body

Both use the standard api_token security scheme (token group: Account Analytics Read). Responses are NDJSON by default, or a single application/json object shaped { "data": [...], "meta": [...], "rows": N } when the query includes a FORMAT JSON clause.

Note: both operations carry x-fern-ignore and x-forge-hidden vendor extensions (Cloudflare's own SDK generators skip them). If the provider generation pipeline filters on these, the path will need to be explicitly whitelisted or added as a manual overlay.

Proposed implementation

Map the GET variant only as a select method. The POST variant takes a raw text/plain body, which does not fit the standard request mapping, and the GET variant covers the use case for all but very long queries.

components:
  x-stackQL-resources:
    sql_query:
      id: cloudflare.analytics_engine.sql_query
      name: sql_query
      title: Analytics Engine SQL Query
      methods:
        query_get:
          operation:
            $ref: '#/paths/~1accounts~1{account_id}~1analytics_engine~1sql/get'
          response:
            mediaType: application/json
            openAPIDocKey: '200'
            objectKey: $.data
      sqlVerbs:
        select:
          - $ref: '#/components/x-stackQL-resources/sql_query/methods/query_get'
        insert: []
        update: []
        delete: []

Response side: mediaType: application/json with objectKey: $.data returns one row object per WAE result row. This requires the inner query to include FORMAT JSON; the NDJSON default will not map through the jsonpath selector. This constraint should be documented on the resource.

Example usage

SELECT *
FROM cloudflare.analytics_engine.sql_query
WHERE account_id = '<account_id>'
AND query = 'SELECT blob1 AS country, sum(_sample_interval) AS downloads
             FROM my_dataset
             WHERE timestamp > NOW() - INTERVAL ''1'' DAY
             GROUP BY country ORDER BY downloads DESC FORMAT JSON'

Notes and caveats

• Inner queries must alias all expressions; WAE returns unaliased keys verbatim (e.g. count()), which produce awkward column names on the StackQL side.
• No new auth configuration is required; the existing provider bearer token works provided it has the Account Analytics Read scope.
• WAE result columns are dynamic (dependent on the inner query), so the response schema is an open object.
• Follow-up (out of scope for this issue): view definitions wrapping common report queries with FORMAT JSON baked in, plus corresponding stackql-query-library templates.

Acceptance criteria

• cloudflare.analytics_engine.sql_query resource published, select verb mapped to the GET operation
• FORMAT JSON requirement documented on the resource
• Example query in resource docs
• Verified against a live WAE dataset (rows returned match SQL API output for the same query)

References

• SQL API: https://developers.cloudflare.com/analytics/analytics-engine/sql-api/
• SQL reference: https://developers.cloudflare.com/analytics/analytics-engine/sql-reference/
• Upstream schema: https://github.com/cloudflare/api-schemas