Skip to content

Commit 6e61aea

Browse files
tothmanotothmano
authored
Add max_of, min_of, hash, unixtime_seconds_todatetime (#285)
1 parent 098a6bb commit 6e61aea

File tree

9 files changed

+598
-123
lines changed

9 files changed

+598
-123
lines changed

‎apl/scalar-functions/conditional-function.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ extend status_human_readable = case(
5454

5555
Evaluates the first argument (the predicate), and returns the value of either the second or third arguments. The second and third arguments must be of the same type.
5656

57+
The `iif` function is equivalent to the `iff` function.
58+
5759
### Arguments
5860

5961
- predicate: An expression that evaluates to a boolean value.

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

Lines changed: 44 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,40 @@
11
---
22
title: 'Datetime functions'
33
description: 'Learn how to use and combine different timespan functions in APL'
4-
sidebarTitle: Datetime
4+
sidebarTitle: Overview
55
tags:
66
['axiom documentation', 'documentation', 'axiom', 'hash_md5', 'hash_sha1', 'hash_256()']
77
---
88

9-
## DateTime/ Timespan functions
9+
The table summarizes the datetime functions available in APL.
1010

11-
| **Function Name** | **Description** |
11+
| Name | Description |
1212
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
13-
| [ago()](#ago) | Subtracts the given timespan from the current UTC clock time. |
14-
| [datetime_add()](#datetime-add) | Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime. |
15-
| [datetime_part()](#datetime-part) | Extracts the requested date part as an integer value. |
16-
| [datetime_diff()](#datetime-diff) | Calculates calendarian difference between two datetime values. |
17-
| [dayofmonth()](#dayofmonth) | Returns the integer number representing the day number of the given month |
18-
| [dayofweek()](#dayofweek) | Returns the integer number of days since the preceding Sunday, as a timespan. |
19-
| [dayofyear()](#dayofyear) | Returns the integer number represents the day number of the given year. |
20-
| [endofyear()](#endofyear) | Returns the end of the year containing the date |
21-
| [getmonth()](#getmonth) | Get the month number (1-12) from a datetime. |
22-
| [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 |
25-
| [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 |
27-
| [endofweek()](#endofweek) | Returns the end of the week containing the date. |
28-
| [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 |
13+
| [ago](#ago) | Subtracts the given timespan from the current UTC clock time. |
14+
| [datetime_add](#datetime-add) | Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime. |
15+
| [datetime_part](#datetime-part) | Extracts the requested date part as an integer value. |
16+
| [datetime_diff](#datetime-diff) | Calculates calendarian difference between two datetime values. |
17+
| [dayofmonth](#dayofmonth) | Returns the integer number representing the day number of the given month |
18+
| [dayofweek](#dayofweek) | Returns the integer number of days since the preceding Sunday, as a timespan. |
19+
| [dayofyear](#dayofyear) | Returns the integer number represents the day number of the given year. |
20+
| [endofyear](#endofyear) | Returns the end of the year containing the date |
21+
| [getmonth](#getmonth) | Get the month number (1-12) from a datetime. |
22+
| [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 |
25+
| [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 |
27+
| [endofweek](#endofweek) | Returns the end of the week containing the date. |
28+
| [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. |
3334

3435
- 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)
3536

36-
## ago()
37+
## ago
3738

3839
Subtracts the given timespan from the current UTC clock time.
3940

@@ -75,7 +76,7 @@ ago(3d)
7576
}
7677
```
7778

78-
## datetime_add()
79+
## datetime_add
7980

8081
Calculates a new datetime from a specified datepart multiplied by a specified amount, added to a specified datetime.
8182

@@ -110,7 +111,7 @@ datetime_add(period,amount,datetime)
110111
}
111112
```
112113

113-
## datetime_part()
114+
## datetime_part
114115

115116
Extracts the requested date part as an integer value.
116117

@@ -144,7 +145,7 @@ datetime_part(part,datetime)
144145
}
145146
```
146147

147-
## datetime_diff()
148+
## datetime_diff
148149

149150
Calculates calendarian difference between two datetime values.
150151

@@ -194,7 +195,7 @@ datetime_diff(period,datetime_1,datetime_2)
194195
}
195196
```
196197

197-
## dayofmonth()
198+
## dayofmonth
198199

199200
Returns the integer number representing the day number of the given month
200201

@@ -227,7 +228,7 @@ dayofmonth(a_date)
227228
}
228229
```
229230

230-
## dayofweek()
231+
## dayofweek
231232

232233
Returns the integer number of days since the preceding Sunday, as a timespan.
233234

@@ -260,7 +261,7 @@ dayofweek(a_date)
260261
}
261262
```
262263

263-
## dayofyear()
264+
## dayofyear
264265

265266
Returns the integer number represents the day number of the given year.
266267

@@ -293,7 +294,7 @@ dayofyear(a_date)
293294
}
294295
```
295296

296-
## endofyear()
297+
## endofyear
297298

298299
Returns the end of the year containing the date
299300

@@ -326,7 +327,7 @@ endofyear(date)
326327
}
327328
```
328329

329-
## getmonth()
330+
## getmonth
330331

331332
Get the month number (1-12) from a datetime.
332333

@@ -335,7 +336,7 @@ Get the month number (1-12) from a datetime.
335336
| extend get_specific_month = getmonth(datetime(2020-07-26T08:20))
336337
```
337338

338-
## getyear()
339+
## getyear
339340

340341
Returns the year part of the `datetime` argument.
341342

@@ -360,7 +361,7 @@ getyear(datetime())
360361
}
361362
```
362363

363-
## hourofday()
364+
## hourofday
364365

365366
Returns the integer number representing the hour number of the given date
366367

@@ -393,7 +394,7 @@ hourofday(a_date)
393394
}
394395
```
395396

396-
## endofday()
397+
## endofday
397398

398399
Returns the end of the day containing the date
399400

@@ -426,7 +427,7 @@ endofday(date)
426427
}
427428
```
428429

429-
## now()
430+
## now
430431

431432
Returns the current UTC clock time, optionally offset by a given timespan. This function can be used multiple times in a statement and the clock time being referenced will be the same for all instances.
432433

@@ -459,7 +460,7 @@ now([offset])
459460
}
460461
```
461462

462-
## endofmonth()
463+
## endofmonth
463464

464465
Returns the end of the month containing the date
465466

@@ -492,7 +493,7 @@ endofmonth(date)
492493
}
493494
```
494495

495-
## endofweek()
496+
## endofweek
496497

497498
Returns the end of the week containing the date
498499

@@ -525,7 +526,7 @@ endofweek(date)
525526
}
526527
```
527528

528-
## monthofyear()
529+
## monthofyear
529530

530531
Returns the integer number represents the month number of the given year.
531532

@@ -558,7 +559,7 @@ monthofyear(datetime("2018-11-21"))
558559
}
559560
```
560561

561-
## startofday()
562+
## startofday
562563

563564
Returns the start of the day containing the date
564565

@@ -591,7 +592,7 @@ startofday(datetime(2020-08-31))
591592
}
592593
```
593594

594-
## startofmonth()
595+
## startofmonth
595596

596597
Returns the start of the month containing the date
597598

@@ -635,7 +636,7 @@ A datetime representing the start of the month for the given date value
635636
}
636637
```
637638

638-
## startofweek()
639+
## startofweek
639640

640641
Returns the start of the week containing the date
641642

@@ -686,7 +687,7 @@ A datetime representing the start of the week for the given date value
686687
| extend start_of_the_week = startofweek(datetime(2018-06-11T00:00:00Z))
687688
```
688689

689-
## startofyear()
690+
## startofyear
690691

691692
Returns the start of the year containing the date
692693

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

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: unixtime_seconds_todatetime
3+
description: 'This page explains how to use the unixtime_seconds_todatetime function in APL.'
4+
---
5+
6+
`unixtime_seconds_todatetime` converts a Unix timestamp that is expressed in whole seconds since 1970-01-01 00:00:00 UTC to an APL [datetime value](/apl/data-types/scalar-data-types).
7+
8+
Use the function whenever you ingest data that stores time as epoch seconds (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_seconds_todatetime` replaces the combination of `eval strftime` / `strptime` that you normally use in Splunk. Pass the epoch value directly and APL returns a `datetime`.
18+
19+
<CodeGroup>
20+
21+
```sql Splunk example
22+
... | eval event_time = strftime(epoch, "%Y-%m-%dT%H:%M:%S")
23+
````
24+
25+
```kusto APL equivalent
26+
...
27+
| extend event_time = unixtime_seconds_todatetime(epoch)
28+
```
29+
30+
</CodeGroup>
31+
32+
</Accordion>
33+
<Accordion title="ANSI SQL users">
34+
35+
Most ANSI SQL engines call this conversion with `FROM_UNIXTIME` or `TO_TIMESTAMP`. The APL version has the same single-argument signature, returns a full `datetime`, and automatically interprets the input as seconds (not milliseconds).
36+
37+
<CodeGroup>
38+
39+
```sql SQL example
40+
SELECT TO_TIMESTAMP(epoch_seconds) AS event_time FROM events;
41+
```
42+
43+
```kusto APL equivalent
44+
['events']
45+
| extend event_time = unixtime_seconds_todatetime(epoch_seconds)
46+
```
47+
48+
</CodeGroup>
49+
50+
</Accordion>
51+
</AccordionGroup>
52+
53+
## Usage
54+
55+
### Syntax
56+
57+
```kusto
58+
unixtime_seconds_todatetime(seconds)
59+
```
60+
61+
### Parameters
62+
63+
| Name | Type | Description |
64+
| --------- | --------------- | ------------------------------------------------------------------ |
65+
| `seconds` | `int` or `long` | Whole seconds since the Unix epoch. Fractional input is truncated. |
66+
67+
### Returns
68+
69+
A `datetime` value that represents the given epoch seconds at UTC precision (1 second).
70+
71+
## Use case example
72+
73+
The HTTP access logs keep the timestamp as epoch seconds and you want to convert the values to datetime.
74+
75+
**Query**
76+
77+
```kusto
78+
['sample-http-logs']
79+
| extend epoch_seconds = toint(datetime_diff('Second', _time, datetime(1970-01-01)))
80+
| extend datetime_standard = unixtime_seconds_todatetime(epoch_seconds)
81+
| project _time, epoch_seconds, 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_seconds%20%3D%20toint(datetime_diff('Second'%2C%20_time%2C%20datetime(1970-01-01)))%20%7C%20extend%20datetime_standard%20%3D%20unixtime_seconds_todatetime(epoch_seconds)%20%7C%20project%20_time%2C%20epoch_seconds%2C%20datetime_standard%22%7D)
85+
86+
**Output**
87+
88+
| _time | epoch_seconds | 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 seconds and then back to datetime for demonstration purposes.

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

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,22 @@
11
---
22
title: 'Hash functions'
33
description: 'Learn how to use and combine various hash functions in APL'
4-
sidebarTitle: Hash
4+
sidebarTitle: Overview
55
tags:
66
['axiom documentation', 'documentation', 'axiom', 'hash_md5', 'hash_sha1', 'hash_256()']
77
---
88

9-
## Hash functions
9+
The table summarizes the hash functions available in APL.
1010

11-
| **Function Name** | **Description** |
11+
| Name | Description |
1212
| --------------------------------- | ------------------------------------------------ |
13-
| [hash_md5()](#hash-md5) | Returns a MD5 hash value for the input value. |
14-
| [hash_sha1()](#hash-sha1) | Returns a sha1 hash value for the input value. |
15-
| [hash_sha256()](#hash-sha256) | Returns a SHA256 hash value for the input value. |
16-
| [hash_sha512()](#hash-sha512) | Returns a SHA512 hash value for the input value. |
13+
| [hash](/apl/scalar-functions/hash-functions/hash) | Returns a signed integer hash for the input value. |
14+
| [hash_md5](#hash-md5) | Returns a MD5 hash value for the input value. |
15+
| [hash_sha1](#hash-sha1) | Returns a sha1 hash value for the input value. |
16+
| [hash_sha256](#hash-sha256) | Returns a SHA256 hash value for the input value. |
17+
| [hash_sha512](#hash-sha512) | Returns a SHA512 hash value for the input value. |
1718

18-
## hash_md5()
19+
## hash_md5
1920

2021
Returns an MD5 hash value for the input value.
2122

@@ -48,7 +49,7 @@ hash_md5(source)
4849
}
4950
```
5051

51-
## hash_sha1()
52+
## hash_sha1
5253

5354
Returns a SHA1 hash value for the input value.
5455

@@ -81,7 +82,7 @@ hash_sha1(source)
8182
}
8283
```
8384

84-
## hash_sha256()
85+
## hash_sha256
8586

8687
Returns a SHA256 hash value for the input value.
8788

@@ -114,7 +115,7 @@ hash_sha256(source)
114115
}
115116
```
116117

117-
## hash_sha512()
118+
## hash_sha512
118119

119120
Returns a SHA512 hash value for the input value.
120121

0 commit comments

Comments
 (0)