ES|QL functions and operators

ES|QL provides a comprehensive set of functions and operators for working with data. The reference documentation is divided into the following categories:

The STATS command supports these aggregate functions:

• AVG
• COUNT
• COUNT_DISTINCT
• MAX
• MEDIAN
• MEDIAN_ABSOLUTE_DEVIATION
• MIN
• PERCENTILE
• [preview] ST_CENTROID_AGG
• [preview] ST_EXTENT_AGG
• STD_DEV
• SUM
• TOP
• VALUES
• WEIGHTED_AVG

Syntax

Parameters

true

Description

The average of a numeric field.

Supported types

Examples

FROM employees
| STATS AVG(height)

The expression can use inline functions. For example, to calculate the average over a multivalued column, first use MV_AVG to average the multiple values per row, and use the result with the AVG function

FROM employees
| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10)

Syntax

Parameters

field

Expression that outputs values to be counted. If omitted, equivalent to COUNT(*) (the number of rows).

Description

Returns the total number (count) of input values.

Supported types

Examples

FROM employees
| STATS COUNT(height)

To count the number of rows, use COUNT() or COUNT(*)

FROM employees
| STATS count = COUNT(*) BY languages
| SORT languages DESC

The expression can use inline functions. This example splits a string into multiple values using the SPLIT function and counts the values

ROW words="foo;bar;baz;qux;quux;foo"
| STATS word_count = COUNT(SPLIT(words, ";"))

To count the number of times an expression returns TRUE use a WHERE command to remove rows that shouldn’t be included

ROW n=1
| WHERE n < 0
| STATS COUNT(n)

To count the same stream of data based on two different expressions use the pattern COUNT(<expression> OR NULL). This builds on the three-valued logic (https://en.wikipedia.org/wiki/Three-valued_logic[3VL]) of the language: TRUE OR NULL is TRUE, but FALSE OR NULL is NULL, plus the way COUNT handles NULLs: COUNT(TRUE) and COUNT(FALSE) are both 1, but COUNT(NULL) is 0.

ROW n=1
| STATS COUNT(n > 0 OR NULL), COUNT(n < 0 OR NULL)

Syntax

Parameters

field

Column or literal for which to count the number of distinct values.

precision

Precision threshold. Refer to Counts are approximate. The maximum supported value is 40000. Thresholds above this number will have the same effect as a threshold of 40000. The default value is 3000.

Description

Returns the approximate number of distinct values.

Supported types

Examples

FROM hosts
| STATS COUNT_DISTINCT(ip0), COUNT_DISTINCT(ip1)

With the optional second parameter to configure the precision threshold

FROM hosts
| STATS COUNT_DISTINCT(ip0, 80000), COUNT_DISTINCT(ip1, 5)

The expression can use inline functions. This example splits a string into multiple values using the SPLIT function and counts the unique values

ROW words="foo;bar;baz;qux;quux;foo"
| STATS distinct_word_count = COUNT_DISTINCT(SPLIT(words, ";"))

Computing exact counts requires loading values into a set and returning its size. This doesn’t scale when working on high-cardinality sets and/or large values as the required memory usage and the need to communicate those per-shard sets between nodes would utilize too many resources of the cluster.

This COUNT_DISTINCT function is based on the HyperLogLog++ algorithm, which counts based on the hashes of the values with some interesting properties:

• configurable precision, which decides on how to trade memory for accuracy,
• excellent accuracy on low-cardinality sets,
• fixed memory usage: no matter if there are tens or billions of unique values, memory usage only depends on the configured precision.

For a precision threshold of c, the implementation that we are using requires about c * 8 bytes.

The following chart shows how the error varies before and after the threshold:

For all 3 thresholds, counts have been accurate up to the configured threshold. Although not guaranteed, this is likely to be the case. Accuracy in practice depends on the dataset in question. In general, most datasets show consistently good accuracy. Also note that even with a threshold as low as 100, the error remains very low (1-6% as seen in the above graph) even when counting millions of items.

The HyperLogLog++ algorithm depends on the leading zeros of hashed values, the exact distributions of hashes in a dataset can affect the accuracy of the cardinality.

The COUNT_DISTINCT function takes an optional second parameter to configure the precision threshold. The precision_threshold options allows to trade memory for accuracy, and defines a unique count below which counts are expected to be close to accurate. Above this value, counts might become a bit more fuzzy. The maximum supported value is 40000, thresholds above this number will have the same effect as a threshold of 40000. The default value is 3000.

Syntax

Parameters

true

Description

The maximum value of a field.

Supported types

Examples

FROM employees
| STATS MAX(languages)

The expression can use inline functions. For example, to calculate the maximum over an average of a multivalued column, use MV_AVG to first average the multiple values per row, and use the result with the MAX function

FROM employees
| STATS max_avg_salary_change = MAX(MV_AVG(salary_change))

Syntax

Parameters

true

Description

The value that is greater than half of all values and less than half of all values, also known as the 50% PERCENTILE.

Supported types

Examples

FROM employees
| STATS MEDIAN(salary), PERCENTILE(salary, 50)

The expression can use inline functions. For example, to calculate the median of the maximum values of a multivalued column, first use MV_MAX to get the maximum value per row, and use the result with the MEDIAN function

FROM employees
| STATS median_max_salary_change = MEDIAN(MV_MAX(salary_change))

Syntax

Parameters

true

Description

Returns the median absolute deviation, a measure of variability. It is a robust statistic, meaning that it is useful for describing data that may have outliers, or may not be normally distributed. For such data it can be more descriptive than standard deviation. It is calculated as the median of each data point’s deviation from the median of the entire sample. That is, for a random variable X, the median absolute deviation is median(|median(X) - X|).

Supported types

Examples

FROM employees
| STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary)

