Skip to content

Commit dc89743

Browse files
committed
[Docs] Refine section titles and structure
- Rename 'Differences from OpenSearch SQL V2 (Legacy)' to 'Migrating from SQL V2'; reframes the section around the user task (moving queries from V2 to the new engine). - Rename 'Query-shape extensions' to 'Query syntax extensions'; less jargon. - Rename 'Catalog statement differences' to 'Metadata statement differences'; matches the terminology already used in V2's own docs/user/dql/metadata.rst. - Update the 'Differences from Standard SQL' intro sentence to state the actual driver of the deviations: each exists to keep queries that worked on OpenSearch SQL V2 working unchanged on the new engine. - Merge the single-row 'Operator differences' section (INTERVAL NULL DAY) into 'Lexical and literal differences' where it fits naturally. - Remove the empty 'Semantic differences' section. Signed-off-by: Chen Dai <daichen@amazon.com>
1 parent 679141e commit dc89743

1 file changed

Lines changed: 13 additions & 30 deletions

File tree

docs/user/general/sql-compatibility.rst

Lines changed: 13 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ Lexical and identifier extensions
6363

6464
SELECT `name` FROM employees
6565

66-
Query-shape extensions
67-
----------------------
66+
Query syntax extensions
67+
-----------------------
6868

6969
* **GROUP BY by select-list alias.** A ``GROUP BY`` item may refer to a select-list
7070
alias as well as a column::
@@ -106,8 +106,8 @@ Full-text search extensions
106106
Differences from Standard SQL
107107
=============================
108108

109-
The following are deliberate deviations from ANSI SQL, adopted to preserve
110-
OpenSearch-idiomatic behavior.
109+
The deviations below are not design choices in isolation — each exists to keep
110+
queries that worked on OpenSearch SQL V2 working unchanged on the new engine.
111111

112112
* **Double-quoted identifiers vs. string literals.** ANSI SQL reserves double
113113
quotes for identifiers. OpenSearch SQL follows BigQuery conventions: some
@@ -133,8 +133,8 @@ OpenSearch-idiomatic behavior.
133133
full-text search function has a natural function-call form.
134134

135135

136-
Differences from OpenSearch SQL V2 (Legacy)
137-
===========================================
136+
Migrating from SQL V2
137+
=====================
138138

139139
The following constructs are accepted by the legacy V2 engine but are **not**
140140
accepted by the new dialect. Where a standard-SQL equivalent exists,
@@ -170,6 +170,9 @@ Lexical and literal differences
170170
* - ``multi_match([f1, f2], 'text')``
171171
- Square-bracket field lists are not supported. Use standard function-argument
172172
form.
173+
* - ``INTERVAL NULL DAY``
174+
- ``INTERVAL`` requires a numeric literal or expression, not ``NULL``. Use
175+
``CAST(NULL AS INTERVAL DAY)`` if a null interval is needed.
173176

174177
Identifier differences
175178
----------------------
@@ -476,19 +479,6 @@ a standard SQL equivalent where one exists.
476479
* - ``TYPEOF(x)``, ``TYPE(x)``, ``FIELD(x)``
477480
- No standard equivalent.
478481

479-
Operator differences
480-
--------------------
481-
482-
.. list-table::
483-
:header-rows: 1
484-
:widths: 40 60
485-
486-
* - V2 syntax
487-
- Comment
488-
* - ``INTERVAL NULL DAY``
489-
- ``INTERVAL`` requires a numeric literal or expression, not ``NULL``. Use
490-
``CAST(NULL AS INTERVAL DAY)`` if a null interval is needed.
491-
492482
Clause and syntactic differences
493483
--------------------------------
494484

@@ -509,11 +499,11 @@ Clause and syntactic differences
509499
* - ``FROM bank b1, b1.firstname``
510500
- Implicit nested-field joins via an alias path are not supported.
511501

512-
Catalog statement differences
513-
-----------------------------
502+
Metadata statement differences
503+
------------------------------
514504

515-
The following catalog-browse statements are not accepted. Catalog browsing is not
516-
part of the SQL surface in the new engine.
505+
The following metadata (catalog-browsing) statements are not accepted. Metadata
506+
browsing is not part of the SQL surface in the new engine.
517507

518508
.. list-table::
519509
:header-rows: 1
@@ -543,13 +533,6 @@ Result-shape differences
543533
- ``EXPLAIN`` returns the physical query plan tree. The format is different
544534
from V2 and is considered internal to the new engine.
545535

546-
Semantic differences
547-
--------------------
548-
549-
No semantic differences from V2 are known at this time. (V2's type system also
550-
requires the result types of a ``CASE`` expression's branches to be compatible;
551-
V2 and the new engine raise equivalent errors for incompatible branch types.)
552-
553536

554537
References
555538
==========

0 commit comments

Comments
 (0)