Basic ES|QL syntax

An ES|QL query can optionally start with query directives to define query settings and general behavior. After any directives, a query is composed of a source command followed by an optional series of processing commands, separated by a pipe character: |. For example:

query-directive
source-command
| processing-command1
| processing-command2
		

For example, this query sets the time_zone directive, then retrieves and filters logs:

SET time_zone = "America/New_York";
FROM logs
| WHERE host.name == "my-host"
| KEEP @timestamp, host.name, message
		

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.

SET time_zone = "America/New_York"; FROM logs | WHERE host.name == "my-host" | KEEP @timestamp, host.name, message
		

FROM idx | EVAL x = 2*y | WHERE y > 0
		

FROM idx | WHERE y > 0 | EVAL x = 2*y
		

Identifiers need to be quoted with backticks (```) if:

• they don’t start with a letter, _ or @
• any of the other characters is not a letter, number, or _

For example:

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:

FROM index
| STATS COUNT(`1.field`)
| EVAL my_count = `COUNT(``1.field``)`
		

ES|QL currently supports numeric and string literals. String literals can also be implicitly converted to other types such as dates, IPs, and versions. Refer to Implicit casting for details.

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.

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.

The :: operator provides a concise syntax for type conversion, as an alternative to the TO_<type> conversion functions:

Example

ROW ver = CONCAT(("0"::INT + 1)::STRING, ".2.3")::VERSION
		

For the full list of supported types, refer to Cast (::).

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
		

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 time span unit. More examples of the usages of time spans can be found in Use time spans in ES|QL.

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

• 1day
• 1 day
• 1 day

Some functions like 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 match:

				POST /_query
					{
"query": """
FROM library
| WHERE match(author, "Frank Herbert", {"minimum_should_match": 2, "operator": "AND"})
| LIMIT 5
"""
}
		

You can also use query parameters in function named parameters:

				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]
}