OpenSearch/docs/en/sql/language/sql-syntax.asciidoc

[[sql-spec-syntax]]
=== SQL Statement Syntax

Big list of the entire syntax in SQL

Each entry might get its own file and code snippet

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-spec}/select.sql-spec[wildcardWithOrder]
--------------------------------------------------


[[sql-spec-syntax-order-by]]
==== ORDER BY

Elasticsearch supports `ORDER BY` for consistent ordering. You add
any field in the index that has <<doc-values,`doc_values`>> or
`SCORE()` to sort by `_score`. By default SQL sorts on what it
considers to be the most efficient way to get the results.

So sorting by a field looks like:

[source,js]
--------------------------------------------------
POST /_xpack/sql
{
    "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:library]

which results in something like:

[source,text]
--------------------------------------------------
     author      |        name        |  page_count   | release_date
-----------------+--------------------+---------------+---------------
Peter F. Hamilton|Pandora's Star      |768            |1078185600000
Vernor Vinge     |A Fire Upon the Deep|613            |707356800000
Frank Herbert    |Dune                |604            |-144720000000
Alastair Reynolds|Revelation Space    |585            |953078400000
James S.A. Corey |Leviathan Wakes     |561            |1306972800000
--------------------------------------------------
// TESTRESPONSE[s/\|/\\|/ s/\+/\\+/]
// TESTRESPONSE[_cat]

[[sql-spec-syntax-order-by-score]]
For sorting by score to be meaningful you need to include a full
text query in the `WHERE` clause. For example:

[source,js]
--------------------------------------------------
POST /_xpack/sql
{
    "query": "SELECT SCORE(), * FROM library WHERE match(name, 'dune') ORDER BY SCORE() DESC"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:library]

Which results in something like:

[source,text]
--------------------------------------------------
    SCORE()    |    author     |       name        |  page_count   | release_date
---------------+---------------+-------------------+---------------+---------------
2.288635       |Frank Herbert  |Dune               |604            |-144720000000
1.8893257      |Frank Herbert  |Dune Messiah       |331            |-6739200000
1.6086555      |Frank Herbert  |Children of Dune   |408            |198892800000
1.4005898      |Frank Herbert  |God Emperor of Dune|454            |359856000000
--------------------------------------------------
// TESTRESPONSE[s/\|/\\|/ s/\+/\\+/ s/\(/\\\(/ s/\)/\\\)/]
// TESTRESPONSE[_cat]

Note that you can return `SCORE()` by adding it to the where clause. This
is possible even if you are not sorting by `SCORE()`:

[source,js]
--------------------------------------------------
POST /_xpack/sql
{
    "query": "SELECT SCORE(), * FROM library WHERE match(name, 'dune') ORDER BY page_count DESC"
}
--------------------------------------------------
// CONSOLE
// TEST[setup:library]

[source,text]
--------------------------------------------------
    SCORE()    |    author     |       name        |  page_count   | release_date
---------------+---------------+-------------------+---------------+---------------
2.288635       |Frank Herbert  |Dune               |604            |-144720000000
1.4005898      |Frank Herbert  |God Emperor of Dune|454            |359856000000
1.6086555      |Frank Herbert  |Children of Dune   |408            |198892800000
1.8893257      |Frank Herbert  |Dune Messiah       |331            |-6739200000
--------------------------------------------------
// TESTRESPONSE[s/\|/\\|/ s/\+/\\+/ s/\(/\\\(/ s/\)/\\\)/]
// TESTRESPONSE[_cat]