The expression can use inline functions. For example, to calculate the median absolute deviation of the maximum values of a multivalued column, first use MV_MAX to get the maximum value per row, and use the result with the MEDIAN_ABSOLUTE_DEVIATION function

FROM employees
| STATS m_a_d_max_salary_change = MEDIAN_ABSOLUTE_DEVIATION(MV_MAX(salary_change))

Syntax

Parameters

true

Description

The minimum value of a field.

Supported types

Examples

FROM employees
| STATS MIN(languages)

The expression can use inline functions. For example, to calculate the minimum over an average of a multivalued column, use MV_AVG to first average the multiple values per row, and use the result with the MIN function

FROM employees
| STATS min_avg_salary_change = MIN(MV_AVG(salary_change))

Syntax

Parameters

true

Description

Returns the value at which a certain percentage of observed values occur. For example, the 95th percentile is the value which is greater than 95% of the observed values and the 50th percentile is the MEDIAN.

Supported types

Examples

FROM employees
| STATS p0 = PERCENTILE(salary,  0)
     , p50 = PERCENTILE(salary, 50)
     , p99 = PERCENTILE(salary, 99)

The expression can use inline functions. For example, to calculate a percentile of the maximum values of a multivalued column, first use MV_MAX to get the maximum value per row, and use the result with the PERCENTILE function

FROM employees
| STATS p80_max_salary_change = PERCENTILE(MV_MAX(salary_change), 80)

There are many different algorithms to calculate percentiles. The naive implementation simply stores all the values in a sorted array. To find the 50th percentile, you simply find the value that is at my_array[count(my_array) * 0.5].

Clearly, the naive implementation does not scale — the sorted array grows linearly with the number of values in your dataset. To calculate percentiles across potentially billions of values in an Elasticsearch cluster, approximate percentiles are calculated.

The algorithm used by the percentile metric is called TDigest (introduced by Ted Dunning in Computing Accurate Quantiles using T-Digests).

When using this metric, there are a few guidelines to keep in mind:

• Accuracy is proportional to q(1-q). This means that extreme percentiles (e.g. 99%) are more accurate than less extreme percentiles, such as the median
• For small sets of values, percentiles are highly accurate (and potentially 100% accurate if the data is small enough).
• As the quantity of values in a bucket grows, the algorithm begins to approximate the percentiles. It is effectively trading accuracy for memory savings. The exact level of inaccuracy is difficult to generalize, since it depends on your data distribution and volume of data being aggregated

The following chart shows the relative error on a uniform distribution depending on the number of collected values and the requested percentile:

It shows how precision is better for extreme percentiles. The reason why error diminishes for large number of values is that the law of large numbers makes the distribution of values more and more uniform and the t-digest tree can do a better job at summarizing it. It would not be the case on more skewed distributions.

Syntax

Parameters

true

Description

Calculate the spatial centroid over a field with spatial point geometry type.

Supported types

Example

FROM airports
| STATS centroid=ST_CENTROID_AGG(location)

Syntax

Parameters

true

Description

Calculate the spatial extent over a field with geometry type. Returns a bounding box for all values of the field.

Supported types

Example

FROM airports
| WHERE country == "India"
| STATS extent = ST_EXTENT_AGG(location)

