Skip to content

Commit 1f8c351

Browse files
maleman842maleman842
authored
Update query-language.md
1 parent 6ac5594 commit 1f8c351

File tree

1 file changed

+51
-9
lines changed

1 file changed

+51
-9
lines changed

‎src/api/public-api/query-language.md

Lines changed: 51 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -59,17 +59,25 @@ The following tables list the query languages's available functions.
5959

6060
| `trait` | |
6161
| ----------- | --------------------------------------------------------------------------------------------------- |
62-
| Syntax | `trait({s: String})` <br> `s` - the name of the the trait to reference |
62+
| Syntax | `trait({s: String})` <br> `s` - the name of the trait to reference |
6363
| Return Type | `ScalarExtractor` |
6464
| Description | Similar to the event operator, the trait operator is used to specify profile trait filter criteria. |
65-
| Notes | You can reference other audiences by using the audience key as the trait name. |
65+
| 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 `\\` |
6666
| Example | `trait('total_spend')` |
6767

68+
| `entity` | |
69+
| ----------- | --------------------------------------------------------------------------------------------------- |
70+
| Syntax | `entity({s: String})` <br> `s` - the relationship slug of the entity to build an extractor for |
71+
| Return Type | `VectorExtractor` |
72+
| Description | Similar to the event operator, the entity operator is used to specify entity filter criteria. |
73+
| Notes | Entity is only used with Linked Audiences. |
74+
| Example | `entity('accounts')` |
75+
6876
| `property` | |
6977
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7078
| 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})` |
7179
| Return Type | `ScalarExtractor` |
72-
| Notes | Only valid within a `where` function or a Reducer. |
80+
| 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 `\\` |
7381
| Example | `property('total')` |
7482

7583
| `context` | |
@@ -81,9 +89,10 @@ The following tables list the query languages's available functions.
8189

8290
| `literal` | |
8391
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
84-
| Syntax | `literal({a: Any})` <br> `a` - the value to treat as a literal expression |
92+
| Syntax | `literal({a: Any})` <br> `a` - the value to treat as a literal expression |
8593
| 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. |
86-
| Example | `literal(100)` <br> |
94+
| 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. |
95+
| Example | `literal(100)` or `literal('value')` or `literal(2022-10-17T00:00:00)` |
8796

8897

8998

@@ -269,18 +278,27 @@ The following tables list the query languages's available functions.
269278
| Syntax | `one_of({a: Array})`<br>`a` - array of possible values |
270279
| Return Type | `Comparator` |
271280
| Description | Matches when the value exactly matches one of the values from the parameter array. |
272-
| Example | `one_of('shoes','shirts')` |
281+
| Example | `one_of('shoes','shirts')` |
282+
283+
| `none_of` | |
284+
| ----------- | ----------------------------------------------------------------------------------------- |
285+
| Syntax | `none_of({a: Array})`<br>`a` - array of possible values |
286+
| Return Type | `Comparator` |
287+
| Description | Matches when the value does not exactly match one of the values from the parameter array. |
288+
| Example | `none_of('shoes','shirts')` |
273289

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

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

286304
| `within_last` | |
@@ -366,7 +384,7 @@ The following tables list the query languages's available functions.
366384
| `ScalarExtractor` (extends `Extractor`, `Scalar`) | |
367385
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
368386
| Base Type | `Extractor`, `Scalar` |
369-
| 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`) |
387+
| 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`) |
370388
| Notes | A `ScalarExtractor` represents extractions of a single data element, like a field value or a trait value. |
371389

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

392410
| `Scalar` | |
393411
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
394-
| 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` |
412+
| 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` |
395413

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

495+
#### Associated with Orders that have an association to Order Products
496+
497+
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:
498+
499+
```sql
500+
entity('orders').where(entity('order-products').count() >= 1).count() >= 1
501+
```
502+
503+
#### Associated to Orders or is a VIP user
504+
505+
This example collects all users which have at least 1 association to an `order` entity or have a `VIP` trait equal to true:
506+
507+
```sql
508+
entity('orders').count() >= 1 OR trait('VIP') = 'true'
509+
```
510+
511+
#### Associated with orders that have a total greater than 500
512+
513+
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:
514+
515+
```sql
516+
entity('orders').where(property('total') > 500).count() >= 1
517+
```
518+
477519
### Computed Traits
478520

479521
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'))
511553
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`:
512554

513555
```sql
514-
event('Shoes Bought').within(30 days).mode(property('spend'), 2)
556+
('Shoes Bought').within(30 days).mode(property('spend'), 2)
515557
```

0 commit comments

Comments
 (0)