Skip to content

Commit 8b550ba

Browse files
tothmanotothmano
authored
Add 4 set functions and 3 unixtime functions (#292)
1 parent 81bc3da commit 8b550ba

11 files changed

+724
-18
lines changed

‎apl/scalar-functions/datetime-functions.mdx

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,22 @@ The table summarizes the datetime functions available in APL.
2020
| [endofyear](#endofyear) | Returns the end of the year containing the date |
2121
| [getmonth](#getmonth) | Get the month number (1-12) from a datetime. |
2222
| [getyear](#getyear) | Returns the year part of the `datetime` argument. |
23-
| [hourofday](#hourofday) | Returns the integer number representing the hour number of the given date |
24-
| [endofday](#endofday) | Returns the end of the day containing the date |
23+
| [hourofday](#hourofday) | Returns the integer number representing the hour number of the given date. |
24+
| [endofday](#endofday) | Returns the end of the day containing the date. |
2525
| [now](#now) | Returns the current UTC clock time, optionally offset by a given timespan. |
26-
| [endofmonth](#endofmonth) | Returns the end of the month containing the date |
26+
| [endofmonth](#endofmonth) | Returns the end of the month containing the date. |
2727
| [endofweek](#endofweek) | Returns the end of the week containing the date. |
2828
| [monthofyear](#monthofyear) | Returns the integer number represents the month number of the given year. |
29-
| [startofday](#startofday) | Returns the start of the day containing the date |
30-
| [startofmonth](#startofmonth) | Returns the start of the month containing the date |
31-
| [startofweek](#startofweek) | Returns the start of the week containing the date |
32-
| [startofyear](#startofyear) | Returns the start of the year containing the date |
33-
| [unixtime_seconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime) | Converts a Unix timestamp to an APL `datetime` value. |
34-
35-
- We support the ISO 8601 format, which is the standard format for representing dates and times in the Gregorian calendar. [Check them out here](/apl/data-types/scalar-data-types#supported-formats)
29+
| [startofday](#startofday) | Returns the start of the day containing the date. |
30+
| [startofmonth](#startofmonth) | Returns the start of the month containing the date. |
31+
| [startofweek](#startofweek) | Returns the start of the week containing the date. |
32+
| [startofyear](#startofyear) | Returns the start of the year containing the date. |
33+
| [unixtime_microseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-microseconds-todatetime) | Converts a Unix timestamp expressed in whole microseconds to an APL `datetime` value. |
34+
| [unixtime_milliseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-milliseconds-todatetime) | Converts a Unix timestamp expressed in whole milliseconds to an APL `datetime` value. |
35+
| [unixtime_nanoseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-nanoseconds-todatetime) | Converts a Unix timestamp expressed in whole nanoseconds to an APL `datetime` value. |
36+
| [unixtime_seconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime) | Converts a Unix timestamp expressed in whole seconds to an APL `datetime` value. |
37+
38+
We support the ISO 8601 format, which is the standard format for representing dates and times in the Gregorian calendar. [Check them out here](/apl/data-types/scalar-data-types#supported-formats)
3639

3740
## ago
3841

‎apl/scalar-functions/datetime-functions/unixtime-microseconds-todatetime.mdx

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: unixtime_microseconds_todatetime
3+
description: 'This page explains how to use the unixtime_microseconds_todatetime function in APL.'
4+
---
5+
6+
`unixtime_microseconds_todatetime` converts a Unix timestamp that is expressed in whole microseconds since 1970-01-01 00:00:00 UTC to an APL `datetime` value.
7+
8+
Use the function whenever you ingest data that stores time as epoch microseconds (for example, JSON logs from NGINX or metrics that follow the StatsD line protocol). Converting to `datetime` lets you bin, filter, and visualize events with the rest of your time-series data.
9+
10+
## For users of other query languages
11+
12+
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
13+
14+
<AccordionGroup>
15+
<Accordion title="Splunk SPL users">
16+
17+
In Splunk, you often convert epoch values with `eval ts=strftime(_time,"%Y-%m-%dT%H:%M:%S.%6N")`. In APL, the conversion happens with a scalar function, so you can use it inline wherever a `datetime` literal is accepted.
18+
19+
<CodeGroup>
20+
21+
```sql Splunk example
22+
| eval eventTime=strftime( micro_ts/1000000 , "%Y-%m-%dT%H:%M:%S.%6N")
23+
````
24+
25+
```kusto APL equivalent
26+
| extend eventTime = unixtime_microseconds_todatetime(micro_ts)
27+
```
28+
29+
</CodeGroup>
30+
31+
</Accordion>
32+
<Accordion title="ANSI SQL users">
33+
34+
Standard SQL engines rarely expose microsecond-epoch helpers. You usually cast or divide by 1,000,000 and add an interval. APL gives you a dedicated scalar function that returns a native `datetime`, which then supports the full date-time syntax.
35+
36+
<CodeGroup>
37+
38+
```sql SQL example
39+
SELECT TIMESTAMP '1970-01-01 00:00:00' + micro_ts / 1000000 * INTERVAL '1 second' FROM events;
40+
```
41+
42+
```kusto APL equivalent
43+
['events']
44+
| extend eventTime = unixtime_microseconds_todatetime(micro_ts)
45+
```
46+
47+
</CodeGroup>
48+
49+
</Accordion>
50+
</AccordionGroup>
51+
52+
## Usage
53+
54+
### Syntax
55+
56+
```kusto
57+
unixtime_microseconds_todatetime(microseconds)
58+
```
59+
60+
### Parameters
61+
62+
| Name | Type | Description |
63+
| --------- | --------------- | ------------------------------------------------------------------ |
64+
| `microseconds` | `int` or `long` | Whole microseconds since the Unix epoch. Fractional input is truncated. |
65+
66+
### Returns
67+
68+
A `datetime` value that represents the given epoch microseconds at UTC precision (1 microsecond).
69+
70+
## Use case example
71+
72+
The HTTP access logs keep the timestamp as epoch microseconds and you want to convert the values to datetime.
73+
74+
**Query**
75+
76+
```kusto
77+
['sample-http-logs']
78+
| extend epoch_microseconds = toint(datetime_diff('Microsecond', _time, datetime(1970-01-01)))
79+
| extend datetime_standard = unixtime_microseconds_todatetime(epoch_microseconds)
80+
| project _time, epoch_microseconds, datetime_standard
81+
```
82+
83+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20extend%20epoch_microseconds%20%3D%20toint(datetime_diff('Microsecond'%2C%20_time%2C%20datetime(1970-01-01)))%20%7C%20extend%20datetime_standard%20%3D%20unixtime_microseconds_todatetime(epoch_microseconds)%20%7C%20project%20_time%2C%20epoch_microseconds%2C%20datetime_standard%22%7D)
84+
85+
**Output**
86+
87+
| _time | epoch_microseconds | datetime_standard |
88+
|------------------|----------------------|-----------------------------|
89+
| May 15, 12:09:22 | 1,747,303,762 | 2025-05-15T10:09:22Z |
90+
91+
This query converts the timestamp to epoch microseconds and then back to datetime for demonstration purposes.
92+
93+
## List of related functions
94+
95+
- [unixtime_milliseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-milliseconds-todatetime): Converts a Unix timestamp expressed in whole milliseconds to an APL `datetime` value.
96+
- [unixtime_nanoseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-nanoseconds-todatetime): Converts a Unix timestamp expressed in whole nanoseconds to an APL `datetime` value.
97+
- [unixtime_seconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime): Converts a Unix timestamp expressed in whole seconds to an APL `datetime` value.

‎apl/scalar-functions/datetime-functions/unixtime-milliseconds-todatetime.mdx

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: unixtime_milliseconds_todatetime
3+
description: 'This page explains how to use the unixtime_milliseconds_todatetime function in APL.'
4+
---
5+
6+
`unixtime_milliseconds_todatetime` converts a Unix timestamp that is expressed in whole milliseconds since 1970-01-01 00:00:00 UTC to an APL `datetime` value.
7+
8+
Use the function whenever you ingest data that stores time as epoch milliseconds (for example, JSON logs from NGINX or metrics that follow the StatsD line protocol). Converting to `datetime` lets you bin, filter, and visualize events with the rest of your time-series data.
9+
10+
## For users of other query languages
11+
12+
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
13+
14+
<AccordionGroup>
15+
<Accordion title="Splunk SPL users">
16+
17+
`unixtime_milliseconds_todatetime()` corresponds to an `eval` expression that divides the epoch value by 1000 and formats the result. You skip both steps in APL because the function takes milliseconds directly.
18+
19+
<CodeGroup>
20+
21+
```sql Splunk example
22+
| eval timestamp=strftime(epoch_ms/1000,"%Y-%m-%dT%H:%M:%SZ")
23+
````
24+
25+
```kusto APL equivalent
26+
| extend timestamp=unixtime_milliseconds_todatetime(epoch_ms)
27+
```
28+
29+
</CodeGroup>
30+
31+
</Accordion>
32+
<Accordion title="ANSI SQL users">
33+
34+
The function plays the same role as `FROM_UNIXTIME()` or `TO_TIMESTAMP()` in SQL dialects. In APL, you don’t divide by 1,000 because the function expects milliseconds.
35+
36+
<CodeGroup>
37+
38+
```sql SQL example
39+
SELECT FROM_UNIXTIME(epoch_ms/1000) AS timestamp FROM requests;
40+
```
41+
42+
```kusto APL equivalent
43+
['sample-http-logs']
44+
| extend timestamp=unixtime_milliseconds_todatetime(epoch_ms)
45+
```
46+
47+
</CodeGroup>
48+
49+
</Accordion>
50+
</AccordionGroup>
51+
52+
## Usage
53+
54+
### Syntax
55+
56+
```kusto
57+
unixtime_milliseconds_todatetime(milliseconds)
58+
```
59+
60+
### Parameters
61+
62+
| Name | Type | Description |
63+
| --------- | --------------- | ------------------------------------------------------------------ |
64+
| `milliseconds` | `int` or `long` | Whole milliseconds since the Unix epoch. Fractional input is truncated. |
65+
66+
### Returns
67+
68+
A `datetime` value that represents the given epoch milliseconds at UTC precision (1 millisecond).
69+
70+
## Use case example
71+
72+
The HTTP access logs keep the timestamp as epoch milliseconds and you want to convert the values to datetime.
73+
74+
**Query**
75+
76+
```kusto
77+
['sample-http-logs']
78+
| extend epoch_milliseconds = toint(datetime_diff('Millisecond', _time, datetime(1970-01-01)))
79+
| extend datetime_standard = unixtime_milliseconds_todatetime(epoch_milliseconds)
80+
| project _time, epoch_milliseconds, datetime_standard
81+
```
82+
83+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20extend%20epoch_milliseconds%20%3D%20toint(datetime_diff('Millisecond'%2C%20_time%2C%20datetime(1970-01-01)))%20%7C%20extend%20datetime_standard%20%3D%20unixtime_milliseconds_todatetime(epoch_milliseconds)%20%7C%20project%20_time%2C%20epoch_milliseconds%2C%20datetime_standard%22%7D)
84+
85+
**Output**
86+
87+
| _time | epoch_milliseconds | datetime_standard |
88+
|------------------|----------------------|-----------------------------|
89+
| May 15, 12:09:22 | 1,747,303,762 | 2025-05-15T10:09:22Z |
90+
91+
This query converts the timestamp to epoch milliseconds and then back to datetime for demonstration purposes.
92+
93+
## List of related functions
94+
95+
- [unixtime_microseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-microseconds-todatetime): Converts a Unix timestamp expressed in whole microseconds to an APL `datetime` value.
96+
- [unixtime_nanoseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-nanoseconds-todatetime): Converts a Unix timestamp expressed in whole nanoseconds to an APL `datetime` value.
97+
- [unixtime_seconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime): Converts a Unix timestamp expressed in whole seconds to an APL `datetime` value.

‎apl/scalar-functions/datetime-functions/unixtime-nanoseconds-todatetime.mdx

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: unixtime_nanoseconds_todatetime
3+
description: 'This page explains how to use the unixtime_nanoseconds_todatetime function in APL.'
4+
---
5+
6+
`unixtime_nanoseconds_todatetime` converts a Unix timestamp that is expressed in whole nanoseconds since 1970-01-01 00:00:00 UTC to an APL `datetime` value.
7+
8+
Use the function whenever you ingest data that stores time as epoch nanoseconds (for example, JSON logs from NGINX or metrics that follow the StatsD line protocol). Converting to `datetime` lets you bin, filter, and visualize events with the rest of your time-series data.
9+
10+
## For users of other query languages
11+
12+
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
13+
14+
<AccordionGroup>
15+
<Accordion title="Splunk SPL users">
16+
17+
Splunk SPL usually stores `_time` in seconds and uses functions such as `strftime` or `strptime` for conversion. In APL, you pass the nanosecond integer directly to `unixtime_nanoseconds_todatetime`, so you don’t divide by 1,000,000,000 first.
18+
19+
<CodeGroup>
20+
21+
```sql Splunk example
22+
| eval event_time = strftime(epoch_ns/1000000000, "%Y-%m-%dT%H:%M:%S.%N%z")
23+
````
24+
25+
```kusto APL equivalent
26+
| extend event_time = unixtime_nanoseconds_todatetime(epoch_ns)
27+
```
28+
29+
</CodeGroup>
30+
31+
</Accordion>
32+
<Accordion title="ANSI SQL users">
33+
34+
Many SQL engines use `TO_TIMESTAMP_LTZ()` or similar functions that expect seconds or microseconds. In APL, you pass the nanosecond value directly, and the function returns a `datetime` (UTC).
35+
36+
<CodeGroup>
37+
38+
```sql SQL example
39+
SELECT TO_TIMESTAMP_LTZ(epoch_ns/1e9) AS event_time
40+
FROM events;
41+
```
42+
43+
```kusto APL equivalent
44+
events
45+
| extend event_time = unixtime_nanoseconds_todatetime(epoch_ns)
46+
```
47+
48+
</CodeGroup>
49+
50+
</Accordion>
51+
</AccordionGroup>
52+
53+
## Usage
54+
55+
### Syntax
56+
57+
```kusto
58+
unixtime_nanoseconds_todatetime(nanoseconds)
59+
```
60+
61+
### Parameters
62+
63+
| Name | Type | Description |
64+
| --------- | --------------- | ------------------------------------------------------------------ |
65+
| `nanoseconds` | `int` or `long` | Whole nanoseconds since the Unix epoch. Fractional input is truncated. |
66+
67+
### Returns
68+
69+
A `datetime` value that represents the given epoch nanoseconds at UTC precision (1 nanosecond).
70+
71+
## Use case example
72+
73+
The HTTP access logs keep the timestamp as epoch nanoseconds and you want to convert the values to datetime.
74+
75+
**Query**
76+
77+
```kusto
78+
['sample-http-logs']
79+
| extend epoch_nanoseconds = toint(datetime_diff('Nanosecond', _time, datetime(1970-01-01)))
80+
| extend datetime_standard = unixtime_nanoseconds_todatetime(epoch_nanoseconds)
81+
| project _time, epoch_nanoseconds, datetime_standard
82+
```
83+
84+
[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20extend%20epoch_nanoseconds%20%3D%20toint(datetime_diff('Nanosecond'%2C%20_time%2C%20datetime(1970-01-01)))%20%7C%20extend%20datetime_standard%20%3D%20unixtime_nanoseconds_todatetime(epoch_nanoseconds)%20%7C%20project%20_time%2C%20epoch_nanoseconds%2C%20datetime_standard%22%7D)
85+
86+
**Output**
87+
88+
| _time | epoch_nanoseconds | datetime_standard |
89+
|------------------|----------------------|-----------------------------|
90+
| May 15, 12:09:22 | 1,747,303,762 | 2025-05-15T10:09:22Z |
91+
92+
This query converts the timestamp to epoch nanoseconds and then back to datetime for demonstration purposes.
93+
94+
## List of related functions
95+
96+
- [unixtime_microseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-microseconds-todatetime): Converts a Unix timestamp expressed in whole microseconds to an APL `datetime` value.
97+
- [unixtime_milliseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-milliseconds-todatetime): Converts a Unix timestamp expressed in whole milliseconds to an APL `datetime` value.
98+
- [unixtime_seconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime): Converts a Unix timestamp expressed in whole seconds to an APL `datetime` value.

‎apl/scalar-functions/datetime-functions/unixtime-seconds-todatetime.mdx

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,11 @@ If you come from other query languages, this section explains how to adjust your
1919
<CodeGroup>
2020

2121
```sql Splunk example
22-
... | eval event_time = strftime(epoch, "%Y-%m-%dT%H:%M:%S")
22+
eval event_time = strftime(epoch, "%Y-%m-%dT%H:%M:%S")
2323
````
2424

2525
```kusto APL equivalent
26-
...
27-
| extend event_time = unixtime_seconds_todatetime(epoch)
26+
extend event_time = unixtime_seconds_todatetime(epoch)
2827
```
2928

3029
</CodeGroup>
@@ -90,3 +89,9 @@ The HTTP access logs keep the timestamp as epoch seconds and you want to convert
9089
| May 15, 12:09:22 | 1,747,303,762 | 2025-05-15T10:09:22Z |
9190

9291
This query converts the timestamp to epoch seconds and then back to datetime for demonstration purposes.
92+
93+
## List of related functions
94+
95+
- [unixtime_microseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-microseconds-todatetime): Converts a Unix timestamp expressed in whole microseconds to an APL `datetime` value.
96+
- [unixtime_milliseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-milliseconds-todatetime): Converts a Unix timestamp expressed in whole milliseconds to an APL `datetime` value.
97+
- [unixtime_nanoseconds_todatetime](/apl/scalar-functions/datetime-functions/unixtime-nanoseconds-todatetime): Converts a Unix timestamp expressed in whole nanoseconds to an APL `datetime` value.

0 commit comments

Comments
 (0)