Syntax

Parameters

true

Description

The standard deviation of a numeric field.

Supported types

Examples

FROM employees
| STATS STD_DEV(height)

The expression can use inline functions. For example, to calculate the standard deviation of each employee’s maximum salary changes, first use MV_MAX on each row, and then use STD_DEV on the result

FROM employees
| STATS stddev_salary_change = STD_DEV(MV_MAX(salary_change))

Syntax

Parameters

true

Description

The sum of a numeric expression.

Supported types

Examples

FROM employees
| STATS SUM(languages)

The expression can use inline functions. For example, to calculate the sum of each employee’s maximum salary changes, apply the MV_MAX function to each row and then sum the results

FROM employees
| STATS total_salary_changes = SUM(MV_MAX(salary_change))

Syntax

Parameters

field

The field to collect the top values for.

limit

The maximum number of values to collect.

order

The order to calculate the top values. Either asc or desc.

Description

Collects the top values for a field. Includes repeated values.

Supported types

Example

FROM employees
| STATS top_salaries = TOP(salary, 3, "desc"), top_salary = MAX(salary)

Syntax

Parameters

true

Description

Returns all values in a group as a multivalued field. The order of the returned values isn’t guaranteed. If you need the values returned in order use MV_SORT.

Supported types

Example

  FROM employees
| EVAL first_letter = SUBSTRING(first_name, 0, 1)
| STATS first_name=MV_SORT(VALUES(first_name)) BY first_letter
| SORT first_letter

Syntax

Parameters

number

A numeric value.

weight

A numeric weight.

Description

The weighted average of a numeric expression.

Supported types

Example

FROM employees
| STATS w_avg = WEIGHTED_AVG(salary, height) by languages
| EVAL w_avg = ROUND(w_avg)
| KEEP w_avg, languages
| SORT languages

The STATS command supports these grouping functions:

• BUCKET
• [preview] CATEGORIZE

Syntax

Parameters

field

Numeric or date expression from which to derive buckets.

buckets

Target number of buckets, or desired bucket size if from and to parameters are omitted.

from

Start of the range. Can be a number, a date or a date expressed as a string.

to

End of the range. Can be a number, a date or a date expressed as a string.

Description

Creates groups of values - buckets - out of a datetime or numeric input. The size of the buckets can either be provided directly, or chosen based on a recommended count and values range.

Supported types

Examples

BUCKET can work in two modes: one in which the size of the bucket is computed based on a buckets count recommendation (four parameters) and a range, and another in which the bucket size is provided directly (two parameters).

Using a target number of buckets, a start of a range, and an end of a range, BUCKET picks an appropriate bucket size to generate the target number of buckets or fewer. For example, asking for at most 20 buckets over a year results in monthly buckets:

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT hire_date

The goal isn’t to provide exactly the target number of buckets, it’s to pick a range that people are comfortable with that provides at most the target number of buckets.

Combine BUCKET with an aggregation to create a histogram:

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT month

Asking for more buckets can result in a smaller range. For example, asking for at most 100 buckets in a year results in weekly buckets:

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT week

If the desired bucket size is known in advance, simply provide it as the second argument, leaving the range out:

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)
| SORT week

BUCKET can also operate on numeric fields. For example, to create a salary histogram:

FROM employees
| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999)
| SORT bs

Unlike the earlier example that intentionally filters on a date range, you rarely want to filter on a numeric range. You have to find the min and max separately. ES|QL doesn’t yet have an easy way to do that automatically.

The range can be omitted if the desired bucket size is known in advance. Simply provide it as the second argument:

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.)
| SORT b

Create hourly buckets for the last 24 hours, and calculate the number of events per hour:

FROM sample_data
| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()
| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())

Create monthly buckets for the year 1985, and calculate the average salary by hiring month

FROM employees
| WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
| SORT bucket

BUCKET may be used in both the aggregating and grouping part of the STATS …​ BY …​ command provided that in the aggregating part the function is referenced by an alias defined in the grouping part, or that it is invoked with the exact same expression:

FROM employees
| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.)
| SORT b1, b2
| KEEP s1, b1, s2, b2

Sometimes you need to change the start value of each bucket by a given duration (similar to date histogram aggregation’s offset parameter). To do so, you will need to take into account how the language handles expressions within the STATS command: if these contain functions or arithmetic operators, a virtual EVAL is inserted before and/or after the STATS command. Consequently, a double compensation is needed to adjust the bucketed date value before the aggregation and then again after. For instance, inserting a negative offset of 1 hour to buckets of 1 year looks like this:

