SQL language reference

The SQL API supports a read-only subset of SQL for analytics queries. SQL keywords and function names are case-insensitive. Dataset and field names are case-sensitive.

Every query must read one schema-qualified dataset and must include an account or zone scope and a lower time bound. For HTTP API requests, you can provide scope and time bounds in SQL or through the JSON request fields. Workers binding queries are the exception: the binding supplies account scope automatically, so include only the time bound in SQL. For example:

SELECT
  clientRequestHttpHost AS host,
  COUNT(*) AS requests
FROM events.httpRequests
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
GROUP BY clientRequestHttpHost
ORDER BY requests DESC
LIMIT 10

• Statements and clauses
• Operators
• Functions
• Data types and literals

The SQL API does not support arbitrary ClickHouse SQL. Unsupported features include:

• Data modification or definition statements, including INSERT, UPDATE, DELETE, CREATE, ALTER, and DROP.
• Joins, unions, common table expressions, and general subqueries. One restricted derived-table projection is supported.
• Window functions.
• Row-level SELECT DISTINCT. COUNT, SUM, and AVG support DISTINCT on unsampled datasets and Workers Analytics Engine datasets.
• FETCH. ClickHouse-backed datasets support OFFSET with LIMIT.
• EXPLAIN, ANALYZE, DESCRIBE, VALUES, and UNNEST.
• SIMILAR TO, LIKE ... ESCAPE, and user-authored casts.
• Aggregate FILTER and aggregate-local ORDER BY clauses.

The API returns an HTTP 422 response when a statement contains unsupported syntax.