Skip to content

Commit 44d4018

Browse files
maleman842maleman842
authored
Update query-language docs to match changes being made with actual query language
The query language is being updated - eq, neq, gt, lt, gte, lte, is_set, is_null are being renamed to equals, differs, greater_than, less_than, at_least, at_most, exists, absent - contains and contains_one of are being consolidated into contains Updated docs to match these changes Also updated to call out a distinct behavior with differs in that it doesn't handle null in an expected way
1 parent 2a89cfe commit 44d4018

File tree

1 file changed

+59
-63
lines changed

1 file changed

+59
-63
lines changed

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

Lines changed: 59 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Follow these syntax rules when you create definitions:
3737
The language supports the following syntactic sugar adjustments:
3838

3939
- The language automatically wraps a 'literal' extractor function around string or number inputs wherever a scalar expression expects them.
40-
- You can invoke the boolean comparator functions `eq`, `neq`, `gt`, `gte`, `lt`, and `lte` by omitting the period and parenthesis and replacing the function name with the equivalent symbols `=`, `!=`, `>`, `>=`, `<`, and `<=`. Regardless of the syntactic sugar, the comparison still dictates the operations allowed in the call-chain.
40+
- You can invoke the boolean comparator functions `equals`, `differs`, `greater_than`, `at_least`, `less_than`, and `at_most` by omitting the period and parenthesis and replacing the function name with the equivalent symbols `=`, `!=`, `>`, `>=`, `<`, and `<=`. Regardless of the syntactic sugar, the comparison still dictates the operations allowed in the call-chain.
4141

4242
### Definition type
4343

@@ -182,60 +182,63 @@ The following tables list the query languages's available functions.
182182

183183
### Comparisons
184184

185-
| `eq` | |
186-
| ----------- | -------------------------------------------------------- |
187-
| Syntax | `eq({v: Scalar})`<br>`v` - value to compare for equality |
188-
| Return Type | `Comparator` |
189-
| Example | `eq(500)`<br>Syntactic Sugar: `== 500` |
190-
191-
| `neq` | |
192-
| ----------- | ----------------------------------------------------------- |
193-
| Syntax | `neq({v: Scalar})`<br>`v` - value to compare for inequality |
194-
| Return Type | `Comparator` |
195-
| Example | `neq(500)`<br>Syntactic Sugar: `!= 500` |
196-
197-
| `is_null` | |
198-
| ----------- | ------------ |
199-
| Syntax | `is_null()` |
200-
| Return Type | `Comparator` |
201-
| Example | `is_null()` |
202-
203-
| `is_set` | |
185+
| `equals` | |
186+
| ----------- | ------------------------------------------------------------ |
187+
| Syntax | `equals({v: Scalar})`<br>`v` - value to compare for equality |
188+
| Return Type | `Comparator` |
189+
| Example | `equals(500)`<br>Syntactic Sugar: `== 500` |
190+
191+
| `differs` | |
192+
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
193+
| Syntax | `differs({v: Scalar})`<br>`v` - value to compare for inequality |
194+
| Return Type | `Comparator` |
195+
| Notes | 'differs' only returns true if the value exists and is not equal. If null values need to be considered then use 'NOT (expression) = (value)' or add a condition to check for nulls '(expression) != (value) OR (expression).absent()'. |
196+
| Example | `differs(500)`<br>Syntactic Sugar: `!= 500` |
197+
198+
| `absent` | |
199+
| ----------- | ----------------------------------------------------------------------------- |
200+
| Syntax | `absent()` |
201+
| Return Type | `Comparator` |
202+
| Description | Returns true when a value is null. Equivalent to `NOT (expression).exists()`. |
203+
| Example | `absent()` |
204+
205+
| `exists` | |
204206
| ----------- | ----------------------------------------------------------------------------------------------- |
205-
| Syntax | `is_set()` |
207+
| Syntax | `exists()` |
206208
| Return Type | `Comparator` |
207-
| Description | Returns true when a value is set, meaning not null. Equivalent to `NOT (expression).is_null()`. |
208-
| Example | `is_set()` |
209-
210-
| `gt` | |
211-
| ----------- | ------------------------------------------- |
212-
| Syntax | `gt({n: Scalar})`<br>`n` - value to compare |
213-
| Return Type | `Comparator` |
214-
| Example | `gt(500)`<br>Syntactic Sugar: `> 500` |
215-
216-
| `gte` | |
217-
| ----------- | -------------------------------------------- |
218-
| Syntax | `gte({n: Scalar})`<br>`n` - value to compare |
219-
| Return Type | `Comparator` |
220-
| Example | `gte(500)`<br>Syntactic Sugar: `>= 500` |
221-
222-
| `lt` | |
223-
| ----------- | ----------------------------------------- |
224-
| Syntax | `lt({n: Scalar})`<br>n - value to compare |
225-
| Return Type | `Comparator` |
226-
| Example | `lt(500)`<br>Syntactic Sugar: `< 500` |
227-
228-
| `lte` | |
229-
| ----------- | -------------------------------------------- |
230-
| Syntax | `lte({n: Scalar})`<br>`n` - value to compare |
231-
| Return Type | `Comparator` |
232-
| Example | `lte(500)`<br>Syntactic Sugar: `<= 500` |
233-
234-
| `contains` | |
235-
| ----------- | -------------------------------------------------------------------------- |
236-
| Syntax | `contains({s: String})`<br>`s` - string to search for in containing string |
237-
| Return Type | `Comparator` |
238-
| Example | `contains('shoes')` |
209+
| Description | Returns true when a value is set, meaning not null. Equivalent to `NOT (expression).absent()`. |
210+
| Example | `exists()` |
211+
212+
| `greater_than` | |
213+
| -------------- | ----------------------------------------------------- |
214+
| Syntax | `greater_than({n: Scalar})`<br>`n` - value to compare |
215+
| Return Type | `Comparator` |
216+
| Example | `greater_than(500)`<br>Syntactic Sugar: `> 500` |
217+
218+
| `at_least` | |
219+
| -------------- | ------------------------------------------------- |
220+
| Syntax | `at_least({n: Scalar})`<br>`n` - value to compare |
221+
| Return Type | `Comparator` |
222+
| Example | `at_least(500)`<br>Syntactic Sugar: `>= 500` |
223+
224+
| `less_than` | |
225+
| -------------- | ------------------------------------------------ |
226+
| Syntax | `less_than({n: Scalar})`<br>n - value to compare |
227+
| Return Type | `Comparator` |
228+
| Example | `less_than(500)`<br>Syntactic Sugar: `< 500` |
229+
230+
| `at_most` | |
231+
| -------------- | ------------------------------------------------ |
232+
| Syntax | `at_most({n: Scalar})`<br>`n` - value to compare |
233+
| Return Type | `Comparator` |
234+
| Example | `at_most(500)`<br>Syntactic Sugar: `<= 500` |
235+
236+
| `contains` | |
237+
| -------------- | ------------------------------------------------------------------------------------------ |
238+
| Syntax | `contains({a: Array})`<br>`a` - array of possible values |
239+
| Return Type | `Comparator` |
240+
| Description | Matches when the value contains one of the elements of the parameter array as a substring. |
241+
| Example | `contains(['shoes','shirts'])` |
239242

