SQL reference
Use this reference when writing queries in Telemetry's Explorer, dashboards, alerts, and Query API. It describes Telemetry's SQL engine, based on our vendored Apache DataFusion fork and the functions enabled by Telemetry. Examples assume the named tables and fields exist in your workspace; replace them with your own schema.
Start with a bounded query
SELECT
date_trunc('hour', timestamp_utc) AS hour,
COUNT(*) AS events
FROM product_events
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY date_trunc('hour', timestamp_utc)
ORDER BY hour;
timestamp_utc is Telemetry's native event-time column. Filter it directly to bound the data read. LIMIT bounds returned rows; it does not necessarily bound the rows scanned or aggregated.
Reference sections
| Section | What you will find |
|---|---|
| Query syntax | SELECT, identifiers, CTEs, joins, grouping, subqueries, sorting, and set operations |
| Data types | Casts, strings, numbers, timestamps, intervals, arrays, structs, and nulls |
| Operators and expressions | Arithmetic, comparison, predicates, CASE, patterns, and literals |
| Scalar functions | Date/time, string, numeric, conditional, and conversion functions |
| String functions | Text search, extraction, formatting, and regular expressions |
| Date and time functions | Timestamp conversion, calendar parts, time buckets, and intervals |
| Aggregate functions | Counts, sums, distinct values, percentiles, and statistics |
| Window functions | Ranking, lag/lead, running totals, and window frames |
| Nested data | Array, struct, and map functions |
For worked analytics queries, visit the SQL recipe library.
Telemetry-specific behavior
Field names preserve case. Telemetry does not lowercase unquoted identifiers. If your field is userId, query userId or "userId", not userid. SQL keywords remain case-insensitive. Double quotes delimit identifiers; single quotes delimit strings.
Nested objects are structured values. Use data.customer.id or data['customer']['id'] to read a nested field. "data.customer.id" names one column whose literal name contains dots; it does not mean the same thing as a nested path. See nested fields in query syntax.
Schema evolution preserves missing values. When a nested field exists in the current table schema but is absent in older stored data, those rows read as typed NULL. A misspelled field or a path that is absent from the table schema can still fail planning. Use IS NULL to inspect absence and COALESCE only when a default is meaningful.
Use the native event time. timestamp_utc is a millisecond timestamp with the UTC timezone. The input timestamp field may have a different representation. Use timestamp_utc for filtering, ordering, bucketing, and time arithmetic.
Scope and compatibility
This reference covers analytical queries against Telemetry tables. Ingestion and table management use Telemetry's APIs and product controls. SQL syntax available in the underlying engine, such as external-table creation, filesystem access, server configuration, or data mutation, is not a promise that the hosted Query API exposes that capability.
Telemetry SQL has familiar PostgreSQL-style expressions, but it is not PostgreSQL. Do not assume that PostgreSQL extensions, JSON operators, MySQL date functions, or warehouse-specific SQL are available. Check the function sections for names and signatures. In particular, a structured event field is not a PostgreSQL JSONB value.
This reference is maintained against Telemetry's vendored engine, rather than the latest upstream documentation. Apache DataFusion is licensed under Apache License 2.0; the function reference retains upstream attribution where documentation is adapted.