ES|QL syntax reference

edit

Basic syntax

edit

An ES|QL query is composed of a source command followed by an optional series of processing commands, separated by a pipe character: |. For example:

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 Commands and Functions and operators.

For readability, this documentation puts each processing command on a new line. However, you can write an ES|QL query as a single line. The following query is identical to the previous one:

source-command | processing-command1 | processing-command2

Identifiers

edit

The identifiers can be used as they are and don’t require quoting, unless containing special characters, in which case they must be quoted with backticks (`). What "special characters" means is command dependent.

For FROM, KEEP, DROP, RENAME, MV_EXPAND and ENRICH these are: =, `, ,, ` ` (space), | , [, ], \t (TAB), \r (CR), \n (LF); one / is allowed unquoted, but a sequence of two or more require quoting.

The rest of the commands - those allowing for identifiers be used in expressions - require quoting if the identifier contains characters other than letters, numbers and _ and doesn’t start with a letter, _ or @.

For instance:

// Retain just one field
FROM index
| KEEP 1.field

is legal. However, if same field is to be used with an EVAL, it’d have to be quoted:

// Copy one field
FROM index
| EVAL my_field = `1.field`

Literals

edit

ES|QL currently supports numeric and string literals.

String literals
edit

A string literal is a sequence of unicode characters delimited by double quotes (").

// Filter by a string value
FROM index
| WHERE first_name == "Georgi"

If the literal string itself contains quotes, these need to be escaped (\\"). ES|QL also supports the triple-quotes (""") delimiter, for convenience:

ROW name = """Indiana "Indy" Jones"""

The special characters CR, LF and TAB can be provided with the usual escaping: \r, \n, \t, respectively.

Numerical literals
edit

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 -:

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 conversion functions.

Comments

edit

ES|QL uses C++ style comments:

  • double slash // for single line comments
  • /* and */ for block comments
// Query the employees index
FROM employees
| WHERE height > 2
FROM /* Query the employees index */ employees
| WHERE height > 2
FROM employees
/* Query the
 * employees
 * index */
| WHERE height > 2

Timespan literals

edit

Datetime intervals and timespans can be expressed using timespan literals. Timespan literals are a combination of a number and a qualifier. These qualifiers are supported:

  • millisecond/milliseconds
  • second/seconds
  • minute/minutes
  • hour/hours
  • day/days
  • week/weeks
  • month/months
  • year/years

Timespan literals are not whitespace sensitive. These expressions are all valid:

  • 1day
  • 1 day
  • 1 day