240243
| `omits` | |
241244
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
@@ -256,13 +259,6 @@ The following tables list the query languages's available functions.
256259
| Return Type | `Comparator` |
257260
| Example | `ends_with('total')` |
258261

259-
| `contains_one` | |
260-
| -------------- | ------------------------------------------------------------------------------------------ |
261-
| Syntax | `contains_one({a: Array})`<br>`a` - array of possible values |
262-
| Return Type | `Comparator` |
263-
| Description | Matches when the value contains one of the elements of the parameter array as a substring. |
264-
| Example | `contains_one(['shoes','shirts'])` |
265-
266262
| `one_of` | |
267263
| ----------- | ---------------------------------------------------------------------------------- |
268264
| Syntax | `one_of({a: Array})`<br>`a` - array of possible values |
@@ -365,7 +361,7 @@ The following tables list the query languages's available functions.
365361
| `ScalarExtractor` (extends `Extractor`, `Scalar`) | |
366362
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
367363
| Base Type | `Extractor`, `Scalar` |
368-
| Operations allowed in call-chain | `eq`, `neq`, `is_null`, `is_set`, `gt`, `gte`, `lt`, `lte`, `contains`, `omits`, `starts_with`, `ends_with`, `contains_one`, `one_of`, `before_date`, `after_date`, `within_last`, `before_last`, `after_next` (inherited from `Scalar`) |
364+
| 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`) |
369365
| Notes | A `ScalarExtractor` represents extractions of a single data element, like a field value or a trait value. |
370366

371367
| `EventPropertyExtractor` (extends `Extractor`) | |
@@ -390,7 +386,7 @@ The following tables list the query languages's available functions.
390386

391387
| `Scalar` | |
392388
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
393-
| Operations allowed in call-chain | `eq`, `neq`, `is_null`, `is_set`, `gt`, `gte`, `lt`, `lte`, `contains`, `omits`, `starts_with`, `ends_with`, `contains_one`, `one_of`, `before_date`, `after_date`, `within_last`, `before_last`, `after_next`, `within_next` |
389+
| 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` |
394390

395391
| `ListScalar` | |
396392
| -------------------------------- | ------- |
@@ -511,4 +507,4 @@ This example calculates the most frequent spend value for each user, based on al
511507

512508
```sql
513509
event(“Shoes Bought”).within(30 days).mode(property(“spend”), 2)
514-
```
510+
```

0 commit comments

Comments
 (0)