diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/is_not_null.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/is_not_null.md new file mode 100644 index 0000000000000..fb5acb31cbd08 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/is_not_null.md @@ -0,0 +1,6 @@ + +::::{note} +If a field is only in some documents it will be `NULL` in the documents that did not contain it. +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/is_null.md b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/is_null.md new file mode 100644 index 0000000000000..fb5acb31cbd08 --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/operators/detailedDescription/is_null.md @@ -0,0 +1,6 @@ + +::::{note} +If a field is only in some documents it will be `NULL` in the documents that did not contain it. +:::: + + diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/is_not_null.md b/docs/reference/query-languages/esql/_snippets/operators/types/is_not_null.md index 19fc0a9465976..f2b65a11de81e 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/is_not_null.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/is_not_null.md @@ -7,6 +7,9 @@ | boolean | boolean | | cartesian_point | boolean | | cartesian_shape | boolean | +| counter_double | boolean | +| counter_integer | boolean | +| counter_long | boolean | | date | boolean | | date_nanos | boolean | | double | boolean | diff --git a/docs/reference/query-languages/esql/_snippets/operators/types/is_null.md b/docs/reference/query-languages/esql/_snippets/operators/types/is_null.md index 19fc0a9465976..f2b65a11de81e 100644 --- a/docs/reference/query-languages/esql/_snippets/operators/types/is_null.md +++ b/docs/reference/query-languages/esql/_snippets/operators/types/is_null.md @@ -7,6 +7,9 @@ | boolean | boolean | | cartesian_point | boolean | | cartesian_shape | boolean | +| counter_double | boolean | +| counter_integer | boolean | +| counter_long | boolean | | date | boolean | | date_nanos | boolean | | double | boolean | diff --git a/docs/reference/query-languages/esql/kibana/definition/operators/is_not_null.json b/docs/reference/query-languages/esql/kibana/definition/operators/is_not_null.json index 2eba6c6c6730f..3722fbfaddeb8 100644 --- a/docs/reference/query-languages/esql/kibana/definition/operators/is_not_null.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/is_not_null.json @@ -3,7 +3,8 @@ "type" : "operator", "operator" : "IS NOT NULL", "name" : "is_not_null", - "description" : "Use `IS NOT NULL` to filter data based on whether the field exists or not.", + "description" : "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.", "signatures" : [ { "params" : [ @@ -11,7 +12,7 @@ "name" : "field", "type" : "boolean", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -23,7 +24,7 @@ "name" : "field", "type" : "cartesian_point", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -35,7 +36,43 @@ "name" : "field", "type" : "cartesian_shape", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "counter_double", + "optional" : false, + "description" : "Value to check. It can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "counter_integer", + "optional" : false, + "description" : "Value to check. It can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "counter_long", + "optional" : false, + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -47,7 +84,7 @@ "name" : "field", "type" : "date", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -59,7 +96,7 @@ "name" : "field", "type" : "date_nanos", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -71,7 +108,7 @@ "name" : "field", "type" : "double", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -83,7 +120,7 @@ "name" : "field", "type" : "geo_point", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -95,7 +132,7 @@ "name" : "field", "type" : "geo_shape", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -107,7 +144,7 @@ "name" : "field", "type" : "integer", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -119,7 +156,7 @@ "name" : "field", "type" : "ip", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -131,7 +168,7 @@ "name" : "field", "type" : "keyword", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -143,7 +180,7 @@ "name" : "field", "type" : "long", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -155,7 +192,7 @@ "name" : "field", "type" : "text", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -167,7 +204,7 @@ "name" : "field", "type" : "unsigned_long", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -179,16 +216,13 @@ "name" : "field", "type" : "version", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, "returnType" : "boolean" } ], - "examples" : [ - "FROM employees\n| WHERE is_rehired IS NOT NULL\n| STATS COUNT(emp_no)" - ], "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/definition/operators/is_null.json b/docs/reference/query-languages/esql/kibana/definition/operators/is_null.json index 6eda2b9db776e..0f6e70f8a0b91 100644 --- a/docs/reference/query-languages/esql/kibana/definition/operators/is_null.json +++ b/docs/reference/query-languages/esql/kibana/definition/operators/is_null.json @@ -3,7 +3,8 @@ "type" : "operator", "operator" : "IS NULL", "name" : "is_null", - "description" : "Use `IS NULL` to filter data based on whether the field exists or not.", + "description" : "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.", "signatures" : [ { "params" : [ @@ -11,7 +12,7 @@ "name" : "field", "type" : "boolean", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -23,7 +24,7 @@ "name" : "field", "type" : "cartesian_point", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -35,7 +36,43 @@ "name" : "field", "type" : "cartesian_shape", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "counter_double", + "optional" : false, + "description" : "Value to check. It can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "counter_integer", + "optional" : false, + "description" : "Value to check. It can be a single- or multi-valued column or an expression." + } + ], + "variadic" : false, + "returnType" : "boolean" + }, + { + "params" : [ + { + "name" : "field", + "type" : "counter_long", + "optional" : false, + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -47,7 +84,7 @@ "name" : "field", "type" : "date", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -59,7 +96,7 @@ "name" : "field", "type" : "date_nanos", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -71,7 +108,7 @@ "name" : "field", "type" : "double", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -83,7 +120,7 @@ "name" : "field", "type" : "geo_point", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -95,7 +132,7 @@ "name" : "field", "type" : "geo_shape", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -107,7 +144,7 @@ "name" : "field", "type" : "integer", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -119,7 +156,7 @@ "name" : "field", "type" : "ip", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -131,7 +168,7 @@ "name" : "field", "type" : "keyword", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -143,7 +180,7 @@ "name" : "field", "type" : "long", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -155,7 +192,7 @@ "name" : "field", "type" : "text", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -167,7 +204,7 @@ "name" : "field", "type" : "unsigned_long", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, @@ -179,16 +216,13 @@ "name" : "field", "type" : "version", "optional" : false, - "description" : "Input value. The input can be a single- or multi-valued column or an expression." + "description" : "Value to check. It can be a single- or multi-valued column or an expression." } ], "variadic" : false, "returnType" : "boolean" } ], - "examples" : [ - "FROM employees\n| WHERE birth_date IS NULL" - ], "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/is_not_null.md b/docs/reference/query-languages/esql/kibana/docs/operators/is_not_null.md index 2dd2dc0902746..25157e2bb7af2 100644 --- a/docs/reference/query-languages/esql/kibana/docs/operators/is_not_null.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/is_not_null.md @@ -1,10 +1,6 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. ### IS NOT NULL -Use `IS NOT NULL` to filter data based on whether the field exists or not. +Returns `false` if the value is `NULL`, `true` otherwise. -```esql -FROM employees -| WHERE is_rehired IS NOT NULL -| STATS COUNT(emp_no) -``` +Note: If a field is only in some documents it will be `NULL` in the documents that did not contain it. diff --git a/docs/reference/query-languages/esql/kibana/docs/operators/is_null.md b/docs/reference/query-languages/esql/kibana/docs/operators/is_null.md index 8a21704a6a70b..625b819935332 100644 --- a/docs/reference/query-languages/esql/kibana/docs/operators/is_null.md +++ b/docs/reference/query-languages/esql/kibana/docs/operators/is_null.md @@ -1,9 +1,6 @@ % This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. ### IS NULL -Use `IS NULL` to filter data based on whether the field exists or not. +Returns `true` if the value is `NULL`, `false` otherwise. -```esql -FROM employees -| WHERE birth_date IS NULL -``` +Note: If a field is only in some documents it will be `NULL` in the documents that did not contain it. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNotNull.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNotNull.java index ce5a660000d09..82818c5a329c0 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNotNull.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNotNull.java @@ -25,6 +25,8 @@ 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.FunctionInfo; +import org.elasticsearch.xpack.esql.expression.function.Param; import org.elasticsearch.xpack.esql.optimizer.rules.physical.local.LucenePushdownPredicates; import org.elasticsearch.xpack.esql.planner.TranslatorHandler; @@ -37,7 +39,42 @@ public class IsNotNull extends UnaryScalarFunction implements EvaluatorMapper, N IsNotNull::new ); - public IsNotNull(Source source, Expression field) { + @FunctionInfo( + description = "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.", + operator = "IS NOT NULL", + returnType = { + "double", + "integer", + "long", + "date_nanos", + "date_period", + "datetime", + "time_duration", + "unsigned_long", + "counter_long", + "counter_integer", + "counter_double" } + ) + public IsNotNull( + Source source, + @Param( + name = "field", + description = "Value to check. It can be a single- or multi-valued column or an expression.", + type = { + "double", + "integer", + "long", + "date_nanos", + "date_period", + "datetime", + "time_duration", + "unsigned_long", + "counter_long", + "counter_integer", + "counter_double" } + ) Expression field + ) { super(source, field); } diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNull.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNull.java index fd17a7014e40b..e93124af54186 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNull.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/predicate/nulls/IsNull.java @@ -26,6 +26,8 @@ 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.FunctionInfo; +import org.elasticsearch.xpack.esql.expression.function.Param; import org.elasticsearch.xpack.esql.optimizer.rules.physical.local.LucenePushdownPredicates; import org.elasticsearch.xpack.esql.planner.TranslatorHandler; @@ -34,7 +36,42 @@ public class IsNull extends UnaryScalarFunction implements EvaluatorMapper, Negatable, TranslationAware { public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "IsNull", IsNull::new); - public IsNull(Source source, Expression field) { + @FunctionInfo( + description = "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.", + operator = "IS NULL", + returnType = { + "double", + "integer", + "long", + "date_nanos", + "date_period", + "datetime", + "time_duration", + "unsigned_long", + "counter_long", + "counter_integer", + "counter_double" } + ) + public IsNull( + Source source, + @Param( + name = "field", + description = "Value to check. It can be a single- or multi-valued column or an expression.", + type = { + "double", + "integer", + "long", + "date_nanos", + "date_period", + "datetime", + "time_duration", + "unsigned_long", + "counter_long", + "counter_integer", + "counter_double" } + ) Expression field + ) { super(source, field); } diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNotNullTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNotNullTests.java index 0af5dc7d0ebeb..888eed8e3df09 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNotNullTests.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNotNullTests.java @@ -34,7 +34,7 @@ public IsNotNullTests(@Name("TestCase") Supplier test public static Iterable parameters() { List suppliers = new ArrayList<>(); for (DataType type : DataType.types()) { - if (false == DataType.isRepresentable(type)) { + if (false == type.isCounter() && false == DataType.isRepresentable(type)) { continue; } if (type != DataType.NULL) { diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNullTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNullTests.java index 4fdc805b18792..6ccc5de5f6d7b 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNullTests.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/nulls/IsNullTests.java @@ -34,7 +34,7 @@ public IsNullTests(@Name("TestCase") Supplier testCas public static Iterable parameters() { List suppliers = new ArrayList<>(); for (DataType type : DataType.types()) { - if (false == DataType.isRepresentable(type)) { + if (false == type.isCounter() && false == DataType.isRepresentable(type)) { continue; } if (type != DataType.NULL) {