mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
215 lines
4.9 KiB
Text
215 lines
4.9 KiB
Text
[[esql-syntax]]
|
|
=== {esql} syntax reference
|
|
|
|
++++
|
|
<titleabbrev>Syntax reference</titleabbrev>
|
|
++++
|
|
|
|
[discrete]
|
|
[[esql-basic-syntax]]
|
|
=== Basic syntax
|
|
|
|
An {esql} query is composed of a <<esql-commands,source command>> followed
|
|
by an optional series of <<esql-commands,processing commands>>,
|
|
separated by a pipe character: `|`. For example:
|
|
|
|
[source,esql]
|
|
----
|
|
source-command
|
|
| processing-command1
|
|
| processing-command2
|
|
----
|
|
|
|
The result of a query is the table produced by the final processing command.
|
|
|
|
For an overview of all supported commands, functions, and operators, refer to <<esql-commands>> and <<esql-functions-operators>>.
|
|
|
|
[NOTE]
|
|
====
|
|
For readability, this documentation puts each processing command on a new
|
|
line. However, you can write an {esql} query as a single line. The following
|
|
query is identical to the previous one:
|
|
|
|
[source,esql]
|
|
----
|
|
source-command | processing-command1 | processing-command2
|
|
----
|
|
====
|
|
|
|
[discrete]
|
|
[[esql-identifiers]]
|
|
==== Identifiers
|
|
|
|
Identifiers need to be quoted with backticks (+{backtick}+) if:
|
|
|
|
* they don't start with a letter, `_` or `@`
|
|
* any of the other characters is not a letter, number, or `_`
|
|
|
|
For example:
|
|
|
|
[source,esql]
|
|
----
|
|
FROM index
|
|
| KEEP `1.field`
|
|
----
|
|
|
|
When referencing a function alias that itself uses a quoted identifier, the
|
|
backticks of the quoted identifier need to be escaped with another backtick. For
|
|
example:
|
|
|
|
[source,esql]
|
|
----
|
|
FROM index
|
|
| STATS COUNT(`1.field`)
|
|
| EVAL my_count = `COUNT(``1.field``)`
|
|
----
|
|
|
|
[discrete]
|
|
[[esql-literals]]
|
|
==== Literals
|
|
|
|
{esql} currently supports numeric and string literals.
|
|
|
|
[discrete]
|
|
[[esql-string-literals]]
|
|
===== String literals
|
|
|
|
A string literal is a sequence of unicode characters delimited by double
|
|
quotes (`"`).
|
|
|
|
[source,esql]
|
|
----
|
|
// Filter by a string value
|
|
FROM index
|
|
| WHERE first_name == "Georgi"
|
|
----
|
|
|
|
If the literal string itself contains quotes, these need to be escaped (`\\"`).
|
|
{esql} also supports the triple-quotes (`"""`) delimiter, for convenience:
|
|
|
|
[source,esql]
|
|
----
|
|
ROW name = """Indiana "Indy" Jones"""
|
|
----
|
|
|
|
The special characters CR, LF and TAB can be provided with the usual escaping:
|
|
`\r`, `\n`, `\t`, respectively.
|
|
|
|
[discrete]
|
|
[[esql-numeric-literals]]
|
|
===== Numerical literals
|
|
|
|
The numeric literals are accepted in decimal and in the scientific notation
|
|
with the exponent marker (`e` or `E`), starting either with a digit, decimal
|
|
point `.` or the negative sign `-`:
|
|
|
|
[source, sql]
|
|
----
|
|
1969 -- integer notation
|
|
3.14 -- decimal notation
|
|
.1234 -- decimal notation starting with decimal point
|
|
4E5 -- scientific notation (with exponent marker)
|
|
1.2e-3 -- scientific notation with decimal point
|
|
-.1e2 -- scientific notation starting with the negative sign
|
|
----
|
|
|
|
The integer numeric literals are implicitly converted to the `integer`, `long`
|
|
or the `double` type, whichever can first accommodate the literal's value.
|
|
|
|
The floating point literals are implicitly converted the `double` type.
|
|
|
|
To obtain constant values of different types, use one of the numeric
|
|
<<esql-type-conversion-functions, conversion functions>>.
|
|
|
|
|
|
[discrete]
|
|
[[esql-comments]]
|
|
==== Comments
|
|
{esql} uses C++ style comments:
|
|
|
|
* double slash `//` for single line comments
|
|
* `/*` and `*/` for block comments
|
|
|
|
[source,esql]
|
|
----
|
|
// Query the employees index
|
|
FROM employees
|
|
| WHERE height > 2
|
|
----
|
|
|
|
[source,esql]
|
|
----
|
|
FROM /* Query the employees index */ employees
|
|
| WHERE height > 2
|
|
----
|
|
|
|
[source,esql]
|
|
----
|
|
FROM employees
|
|
/* Query the
|
|
* employees
|
|
* index */
|
|
| WHERE height > 2
|
|
----
|
|
|
|
[discrete]
|
|
[[esql-timespan-literals]]
|
|
==== Timespan literals
|
|
|
|
Datetime intervals and timespans can be expressed using timespan literals.
|
|
Timespan literals are a combination of a number and a temporal unit. The
|
|
supported temporal units are listed in <<esql-time-spans-table, time span unit>>.
|
|
More examples of the usages of time spans can be found in
|
|
<<esql-time-spans, Use time spans in ES|QL>>.
|
|
|
|
|
|
Timespan literals are not whitespace sensitive. These expressions are all valid:
|
|
|
|
* `1day`
|
|
* `1 day`
|
|
* `1 day`
|
|
|
|
[discrete]
|
|
[[esql-function-named-params]]
|
|
==== Function named parameters
|
|
|
|
Some functions like <<esql-match,match>> use named parameters to provide additional options.
|
|
|
|
Named parameters allow specifying name value pairs, using the following syntax:
|
|
|
|
`{"option_name": option_value, "another_option_name": another_value}`
|
|
|
|
Valid value types are strings, numbers and booleans.
|
|
|
|
An example using <<esql-match,match>>:
|
|
|
|
[source,console]
|
|
----
|
|
POST /_query
|
|
{
|
|
"query": """
|
|
FROM library
|
|
| WHERE match(author, "Frank Herbert", {"minimum_should_match": 2, "operator": "AND"})
|
|
| LIMIT 5
|
|
"""
|
|
}
|
|
----
|
|
// TEST[setup:library]
|
|
|
|
You can also use <<esql-rest-params,query parameters>> in function named parameters:
|
|
|
|
[source,console]
|
|
----
|
|
POST /_query
|
|
{
|
|
"query": """
|
|
FROM library
|
|
| EVAL year = DATE_EXTRACT("year", release_date)
|
|
| WHERE page_count > ? AND match(author, ?, {"minimum_should_match": ?})
|
|
| LIMIT 5
|
|
""",
|
|
"params": [300, "Frank Herbert", 2]
|
|
}
|
|
----
|
|
// TEST[setup:library]
|
|
|