Skip to content

Commit e26eaeb

Browse files
46bit46bit
committed
DS-15647 DS-15648: Document aggregate-if and date/time function additions to the WAE SQL API
This commit adds the following function additions to the docs: - `countIf` - `sumIf` - `avgIf` - `toYear` - `toMonth` - `toDayOfMonth` - `toHour` - `toMinute` - `toSecond` - `toStartOfYear` - `toStartOfMonth` - `toStartOfDay` - `toStartOfHour` - `toStartOfFifteenMinutes` - `toStartOfMinute` - `today` This commit reorders the date/time docs page to be in approximate alphabetical order, which works much better than just appending the functions to the end.
1 parent fd84924 commit e26eaeb

File tree

2 files changed

+297
-21
lines changed

2 files changed

+297
-21
lines changed

‎src/content/docs/analytics/analytics-engine/sql-reference/aggregate-functions.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,3 +248,57 @@ SELECT topKWeighted(double1, _sample_interval) FROM my_dataset
248248
-- find the 15 most common values of <blob1>, weighted by `_sample_interval`
249249
SELECT topKWeighted(15)(blob1, _sample_interval) FROM my_dataset
250250
```
251+
252+
## countIf <Badge text="New" variant="tip" size="small" />
253+
254+
Usage:
255+
256+
```sql
257+
countIf(<expr>)
258+
```
259+
260+
`countIf` is an aggregation function that returns the number of rows in the results set,
261+
but only counting rows where a provided expression evaluates to true.
262+
263+
Example:
264+
265+
```sql
266+
-- return the number of rows where `double1` is greater than 5
267+
countIf(double1 > 5)
268+
```
269+
270+
## sumIf <Badge text="New" variant="tip" size="small" />
271+
272+
Usage:
273+
274+
```sql
275+
sumIf(<expr>, <expr>)
276+
```
277+
278+
`sumIf` is an aggregation function that returns the sum of a first expression across all rows in the results set,
279+
but only including rows where a second expression evaluates to true.
280+
281+
Example:
282+
283+
```sql
284+
-- return the sum of column `item_cost` of all items where another column `in_stock` is not zero
285+
sumIf(item_cost, in_stock > 0)
286+
```
287+
288+
## avgIf <Badge text="New" variant="tip" size="small" />
289+
290+
Usage:
291+
292+
```sql
293+
avgIf(<expr>, <expr>)
294+
```
295+
296+
`avgIf` is an aggregation function that returns the mean of an expression across all rows in the results set,
297+
but only including rows where a second expression evaluates to true.
298+
299+
Example:
300+
301+
```sql
302+
-- return the mean of column `item_cost` where another column `in_stock` is not zero
303+
avgIf(item_cost, in_stock > 0)
304+
```

‎src/content/docs/analytics/analytics-engine/sql-reference/date-time-functions.mdx‎

Lines changed: 243 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,55 @@ head:
99

1010
---
1111

12+
import { Badge } from "~/components"
13+
14+
## formatDateTime
15+
16+
Usage:
17+
18+
```sql
19+
formatDateTime(<datetime expression>, <format string>[, <timezone string>])
20+
```
21+
22+
`formatDateTime` prints a datetime as a string according to a provided format string. Refer to
23+
[ClickHouse's documentation](https://clickhouse.com/docs/en/sql-reference/functions/date-time-functions/#formatdatetime)
24+
for a list of supported formatting options.
25+
26+
Examples:
27+
28+
```sql
29+
-- prints the current YYYY-MM-DD in UTC
30+
formatDateTime(now(), '%Y-%m-%d')
31+
32+
-- prints YYYY-MM-DD in the datetime's timezone
33+
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d')
34+
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d')
35+
36+
-- prints YYYY-MM-DD in UTC
37+
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d', 'Etc/UTC')
38+
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d', 'Etc/UTC')
39+
```
40+
41+
## now
42+
43+
Usage:
44+
45+
```sql
46+
now()
47+
```
48+
49+
Returns the current time as a DateTime.
50+
51+
## today <Badge text="New" variant="tip" size="small" />
52+
53+
Usage:
54+
55+
```sql
56+
now()
57+
```
58+
59+
Returns the current date as a `Date`.
60+
1261
## toDateTime
1362

1463
Usage:
@@ -37,58 +86,123 @@ toDateTime('1981-04-12 12:00:04') -- string with datetime in 'YYYY-MM-DD hh:mm:s
3786
toDateTime('2022-12-01 16:17:00', 'America/New_York')
3887
```
3988

