Skip to content

Commit 3d28d7d

Browse files
tothmanotothmano
authored
Add type functions (#307)
1 parent bbcf30a commit 3d28d7d

File tree

5 files changed

+317
-1
lines changed

5 files changed

+317
-1
lines changed

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Type funtions
3+
description: 'This section explains how to use type functions in APL.'
4+
sidebarTitle: Overview
5+
---
6+
7+
The table summarizes the type functions available in APL.
8+
9+
| Function | Description |
10+
|-----------------------------------------------------------------------------------------|-------------|
11+
| [ismap](/apl/scalar-functions/type-functions/ismap) | Checks whether a value is of the `dynamic` type and represents a mapping. |
12+
| [isreal](/apl/scalar-functions/type-functions/isreal) | Checks whether a value is a real number. |
13+
| [isstring](/apl/scalar-functions/type-functions/isstring) | Checks whether a value is a string. |

‎apl/scalar-functions/type-functions/ismap.mdx

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: ismap
3+
description: 'This page explains how to use the ismap function in APL.'
4+
---
5+
6+
Use the `ismap` function in APL to check whether a value is of the `dynamic` type and represents a mapping (also known as a dictionary, associative array, property bag, or object). A mapping consists of key-value pairs where keys are strings and values can be of any type. This function is especially useful when working with semi-structured data, such as logs or telemetry traces, where fields might dynamically contain arrays, objects, or scalar values.
7+
8+
Use `ismap` to:
9+
10+
- Filter records where a field is a map.
11+
- Validate input types in heterogeneous data.
12+
- Avoid runtime errors in downstream operations expecting map values.
13+
14+
## For users of other query languages
15+
16+
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
17+
18+
<AccordionGroup>
19+
<Accordion title="Splunk SPL users">
20+
21+
In Splunk SPL, you typically work with field types implicitly and rarely check if a field is a dictionary. SPL lacks a direct equivalent to APL’s `ismap`, but you might perform similar validations using `typeof` checks or custom functions in `eval`.
22+
23+
<CodeGroup>
24+
```sql Splunk example
25+
| eval is_map=if(typeof(field) == "object", true, false)
26+
````
27+
28+
```kusto APL equivalent
29+
['sample-http-logs']
30+
| extend is_map = ismap(dynamic_field)
31+
```
32+
33+
</CodeGroup>
34+
35+
</Accordion>
36+
<Accordion title="ANSI SQL users">
37+
38+
ANSI SQL does not natively support map types. If you use a platform that supports JSON or semi-structured data (such as PostgreSQL with `jsonb`, BigQuery with `STRUCT`, or Snowflake), you can simulate map checks using type inspection or schema introspection.
39+
40+
<CodeGroup>
41+
```sql SQL example
42+
SELECT
43+
CASE
44+
WHEN json_type(field) = 'object' THEN true
45+
ELSE false
46+
END AS is_map
47+
FROM logs
48+
```
49+
50+
```kusto APL equivalent
51+
['sample-http-logs']
52+
| extend is_map = ismap(dynamic_field)
53+
```
54+
55+
</CodeGroup>
56+
57+
</Accordion>
58+
</AccordionGroup>
59+
60+
## Usage
61+
62+
### Syntax
63+
64+
```kusto
65+
ismap(value)
66+
```
67+
68+
### Parameters
69+
70+
| Name | Type | Description |
71+
| ------- | --------- | ----------------------------------- |
72+
| `value` | any | The value to check for being a map. |
73+
74+
### Returns
75+
76+
Returns `true` if the value is a mapping (dictionary), otherwise returns `false`.
77+
78+
## Example
79+
80+
Use `ismap` to find log entries where a dynamic field contains structured key-value pairs, such as metadata attached to HTTP requests.
81+
82+
**Query**
83+
84+
```kusto
85+
['sample-http-logs']
86+
| extend is_structured = ismap(dynamic({"a":1, "b":2}))
87+
```
88+
89+
[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%20is_structured%20%3D%20ismap(dynamic(%7B'a'%3A1%2C%20'b'%3A2%7D))%22%7D)
90+
91+
**Output**
92+
93+
| _time | is_structured |
94+
| -------------------- | -------------- |
95+
| 2025-06-06T08:00:00Z | true |
96+
97+
## List of related functions
98+
99+
- [isreal](/apl/scalar-functions/type-functions/ismap): Checks whether a value is a real number.
100+
- [isstring](/apl/scalar-functions/type-functions/isstring): Checks whether a value is a string. Use this for scalar string validation.

‎apl/scalar-functions/type-functions/isreal.mdx

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: isreal
3+
description: 'This page explains how to use the isreal function in APL.'
4+
---
5+
6+
Use the `isreal` function to determine whether a value is a real number. This function is helpful when you need to validate data before performing numeric operations. For example, you can use `isreal` to filter out invalid values which could otherwise disrupt aggregations or calculations.
7+
8+
You often use `isreal` in data cleaning pipelines, conditional logic, and when inspecting metrics like durations, latencies, or numeric identifiers. It’s especially useful when working with telemetry or log data that includes optional or incomplete numeric fields.
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 uses the `isnum` function to check whether a string represents a numeric value.
18+
19+
<CodeGroup>
20+
```sql Splunk example
21+
... | eval is_valid = if(isnum(duration), "yes", "no")
22+
````
23+
24+
```kusto APL equivalent
25+
... | extend is_valid = iff(isreal(duration), 'yes', 'no')
26+
```
27+
28+
</CodeGroup>
29+
30+
</Accordion>
31+
<Accordion title="ANSI SQL users">
32+
33+
ANSI SQL does not have a direct equivalent to `isreal`. You typically check for numeric values using `IS NOT NULL` and avoid known invalid markers manually. APL’s `isreal` abstracts this by directly checking if a value is a real number.
34+
35+
<CodeGroup>
36+
```sql SQL example
37+
SELECT *,
38+
CASE WHEN duration IS NOT NULL THEN 'yes' ELSE 'no' END AS is_valid
39+
FROM traces
40+
```
41+
42+
```kusto APL equivalent
43+
['otel-demo-traces']
44+
| extend is_valid = iff(isreal(duration), 'yes', 'no')
45+
```
46+
47+
</CodeGroup>
48+
49+
</Accordion>
50+
</AccordionGroup>
51+
52+
## Usage
53+
54+
### Syntax
55+
56+
```kusto
57+
isreal(value)
58+
```
59+
60+
### Parameters
61+
62+
| Name | Type | Description |
63+
| ----- | ------- | ---------------------------- |
64+
| value | any | The input value to evaluate. |
65+
66+
### Returns
67+
68+
Returns `true` if the input is a valid real number. Returns `false` for strings, nulls, or non-numeric types.
69+
70+
## Example
71+
72+
Use `isreal` to identify real number values.
73+
74+
**Query**
75+
76+
```kusto
77+
['sample-http-logs']
78+
| extend is_real = isreal(123.11)
79+
```
80+
81+
[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%20is_real%20%3D%20isreal(123.11)%22%7D)
82+
83+
**Output**
84+
85+
| _time | is_real |
86+
| -------------------- | ----------------- |
87+
| 2025-06-05T12:01:00Z | true |
88+
89+
## List of related functions
90+
91+
- [ismap](/apl/scalar-functions/type-functions/ismap): Checks whether a value is of the `dynamic` type and represents a mapping.
92+
- [isstring](/apl/scalar-functions/type-functions/isstring): Checks whether a value is a string. Use this for scalar string validation.

‎apl/scalar-functions/type-functions/isstring.mdx

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: isstring
3+
description: 'This page explains how to use the isstring function in APL.'
4+
---
5+
6+
Use the `isstring` function to determine whether a value is of type string. This function is especially helpful when working with heterogeneous datasets where field types are not guaranteed, or when ingesting data from sources with loosely structured or mixed schemas.
7+
8+
You can use `isstring` to:
9+
- Filter rows based on whether a field is a string.
10+
- Validate and clean data before applying string functions.
11+
- Avoid runtime errors in queries that expect specific data types.
12+
13+
## For users of other query languages
14+
15+
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
16+
17+
<AccordionGroup>
18+
<Accordion title="Splunk SPL users">
19+
20+
In Splunk SPL, type checking is typically implicit and not exposed through a dedicated function like `isstring`. Instead, you often rely on function compatibility and casting behavior. In APL, `isstring` provides an explicit and reliable way to check if a value is a string before further processing.
21+
22+
<CodeGroup>
23+
```sql Splunk example
24+
| eval type=if(isstr(field), "string", "not string")
25+
````
26+
27+
```kusto APL equivalent
28+
['sample-http-logs']
29+
| extend type=iff(isstring(status), 'string', 'not string')
30+
```
31+
32+
</CodeGroup>
33+
34+
</Accordion>
35+
<Accordion title="ANSI SQL users">
36+
37+
ANSI SQL does not include a built-in `IS STRING` function. Instead, type checks usually rely on schema constraints, manual casting, or vendor-specific solutions. In contrast, APL offers `isstring` as a first-class function that returns a boolean indicating whether a value is of type string.
38+
39+
<CodeGroup>
40+
```sql SQL example
41+
SELECT
42+
CASE
43+
WHEN typeof(status) = 'VARCHAR' THEN 'string'
44+
ELSE 'not string'
45+
END AS type
46+
FROM logs
47+
```
48+
49+
```kusto APL equivalent
50+
['sample-http-logs']
51+
| extend type=iff(isstring(status), 'string', 'not string')
52+
```
53+
54+
</CodeGroup>
55+
56+
</Accordion>
57+
</AccordionGroup>
58+
59+
## Usage
60+
61+
### Syntax
62+
63+
```kusto
64+
isstring(value)
65+
```
66+
67+
### Parameters
68+
69+
| Name | Type | Description |
70+
| ------- | ---- | ---------------------------------- |
71+
| `value` | any | The value to test for string type. |
72+
73+
### Returns
74+
75+
A `bool` value that is `true` if the input value is of type string, `false` otherwise.
76+
77+
## Use case example
78+
79+
Use `isstring` to filter rows where the HTTP status code is a valid string.
80+
81+
**Query**
82+
83+
```kusto
84+
['sample-http-logs']
85+
| extend is_string = isstring(status)
86+
| where is_string
87+
```
88+
89+
[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%20is_string%20%3D%20isstring(status)%20%7C%20where%20is_string%22%7D)
90+
91+
**Output**
92+
93+
| _time | status | is_string |
94+
| -------------------- | ------ | --- |
95+
| 2025-06-05T12:10:00Z | "404" | true |
96+
97+
This query filters out logs where the `status` field is stored as a string, which can help filter out ingestion issues or schema inconsistencies.
98+
99+
## List of related functions
100+
101+
- [ismap](/apl/scalar-functions/type-functions/ismap): Checks whether a value is of the `dynamic` type and represents a mapping.
102+
- [isreal](/apl/scalar-functions/type-functions/isreal): Checks whether a value is a real number.

‎docs.json

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -384,7 +384,16 @@
384384
"apl/scalar-functions/pair-functions",
385385
"apl/scalar-functions/rounding-functions",
386386
"apl/scalar-functions/string-functions",
387-
"apl/scalar-functions/sql-functions"
387+
"apl/scalar-functions/sql-functions",
388+
{
389+
"group": "Type functions",
390+
"pages": [
391+
"apl/scalar-functions/type-functions",
392+
"apl/scalar-functions/type-functions/ismap",
393+
"apl/scalar-functions/type-functions/isreal",
394+
"apl/scalar-functions/type-functions/isstring"
395+
]
396+
}
388397
]
389398
},
390399
{

0 commit comments

Comments
 (0)