FROM employees
| STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR
| EVAL d_count = MV_COUNT(dates)
| SORT d_count, b
| LIMIT 3

Syntax

Parameters

field

Expression to categorize

Description

Groups text messages into categories of similarly formatted text values.

CATEGORIZE has the following limitations:

• can’t be used within other expressions
• can’t be used with multiple groupings
• can’t be used or referenced within aggregate functions

Supported types

Example

This example categorizes server logs messages into categories and aggregates their counts.

FROM sample_data
| STATS count=COUNT() BY category=CATEGORIZE(message)

Conditional functions return one of their arguments by evaluating in an if-else manner. ES|QL supports these conditional functions:

• CASE
• COALESCE
• GREATEST
• LEAST

Syntax

Parameters

condition

A condition.

trueValue

The value that’s returned when the corresponding condition is the first to evaluate to true. The default value is returned when no condition matches.

elseValue

The value that’s returned when no condition evaluates to true.

Description

Accepts pairs of conditions and values. The function returns the value that belongs to the first condition that evaluates to true. If the number of arguments is odd, the last argument is the default value which is returned when no condition matches. If the number of arguments is even, and no condition matches, the function returns null.

Supported types

Examples

Determine whether employees are monolingual, bilingual, or polyglot:

FROM employees
| EVAL type = CASE(
    languages <= 1, "monolingual",
    languages <= 2, "bilingual",
     "polyglot")
| KEEP emp_no, languages, type

Calculate the total connection success rate based on log messages:

FROM sample_data
| EVAL successful = CASE(
    STARTS_WITH(message, "Connected to"), 1,
    message == "Connection error", 0
  )
| STATS success_rate = AVG(successful)

Calculate an hourly error rate as a percentage of the total number of log messages:

FROM sample_data
| EVAL error = CASE(message LIKE "*error*", 1, 0)
| EVAL hour = DATE_TRUNC(1 hour, @timestamp)
| STATS error_rate = AVG(error) by hour
| SORT hour

Syntax

Parameters

first

Expression to evaluate.

rest

Other expression to evaluate.

Description

Returns the first of its arguments that is not null. If all arguments are null, it returns null.

Supported types

Example

ROW a=null, b="b"
| EVAL COALESCE(a, b)

Syntax

Parameters

first

First of the columns to evaluate.

rest

The rest of the columns to evaluate.

Description

Returns the maximum value from multiple columns. This is similar to MV_MAX except it is intended to run on multiple columns at once.

Supported types

Example

ROW a = 10, b = 20
| EVAL g = GREATEST(a, b)

Syntax

Parameters

first

First of the columns to evaluate.

rest

The rest of the columns to evaluate.

Description

Returns the minimum value from multiple columns. This is similar to MV_MIN except it is intended to run on multiple columns at once.

Supported types

Example

ROW a = 10, b = 20
| EVAL l = LEAST(a, b)

ES|QL supports these date-time functions:

• DATE_DIFF
• DATE_EXTRACT
• DATE_FORMAT
• DATE_PARSE
• DATE_TRUNC
• NOW

Syntax

Parameters

unit

Time difference unit

startTimestamp

A string representing a start timestamp

endTimestamp

A string representing an end timestamp

Description

Subtracts the startTimestamp from the endTimestamp and returns the difference in multiples of unit. If startTimestamp is later than the endTimestamp, negative values are returned.

Note that while there is an overlap between the function’s supported units and ES|QL's supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not necessarily common with the date-time nomenclature used by Elasticsearch.

Supported types

Examples

ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2)

When subtracting in calendar units - like year, month a.s.o. - only the fully elapsed units are counted. To avoid this and obtain also remainders, simply switch to the next smaller unit and do the date math accordingly.

ROW end_23=TO_DATETIME("2023-12-31T23:59:59.999Z"),
  start_24=TO_DATETIME("2024-01-01T00:00:00.000Z"),
    end_24=TO_DATETIME("2024-12-31T23:59:59.999")
| EVAL end23_to_start24=DATE_DIFF("year", end_23, start_24)
| EVAL end23_to_end24=DATE_DIFF("year", end_23, end_24)
| EVAL start_to_end_24=DATE_DIFF("year", start_24, end_24)

Syntax

Parameters

datePart