40-
## now
89+
## toYear <Badge text="New" variant="tip" size="small" />
4190

4291
Usage:
4392

4493
```sql
45-
now()
94+
toYear(<datetime>)
4695
```
4796

48-
Returns the current time as a DateTime.
97+
`toYear` returns the year of a datetime.
4998

50-
## toUnixTimestamp
99+
Examples:
100+
101+
```sql
102+
-- returns the number 2025
103+
toYear(toDateTime('2025-10-27 00:00:00'))
104+
```
105+
106+
## toMonth <Badge text="New" variant="tip" size="small" />
51107

52108
Usage:
53109

54110
```sql
55-
toUnixTimestamp(<datetime>)
111+
toMonth(<datetime>)
56112
```
57113

58-
`toUnixTimestamp` converts a datetime into an integer unix timestamp.
114+
`toMonth` returns the year of a datetime.
59115

60116
Examples:
61117

62118
```sql
63-
-- get the current unix timestamp
64-
toUnixTimestamp(now())
119+
-- returns the number 10
120+
toMonth(toDateTime('2025-10-27 00:00:00'))
65121
```
66122

67-
## formatDateTime
123+
## toDayOfMonth <Badge text="New" variant="tip" size="small" />
68124

69125
Usage:
70126

71127
```sql
72-
formatDateTime(<datetime expression>, <format string>[, <timezone string>])
128+
toDayOfMonth(<datetime>)
73129
```
74130

