From fef50f6550e97e868bb285eb9af76e56a899a169 Mon Sep 17 00:00:00 2001 From: Esther Kim Date: Tue, 6 Aug 2024 16:31:00 -0400 Subject: [PATCH] Add scalar functions (#24457) * Add scalar functions * Add punctuation and check grammar * Add links to reference index and move links to bottom * Add links to references from the landing page and remake window funtions private * Add further reading section oops * Remove Window functions from menu * Apply suggestions from code review Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> --------- Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> --- config/_default/menus/main.en.yaml | 10 +++++----- content/en/dashboards/ddsql_editor/_index.md | 7 ++++--- .../ddsql_editor/reference/_index.md | 9 +++++++++ .../reference/expressions_and_operators.md | 16 +++++++++++++-- .../reference/scalar_functions.md | 20 ++++++++++++++++--- .../reference/window_functions.md | 1 + 6 files changed, 50 insertions(+), 13 deletions(-) diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index c7fdba034dfc1..8ee619029e6d0 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -1361,11 +1361,11 @@ menu: parent: dashboards_ddsql_editor_reference identifier: dashboards_ddsql_editor_reference_aggregation_functions weight: 11025 - - name: Window Functions - url: dashboards/ddsql_editor/reference/window_functions - parent: dashboards_ddsql_editor_reference - identifier: dashboards_ddsql_editor_reference_window_functions - weight: 11026 + # - name: Window Functions + # url: dashboards/ddsql_editor/reference/window_functions + # parent: dashboards_ddsql_editor_reference + # identifier: dashboards_ddsql_editor_reference_window_functions + # weight: 11026 - name: Querying Tags url: dashboards/ddsql_editor/reference/tags parent: dashboards_ddsql_editor_reference diff --git a/content/en/dashboards/ddsql_editor/_index.md b/content/en/dashboards/ddsql_editor/_index.md index 16f29bea4c0b0..35ff43f0ee832 100644 --- a/content/en/dashboards/ddsql_editor/_index.md +++ b/content/en/dashboards/ddsql_editor/_index.md @@ -1,14 +1,15 @@ --- title: DDSQL Editor further_reading: -- link: "dashboards/ddsql_editor/reference" +- link: "/dashboards/ddsql_editor/reference" tag: "Documentation" - text: "Query References" + text: "References for DDSQL Queries" - link: "dashboards/guide/ddsql_use_cases" tag: "Guide" text: "Common queries and use cases" --- + {{< callout url="https://datadoghq.com/private-beta/ddsql-editor">}} DDSQL Editor is in private beta. {{< /callout >}} @@ -27,7 +28,7 @@ Type your question into the search box, and Datadog builds the SQL query for you ### Use SQL syntax (DDSQL) -Get exactly the data you want by writing your own `SELECT` statement. Query tags as if they are standard table columns. +Get exactly the data you want by writing your own `SELECT` statement. Query tags as if they are standard table columns. For more information on DDSQL queries, see the [DDSQL Reference][2] documentation. {{< code-block lang="sql" >}} SELECT instance_type, count(instance_type) diff --git a/content/en/dashboards/ddsql_editor/reference/_index.md b/content/en/dashboards/ddsql_editor/reference/_index.md index cb3b8fa0279bc..7286ebd7fe921 100644 --- a/content/en/dashboards/ddsql_editor/reference/_index.md +++ b/content/en/dashboards/ddsql_editor/reference/_index.md @@ -12,6 +12,15 @@ DDSQL is a query language for Datadog data. It implements several standard SQL o You can use DDSQL to query your infrastructure in the [DDSQL Editor][2] in Datadog. +{{< whatsnext desc="" >}} + {{< nextlink href="dashboards/ddsql_editor/reference/aggregation_functions" >}}Aggregation Functions{{< /nextlink >}} + {{< nextlink href="dashboards/ddsql_editor/reference/data_types" >}}Data Types{{< /nextlink >}} + {{< nextlink href="dashboards/ddsql_editor/reference/expressions_and_operators" >}}Expressions and Operators{{< /nextlink >}} + {{< nextlink href="dashboards/ddsql_editor/reference/scalar_functions" >}}Scalar Functions{{< /nextlink >}} + {{< nextlink href="dashboards/ddsql_editor/reference/statements" >}}Statements{{< /nextlink >}} + {{< nextlink href="dashboards/ddsql_editor/reference/tags" >}}Tags{{< /nextlink >}} +{{< /whatsnext >}} + [1]: /dashboards/ddsql_editor/reference/tags [2]: https://app.datadoghq.com/ddsql/editor \ No newline at end of file diff --git a/content/en/dashboards/ddsql_editor/reference/expressions_and_operators.md b/content/en/dashboards/ddsql_editor/reference/expressions_and_operators.md index dc984eb564949..3c563c03ef25b 100644 --- a/content/en/dashboards/ddsql_editor/reference/expressions_and_operators.md +++ b/content/en/dashboards/ddsql_editor/reference/expressions_and_operators.md @@ -54,8 +54,16 @@ DDSQL also supports the following comparator keywords as they are defined in the DDSQL supports the `BETWEEN` keyword such that `a BETWEEN x AND y` is equivalent to `a >= x AND a <= y`. See [the Postgres documentation for `BETWEEN`][2] for details. -[1]: /dashboards/ddsql_editor/reference/tags/ -[2]: https://www.postgresql.org/docs/current/functions-comparison.html +## Logical operators + +| Name | Description | +|---------|-------------------------| +| AND | Boolean logic, a & b | +| OR | Boolean logic, a || b | +| XOR | Boolean logic, a ^ b | +| NOT | Boolean logic, !a | +| IS NULL | Returns true for each row that is null | + ## CASE @@ -108,3 +116,7 @@ expression::type {{< /code-block >}} For example, `SELECT 1::text;`. + + +[1]: /dashboards/ddsql_editor/reference/tags/ +[2]: https://www.postgresql.org/docs/current/functions-comparison.html diff --git a/content/en/dashboards/ddsql_editor/reference/scalar_functions.md b/content/en/dashboards/ddsql_editor/reference/scalar_functions.md index 872f2138f5bb9..59dc45fc66442 100644 --- a/content/en/dashboards/ddsql_editor/reference/scalar_functions.md +++ b/content/en/dashboards/ddsql_editor/reference/scalar_functions.md @@ -19,6 +19,15 @@ These functions return one value per row. | substr(expr *s*, numeric *start*, numeric *numChars*) | text | Returns a substring of *s* from *start* to a max of *numChars*, if provided. *start* is a 1-based index, so `substr('hello', 2)` returns `'ello'`. If the start is less than 1, it is treated as if it were 1. The result is computed by taking the range of characters `[start, start+numChars]`, where if any value is less than 1, it is treated as 1. This means `substr('hello', -2, 4)` returns `'h'`. | | replace(text *s*, text *from*, text *to*) | text | Replaces all occurrences in *s* of substring *from* with substring *to*. | | regexp_replace(text *s*, text *pattern*, text *replacement*) | text | Replace substrings in *s* that match the POSIX regular expression *pattern* with the *replacement*. Supports Go's [regular expression syntax][1]. | + reverse(expr *text*) | string | Reverses the string (brown → nworb). | +| md5(expr *text*) | string | Calculates the MD5 hash of a string and returns the result in hexadecimal. | +| char_length(str *text*) | integer | Returns number of characters in str. | +| left(str *text*, *n* int) | text | Returns first *n* characters in str. When *n* is negative, return all but last \|n\| characters.| +| right(str *text*, *n* int) | text | Returns last *n* characters in str. When *n* is negative, return all but first \|n\| characters.| +| ltrim(str *text* [, characters text]) | text | Removes the longest string containing only characters from characters (a space by default) from the start of str. | +| rtrim(str *text* [, characters text])| text | Removes the longest string containing only characters from characters (a space by default) from the end of str | +| trim([leading \| trailing \| both] [characters] from str) | text | Removes the longest string containing only the characters (a space by default) from the start/end/both ends of str. | +| sort_order_ip(ip text) | text | Returns a string representing a sort order over IPv4 and IPv6 range. | ## Mathematical functions and operators @@ -32,6 +41,9 @@ These functions return one value per row. | ceil(numeric *n*) | numeric | Returns the nearest integer that is greater than or equal to *n*. | | power(numeric *n*, numeric *s*) | numeric | Raises *n* to the *s* power. | | ln(numeric *n*) | numeric | Calculates the natural logarithm of *n*. | +| log(numeric *n*) | numeric | Calculates the logarithm to base 10 of *n*. | +| log2(numeric *n*) | numeric | Calculates the logarithm to base 2 of *n*. | +| exp(numeric *n*) | numeric | Returns the mathematical constant e, raised to the power of *n*. | | sqrt(numeric *n*) | numeric | Calculates the square root of *n*. | @@ -52,6 +64,8 @@ These functions return one value per row. | Name | Return type | Description | |------|-------------|-------------| | date_trunc(string *precision*, timestamp *t*) | timestamp | Truncates the timestamp to the chosen *precision* ("second", "minute", "hour", "day", "week", "month", or "year"). | +| date_diff(string *precision*, timestamp *t*, timestamp *t*) | integer | Returns the difference between two dates, in the precision specified. | +| to_timestamp(numeric *n*) | timestamp | Transforms *n* into a timestamp, considering *n* as the time in seconds.| ## Conditional expressions @@ -65,9 +79,9 @@ These functions return one value per row. | Name | Return type | Description | |------|-------------|-------------| | json_extract_path_text(text json, text path…) | text | Extracts the JSON sub-object in JSON as text, defined by the path. Its behavior is equivalent to the [postgres function with the same name][2]. For example, `json_extract_path_text(col, ‘forest')` returns the value of the key `forest` for each JSON object in `col`. See the example below for a JSON array syntax.| -| json_extract_path(text json, text path…) | json | Same functionality as `json_extract_path_text`, but returns a column of type `JSON` instead of type `text`. | -| json_build_object(key1 text, value1 json/text/int/float, key2 text, value2 json/text/int/float, ...) | json | Builds a JSON object based on the parameters passed in. The parameters to the function are the keys and values of the JSON object being built, alternating between the key and value mapped to each key. -| row_to_json(table) | json | Returns a JSON representation of each row in a table as a JSON value. The JSON keys are the column names, and the values are the values under each row in each column. **Note*: `row_to_json` takes in a table name, NOT a column name. | +| json_extract_path(text json, text path…) | json | Same functionality as `json_extract_path_text`, but returns a column of JSON type instead of text type.| +| json_build_object(key1 text, value1 json/text/int/float, key2 text, value2 json/text/int/float, … ) | json | Builds a JSON object based on the parameters passed in. The parameters to the function are the keys/values of the JSON object being built, alternating between key and value mapped to each key.| +| row_to_json(table) | json | Returns a JSON representation of each row in a table as a JSON value. The JSON keys are the column names, and the values are the values under each row at each column.

Note: row_to_json takes in a table name, NOT a column. | ### JSON array Return the 0th element in a JSON array under the key `forest` in each JSON object or row in `col`. diff --git a/content/en/dashboards/ddsql_editor/reference/window_functions.md b/content/en/dashboards/ddsql_editor/reference/window_functions.md index 29fb95cde2a74..986ef5ead1b98 100644 --- a/content/en/dashboards/ddsql_editor/reference/window_functions.md +++ b/content/en/dashboards/ddsql_editor/reference/window_functions.md @@ -1,5 +1,6 @@ --- title: DDSQL Window Functions +private: true --- {{< callout url="https://datadoghq.com/private-beta/ddsql-editor">}}