OpenSearch/x-pack/docs/en/sql/functions/index.asciidoc

[[sql-functions]]
== Functions and Operators

{es-sql} provides a number of built-in operators and functions.

=== Comparison Operators

{es-sql} supports the following comparison operators:

* Equality (`=`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereFieldEquality]
--------------------------------------------------

* Inequality (`<>` or `!=` or `<=>`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereFieldNonEquality]
--------------------------------------------------

* Comparison (`<`, `<=`, `>`, `>=`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereFieldLessThan]
--------------------------------------------------

* `BETWEEN`

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereBetween]
--------------------------------------------------

* `IS NULL`/`IS NOT NULL`

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereIsNotNullAndIsNull]
--------------------------------------------------


=== Logical Operators

{es-sql} supports the following logical operators:

* `AND`

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereFieldAndComparison]
--------------------------------------------------

* `OR`

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereFieldOrComparison]
--------------------------------------------------

* `NOT`

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/filter.sql-spec[whereFieldEqualityNot]
--------------------------------------------------


=== Math Operators

{es-sql} supports the following math operators:

* Add (`+`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/arithmetic.sql-spec[plus]
--------------------------------------------------

* Subtract (infix `-`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/arithmetic.sql-spec[minus]
--------------------------------------------------

* Negate (unary `-`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/arithmetic.sql-spec[unaryMinus]
--------------------------------------------------

* Multiply (`*`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/arithmetic.sql-spec[multiply]
--------------------------------------------------

* Divide (`/`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/arithmetic.sql-spec[divide]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Modulo_operation[Modulo] or Reminder(`%`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/arithmetic.sql-spec[mod]
--------------------------------------------------


=== Math Functions

All math and trigonometric functions require their input (where applicable)
to be numeric.

==== Generic

* `ABS`

https://en.wikipedia.org/wiki/Absolute_value[Absolute value], returns \[same type as input]

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[abs]
--------------------------------------------------

* `CBRT`

https://en.wikipedia.org/wiki/Cube_root[Cube root], returns `double`

// TODO make the example in the tests presentable

* `CEIL`

https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Ceiling], returns `double`

* `CEILING`

Same as `CEIL`

// TODO make the example in the tests presentable

* `E`

https://en.wikipedia.org/wiki/E_%28mathematical_constant%29[Euler's number], returns `2.7182818284590452354`


* https://en.wikipedia.org/wiki/Rounding#Round_half_up[Round] (`ROUND`)

// TODO make the example in the tests presentable

NOTE: This rounds "half up" meaning that `ROUND(-1.5)` results in `-1`.


* https://en.wikipedia.org/wiki/Floor_and_ceiling_functions[Floor] (`FLOOR`)

// TODO make the example in the tests presentable

* https://en.wikipedia.org/wiki/Natural_logarithm[Natural logarithm] (`LOG`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[log]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Logarithm[Logarithm] base 10 (`LOG10`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[log10]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Square_root[Square root] (`SQRT`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[sqrt]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Exponential_function[e^x^] (`EXP`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[exp]
--------------------------------------------------

* https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html#expm1-double-[e^x^ - 1] (`EXPM1`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[expm1]
--------------------------------------------------

==== Trigonometric

* Convert from https://en.wikipedia.org/wiki/Radian[radians]
to https://en.wikipedia.org/wiki/Degree_(angle)[degrees] (`DEGREES`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[degrees]
--------------------------------------------------

* Convert from https://en.wikipedia.org/wiki/Degree_(angle)[degrees]
to https://en.wikipedia.org/wiki/Radian[radians] (`RADIANS`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[degrees]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Trigonometric_functions#sine[Sine] (`SIN`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[sin]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Trigonometric_functions#cosine[Cosine] (`COS`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[cos]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Trigonometric_functions#tangent[Tangent] (`TAN`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[tan]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[Arc sine] (`ASIN`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[asin]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[Arc cosine] (`ACOS`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[acos]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[Arc tangent] (`ATAN`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[atan]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Hyperbolic_function[Hyperbolic sine] (`SINH`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[sinh]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Hyperbolic_function[Hyperbolic cosine] (`COSH`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/math.sql-spec[cosh]
--------------------------------------------------

[[sql-functions-datetime]]
=== Date and Time Functions

* Extract the year from a date (`YEAR`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[year]
--------------------------------------------------

* Extract the month of the year from a date (`MONTH_OF_YEAR` or `MONTH`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[monthOfYear]
--------------------------------------------------

* Extract the week of the year from a date (`WEEK_OF_YEAR` or `WEEK`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[weekOfYear]
--------------------------------------------------

* Extract the day of the year from a date (`DAY_OF_YEAR` or `DOY`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[dayOfYear]
--------------------------------------------------

* Extract the day of the month from a date (`DAY_OF_MONTH`, `DOM`, or `DAY`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[dayOfMonth]
--------------------------------------------------

* Extract the day of the week from a date (`DAY_OF_WEEK` or `DOW`).
Monday is `1`, Tuesday is `2`, etc.

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[dayOfWeek]
--------------------------------------------------

* Extract the hour of the day from a date (`HOUR_OF_DAY` or `HOUR`).
Monday is `1`, Tuesday is `2`, etc.

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[hourOfDay]
--------------------------------------------------

* Extract the minute of the day from a date (`MINUTE_OF_DAY`).

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[minuteOfDay]
--------------------------------------------------

* Extract the minute of the hour from a date (`MINUTE_OF_HOUR`, `MINUTE`).

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[minuteOfHour]
--------------------------------------------------

* Extract the second of the minute from a date (`SECOND_OF_MINUTE`, `SECOND`).

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[secondOfMinute]
--------------------------------------------------

* Extract

As an alternative, one can support `EXTRACT` to extract fields from datetimes.
You can run any <<sql-functions-datetime,datetime function>>
with `EXTRACT(<datetime_function> FROM <expression>)`. So

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[extractDayOfYear]
--------------------------------------------------

is the equivalent to

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/datetime.csv-spec[dayOfYear]
--------------------------------------------------


[[sql-functions-aggregate]]
=== Aggregate Functions

==== Basic

* https://en.wikipedia.org/wiki/Arithmetic_mean[Average] (`AVG`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/agg.sql-spec[avg]
--------------------------------------------------

* Count the number of matching fields (`COUNT`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/agg.sql-spec[countStar]
--------------------------------------------------

* Count the number of distinct values in matching documents (`COUNT(DISTINCT`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/agg.sql-spec[countDistinct]
--------------------------------------------------

* Find the maximum value in matching documents (`MAX`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/agg.sql-spec[max]
--------------------------------------------------

* Find the minimum value in matching documents (`MIN`)

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/agg.sql-spec[min]
--------------------------------------------------

* https://en.wikipedia.org/wiki/Kahan_summation_algorithm[Sum]
all values of matching documents (`SUM`).

["source","sql",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{sql-specs}/agg.csv-spec[sum]
--------------------------------------------------