Part of the date to extract. Can be: aligned_day_of_week_in_month, aligned_day_of_week_in_year, aligned_week_of_month, aligned_week_of_year, ampm_of_day, clock_hour_of_ampm, clock_hour_of_day, day_of_month, day_of_week, day_of_year, epoch_day, era, hour_of_ampm, hour_of_day, instant_seconds, micro_of_day, micro_of_second, milli_of_day, milli_of_second, minute_of_day, minute_of_hour, month_of_year, nano_of_day, nano_of_second, offset_seconds, proleptic_month, second_of_day, second_of_minute, year, or year_of_era. Refer to java.time.temporal.ChronoField for a description of these values. If null, the function returns null.

date

Date expression. If null, the function returns null.

Description

Extracts parts of a date, like year, month, day, hour.

Supported types

Examples

ROW date = DATE_PARSE("yyyy-MM-dd", "2022-05-06")
| EVAL year = DATE_EXTRACT("year", date)

Find all events that occurred outside of business hours (before 9 AM or after 5PM), on any given date:

FROM sample_data
| WHERE DATE_EXTRACT("hour_of_day", @timestamp) < 9 AND DATE_EXTRACT("hour_of_day", @timestamp) >= 17

Syntax

Parameters

dateFormat

Date format (optional). If no format is specified, the yyyy-MM-dd'T'HH:mm:ss.SSSZ format is used. If null, the function returns null.

date

Date expression. If null, the function returns null.

Description

Returns a string representation of a date, in the provided format.

Supported types

Example

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL hired = DATE_FORMAT("yyyy-MM-dd", hire_date)

Syntax

Parameters

datePattern

The date format. Refer to the DateTimeFormatter documentation for the syntax. If null, the function returns null.

dateString

Date expression as a string. If null or an empty string, the function returns null.

Description

Returns a date by parsing the second argument using the format specified in the first argument.

Supported types

Example

ROW date_string = "2022-05-06"
| EVAL date = DATE_PARSE("yyyy-MM-dd", date_string)

Syntax

Parameters

interval

Interval; expressed using the timespan literal syntax.

date

Date expression

Description

Rounds down a date to the closest interval.

Supported types

Examples

FROM employees
| KEEP first_name, last_name, hire_date
| EVAL year_hired = DATE_TRUNC(1 year, hire_date)

Combine DATE_TRUNC with STATS to create date histograms. For example, the number of hires per year:

FROM employees
| EVAL year = DATE_TRUNC(1 year, hire_date)
| STATS hires = COUNT(emp_no) BY year
| SORT year

Or an hourly error rate:

FROM sample_data
| EVAL error = CASE(message LIKE "*error*", 1, 0)
| EVAL hour = DATE_TRUNC(1 hour, @timestamp)
| STATS error_rate = AVG(error) by hour
| SORT hour

Syntax

Parameters

Description

Returns current date and time.

Supported types

Examples

ROW current_date = NOW()

To retrieve logs from the last hour:

FROM sample_data
| WHERE @timestamp > NOW() - 1 hour

ES|QL supports these IP functions:

• CIDR_MATCH
• IP_PREFIX

Syntax

Parameters

ip

IP address of type ip (both IPv4 and IPv6 are supported).

blockX

CIDR block to test the IP against.

Description

Returns true if the provided IP is contained in one of the provided CIDR blocks.

Supported types

Example

FROM hosts
| WHERE CIDR_MATCH(ip1, "127.0.0.2/32", "127.0.0.3/32")
| KEEP card, host, ip0, ip1

Syntax

Parameters

ip

IP address of type ip (both IPv4 and IPv6 are supported).

prefixLengthV4

Prefix length for IPv4 addresses.

prefixLengthV6

Prefix length for IPv6 addresses.

Description

Truncates an IP to a given prefix length.

Supported types

Example

row ip4 = to_ip("1.2.3.4"), ip6 = to_ip("fe80::cae2:65ff:fece:feb9")
| eval ip4_prefix = ip_prefix(ip4, 24, 0), ip6_prefix = ip_prefix(ip6, 0, 112);

ES|QL supports these mathematical functions:

• ABS
• ACOS
• ASIN
• ATAN
• ATAN2
• CBRT
• CEIL
• COS
• COSH
• E
• EXP
• FLOOR
• HYPOT
• LOG
• LOG10
• PI
• POW
• ROUND
• SIGNUM
• SIN
• SINH
• SQRT
• TAN
• TANH
• TAU

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the absolute value.

Supported types

Examples

ROW number = -1.0
| EVAL abs_number = ABS(number)

