Skip to content

Commit 83435e5

Browse files
sade-wusisade-wusi
authored
Merge pull request #7733 from segmentio/maleman842-patch-1
Update query language
2 parents 98e73de + 272c282 commit 83435e5

File tree

1 file changed

+64
-22
lines changed

1 file changed

+64
-22
lines changed

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

Lines changed: 64 additions & 22 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. The `.` character indicates traversal through nested structures. If the trait name contains a literal period (`.`), 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. The `.` character indicates traversal through nested structures. If the trait name contains a literal period (`.`), it must be escaped using `\\\\`. |
7381
| Example | `property('total')` |
7482

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

82-
| `literal` | |
83-
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
84-
| Syntax | `literal({a: Any})` <br> `a` - the value to treat as a literal expression |
90+
| `literal` | |
91+
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
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`, `float`, `string`, `date` or `timestamp`, where `date` uses the format `yyyy-mm-dd` and `timestamp` follows the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} format. `string` is generally interchangeable with all other formats, except when used in a `property` chained to an `entity`. In this case, Segment recommends matching the data type of the entity property being targeted. |
95+
| Example | `literal(100)`, `literal('value')`, or `literal(2022-10-17T00:00:00)` |
8796

8897

8998

@@ -269,19 +278,28 @@ 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')` |
273-
274-
| `before_date` | |
275-
| ------------- | --------------------------------------------------------- |
276-
| Syntax | `before_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
277-
| Return Type | `Comparator` |
278-
| Example | `before_date('2023-12-07T18:50:00Z')` |
279-
280-
| `after_date` | |
281-
| ------------ | -------------------------------------------------------- |
282-
| Syntax | `after_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
283-
| Return Type | `Comparator` |
284-
| Example | `after_date('2023-12-07T18:50:00Z')` |
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')` |
289+
290+
| `before_date` | |
291+
| ------------- | ---------------------------------------------------------------------------- |
292+
| Syntax | `before_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
293+
| Return Type | `Comparator` |
294+
| Notes | `string` format can also be used |
295+
| Example | `before_date(2023-12-07T18:50:00Z)` or `before_date('2023-12-07T18:50:00Z')` |
296+
297+
| `after_date` | |
298+
| ------------ | -------------------------------------------------------------------------- |
299+
| Syntax | `after_date({t: Timestamp})`<br>`t` - ISO 8601 timestamp |
300+
| Return Type | `Comparator` |
301+
| Notes | `string` format can also be used |
302+
| Example | `after_date(2023-12-07T18:50:00Z)` or `after_date('2023-12-07T18:50:00Z')` |
285303

286304
| `within_last` | |
287305
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -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 who 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 who 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.

0 commit comments

Comments
 (0)