75-
`formatDateTime` prints a datetime as a string according to a provided format string. Refer to
76-
[ClickHouse's documentation](https://clickhouse.com/docs/en/sql-reference/functions/date-time-functions/#formatdatetime)
77-
for a list of supported formatting options.
131+
`toDayOfMonth` returns the day of the month from a datetime.
78132

79133
Examples:
80134

81135
```sql
82-
-- prints the current YYYY-MM-DD in UTC
83-
formatDateTime(now(), '%Y-%m-%d')
136+
-- returns the number 27
137+
toDayOfMonth(toDateTime('2025-10-27 00:00:00'))
138+
```
84139

85-
-- prints YYYY-MM-DD in the datetime's timezone
86-
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d')
87-
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d')
140+
## toHour <Badge text="New" variant="tip" size="small" />
88141

89-
-- prints YYYY-MM-DD in UTC
90-
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d', 'Etc/UTC')
91-
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d', 'Etc/UTC')
142+
Usage:
143+
144+
```sql
145+
toHour(<datetime>)
146+
```
147+
148+
`toHour` returns the hour of the day from a datetime.
149+
150+
Examples:
151+
152+
```sql
153+
-- returns the number 9
154+
toHour(toDateTime('2025-10-27 09:11:13'))
155+
```
156+
157+
## toMinute <Badge text="New" variant="tip" size="small" />
158+
159+
Usage:
160+
161+
```sql
162+
toMinute(<datetime>)
163+
```
164+
165+
`toMinute` returns the minute of the hour from a datetime.
166+
167+
Examples:
168+
169+
```sql
170+
-- returns the number 11
171+
toMinute(toDateTime('2025-10-27 09:11:13'))
172+
```
173+
174+
## toSecond <Badge text="New" variant="tip" size="small" />
175+
176+
Usage:
177+
178+
```sql
179+
toSecond(<datetime>)
180+
```
181+
182+
`toSecond` returns the second of the minute from a datetime.
183+
184+
Examples:
185+
186+
```sql
187+
-- returns the number 13
188+
toSecond(toDateTime('2025-10-27 09:11:13'))
189+
```
190+
191+
## toUnixTimestamp
192+
193+
Usage:
194+
195+
```sql
196+
toUnixTimestamp(<datetime>)
197+
```
198+
199+
`toUnixTimestamp` converts a datetime into an integer unix timestamp.
200+
201+
Examples:
202+
203+
```sql
204+
-- get the current unix timestamp
205+
toUnixTimestamp(now())
92206
```
93207

94208
## toStartOfInterval
@@ -119,3 +233,111 @@ FROM your_dataset
119233
GROUP BY hour
120234
ORDER BY hour ASC
121235
```
236+
237+
## toStartOfYear <Badge text="New" variant="tip" size="small" />
238+
239+
Usage:
240+
241+
```sql
242+
toStartOfYear(<datetime>)
243+
```
244+
245+
`toStartOfYear` rounds down a datetime to the nearest start of year. This can be useful
246+
for grouping data into equal-sized time ranges.
247+
248+
Examples:
249+
250+
```sql
251+
-- round a timestamp down to 2025-01-01 00:00:00
252+
toStartOfYear(toDateTime('2025-10-27 00:00:00'))
253+
```
254+
255+
## toStartOfMonth <Badge text="New" variant="tip" size="small" />
256+
257+
Usage:
258+
259+
```sql
260+
toStartOfMonth(<datetime>)
261+
```
262+
263+
`toStartOfMonth` rounds down a datetime to the nearest start of month. This can be useful
264+
for grouping data into equal-sized time ranges.
265+
266+
Examples:
267+
268+
```sql
269+
-- round a timestamp down to 2025-10-01 00:00:00
270+
toStartOfMonth(toDateTime('2025-10-27 00:00:00'))
271+
```
272+
273+
## toStartOfDay <Badge text="New" variant="tip" size="small" />
274+
275+
Usage:
276+
277+
```sql
278+
toStartOfDay(<datetime>)
279+
```
280+
281+
`toStartOfDay` rounds down a datetime to the nearest start of day. This can be useful
282+
for grouping data into equal-sized time ranges.
283+
284+
Examples:
285+
286+
```sql
287+
-- round a timestamp down to 2025-10-27 00:00:00
288+
toStartOfDay(toDateTime('2025-10-27 00:00:00'))
289+
```
290+
291+
## toStartOfHour <Badge text="New" variant="tip" size="small" />
292+
293+
Usage:
294+
295+
```sql
296+
toStartOfHour(<datetime>)
297+
```
298+
299+
`toStartOfHour` rounds down a datetime to the nearest start of hour. This can be useful
300+
for grouping data into equal-sized time ranges.
301+
302+
Examples:
303+
304+
```sql
305+
-- round a timestamp down to 2025-10-27 16:00:00
306+
toStartOfHour(toDateTime('2025-10-27 16:55:25'))
307+
```
308+
309+
## toStartOfFifteenMinutes <Badge text="New" variant="tip" size="small" />
310+
311+
Usage:
312+
313+
```sql
314+
toStartOfFifteenMinutes(<datetime>)
315+
```
316+
317+
`toStartOfFifteenMinutes` rounds down a datetime to the nearest fifteen minutes. This can be useful
318+
for grouping data into equal-sized time ranges.
319+
320+
Examples:
321+
322+
```sql
323+
-- round a timestamp down to 2025-10-27 16:45:00
324+
toStartOfFifteenMinutes(toDateTime('2025-10-27 16:55:25'))
325+
```
326+
327+
## toStartOfMinute <Badge text="New" variant="tip" size="small" />
328+
329+
Usage:
330+
331+
```sql
332+
toStartOfMinute(<datetime>)
333+
```
334+
335+
`toStartOfMinute` rounds down a datetime to the nearest minute. This can be useful
336+
for grouping data into equal-sized time ranges.
337+
338+
Examples:
339+
340+
```sql
341+
-- round a timestamp down to 2025-10-27 16:55:00
342+
toStartOfMinute(toDateTime('2025-10-27 16:55:25'))
343+
```

0 commit comments

Comments
 (0)