FROM employees
| KEEP first_name, last_name, height
| EVAL abs_height = ABS(0.0 - height)

Syntax

Parameters

number

Number between -1 and 1. If null, the function returns null.

Description

Returns the arccosine of n as an angle, expressed in radians.

Supported types

Example

ROW a=.9
| EVAL acos=ACOS(a)

Syntax

Parameters

number

Number between -1 and 1. If null, the function returns null.

Description

Returns the arcsine of the input numeric expression as an angle, expressed in radians.

Supported types

Example

ROW a=.9
| EVAL asin=ASIN(a)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the arctangent of the input numeric expression as an angle, expressed in radians.

Supported types

Example

ROW a=12.9
| EVAL atan=ATAN(a)

Syntax

Parameters

y_coordinate

y coordinate. If null, the function returns null.

x_coordinate

x coordinate. If null, the function returns null.

Description

The angle between the positive x-axis and the ray from the origin to the point (x , y) in the Cartesian plane, expressed in radians.

Supported types

Example

ROW y=12.9, x=.6
| EVAL atan2=ATAN2(y, x)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the cube root of a number. The input can be any numeric value, the return value is always a double. Cube roots of infinities are null.

Supported types

Example

ROW d = 1000.0
| EVAL c = cbrt(d)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Round a number up to the nearest integer.

Supported types

Example

ROW a=1.8
| EVAL a=CEIL(a)

Syntax

Parameters

angle

An angle, in radians. If null, the function returns null.

Description

Returns the cosine of an angle.

Supported types

Example

ROW a=1.8
| EVAL cos=COS(a)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the hyperbolic cosine of a number.

Supported types

Example

ROW a=1.8
| EVAL cosh=COSH(a)

Syntax

Parameters

Description

Returns Euler’s number.

Supported types

Example

ROW E()

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the value of e raised to the power of the given number.

Supported types

Example

ROW d = 5.0
| EVAL s = EXP(d)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Round a number down to the nearest integer.

Supported types

Example

ROW a=1.8
| EVAL a=FLOOR(a)

Syntax

Parameters

number1

Numeric expression. If null, the function returns null.

number2

Numeric expression. If null, the function returns null.

Description

Returns the hypotenuse of two numbers. The input can be any numeric values, the return value is always a double. Hypotenuses of infinities are null.

Supported types

Example

ROW a = 3.0, b = 4.0
| EVAL c = HYPOT(a, b)

Syntax

Parameters

base

Base of logarithm. If null, the function returns null. If not provided, this function returns the natural logarithm (base e) of a value.

number

Numeric expression. If null, the function returns null.

Description

Returns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double. Logs of zero, negative numbers, and base of one return null as well as a warning.

Supported types

Examples

ROW base = 2.0, value = 8.0
| EVAL s = LOG(base, value)

row value = 100
| EVAL s = LOG(value);

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double. Logs of 0 and negative numbers return null as well as a warning.

Supported types

Example

ROW d = 1000.0
| EVAL s = LOG10(d)

Syntax

Parameters

Description

Returns Pi, the ratio of a circle’s circumference to its diameter.

Supported types

Example

ROW PI()

Syntax

Parameters

base

Numeric expression for the base. If null, the function returns null.

exponent

Numeric expression for the exponent. If null, the function returns null.

Description

Returns the value of base raised to the power of exponent.

Supported types

Examples

ROW base = 2.0, exponent = 2
| EVAL result = POW(base, exponent)

The exponent can be a fraction, which is similar to performing a root. For example, the exponent of 0.5 will give the square root of the base:

ROW base = 4, exponent = 0.5
| EVAL s = POW(base, exponent)

Syntax

Parameters

number

The numeric value to round. If null, the function returns null.

decimals

The number of decimal places to round to. Defaults to 0. If null, the function returns null.

Description

Rounds a number to the specified number of decimal places. Defaults to 0, which returns the nearest integer. If the precision is a negative number, rounds to the number of digits left of the decimal point.

Supported types

Example

FROM employees
| KEEP first_name, last_name, height
| EVAL height_ft = ROUND(height * 3.281, 1)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the sign of the given number. It returns -1 for negative numbers, 0 for 0 and 1 for positive numbers.

Supported types

Example

ROW d = 100.0
| EVAL s = SIGNUM(d)

Syntax

Parameters

angle

An angle, in radians. If null, the function returns null.

Description

Returns the sine of an angle.

Supported types

Example

ROW a=1.8
| EVAL sin=SIN(a)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the hyperbolic sine of a number.

