Skip to content

Commit 09e9abb

Browse files
k-anshulk-anshul
authored
improvement to metrics sql docs (#9217)
* improvement to metrics sql docs * improvement to metrics sql docs
1 parent b3caa98 commit 09e9abb

1 file changed

Lines changed: 109 additions & 13 deletions

File tree

‎docs/docs/developers/build/metrics-view/metrics-sql.md‎

Lines changed: 109 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
title: Metrics SQL
2+
title: Metrics SQL
33
description: Query metrics views using SQL syntax
44
sidebar_label: Metrics SQL
55
---
66

77
You can write a SQL query referring to metrics definitions and dimensions defined in a metrics view.
88
It should have the following structure:
9-
9+
1010
```yaml
1111
type: api
1212
metrics_sql: SELECT publisher, domain, total_records FROM ad_bids_metrics
@@ -50,19 +50,116 @@ SELECT toUpper(publisher) AS publisher, domain AS domain, COUNT(*) AS total_reco
5050

5151
Queries executed via Metrics SQL are subject to the security policies and access controls defined in the metrics view YAML configuration, ensuring data security and compliance.
5252

53-
## Limitations
53+
## Supported SQL Features
5454

55-
Metrics SQL is specifically designed for querying metrics views and may not support all features found in standard SQL. Its primary focus is on providing an efficient and easy way to extract data within the constraints of metrics view configurations.
55+
### SELECT
5656

57-
## Supported SQL Features
57+
Reference dimensions and measures by name. The `date_trunc` function can be used to group a time dimension by a specific grain (and optionally aliased with `AS`):
58+
59+
```sql
60+
SELECT date_trunc('MONTH', timestamp) AS month, publisher, total_records FROM ad_bids_metrics
61+
```
5862

59-
- **SELECT** statements with plain `dimension` and `measure` references.
60-
- A single **FROM** clause referencing a `metrics view`.
61-
- **WHERE** clause that can reference selected `dimensions` only.
62-
- Operators in **WHERE** and **HAVING** clauses include `=`, `!=`, `>`, `>=`, `<`, `<=`, IN, LIKE, AND, OR, and parentheses for structuring the expression.
63-
- **HAVING** clause for filtering on aggregated results, referencing selected dimension and measure names. Supports the same expression capabilities as the WHERE clause.
64-
- **ORDER BY** clause for sorting the results.
65-
- **LIMIT** and **OFFSET** clauses for controlling the result set size and pagination.
63+
Supported grains: `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`.
64+
65+
### FROM
66+
67+
A single metrics view name. Joins and subqueries in the FROM clause are not supported.
68+
69+
### WHERE and HAVING
70+
71+
`WHERE` filters on dimensions; `HAVING` filters on aggregated measures. Both support the same operators and functions.
72+
73+
### ORDER BY, LIMIT, OFFSET
74+
75+
Standard SQL sorting and pagination clauses are supported:
76+
77+
```sql
78+
SELECT publisher, total_records FROM ad_bids_metrics
79+
ORDER BY total_records DESC
80+
LIMIT 20 OFFSET 40
81+
```
82+
83+
## Operators
84+
85+
The following operators are supported in `WHERE` and `HAVING` clauses:
86+
87+
| Operator |
88+
|----------|
89+
| `=`, `!=`, `<`, `<=`, `>`, `>=` |
90+
| `AND`, `OR`, `(` `)` |
91+
| `IN (...)`, `NOT IN (...)` |
92+
| `LIKE`, `NOT LIKE` (case-insensitive, `%` wildcard) |
93+
| `BETWEEN ... AND ...` |
94+
| `IS NULL`, `IS NOT NULL` |
95+
| `IS TRUE`, `IS FALSE`, `IS NOT TRUE`, `IS NOT FALSE` |
96+
97+
```sql
98+
SELECT publisher, total_records FROM ad_bids_metrics
99+
WHERE (publisher IS NOT NULL AND domain LIKE '%google%')
100+
OR publisher IN ('Yahoo', 'Microsoft')
101+
```
102+
103+
## Functions
104+
105+
### Time range functions
106+
107+
`time_range_start` and `time_range_end` resolve a Rill time expression against the metrics view's watermark and time range. They must be compared against the time dimension:
108+
109+
```sql
110+
SELECT publisher, total_records FROM ad_bids_metrics
111+
WHERE timestamp > time_range_start('7D as of watermark/D+1D')
112+
AND timestamp <= time_range_end('7D as of watermark/D+1D')
113+
```
114+
115+
### Interval arithmetic
116+
117+
Add or subtract an interval from a timestamp literal using `INTERVAL amount UNIT` syntax. Supported units: `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`.
118+
119+
```sql
120+
SELECT publisher, total_records FROM ad_bids_metrics
121+
WHERE timestamp > '2024-07-30' - INTERVAL 90 DAY
122+
```
123+
124+
### now()
125+
126+
Returns the current timestamp:
127+
128+
```sql
129+
SELECT publisher, total_records FROM ad_bids_metrics
130+
WHERE timestamp > now() - INTERVAL 7 DAY
131+
```
132+
133+
### CAST
134+
135+
Casting to `DATETIME` or `TIMESTAMP` is supported (other target types are not):
136+
137+
```sql
138+
SELECT publisher, total_records FROM ad_bids_metrics
139+
WHERE timestamp > CAST('2024-01-01' AS TIMESTAMP)
140+
```
141+
142+
## Subqueries
143+
144+
Subqueries are supported inside `IN` expressions. The subquery must select exactly one dimension from the same metrics view and can include its own `WHERE` and `HAVING` clauses:
145+
146+
```sql
147+
SELECT publisher, total_records FROM ad_bids_metrics
148+
WHERE publisher IN (
149+
SELECT publisher FROM ad_bids_metrics
150+
HAVING total_records > 100
151+
)
152+
```
153+
154+
Subqueries do not support `ORDER BY`, `LIMIT`, `DISTINCT`, window functions, joins, or CTEs.
155+
156+
## Limitations
157+
158+
- Only one metrics view can be queried per statement (no joins).
159+
- `SELECT *` is not supported; list dimensions and measures explicitly.
160+
- `GROUP BY` is implicit based on selected dimensions and cannot be specified manually.
161+
- Aggregate functions like `COUNT()` or `SUM()` cannot be used directly; reference predefined measures instead.
162+
- Set operations (`UNION`, `INTERSECT`, `EXCEPT`) and CTEs (`WITH`) are not supported.
66163

67164
:::warning
68165
The Metrics SQL feature is currently evolving. We are dedicated to enhancing the syntax by introducing additional SQL features, while striving to maintain support for existing syntax. However, please be advised that backward compatibility cannot be guaranteed at all times. Additionally, users should be aware that there may be untested edge cases in the current implementation. We appreciate your understanding as we work to refine and improve this feature.
@@ -71,4 +168,3 @@ Metrics SQL is specifically designed for querying metrics views and may not supp
71168
## Using Metrics SQL in custom APIs
72169

73170
To expose Metrics SQL queries as HTTP API endpoints, see the [Metrics SQL APIs](/developers/build/custom-apis/metrics-sql) guide. You can also add [dynamic templating](/developers/build/custom-apis/templating), [security rules](/developers/build/custom-apis/security), and [OpenAPI documentation](/developers/build/custom-apis/openapi) to your Metrics SQL APIs.
74-

0 commit comments

Comments
 (0)