Fix the ESQL docs for the null predicates (#130440)

Fix null predicates docs

* This also includes moving the note above the examples in the Kibana inline docs.
* Add missing knn docs
* Refine newlines in kibana docs

docs/reference/query-languages/esql/_snippets/functions/description/knn.md

@@ -0,0 +1,6 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Description**
+
+Finds the k nearest vectors to a query vector, as measured by a similarity metric. knn function finds nearest vectors through approximate search on indexed dense_vectors.
+

docs/reference/query-languages/esql/_snippets/functions/examples/knn.md

@@ -0,0 +1,30 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Examples**
+
+```esql
+from colors metadata _score
+| where knn(rgb_vector, [0, 120, 0])
+| sort _score desc, color asc
+```
+
+| color:text | rgb_vector:dense_vector |
+| --- | --- |
+| green | [0.0, 128.0, 0.0] |
+| black | [0.0, 0.0, 0.0] |
+| olive | [128.0, 128.0, 0.0] |
+| teal | [0.0, 128.0, 128.0] |
+| lime | [0.0, 255.0, 0.0] |
+| sienna | [160.0, 82.0, 45.0] |
+| maroon | [128.0, 0.0, 0.0] |
+| navy | [0.0, 0.0, 128.0] |
+| gray | [128.0, 128.0, 128.0] |
+| chartreuse | [127.0, 255.0, 0.0] |
+
+```esql
+from colors metadata _score
+| where knn(rgb_vector, [0,255,255], {"k": 4})
+| sort _score desc, color asc
+```
+
+

docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/knn.md

@@ -0,0 +1,19 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Supported function named parameters**
+
+`num_candidates`
+:   (integer) The number of nearest neighbor candidates to consider per shard while doing knn search. Cannot exceed 10,000. Increasing num_candidates tends to improve the accuracy of the final results. Defaults to 1.5 * k
+
+`boost`
+:   (float) Floating point number used to decrease or increase the relevance scores of the query.Defaults to 1.0.
+
+`k`
+:   (integer) The number of nearest neighbors to return from each shard. Elasticsearch collects k results from each shard, then merges them to find the global top results. This value must be less than or equal to num_candidates. Defaults to 10.
+
+`rescore_oversample`
+:   (double) Applies the specified oversampling for rescoring quantized vectors. See [oversampling and rescoring quantized vectors](docs-content://solutions/search/vector/knn.md#dense-vector-knn-search-rescoring) for details.
+
+`similarity`
+:   (double) The minimum similarity required for a document to be considered a match. The similarity value calculated relates to the raw similarity used, not the document score.
+

docs/reference/query-languages/esql/_snippets/functions/layout/knn.md

@@ -0,0 +1,30 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+## `KNN` [esql-knn]
+```{applies_to}
+stack: development
+serverless: preview
+```
+
+**Syntax**
+
+:::{image} ../../../images/functions/knn.svg
+:alt: Embedded
+:class: text-center
+:::
+
+
+:::{include} ../parameters/knn.md
+:::
+
+:::{include} ../description/knn.md
+:::
+
+:::{include} ../types/knn.md
+:::
+
+:::{include} ../functionNamedParams/knn.md
+:::
+
+:::{include} ../examples/knn.md
+:::

docs/reference/query-languages/esql/_snippets/functions/parameters/knn.md

@@ -0,0 +1,13 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Parameters**
+
+`field`
+:   Field that the query will target.
+
+`query`
+:   Vector value to find top nearest neighbours for.
+
+`options`
+:   (Optional) kNN additional options as [function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params). See [knn query](/reference/query-languages/query-dsl/query-dsl-match-query.md#query-dsl-knn-query) for more information.
+

docs/reference/query-languages/esql/_snippets/operators/examples/predicates.md

@@ -1,26 +0,0 @@
-% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
-
-**Examples**
-
-```esql
-FROM employees
-| WHERE birth_date IS NULL
-```
-
-| first_name:keyword | last_name:keyword |
-| --- | --- |
-| Basil | Tramer |
-| Florian | Syrotiuk |
-| Lucien | Rosenbaum |
-
-```esql
-FROM employees
-| WHERE is_rehired IS NOT NULL
-| STATS COUNT(emp_no)
-```
-
-| COUNT(emp_no):long |
-| --- |
-| 84 |
-
-

docs/reference/query-languages/esql/_snippets/operators/types/predicates.md

@@ -1,22 +0,0 @@
-% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
-
-**Supported types**
-
-| field | result |
-| --- | --- |
-| boolean | boolean |
-| cartesian_point | boolean |
-| cartesian_shape | boolean |
-| date | boolean |
-| date_nanos | boolean |
-| double | boolean |
-| geo_point | boolean |
-| geo_shape | boolean |
-| integer | boolean |
-| ip | boolean |
-| keyword | boolean |
-| long | boolean |
-| text | boolean |
-| unsigned_long | boolean |
-| version | boolean |
-

docs/reference/query-languages/esql/images/operators/predicates.svg

@@ -1 +0,0 @@
-<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="348" height="46" viewbox="0 0 348 46"><defs><style type="text/css">.c{fill:none;stroke:#222222;}.j{fill:#000000;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}.l{fill:#e4f4ff;stroke:#222222;}.syn{fill:#8D8D8D;font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;font-size:20px;}</style></defs><path class="c" d="M0 31h5m296 0h10m32 0h5"/><rect class="l" x="5" y="5" width="296" height="36" rx="7"/><text class="syn" x="15" y="31">IS NULL and IS NOT NULL</text><rect class="l" x="311" y="5" width="32" height="36" rx="7"/><text class="j" x="321" y="31">v</text></svg>

docs/reference/query-languages/esql/kibana/definition/functions/st_geohash.json

@@ -52,4 +52,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/functions/st_geohex.json

@@ -55,4 +55,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/functions/st_geohex_to_long.json

@@ -34,4 +34,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/functions/st_geohex_to_string.json

@@ -34,4 +34,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/functions/st_geotile.json

@@ -52,4 +52,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/functions/st_geotile_to_long.json

@@ -34,4 +34,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/functions/st_geotile_to_string.json

@@ -34,4 +34,4 @@
   ],
   "preview" : true,
   "snapshot_only" : true
-}
+}

docs/reference/query-languages/esql/kibana/definition/operators/is_not_null.json

@@ -223,6 +223,9 @@
       "returnType" : "boolean"
     }
   ],