Supported types

Example

ROW a=1.8
| EVAL sinh=SINH(a)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the square root of a number. The input can be any numeric value, the return value is always a double. Square roots of negative numbers and infinities are null.

Supported types

Example

ROW d = 100.0
| EVAL s = SQRT(d)

Syntax

Parameters

angle

An angle, in radians. If null, the function returns null.

Description

Returns the tangent of an angle.

Supported types

Example

ROW a=1.8
| EVAL tan=TAN(a)

Syntax

Parameters

number

Numeric expression. If null, the function returns null.

Description

Returns the hyperbolic tangent of a number.

Supported types

Example

ROW a=1.8
| EVAL tanh=TANH(a)

Syntax

Parameters

Description

Returns the ratio of a circle’s circumference to its radius.

Supported types

Example

ROW TAU()

Full text functions are used to search for text in fields. Text analysis is used to analyze the query before it is searched.

Full text functions can be used to match multivalued fields. A multivalued field that contains a value that matches a full text query is considered to match the query.

Full text functions are significantly more performant for text search use cases on large data sets than using pattern matching or regular expressions with LIKE or RLIKE

See full text search limitations for information on the limitations of full text search.

ES|QL supports these full-text search functions:

• [preview] KQL
• [preview] MATCH
• [preview] QSTR

Syntax

Parameters

query

Query string in KQL query string format.

Description

Performs a KQL query. Returns true if the provided KQL query string matches the row.

Supported types

Example

FROM books
| WHERE KQL("author: Faulkner")
| KEEP book_no, author
| SORT book_no
| LIMIT 5

Syntax

Parameters

field

Field that the query will target.

query

Value to find in the provided field.

options

(Optional) Match additional options as function named parameters. See match query for more information.

Description

Use MATCH to perform a match query on the specified field. Using MATCH is equivalent to using the match query in the Elasticsearch Query DSL. Match can be used on fields from the text family like text and semantic_text, as well as other field types like keyword, boolean, dates, and numeric types. Match can use function named parameters to specify additional options for the match query. All match query parameters are supported. For a simplified syntax, you can use the match operator : operator instead of MATCH. MATCH returns true if the provided query matches the row.

Supported types

Supported function named parameters

Examples

FROM books
| WHERE MATCH(author, "Faulkner")
| KEEP book_no, author
| SORT book_no
| LIMIT 5

FROM books
| WHERE MATCH(title, "Hobbit Back Again", {"operator": "AND"})
| KEEP title;

Syntax

Parameters

query

Query string in Lucene query string format.

Description

Performs a query string query. Returns true if the provided query string matches the row.

Supported types

Example

FROM books
| WHERE QSTR("author: Faulkner")
| KEEP book_no, author
| SORT book_no
| LIMIT 5

ES|QL supports these spatial functions:

• ST_DISTANCE
• ST_INTERSECTS
• ST_DISJOINT
• ST_CONTAINS
• ST_WITHIN
• ST_X
• ST_Y
• [preview] ST_ENVELOPE
• [preview] ST_XMAX
• [preview] ST_XMIN
• [preview] ST_YMAX
• [preview] ST_YMIN

Syntax

Parameters

geomA

Expression of type geo_point or cartesian_point. If null, the function returns null.

geomB

Expression of type geo_point or cartesian_point. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_point and cartesian_point parameters.

Description

Computes the distance between two points. For cartesian geometries, this is the pythagorean distance in the same units as the original coordinates. For geographic geometries, this is the circular distance along the great circle in meters.

Supported types

Example

FROM airports
| WHERE abbrev == "CPH"
| EVAL distance = ST_DISTANCE(location, city_location)
| KEEP abbrev, name, location, city_location, distance

Syntax

Parameters

geomA

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null.

geomB

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns true if two geometries intersect. They intersect if they have any point in common, including their interior points (points along lines or within polygons). This is the inverse of the ST_DISJOINT function. In mathematical terms: ST_Intersects(A, B) ⇔ A ⋂ B ≠ ∅

Supported types

Example

FROM airports
| WHERE ST_INTERSECTS(location, TO_GEOSHAPE("POLYGON((42 14, 43 14, 43 15, 42 15, 42 14))"))

Syntax

Parameters

geomA

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null.

geomB

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns whether the two geometries or geometry columns are disjoint. This is the inverse of the ST_INTERSECTS function. In mathematical terms: ST_Disjoint(A, B) ⇔ A ⋂ B = ∅

Supported types

Example

