Skip to content

Commit d7fd16e

Browse files
Document time arithmetic and fix typos in timestamp operations (#297)
Add Arithmetic section to timestamp-operations.malloynb documenting the `expr + N unit` / `expr - N unit` syntax for date and timestamp values. Add corresponding entry in the expressions.malloynb summary table. Also fix pre-existing typos: "funtion" → "function", wrong day-of-month result, and incorrect week truncation comment. Rename page title to "Timestamp and Date Operations". Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b66252f commit d7fd16e

2 files changed

Lines changed: 31 additions & 4 deletions

File tree

src/documentation/language/expressions.malloynb

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ the same syntax users are familiar with. However, Malloy also introduces several
2020
| [Pick expressions](#pick-expressions)<br/>Malloy's take on <code>CASE</code> statements | `pick 'S' when size < 3 else 'L'`<br/> |
2121
| [Time ranges](#time-ranges)<br/>Ranges with start and end or duration | `start_time for 3 hours`<br/>`@2003 for 10 months` <br/> `@2003 to @2005` |
2222
| [Numeric ranges](#numeric-ranges)<br/>Numeric ranges with start and end | `10 to 20` |
23+
| [Time arithmetic](timestamp-operations.malloynb#arithmetic)<br/>Add or subtract durations from times | `event_time + 3 days`<br/>`now - 30 days` |
2324
| [Time truncation](#time-truncation) | `event_time.quarter` <br/> `now.year` |
2425
| [Time extraction](#time-extraction)<br/>Extract one part of a time value | `day_of_year(event_time)` <br/> `minute(now)` |
2526
| [Interval extraction](#interval-extraction)<br/>Extract the interval between two times | `days(created_at to shipped_at)` |

src/documentation/language/timestamp-operations.malloynb

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
>>>markdown
2-
# Timestamp Operations
2+
# Timestamp and Date Operations
33

44
## Truncation
55

@@ -10,7 +10,7 @@ For truncation to a time unit (timeframe), use the period (`.`) operator followe
1010
`expr.minute` | 2021-08-06 00:36
1111
`expr.hour` | 2021-08-06 00:00
1212
`expr.day` | 2021-08-06 00:00
13-
`expr.week` | 2021-08-01 00:00 _(the week containing the 10th)_
13+
`expr.week` | 2021-08-01 00:00 _(the week containing the 6th)_
1414
`expr.month` | 2021-08-01 00:00
1515
`expr.quarter` | 2021-06-01 00:00
1616
`expr.year` | 2021-01-01 00:00
@@ -19,14 +19,14 @@ For truncation to a time unit (timeframe), use the period (`.`) operator followe
1919

2020
## Extraction
2121

22-
To extract an integer from a component of a timestamp, malloy uses the time unit (timeframe) in the form of a funtion call.
22+
To extract an integer from a component of a timestamp, malloy uses the time unit (timeframe) in the form of a function call.
2323

2424
The "Result" column uses a value of `@2021-08-06 00:55:05` for `expr`.
2525

2626
expression | meaning | result
2727
---- | ---- | ----
2828
`day_of_year(expr)` | day of year, 1-365 | 218
29-
`day(expr)` | day of month 1-31 | 5
29+
`day(expr)` | day of month 1-31 | 6
3030
`day_of_week(expr)` | day of week 1-7 | 6 _(Note: 1 represents Sunday)_
3131
`week(expr)` | week in year, 1-53 | 31
3232
`quarter(expr)` | quarter in year 1-4 | 3
@@ -63,3 +63,29 @@ expression | meaning
6363
`timestamptz_value::timestamp` | Converts timestamptz to timestamp in the query timezone
6464

6565
* See [Timezones](timezones.malloynb) for more information on how timezones interact with casting.
66+
67+
## Arithmetic
68+
69+
Add or subtract a duration from a timestamp or date using `+` or `-` with a number and time unit.
70+
71+
expression | result (expr = @2021-02-24 03:05:06)
72+
---- | ----
73+
`expr + 10 seconds` | 2021-02-24 03:05:16
74+
`expr - 6 seconds` | 2021-02-24 03:05:00
75+
`expr + 10 minutes` | 2021-02-24 03:15:06
76+
`expr + 10 hours` | 2021-02-24 13:05:06
77+
`expr + 3 days` | 2021-02-27 03:05:06
78+
`expr - 2 weeks` | 2021-02-10 03:05:06
79+
`expr + 9 months` | 2021-11-24 03:05:06
80+
`expr + 2 quarters` | 2021-08-24 03:05:06
81+
`expr + 10 years` | 2031-02-24 03:05:06
82+
83+
The supported time units are `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `quarters`, and `years`. Both singular and plural forms are accepted (e.g. `1 day` or `3 days`).
84+
85+
Date arithmetic works on both timestamps and dates. The units `seconds`, `minutes`, and `hours` can only be used with timestamps — using them with a date value will produce a compile error.
86+
87+
This is commonly used with `now` for relative time filters:
88+
89+
```
90+
where: event_date > now - 30 days
91+
```

0 commit comments

Comments
 (0)