From 8a832ff3536ab74ea2c5ef32c319167272ae44aa Mon Sep 17 00:00:00 2001 From: Andrew Shi Date: Tue, 29 Oct 2024 13:31:03 -0400 Subject: [PATCH] Document string DSL functions (#721) --- docs/dataset/advanced-usage/custom-queries.md | 56 ++++++++++++------- 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/docs/dataset/advanced-usage/custom-queries.md b/docs/dataset/advanced-usage/custom-queries.md index 4b44f5e2f..fee4c687c 100644 --- a/docs/dataset/advanced-usage/custom-queries.md +++ b/docs/dataset/advanced-usage/custom-queries.md @@ -27,27 +27,32 @@ You can access datapoint fields by typing `@datapoint.` or result fields via `@r This table summarized the the available operations. -| **Category** | **Operators** | **Example** | **Description** | -|--------------------------|---------------|------------------------------------------|-------------------------------------------------------------------| -| **Logical Operators** | `and` | `@datapoint.a > 2 and @datapoint.b < 3` | Logical AND | -| | `or` | `@datapoint.a <= 4 or @datapoint.b >= 5` | Logical OR | -| **Relational Operators** | `==` | `@datapoint.a == 10` | Equal to | -| | `!=` | `@datapoint.a != 5` | Not equal to | -| | `>` | `@datapoint.a > 20` | Greater than | -| | `>=` | `@datapoint.a >= 15` | Greater than or equal to | -| | `<` | `@datapoint.a < 30` | Less than | -| | `<=` | `@datapoint.a <= 25` | Less than or equal to | -| **Arithmetic Operators** | `+` | `@datapoint.a + 5` | Addition | -| | `-` | `@datapoint.a - 3` | Subtraction | -| | `*` | `@datapoint.a * 2` | Multiplication | -| | `/` | `@datapoint.a / 4` | Division | -| **Power Operator** | `^` | `@datapoint.a ^ 2` | Power | -| **Functions** | `abs` | `abs(@datapoint.a - 10)` | Returns the absolute value | -| | `floor` | `floor(@datapoint.a)` | Returns the value rounded to the nearest equal or smaller integer | -| | `round` | `round(@datapoint.a)` | Returns the rounded value | -| | `sqrt` | `sqrt(@datapoint.a)` | Returns the square root value | -| **Array Functions** | `array_size` | `array_size(@datapoint.a[])` | Returns the number of objects in the array | -| | `filter` | `filter(@datapoint.a, val -> val.area >= 400)`| Returns an array with objects that have an area of more than 400| +| **Category** | **Operators** | **Example** | **Description** | +|--------------------------|---------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Logical Operators** | `and` | `@datapoint.a > 2 and @datapoint.b < 3` | Logical AND | +| | `or` | `@datapoint.a <= 4 or @datapoint.b >= 5` | Logical OR | +| **Relational Operators** | `==` | `@datapoint.a == 10` | Equal to | +| | `!=` | `@datapoint.a != 5` | Not equal to | +| | `>` | `@datapoint.a > 20` | Greater than | +| | `>=` | `@datapoint.a >= 15` | Greater than or equal to | +| | `<` | `@datapoint.a < 30` | Less than | +| | `<=` | `@datapoint.a <= 25` | Less than or equal to | +| **Arithmetic Operators** | `+` | `@datapoint.a + 5` | Addition | +| | `-` | `@datapoint.a - 3` | Subtraction | +| | `*` | `@datapoint.a * 2` | Multiplication | +| | `/` | `@datapoint.a / 4` | Division | +| **Power Operator** | `^` | `@datapoint.a ^ 2` | Power | +| **Numeric Functions** | `abs` | `abs(@datapoint.a - 10)` | Returns the absolute value. | +| | `floor` | `floor(@datapoint.a)` | Returns the value rounded to the nearest equal or smaller integer. | +| | `round` | `round(@datapoint.a)` | Returns the rounded value. | +| | `sqrt` | `sqrt(@datapoint.a)` | Returns the square root value. | +| **String Functions** | `lower` | `lower(@datapoint.a)` | Returns the string value with all characters converted to lowercase. | +| | `upper` | `upper(@datapoint.a)` | Returns the string value with all characters converted to uppercase. | +| | `ltrim` | `ltrim(@datapoint.a [, ])` | Returns the string value with left-side characters matching `` removed.
If `` is unspecified, it defaults to `' '`, a blank space character. | +| | `replace` | `replace(@datapoint.a, [, ])` | Returns the string value with instances of the substring `` converted to ``.
If `` is unspecified, all instances of `` are deleted instead. | +| | `substr` | `substr(@datapoint.a, [, ])` | Returns the substring within the value starting with the `` index and with `` characters.
The start position is 1-indexed, not 0-indexed. For example, `substr('abc', 1, 1)` returns `a`, not `b`.
If `` is unspecified, all characters until the end are returned. | +| **Array Functions** | `array_size` | `array_size(@datapoint.a[])` | Returns the number of objects in the array. | +| | `filter` | `filter(@datapoint.a, val -> val.area >= 400)` | Returns an array with objects that have an area of more than 400. | !!! Example **Combining Logical and Relational Operators** @@ -74,6 +79,15 @@ This table summarized the the available operations. sqrt(@datapoint.b + @datapoint.c) ``` + **Using String Functions** + + ```dsl + replace(lower(@datapoint.locator), "s3", "gs") + ``` + ```dsl + substr(ltrim(@datapoint.text), 5, 3) + ``` + **Using array filters and size** This function returns the number of objects that have an area of more than 400