[[esql-syntax]] === {esql} syntax reference ++++ Syntax reference ++++ [discrete] [[esql-basic-syntax]] === Basic syntax An {esql} query is composed of a <> followed by an optional series of <>, 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 <> and <>. [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 <>. [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 <>. More examples of the usages of time spans can be found in <>. 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 <> 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 <>: [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 <> 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]