+  "examples" : [
+    "FROM employees\n| WHERE is_rehired IS NOT NULL\n| STATS COUNT(emp_no)"
+  ],
   "preview" : false,
   "snapshot_only" : false
 }

docs/reference/query-languages/esql/kibana/definition/operators/is_null.json

@@ -223,6 +223,9 @@
       "returnType" : "boolean"
     }
   ],
+  "examples" : [
+    "FROM employees\n| WHERE birth_date IS NULL"
+  ],
   "preview" : false,
   "snapshot_only" : false
 }

docs/reference/query-languages/esql/kibana/definition/operators/predicates.json

@@ -1,194 +0,0 @@
-{
-  "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.",
-  "type" : "scalar",
-  "name" : "predicates",
-  "description" : "For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates.",
-  "signatures" : [
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "boolean",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "cartesian_point",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "cartesian_shape",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "date",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "date_nanos",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "double",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "geo_point",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "geo_shape",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "integer",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "ip",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "keyword",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "long",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "text",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "unsigned_long",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    },
-    {
-      "params" : [
-        {
-          "name" : "field",
-          "type" : "version",
-          "optional" : false,
-          "description" : "Input value. The input can be a single- or multi-valued column or an expression."
-        }
-      ],
-      "variadic" : false,
-      "returnType" : "boolean"
-    }
-  ],
-  "examples" : [
-    "FROM employees\n| WHERE birth_date IS NULL",
-    "FROM employees\n| WHERE is_rehired IS NOT NULL\n| STATS COUNT(emp_no)"
-  ],
-  "preview" : false,
-  "snapshot_only" : false
-}

docs/reference/query-languages/esql/kibana/docs/functions/avg_over_time.md

@@ -3,8 +3,9 @@
 ### AVG OVER TIME
 The average over time of a numeric field.
 
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds
+
 ```esql
 TS k8s
 | STATS max_cost=max(avg_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
 ```
-Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/bit_length.md

@@ -3,10 +3,11 @@
 ### BIT LENGTH
 Returns the bit length of a string.
 
+Note: All strings are in UTF-8, so a single character can use multiple bytes.
+
 ```esql
 FROM airports
 | WHERE country == "India"
 | KEEP city
 | EVAL fn_length = LENGTH(city), fn_bit_length = BIT_LENGTH(city)
 ```
-Note: All strings are in UTF-8, so a single character can use multiple bytes.

docs/reference/query-languages/esql/kibana/docs/functions/byte_length.md

@@ -3,10 +3,11 @@
 ### BYTE LENGTH
 Returns the byte length of a string.
 
+Note: All strings are in UTF-8, so a single character can use multiple bytes.
+
 ```esql
 FROM airports
 | WHERE country == "India"
 | KEEP city
 | EVAL fn_length = LENGTH(city), fn_byte_length = BYTE_LENGTH(city)
 ```
-Note: All strings are in UTF-8, so a single character can use multiple bytes.

docs/reference/query-languages/esql/kibana/docs/functions/ceil.md

@@ -3,8 +3,9 @@
 ### CEIL
 Round a number up to the nearest integer.
 
+Note: This is a noop for `long` (including unsigned) and `integer`. For `double` this picks the closest `double` value to the integer similar to [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#ceil(double)).
+
 ```esql
 ROW a=1.8
 | EVAL a=CEIL(a)
 ```
-Note: This is a noop for `long` (including unsigned) and `integer`. For `double` this picks the closest `double` value to the integer similar to [Math.ceil](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#ceil(double)).

docs/reference/query-languages/esql/kibana/docs/functions/first_over_time.md

@@ -3,8 +3,9 @@
 ### FIRST OVER TIME
 The earliest value of a field, where recency determined by the `@timestamp` field.
 
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds
+
 ```esql
 TS k8s
 | STATS max_cost=max(first_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
 ```
-Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/floor.md

@@ -3,10 +3,11 @@
 ### FLOOR
 Round a number down to the nearest integer.
 
+Note: This is a noop for `long` (including unsigned) and `integer`.
+For `double` this picks the closest `double` value to the integer
+similar to [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#floor(double)).
+
 ```esql
 ROW a=1.8
 | EVAL a=FLOOR(a)
 ```
-Note: This is a noop for `long` (including unsigned) and `integer`.
-For `double` this picks the closest `double` value to the integer
-similar to [Math.floor](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Math.html#floor(double)).

docs/reference/query-languages/esql/kibana/docs/functions/greatest.md

@@ -4,8 +4,9 @@
 Returns the maximum value from multiple columns. This is similar to [`MV_MAX`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/mv-functions#esql-mv_max)
 except it is intended to run on multiple columns at once.
 
+Note: When run on `keyword` or `text` fields, this returns the last string in alphabetical order. When run on `boolean` columns this will return `true` if any values are `true`.
+
 ```esql
 ROW a = 10, b = 20
 | EVAL g = GREATEST(a, b)
 ```
-Note: When run on `keyword` or `text` fields, this returns the last string in alphabetical order. When run on `boolean` columns this will return `true` if any values are `true`.

docs/reference/query-languages/esql/kibana/docs/functions/last_over_time.md

@@ -3,8 +3,9 @@
 ### LAST OVER TIME
 The latest value of a field, where recency determined by the `@timestamp` field.
 
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds
+
 ```esql
 TS k8s
 | STATS max_cost=max(last_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
 ```
-Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/length.md

@@ -3,10 +3,11 @@
 ### LENGTH
 Returns the character length of a string.
 
+Note: All strings are in UTF-8, so a single character can use multiple bytes.
+
 ```esql
 FROM airports
 | WHERE country == "India"
 | KEEP city
 | EVAL fn_length = LENGTH(city)
 ```
-Note: All strings are in UTF-8, so a single character can use multiple bytes.

docs/reference/query-languages/esql/kibana/docs/functions/max_over_time.md

@@ -3,8 +3,9 @@
 ### MAX OVER TIME
 The maximum over time value of a field.
 
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds
+
 ```esql
 TS k8s
 | STATS cost=sum(max_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
 ```
-Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/median.md

@@ -3,8 +3,9 @@
 ### MEDIAN
 The value that is greater than half of all values and less than half of all values, also known as the 50% [`PERCENTILE`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile).
 
+Note: Like [`PERCENTILE`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), `MEDIAN` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).
+
 ```esql
 FROM employees
 | STATS MEDIAN(salary), PERCENTILE(salary, 50)
 ```
-Note: Like [`PERCENTILE`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), `MEDIAN` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).

docs/reference/query-languages/esql/kibana/docs/functions/median_absolute_deviation.md

@@ -5,8 +5,9 @@ Returns the median absolute deviation, a measure of variability. It is a robust
 
 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|)`.
 
+Note: Like [`PERCENTILE`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), `MEDIAN_ABSOLUTE_DEVIATION` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).
+
 ```esql
 FROM employees
 | STATS MEDIAN(salary), MEDIAN_ABSOLUTE_DEVIATION(salary)
 ```
-Note: Like [`PERCENTILE`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile), `MEDIAN_ABSOLUTE_DEVIATION` is [usually approximate](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/aggregation-functions#esql-percentile-approximate).

docs/reference/query-languages/esql/kibana/docs/functions/min_over_time.md

@@ -3,8 +3,9 @@
 ### MIN OVER TIME
 The minimum over time value of a field.
 
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds
+
 ```esql
 TS k8s
 | STATS cost=sum(min_over_time(network.cost)) BY cluster, time_bucket = bucket(@timestamp,1minute)
 ```
-Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/mv_dedupe.md

@@ -3,8 +3,9 @@
 ### MV DEDUPE
 Remove duplicate values from a multivalued field.
 
+Note: `MV_DEDUPE` may, but won’t always, sort the values in the column.
+
 ```esql
 ROW a=["foo", "foo", "bar", "foo"]
 | EVAL dedupe_a = MV_DEDUPE(a)
 ```
-Note: `MV_DEDUPE` may, but won’t always, sort the values in the column.

docs/reference/query-languages/esql/kibana/docs/functions/mv_median_absolute_deviation.md

@@ -5,8 +5,9 @@ Converts a multivalued field into a single valued field containing the median ab
 
 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|)`.
 
+Note: If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0.
+
 ```esql
 ROW values = [0, 2, 5, 6]
 | EVAL median_absolute_deviation = MV_MEDIAN_ABSOLUTE_DEVIATION(values), median = MV_MEDIAN(values)
 ```
-Note: If the field has an even number of values, the medians will be calculated as the average of the middle two values. If the value is not a floating point number, the averages are rounded towards 0.

docs/reference/query-languages/esql/kibana/docs/functions/pow.md

@@ -3,8 +3,9 @@
 ### POW
 Returns the value of `base` raised to the power of `exponent`.
 
+Note: It is still possible to overflow a double result here; in that case, null will be returned.
+
 ```esql
 ROW base = 2.0, exponent = 2
 | EVAL result = POW(base, exponent)
 ```
-Note: It is still possible to overflow a double result here; in that case, null will be returned.

docs/reference/query-languages/esql/kibana/docs/functions/rate.md

@@ -3,8 +3,9 @@
 ### RATE
 The rate of a counter field.
 
+Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds
+
 ```esql
 TS k8s
 | STATS max(rate(network.total_bytes_in)) BY time_bucket = bucket(@timestamp,5minute)
 ```
-Note: Available with the [TS](https://www.elastic.co/docs/reference/query-languages/esql/commands/source-commands#esql-ts) command in snapshot builds

docs/reference/query-languages/esql/kibana/docs/functions/to_date_nanos.md

@@ -3,10 +3,11 @@
 ### TO DATE NANOS
 Converts an input to a nanosecond-resolution date value (aka date_nanos).
 
+Note: The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning.  Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.
+
 ```esql
 FROM date_nanos
 | WHERE MV_MIN(nanos) < TO_DATE_NANOS("2023-10-23T12:27:28.948Z")
     AND millis > "2000-01-01"
 | SORT nanos DESC
 ```
-Note: The range for date nanos is 1970-01-01T00:00:00.000000000Z to 2262-04-11T23:47:16.854775807Z, attempting to convert values outside of that range will result in null with a warning.  Additionally, integers cannot be converted into date nanos, as the range of integer nanoseconds only covers about 2 seconds after epoch.

docs/reference/query-languages/esql/kibana/docs/functions/to_datetime.md

@@ -5,8 +5,9 @@ Converts an input value to a date value.
 A string will only be successfully converted if it’s respecting the format `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`.
 To convert dates in other formats, use [`DATE_PARSE`](https://www.elastic.co/docs/reference/query-languages/esql/functions-operators/date-time-functions#esql-date_parse).
 
+Note: Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded.
+
 ```esql
 ROW string = ["1953-09-02T00:00:00.000Z", "1964-06-02T00:00:00.000Z", "1964-06-02 00:00:00"]
 | EVAL datetime = TO_DATETIME(string)
 ```
-Note: Note that when converting from nanosecond resolution to millisecond resolution with this function, the nanosecond date is truncated, not rounded.

docs/reference/query-languages/esql/kibana/docs/operators/add.md

@@ -2,4 +2,3 @@
 
 ### ADD `+`
 Add two numbers together. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is `null`.
-

docs/reference/query-languages/esql/kibana/docs/operators/is_not_null.md

@@ -4,3 +4,9 @@
 Returns `false` if the value is `NULL`, `true` otherwise.
 
 Note: If a field is only in some documents it will be `NULL` in the documents that did not contain it.
+
+```esql
+FROM employees
+| WHERE is_rehired IS NOT NULL
+| STATS COUNT(emp_no)
+```

docs/reference/query-languages/esql/kibana/docs/operators/is_null.md

@@ -4,3 +4,8 @@
 Returns `true` if the value is `NULL`, `false` otherwise.
 
 Note: If a field is only in some documents it will be `NULL` in the documents that did not contain it.
+
+```esql
+FROM employees
+| WHERE birth_date IS NULL
+```

docs/reference/query-languages/esql/kibana/docs/operators/mod.md

@@ -2,4 +2,3 @@
 
 ### MODULO `%`
 Divide one number by another and return the remainder. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is `null`.
-

docs/reference/query-languages/esql/kibana/docs/operators/mul.md

@@ -2,4 +2,3 @@
 
 ### MULTIPLY `*`
 Multiply two numbers together. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is `null`.
-

docs/reference/query-languages/esql/kibana/docs/operators/neg.md

@@ -2,4 +2,3 @@
 
 ### NEGATE `-`
 Returns the negation of the argument.
-

docs/reference/query-languages/esql/kibana/docs/operators/not in.md

@@ -2,4 +2,3 @@
 
 ### NOT IN
 The `NOT IN` operator allows testing whether a field or expression does *not* equal any element in a list of literals, fields or expressions.
-

docs/reference/query-languages/esql/kibana/docs/operators/not like.md

@@ -10,4 +10,3 @@ The following wildcard characters are supported:
 
 * `*` matches zero or more characters.
 * `?` matches one character.
-

docs/reference/query-languages/esql/kibana/docs/operators/not rlike.md

@@ -5,4 +5,3 @@ Use `RLIKE` to filter data based on string patterns using using
 [regular expressions](https://www.elastic.co/docs/reference/query-languages/query-dsl/regexp-syntax). `RLIKE` usually acts on a field placed on
 the left-hand side of the operator, but it can also act on a constant (literal)
 expression. The right-hand side of the operator represents the pattern.
-

docs/reference/query-languages/esql/kibana/docs/operators/predicates.md

@@ -1,9 +0,0 @@
-% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
-
-### PREDICATES
-For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates.
-
-```esql
-FROM employees
-| WHERE birth_date IS NULL
-```

docs/reference/query-languages/esql/kibana/docs/operators/sub.md

@@ -2,4 +2,3 @@
 
 ### SUBTRACT `-`
 Subtract one number from another. If either field is [multivalued](https://www.elastic.co/docs/reference/query-languages/esql/esql-multivalued-fields) then the result is `null`.
-

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNotNull.java

@@ -25,6 +25,7 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
 import org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.optimizer.rules.physical.local.LucenePushdownPredicates;
@@ -54,7 +55,8 @@ public class IsNotNull extends UnaryScalarFunction implements EvaluatorMapper, N
             "unsigned_long",
             "counter_long",
             "counter_integer",
-            "counter_double" }
+            "counter_double" },
+        examples = { @Example(file = "null", tag = "is-not-null") }
     )
     public IsNotNull(
         Source source,

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNull.java

@@ -26,6 +26,7 @@ import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
 import org.elasticsearch.xpack.esql.core.tree.Source;
 import org.elasticsearch.xpack.esql.core.type.DataType;
 import org.elasticsearch.xpack.esql.evaluator.mapper.EvaluatorMapper;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.optimizer.rules.physical.local.LucenePushdownPredicates;
@@ -51,7 +52,8 @@ public class IsNull extends UnaryScalarFunction implements EvaluatorMapper, Nega
             "unsigned_long",
             "counter_long",
             "counter_integer",
-            "counter_double" }
+            "counter_double" },
+        examples = { @Example(file = "null", tag = "is-null") }
     )
     public IsNull(
         Source source,

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java

@@ -1055,19 +1055,21 @@ public abstract class DocsV3Support {
         builder.append("### ").append(titleName.toUpperCase(Locale.ROOT)).append("\n");
         String cleanedDesc = replaceLinks(info.description());
         cleanedDesc = removeAppliesToBlocks(cleanedDesc);
-        builder.append(cleanedDesc).append("\n\n");
+        builder.append(cleanedDesc).append("\n");
+
+        if (Strings.isNullOrEmpty(info.note()) == false) {
+            String cleanedNote = replaceLinks(info.note());
+            cleanedNote = removeAppliesToBlocks(cleanedNote);
+            builder.append("\nNote: ").append(cleanedNote).append("\n");
+        }
 
         if (info.examples().length > 0) {
             Example example = info.examples()[0];
-            builder.append("```esql\n");
+            builder.append("\n```esql\n");
             builder.append(loadExample(example.file(), example.tag()));
             builder.append("\n```\n");
         }
-        if (Strings.isNullOrEmpty(info.note()) == false) {
-            String cleanedNote = replaceLinks(info.note());
-            cleanedNote = removeAppliesToBlocks(cleanedNote);
-            builder.append("Note: ").append(cleanedNote).append("\n");
-        }
+
         String rendered = builder.toString();
         logger.info("Writing kibana inline docs for [{}]:\n{}", name, rendered);
         writeToTempKibanaDir("docs", "md", rendered);

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/predicate/operator/NullPredicatesTests.java

@@ -1,181 +0,0 @@
-/*
- * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
- * or more contributor license agreements. Licensed under the Elastic License
- * 2.0; you may not use this file except in compliance with the Elastic License
- * 2.0.
- */
-
-package org.elasticsearch.xpack.esql.expression.predicate.operator;
-
-import org.elasticsearch.test.ESTestCase;
-import org.elasticsearch.xpack.esql.core.expression.Expression;
-import org.elasticsearch.xpack.esql.core.type.DataType;
-import org.elasticsearch.xpack.esql.expression.function.AbstractFunctionTestCase;
-import org.elasticsearch.xpack.esql.expression.function.DocsV3Support;
-import org.elasticsearch.xpack.esql.expression.function.Example;
-import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
-import org.elasticsearch.xpack.esql.expression.function.Param;
-import org.elasticsearch.xpack.esql.expression.function.scalar.convert.ToStringTests;
-import org.junit.AfterClass;
-
-import java.util.LinkedHashMap;
-import java.util.List;
-import java.util.Map;
-
-/**
- * In the documentation we document `IS NULL` and `IS NOT NULL` together.
- */
-public class NullPredicatesTests extends ESTestCase {
-    public void testDummy() {
-        assert true;
-    }
-
-    @AfterClass
-    public static void renderDocs() throws Exception {
-        if (System.getProperty("generateDocs") == null) {
-            return;
-        }
-        renderNullPredicate(
-            new DocsV3Support.OperatorConfig(
-                "predicates",
-                "IS NULL and IS NOT NULL",
-                TestNullPredicates.class,
-                DocsV3Support.OperatorCategory.UNARY
-            )
-        );
-        renderNullPredicate(
-            new DocsV3Support.OperatorConfig(
-                "is_null",
-                "IS NULL",
-                TestIsNullPredicate.class,
-                DocsV3Support.OperatorCategory.NULL_PREDICATES
-            )
-        );
-        renderNullPredicate(
-            new DocsV3Support.OperatorConfig(
-                "is_not_null",
-                "IS NOT NULL",
-                TestIsNotNullPredicate.class,
-                DocsV3Support.OperatorCategory.NULL_PREDICATES
-            )
-        );
-    }
-
-    private static void renderNullPredicate(DocsV3Support.OperatorConfig op) throws Exception {
-        var docs = new DocsV3Support.OperatorsDocsSupport(op.name(), NullPredicatesTests.class, op, NullPredicatesTests::signatures);
-        docs.renderSignature();
-        docs.renderDocs();
-    }
-
-    public static Map<List<DataType>, DataType> signatures() {
-        // TODO: Verify the correct datatypes for this
-        Map<List<DataType>, DataType> toString = AbstractFunctionTestCase.signatures(ToStringTests.class);
-        Map<List<DataType>, DataType> results = new LinkedHashMap<>();
-        for (var entry : toString.entrySet()) {
-            DataType dataType = entry.getKey().getFirst();
-            results.put(List.of(dataType), DataType.BOOLEAN);
-        }
-        return results;
-    }
-
-    /**
-     * This class only exists to provide FunctionInfo for the documentation
-     */
-    public class TestNullPredicates {
-        @FunctionInfo(
-            returnType = {},
-            description = "For NULL comparison use the `IS NULL` and `IS NOT NULL` predicates.",
-            examples = { @Example(file = "null", tag = "is-null"), @Example(file = "null", tag = "is-not-null") }
-        )
-        public TestNullPredicates(
-            @Param(
-                name = "field",
-                type = {
-                    "boolean",
-                    "cartesian_point",
-                    "cartesian_shape",
-                    "date",
-                    "date_nanos",
-                    "double",
-                    "geo_point",
-                    "geo_shape",
-                    "integer",
-                    "ip",
-                    "keyword",
-                    "long",
-                    "text",
-                    "unsigned_long",
-                    "version" },
-                description = "Input value. The input can be a single- or multi-valued column or an expression."
-            ) Expression v
-        ) {}
-    }
-
-    /**
-     * This class only exists to provide FunctionInfo for the documentation
-     */
-    public class TestIsNullPredicate {
-        @FunctionInfo(
-            operator = "IS NULL",
-            returnType = {},
-            description = "Use `IS NULL` to filter data based on whether the field exists or not.",
-            examples = { @Example(file = "null", tag = "is-null") }
-        )
-        public TestIsNullPredicate(
-            @Param(
-                name = "field",
-                type = {
-                    "boolean",
-                    "cartesian_point",
-                    "cartesian_shape",
-                    "date",
-                    "date_nanos",
-                    "double",
-                    "geo_point",
-                    "geo_shape",
-                    "integer",
-                    "ip",
-                    "keyword",
-                    "long",
-                    "text",
-                    "unsigned_long",
-                    "version" },
-                description = "Input value. The input can be a single- or multi-valued column or an expression."
-            ) Expression v
-        ) {}
-    }
-
-    /**
-     * This class only exists to provide FunctionInfo for the documentation
-     */
-    public class TestIsNotNullPredicate {
-        @FunctionInfo(
-            operator = "IS NOT NULL",
-            returnType = {},
-            description = "Use `IS NOT NULL` to filter data based on whether the field exists or not.",
-            examples = { @Example(file = "null", tag = "is-not-null") }
-        )
-        public TestIsNotNullPredicate(
-            @Param(
-                name = "field",
-                type = {
-                    "boolean",
-                    "cartesian_point",
-                    "cartesian_shape",
-                    "date",
-                    "date_nanos",
-                    "double",
-                    "geo_point",
-                    "geo_shape",
-                    "integer",
-                    "ip",
-                    "keyword",
-                    "long",
-                    "text",
-                    "unsigned_long",
-                    "version" },
-                description = "Input value. The input can be a single- or multi-valued column or an expression."
-            ) Expression v
-        ) {}
-    }
-}