Skip to content

Update query language #7733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 13 commits into from
Jul 10, 2025
Merged

Update query language #7733

Changes from 5 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
1f8c351
Update query-language.md
maleman842 Jul 1, 2025
2ca0b10
Update query-language.md
maleman842 Jul 2, 2025
9222f83
Update query-language.md
maleman842 Jul 2, 2025
a0110f2
Update query-language.md
maleman842 Jul 2, 2025
22bf630
Update query-language.md
maleman842 Jul 3, 2025
7f3ea2f
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
9552e8f
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
7929f63
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
b83273b
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
5c74d0b
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
4fceccc
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
85a20ab
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
272c282
Update src/api/public-api/query-language.md
maleman842 Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 64 additions & 22 deletions src/api/public-api/query-language.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,17 +59,25 @@ The following tables list the query languages's available functions.

| `trait` | |
| ----------- | --------------------------------------------------------------------------------------------------- |
| Syntax | `trait({s: String})` <br> `s` - the name of the the trait to reference |
| Syntax | `trait({s: String})` <br> `s` - the name of the trait to reference |
| Return Type | `ScalarExtractor` |
| Description | Similar to the event operator, the trait operator is used to specify profile trait filter criteria. |
| Notes | You can reference other audiences by using the audience key as the trait name. |
| Notes | You can reference other audiences by using the audience key as the trait name. Also note that inclusion of a `.` signifies traversal through nested structures. If the trait name contains a literal dot, it must be escaped using `\\\\` |
| Example | `trait('total_spend')` |

| `entity` | |
| ----------- | --------------------------------------------------------------------------------------------------- |
| Syntax | `entity({s: String})` <br> `s` - the relationship slug of the entity to build an extractor for |
| Return Type | `VectorExtractor` |
| Description | Similar to the event operator, the entity operator is used to specify entity filter criteria. |
| Notes | Entity is only used with Linked Audiences. |
| Example | `entity('accounts')` |

| `property` | |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Syntax | `property({s: String})` <br> `s` - the name of the property to build an extractor for <br> In the context of funnel audiences, you can add a parent prefix to reference the parent event. <br> `property(parent: {s: String})` |
| Return Type | `ScalarExtractor` |
| Notes | Only valid within a `where` function or a Reducer. |
| Notes | Only valid within a `where` function or a Reducer. Also note that inclusion of a `.` signifies traversal through nested structures. If the property name contains a literal dot, it must be escaped using `\\\\` |
| Example | `property('total')` |

| `context` | |
Expand All @@ -79,11 +87,12 @@ The following tables list the query languages's available functions.
| Notes | Only valid within a `where` function or a Reducer. |
| Example | `context('page.url')` |

| `literal` | |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Syntax | `literal({a: Any})` <br> `a` - the value to treat as a literal expression |
| `literal` | |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Syntax | `literal({a: Any})` <br> `a` - the value to treat as a literal expression |
| Operations allowed in call-chain | None allowed; typically used within another function, like a comparison (with syntactic sugar, this would appear on the right side of the comparison). The outer function or comparison dictates the operations allowed in the call-chain. |
| Example | `literal(100)` <br> |
| Notes | Literals can be `int`s, `float`s, `string`s, `date`s or `timestamp`s, where `date`s use the format `yyyy-mm-dd` and `timestamp`s follow ISO 8601 format. Note that in general `string` is interchangeable with all other formats, except when used in a `property` chained to an `entity`. In this case, we recommend matching the data type of the entity property being targeted. |
| Example | `literal(100)` or `literal('value')` or `literal(2022-10-17T00:00:00)` |



Expand Down Expand Up @@ -269,19 +278,28 @@ The following tables list the query languages's available functions.
| Syntax | `one_of({a: Array})`<br>`a` - array of possible values |
| Return Type | `Comparator` |
| Description | Matches when the value exactly matches one of the values from the parameter array. |
| Example | `one_of('shoes','shirts')` |