FROM airport_city_boundaries
| WHERE ST_DISJOINT(city_boundary, TO_GEOSHAPE("POLYGON((-10 -60, 120 -60, 120 60, -10 60, -10 -60))"))
| KEEP abbrev, airport, region, city, city_location

Syntax

Parameters

geomA

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null.

geomB

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns whether the first geometry contains the second geometry. This is the inverse of the ST_WITHIN function.

Supported types

Example

FROM airport_city_boundaries
| WHERE ST_CONTAINS(city_boundary, TO_GEOSHAPE("POLYGON((109.35 18.3, 109.45 18.3, 109.45 18.4, 109.35 18.4, 109.35 18.3))"))
| KEEP abbrev, airport, region, city, city_location

Syntax

Parameters

geomA

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null.

geomB

Expression of type geo_point, cartesian_point, geo_shape or cartesian_shape. If null, the function returns null. The second parameter must also have the same coordinate system as the first. This means it is not possible to combine geo_* and cartesian_* parameters.

Description

Returns whether the first geometry is within the second geometry. This is the inverse of the ST_CONTAINS function.

Supported types

Example

FROM airport_city_boundaries
| WHERE ST_WITHIN(city_boundary, TO_GEOSHAPE("POLYGON((109.1 18.15, 109.6 18.15, 109.6 18.65, 109.1 18.65, 109.1 18.15))"))
| KEEP abbrev, airport, region, city, city_location

Syntax

Parameters

point

Expression of type geo_point or cartesian_point. If null, the function returns null.

Description

Extracts the x coordinate from the supplied point. If the points is of type geo_point this is equivalent to extracting the longitude value.

Supported types

Example

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)

Syntax

Parameters

point

Expression of type geo_point or cartesian_point. If null, the function returns null.

Description

Extracts the y coordinate from the supplied point. If the points is of type geo_point this is equivalent to extracting the latitude value.

Supported types

Example

ROW point = TO_GEOPOINT("POINT(42.97109629958868 14.7552534006536)")
| EVAL x =  ST_X(point), y = ST_Y(point)

Syntax

Parameters

geometry

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Determines the minimum bounding box of the supplied geometry.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| KEEP abbrev, airport, envelope

Syntax

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the maximum value of the x coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the maximum longitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax

Syntax

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the minimum value of the x coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the minimum longitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax

Syntax

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the maximum value of the y coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the maximum latitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax

Syntax

Parameters

point

Expression of type geo_point, geo_shape, cartesian_point or cartesian_shape. If null, the function returns null.

Description

Extracts the minimum value of the y coordinates from the supplied geometry. If the geometry is of type geo_point or geo_shape this is equivalent to extracting the minimum latitude value.

Supported types

Example

FROM airport_city_boundaries
| WHERE abbrev == "CPH"
| EVAL envelope = ST_ENVELOPE(city_boundary)
| EVAL xmin = ST_XMIN(envelope), xmax = ST_XMAX(envelope), ymin = ST_YMIN(envelope), ymax = ST_YMAX(envelope)
| KEEP abbrev, airport, xmin, xmax, ymin, ymax

ES|QL supports these string functions:

• BIT_LENGTH
• BYTE_LENGTH
• CONCAT
• ENDS_WITH
• FROM_BASE64
• HASH
• LEFT
• LENGTH
• LOCATE
• LTRIM
• MD5
• REPEAT
• REPLACE
• REVERSE
• RIGHT
• RTRIM
• SHA1
• SHA256
• SPACE
• SPLIT
• STARTS_WITH
• SUBSTRING
• TO_BASE64
• TO_LOWER
• TO_UPPER
• TRIM

Syntax

Parameters

string

String expression. If null, the function returns null.

Description

Returns the bit length of a string.

Supported types

Example

FROM airports
| WHERE country == "India"
| KEEP city
| EVAL fn_length = LENGTH(city), fn_bit_length = BIT_LENGTH(city)

Syntax

Parameters

string

String expression. If null, the function returns null.

Description

Returns the byte length of a string.

Supported types

Example

FROM airports
| WHERE country == "India"
| KEEP city
| EVAL fn_length = LENGTH(city), fn_byte_length = BYTE_LENGTH(city)

Syntax

Parameters

string1

Strings to concatenate.

string2

Strings to concatenate.

Description

Concatenates two or more strings.

Supported types

Example

FROM employees
| KEEP first_name, last_name
| EVAL fullname = CONCAT(first_name, " ", last_name)

Syntax

Parameters