Browse Source

ESQL docs: Push down needs index and doc_values (#110353)

This adds a `NOTE` to each comparison saying that pushing the comparison
to the search index requires that the field have an `index` and
`doc_values`. This is unique compared to the rest of Elasticsearch which
only requires an `index` and it's caused by our insistence that
comparisons only return true for single-valued fields. We can in future
accelerate comparisons without `doc_values`, but we just haven't written
that code yet.
Nik Everett 1 year ago
parent
commit
6fbc52d170
1 changed files with 69 additions and 0 deletions
  1. 69 0
      docs/reference/esql/functions/binary.asciidoc

+ 69 - 0
docs/reference/esql/functions/binary.asciidoc

@@ -7,6 +7,12 @@
 [.text-center]
 image::esql/functions/signature/equals.svg[Embedded,opts=inline]
 
+Check if two fields are equal. If either field is <<esql-multivalued-fields,multivalued>> then
+the result is `null`.
+
+NOTE: This is pushed to the underlying search index if one side of the comparison is constant
+      and the other side is a field in the index that has both an <<mapping-index>> and <<doc-values>>.
+
 Supported types:
 
 include::types/equals.asciidoc[]
@@ -15,6 +21,12 @@ include::types/equals.asciidoc[]
 [.text-center]
 image::esql/functions/signature/not_equals.svg[Embedded,opts=inline]
 
+Check if two fields are unequal. If either field is <<esql-multivalued-fields,multivalued>> then
+the result is `null`.
+
+NOTE: This is pushed to the underlying search index if one side of the comparison is constant
+      and the other side is a field in the index that has both an <<mapping-index>> and <<doc-values>>.
+
 Supported types:
 
 include::types/not_equals.asciidoc[]
@@ -23,55 +35,112 @@ include::types/not_equals.asciidoc[]
 [.text-center]
 image::esql/functions/signature/less_than.svg[Embedded,opts=inline]
 
+Check if one field is less than another. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+NOTE: This is pushed to the underlying search index if one side of the comparison is constant
+      and the other side is a field in the index that has both an <<mapping-index>> and <<doc-values>>.
+
+Supported types:
+
 include::types/less_than.asciidoc[]
 
 ==== Less than or equal to `<=`
 [.text-center]
 image::esql/functions/signature/less_than_or_equal.svg[Embedded,opts=inline]
 
+Check if one field is less than or equal to another. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+NOTE: This is pushed to the underlying search index if one side of the comparison is constant
+      and the other side is a field in the index that has both an <<mapping-index>> and <<doc-values>>.
+
+Supported types:
+
 include::types/less_than_or_equal.asciidoc[]
 
 ==== Greater than `>`
 [.text-center]
 image::esql/functions/signature/greater_than.svg[Embedded,opts=inline]
 
+Check if one field is greater than another. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+NOTE: This is pushed to the underlying search index if one side of the comparison is constant
+      and the other side is a field in the index that has both an <<mapping-index>> and <<doc-values>>.
+
+Supported types:
+
 include::types/greater_than.asciidoc[]
 
 ==== Greater than or equal to `>=`
 [.text-center]
 image::esql/functions/signature/greater_than_or_equal.svg[Embedded,opts=inline]
 
+Check if one field is greater than or equal to another. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+NOTE: This is pushed to the underlying search index if one side of the comparison is constant
+      and the other side is a field in the index that has both an <<mapping-index>> and <<doc-values>>.
+
+Supported types:
+
 include::types/greater_than_or_equal.asciidoc[]
 
 ==== Add `+`
 [.text-center]
 image::esql/functions/signature/add.svg[Embedded,opts=inline]
 
+Add two numbers together. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+Supported types:
+
 include::types/add.asciidoc[]
 
 ==== Subtract `-`
 [.text-center]
 image::esql/functions/signature/sub.svg[Embedded,opts=inline]
 
+Subtract one number from another. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+Supported types:
+
 include::types/sub.asciidoc[]
 
 ==== Multiply `*`
 [.text-center]
 image::esql/functions/signature/mul.svg[Embedded,opts=inline]
 
+Multiply two numbers together. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+Supported types:
+
 include::types/mul.asciidoc[]
 
 ==== Divide `/`
 [.text-center]
 image::esql/functions/signature/div.svg[Embedded,opts=inline]
 
+Divide one number by another. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
 NOTE: Division of two integer types will yield an integer result, rounding towards 0.
       If you need floating point division, <<esql-cast-operator>> one of the arguments to a `DOUBLE`.
 
+Supported types:
+
 include::types/div.asciidoc[]
 
 ==== Modulus `%`
 [.text-center]
 image::esql/functions/signature/mod.svg[Embedded,opts=inline]
 
+Divide one number by another and return the remainder. If either field is <<esql-multivalued-fields,multivalued>>
+then the result is `null`.
+
+Supported types:
+
 include::types/mod.asciidoc[]