| `before_date` | |
| ------------- | --------------------------------------------------------- |
| Syntax | `before_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
| Return Type | `Comparator` |
| Example | `before_date('2023-12-07T18:50:00Z')` |

| `after_date` | |
| ------------ | -------------------------------------------------------- |
| Syntax | `after_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
| Return Type | `Comparator` |
| Example | `after_date('2023-12-07T18:50:00Z')` |
| Example | `one_of('shoes','shirts')` |

| `none_of` | |
| ----------- | ----------------------------------------------------------------------------------------- |
| Syntax | `none_of({a: Array})`<br>`a` - array of possible values |
| Return Type | `Comparator` |
| Description | Matches when the value does not exactly match one of the values from the parameter array. |
| Example | `none_of('shoes','shirts')` |

| `before_date` | |
| ------------- | ---------------------------------------------------------------------------- |
| Syntax | `before_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
| Return Type | `Comparator` |
| Notes | `string` format can also be use |
| Example | `before_date(2023-12-07T18:50:00Z)` or `before_date('2023-12-07T18:50:00Z')` |

| `after_date` | |
| ------------ | -------------------------------------------------------------------------- |
| Syntax | `after_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
| Return Type | `Comparator` |
| Notes | `string` format can also be use |
| Example | `after_date(2023-12-07T18:50:00Z)` or `after_date('2023-12-07T18:50:00Z')` |

| `within_last` | |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
Expand Down Expand Up @@ -366,7 +384,7 @@ The following tables list the query languages's available functions.
| `ScalarExtractor` (extends `Extractor`, `Scalar`) | |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base Type | `Extractor`, `Scalar` |
| Operations allowed in call-chain | `equals`, `differs`, `absent`, `exists`, `greater_than`, `at_least`, `less_than`, `at_most`, `contains`, `omits`, `starts_with`, `ends_with`, `one_of`, `before_date`, `after_date`, `within_last`, `before_last`, `after_next` (inherited from `Scalar`) |
| Operations allowed in call-chain | `equals`, `differs`, `absent`, `exists`, `greater_than`, `at_least`, `less_than`, `at_most`, `contains`, `omits`, `starts_with`, `ends_with`, `one_of`, `none_of`, `before_date`, `after_date`, `within_last`, `before_last`, `after_next` (inherited from `Scalar`) |
| Notes | A `ScalarExtractor` represents extractions of a single data element, like a field value or a trait value. |

| `EventPropertyExtractor` (extends `Extractor`) | |
Expand All @@ -391,7 +409,7 @@ The following tables list the query languages's available functions.

| `Scalar` | |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operations allowed in call-chain | `equals`, `differs`, `absent`, `exists`, `greater_than`, `at_least`, `less_than`, `at_most`, `contains`, `omits`, `starts_with`, `ends_with`, `one_of`, `before_date`, `after_date`, `within_last`, `before_last`, `after_next`, `within_next` |
| Operations allowed in call-chain | `equals`, `differs`, `absent`, `exists`, `greater_than`, `at_least`, `less_than`, `at_most`, `contains`, `omits`, `starts_with`, `ends_with`, `one_of`, `none_of`, `before_date`, `after_date`, `within_last`, `before_last`, `after_next`, `within_next` |

| `ListScalar` | |
| -------------------------------- | ------- |
Expand Down Expand Up @@ -474,6 +492,30 @@ This example collects all accounts where any associated users performed the `Sho
ANY event('Shoes Bought').count() >= 1
```

#### Associated with Orders that have an association to Order Products

This example collects all users which have at least 1 association to an `orders` entity where the `orders` entity has at least 1 association to an `order-products` entity:

```sql
entity('orders').where(entity('order-products').count() >= 1).count() >= 1
```

#### Associated to Orders or is a VIP user

This example collects all users which have at least 1 association to an `order` entity or have a `VIP` trait equal to true:

```sql
entity('orders').count() >= 1 OR trait('VIP') = 'true'
```

#### Associated with orders that have a total greater than 500

This example collects all users with at least 1 association to an `orders` entity where the `orders` entity has a `total` property greater than 500:

```sql
entity('orders').where(property('total') > 500).count() >= 1
```

### Computed Traits

Suppose you wanted to calculate the average spend based on all `Shoes Bought` events performed within the last 30 days for each user.
Expand Down