From 1f8c351514799dd263006e5d4c31af36b4f9a9f4 Mon Sep 17 00:00:00 2001
From: maleman842 <79479130+maleman842@users.noreply.github.com>
Date: Tue, 1 Jul 2025 16:04:28 -0700
Subject: [PATCH 1/5] Update query-language.md
---
src/api/public-api/query-language.md | 60 +++++++++++++++++++++++-----
1 file changed, 51 insertions(+), 9 deletions(-)
diff --git a/src/api/public-api/query-language.md b/src/api/public-api/query-language.md
index 73e93ae2c7..14deb4415c 100644
--- a/src/api/public-api/query-language.md
+++ b/src/api/public-api/query-language.md
@@ -59,17 +59,25 @@ The following tables list the query languages's available functions.
| `trait` | |
| ----------- | --------------------------------------------------------------------------------------------------- |
-| Syntax | `trait({s: String})`
`s` - the name of the the trait to reference |
+| Syntax | `trait({s: String})`
`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 dor, it must be escaped using `\\` |
| Example | `trait('total_spend')` |
+| `entity` | |
+| ----------- | --------------------------------------------------------------------------------------------------- |
+| Syntax | `entity({s: String})`
`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})`
`s` - the name of the property to build an extractor for
In the context of funnel audiences, you can add a parent prefix to reference the parent event.
`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 dor, it must be escaped using `\\` |
| Example | `property('total')` |
| `context` | |
@@ -81,9 +89,10 @@ The following tables list the query languages's available functions.
| `literal` | |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Syntax | `literal({a: Any})`
`a` - the value to treat as a literal expression |
+| Syntax | `literal({a: Any})`
`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)`
|
+| Notes | Literals can be `int`s, `float`s, `string`s, or `timestamp`s, where `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 using `timestamp` over `string` based on the datatype you're targeting. |
+| Example | `literal(100)` or `literal('value')` or `literal(2022-10-17T00:00:00)` |
@@ -269,18 +278,27 @@ The following tables list the query languages's available functions.
| Syntax | `one_of({a: Array})`
`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')` |
+| Example | `one_of('shoes','shirts')` |
+
+| `none_of` | |
+| ----------- | ----------------------------------------------------------------------------------------- |
+| Syntax | `none_of({a: Array})`
`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})`
`t` - ISO 8601 timestamp |
| Return Type | `Comparator` |
+| Notes | `string` format can also be use |
| Example | `before_date('2023-12-07T18:50:00Z')` |
| `after_date` | |
| ------------ | -------------------------------------------------------- |
| Syntax | `after_date({t: Timestamp})`
`t` - ISO 8601 timestamp |
| Return Type | `Comparator` |
+| Notes | `string` format can also be use |
| Example | `after_date('2023-12-07T18:50:00Z')` |
| `within_last` | |
@@ -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`) | |
@@ -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` | |
| -------------------------------- | ------- |
@@ -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.
@@ -511,5 +553,5 @@ event('Shoes Bought').within(30 days).first(property('spend'))
This example calculates the most frequent spend value for each user, based on all `Shoes Bought` events performed within the last 30 days. It only considers spend values that have a minimum frequency of `2`:
```sql
-event('Shoes Bought').within(30 days).mode(property('spend'), 2)
+('Shoes Bought').within(30 days).mode(property('spend'), 2)
```
From 2ca0b109c91cf864925cc3a97f3c956f178dff84 Mon Sep 17 00:00:00 2001
From: maleman842 <79479130+maleman842@users.noreply.github.com>
Date: Wed, 2 Jul 2025 09:28:37 -0700
Subject: [PATCH 2/5] Update query-language.md
---
src/api/public-api/query-language.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/api/public-api/query-language.md b/src/api/public-api/query-language.md
index 14deb4415c..34e2a7966c 100644
--- a/src/api/public-api/query-language.md
+++ b/src/api/public-api/query-language.md
@@ -62,7 +62,7 @@ The following tables list the query languages's available functions.
| Syntax | `trait({s: String})`
`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. Also note that inclusion of a `.` signifies traversal through nested structures. If the trait name contains a literal dor, it must be escaped using `\\` |
+| 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` | |
From 9222f83a2ace1582f0778784087f378a33b4d133 Mon Sep 17 00:00:00 2001
From: maleman842 <79479130+maleman842@users.noreply.github.com>
Date: Wed, 2 Jul 2025 09:29:47 -0700
Subject: [PATCH 3/5] Update query-language.md
---
src/api/public-api/query-language.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/api/public-api/query-language.md b/src/api/public-api/query-language.md
index 34e2a7966c..64915e163c 100644
--- a/src/api/public-api/query-language.md
+++ b/src/api/public-api/query-language.md
@@ -77,7 +77,7 @@ The following tables list the query languages's available functions.
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Syntax | `property({s: String})`
`s` - the name of the property to build an extractor for
In the context of funnel audiences, you can add a parent prefix to reference the parent event.
`property(parent: {s: String})` |
| Return Type | `ScalarExtractor` |
-| 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 dor, it must be escaped using `\\` |
+| 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` | |
From a0110f2bed6e0a1bd8ba215e1c77124abe8b24a0 Mon Sep 17 00:00:00 2001
From: maleman842 <79479130+maleman842@users.noreply.github.com>
Date: Wed, 2 Jul 2025 09:31:30 -0700
Subject: [PATCH 4/5] Update query-language.md
---
src/api/public-api/query-language.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/api/public-api/query-language.md b/src/api/public-api/query-language.md
index 64915e163c..b00c9781a9 100644
--- a/src/api/public-api/query-language.md
+++ b/src/api/public-api/query-language.md
@@ -553,5 +553,5 @@ event('Shoes Bought').within(30 days).first(property('spend'))
This example calculates the most frequent spend value for each user, based on all `Shoes Bought` events performed within the last 30 days. It only considers spend values that have a minimum frequency of `2`:
```sql
-('Shoes Bought').within(30 days).mode(property('spend'), 2)
+event('Shoes Bought').within(30 days).mode(property('spend'), 2)
```
From 22bf630834f58f2c1d5f1bc7a24b8f04a5d3b021 Mon Sep 17 00:00:00 2001
From: maleman842 <79479130+maleman842@users.noreply.github.com>
Date: Thu, 3 Jul 2025 07:45:38 -0700
Subject: [PATCH 5/5] Update query-language.md
---
src/api/public-api/query-language.md | 36 ++++++++++++++--------------
1 file changed, 18 insertions(+), 18 deletions(-)
diff --git a/src/api/public-api/query-language.md b/src/api/public-api/query-language.md
index b00c9781a9..d98e28bddc 100644
--- a/src/api/public-api/query-language.md
+++ b/src/api/public-api/query-language.md
@@ -87,12 +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})`
`a` - the value to treat as a literal expression |
+| `literal` | |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Syntax | `literal({a: Any})`
`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. |
-| Notes | Literals can be `int`s, `float`s, `string`s, or `timestamp`s, where `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 using `timestamp` over `string` based on the datatype you're targeting. |
-| Example | `literal(100)` or `literal('value')` or `literal(2022-10-17T00:00:00)` |
+| 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)` |
@@ -287,19 +287,19 @@ The following tables list the query languages's available functions.
| 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})`
`t` - ISO 8601 timestamp |
-| Return Type | `Comparator` |
-| Notes | `string` format can also be use |
-| Example | `before_date('2023-12-07T18:50:00Z')` |
-
-| `after_date` | |
-| ------------ | -------------------------------------------------------- |
-| Syntax | `after_date({t: Timestamp})`
`t` - ISO 8601 timestamp |
-| Return Type | `Comparator` |
-| Notes | `string` format can also be use |
-| Example | `after_date('2023-12-07T18:50:00Z')` |
+| `before_date` | |
+| ------------- | ---------------------------------------------------------------------------- |
+| Syntax | `before_date({t: Timestamp})`
`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})`
`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` | |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |