DDSQL Editor Clarifications #24431
DDSQL Editor Clarifications #24431
Conversation
| @@ -8,7 +8,7 @@ DDSQL is in private beta. | |||
|
|
|||
| ## Overview | |||
|
|
|||
| DDSQL is a query language for Datadog data. It implements several standard SQL functions, such as `SELECT`, and allows queries against unstructured data, such as [tags][1]. | |||
| DDSQL is a query language for Datadog data. It implements several standard SQL operations, such as `SELECT`, and allows queries against unstructured data, such as [tags][1]. | |||
There was a problem hiding this comment.
SELECT is a statement, not a function; in SQL, a function is of the form function_name(args, …). "operation" is a more general term encompassing both.
| @@ -8,16 +8,15 @@ DDSQL is in private beta. | |||
|
|
|||
| ## Data types | |||
|
|
|||
| DDSQL implements a simplified version of the SQL type system that is mostly descended from SQLite. | |||
| DDSQL implements a simplified version of the SQL type system that is mostly descended from PostgreSQL. | |||
There was a problem hiding this comment.
While it may bear similarities to the SQLite type system, SQLite is a dynamically typed SQL, and DDSQL is statically typed. Both historically and currently, DDSQL adheres to PostgreSQL where possible.
| | text | char, varchar, json | Storage is always unlimited-length UTF-8. | | ||
| | real | double | Storage is always IEEE-754 float64. | | ||
| | real | double, decimal | Storage is always IEEE-754 float64. | |
There was a problem hiding this comment.
In DDSQL, decimal is an alias of real, not a separate type.
| [2]: https://www.postgresql.org/docs/current/functions-comparison.html | ||
|
|
||
| ## CASE |
There was a problem hiding this comment.
While CASE and CAST begin with keywords like a statement or clause, they are technically expressions in SQL - they can be used as (or inside) the expressions placeholder in the syntax described under SELECT in the "Statements" page.
Note that this block has been moved without modification to expressions and operators.
| [ FROM rel_source EVENT_SEARCH 'some message' USE EVENT_INDEX 'index_name' | ||
| [ JOIN_TYPE rel_source ... [ ON condition | USING (column, ... ) ] ] ... ] | ||
| [ WHERE condition ] | ||
| [ FROM rel_source |
There was a problem hiding this comment.
Several changes here:
EVENT_SEARCHandUSE EVENT_INDEXare both separably optional, so additional[ ]are added. e.g.FROM t WHERE …,FROM t EVENT_SEARCH 'x', andFROM t USE EVENT_INDEX 'y'are all valid.join_typebelow is described asINNER,OUTER,LEFT, orRIGHT, but the keywordJOINwas missing; that keyword is required.- I indented the
JOINclause under theFROMone, to indicate that it can only be used with (and immediately following) aFROMclause.
|
|
||
| `JOIN_TYPE` | ||
| `join_type` |
There was a problem hiding this comment.
Changed to lower-case, as this is a placeholder, not a keyword. The syntax above uses all-caps for keywords and lower-case for placeholders, so I'm aligning with that.
| @@ -8,9 +8,11 @@ DDSQL is in private beta. | |||
|
|
|||
| Tags are a widespread mechanism to encode metadata about a particular record across several products at Datadog. Tags are key-value pairs for which a key may contain multiple values. | |||
|
|
|||
| Tags are modeled in DDSQL with the key as a column name, and values in a `group` type, a sorted set of strings with tag-like "= is contains" semantics. | |||
There was a problem hiding this comment.
The group type is mentioned under "Data Types", so I thought it made sense to be clear about that type here.
| ## Equality comparisons | ||
|
|
||
| Equality comparisons with tags are treated as a "contains" comparison rather than requiring strict equality. `service='website'` is true if a record has a `service` tag with the value `website`, even if it has other service tags as well. | ||
| Equality comparisons between tags and strings are treated as a "contains" comparison rather than requiring strict equality. `service='website'` is true if a record has a `service` tag with the value `website`, even if it has other service tags as well. |
There was a problem hiding this comment.
I wanted to clarify that the "contains" behavior applies specifically to equality between tags and strings; as noted in the following section, equality between tags and tags (e.g. group1 = group2) is strict equality.
While these phrases use keywords like statements or clauses, both are used as expressions in SQL statements: they are useable in SELECT, WHERE, and other places expressions are used, and can also be nested with other expressions.
936285e to
4adc507
Compare
|
Added DOCS-8607 to track review. |
* [ddsql_editor] Some clarifications on DDSQL types and statements * [ddsql_editor] Moved CAST and CASE from statements to expressions While these phrases use keywords like statements or clauses, both are used as expressions in SQL statements: they are useable in SELECT, WHERE, and other places expressions are used, and can also be nested with other expressions.
What does this PR do? What is the motivation?
This clarifies some of the DDSQL editor language features to improve precision.
Merge instructions
Additional notes