diff --git a/docs/reference/query-languages/esql/_snippets/functions/examples/copy_sign.md b/docs/reference/query-languages/esql/_snippets/functions/examples/copy_sign.md new file mode 100644 index 0000000000000..a8dab1d58b9bb --- /dev/null +++ b/docs/reference/query-languages/esql/_snippets/functions/examples/copy_sign.md @@ -0,0 +1,16 @@ +% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it. + +**Example** + +```esql +FROM employees +| EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change)) +``` + +| emp_no:integer | salary:integer | salary_change:double | cs1:integer | +| --- | --- | --- | --- | +| 10001 | 57305 | 1.19 | 57305 | +| 10002 | 56371 | [-7.23, 11.17] | -56371 | +| 10003 | 61805 | [12.82, 14.68] | 61805 | + + diff --git a/docs/reference/query-languages/esql/_snippets/functions/layout/copy_sign.md b/docs/reference/query-languages/esql/_snippets/functions/layout/copy_sign.md index 062ba0001dd71..436e6b8b943d7 100644 --- a/docs/reference/query-languages/esql/_snippets/functions/layout/copy_sign.md +++ b/docs/reference/query-languages/esql/_snippets/functions/layout/copy_sign.md @@ -21,3 +21,6 @@ stack: ga 9.1.0 :::{include} ../types/copy_sign.md ::: + +:::{include} ../examples/copy_sign.md +::: diff --git a/docs/reference/query-languages/esql/kibana/definition/functions/copy_sign.json b/docs/reference/query-languages/esql/kibana/definition/functions/copy_sign.json index 51d3edca937f8..e1be51a240428 100644 --- a/docs/reference/query-languages/esql/kibana/definition/functions/copy_sign.json +++ b/docs/reference/query-languages/esql/kibana/definition/functions/copy_sign.json @@ -167,6 +167,9 @@ "returnType" : "long" } ], + "examples" : [ + "FROM employees\n| EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change))" + ], "preview" : false, "snapshot_only" : false } diff --git a/docs/reference/query-languages/esql/kibana/docs/functions/copy_sign.md b/docs/reference/query-languages/esql/kibana/docs/functions/copy_sign.md index e2bd39f147fbd..30738f8bdcbe0 100644 --- a/docs/reference/query-languages/esql/kibana/docs/functions/copy_sign.md +++ b/docs/reference/query-languages/esql/kibana/docs/functions/copy_sign.md @@ -4,3 +4,8 @@ Returns a value with the magnitude of the first argument and the sign of the second argument. This function is similar to Java's Math.copySign(double magnitude, double sign) which is similar to `copysign` from [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754). + +```esql +FROM employees +| EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change)) +``` diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec index d5bd9536cb5fe..3fcd32b25a060 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec +++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec @@ -1855,15 +1855,19 @@ cs1:double | cs2:integer | cs3:integer copySignWithMixedNumericValuesWithMV required_capability: copy_sign +// tag::copy_sign[] FROM employees | EVAL cs1 = COPY_SIGN(salary, LEAST(salary_change)) +// end::copy_sign[] | KEEP emp_no, salary, salary_change, cs1 | SORT emp_no | LIMIT 3 ; - emp_no:integer | salary:integer | salary_change:double | cs1:integer - 10001 | 57305 | 1.19 | 57305 - 10002 | 56371 | [-7.23, 11.17] | -56371 - 10003 | 61805 | [12.82, 14.68] | 61805 +// tag::copy_sign-result[] +emp_no:integer | salary:integer | salary_change:double | cs1:integer +10001 | 57305 | 1.19 | 57305 +10002 | 56371 | [-7.23, 11.17] | -56371 +10003 | 61805 | [12.82, 14.68] | 61805 +// end::copy_sign-result[] ; diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CopySign.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CopySign.java index 522c936bd3418..232453bd96092 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CopySign.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CopySign.java @@ -19,6 +19,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.expression.function.Example; import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesTo; import org.elasticsearch.xpack.esql.expression.function.FunctionAppliesToLifecycle; import org.elasticsearch.xpack.esql.expression.function.FunctionInfo; @@ -69,7 +70,8 @@ EvalOperator.ExpressionEvaluator.Factory create( This function is similar to Java's Math.copySign(double magnitude, double sign) which is similar to `copysign` from [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754).""", returnType = { "double", "integer", "long" }, - appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1.0") } + appliesTo = { @FunctionAppliesTo(lifeCycle = FunctionAppliesToLifecycle.GA, version = "9.1.0") }, + examples = { @Example(file = "math", tag = "copy_sign") } ) public CopySign( Source source, diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java index 397ff46eb0f29..2e5402b791366 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java @@ -1402,6 +1402,11 @@ void renderKibanaFunctionDefinition( builder.value(loadExample(example.file(), example.tag())); } builder.endArray(); + } else if (info.operator().isEmpty()) { + // CI will fail in Kibana if we add a function with no examples + throw new IllegalArgumentException( + "Failed to write Kibana function definition: no examples found for function [" + name + "]." + ); } builder.field("preview", info.preview()); builder.field("snapshot_only", EsqlFunctionRegistry.isSnapshotOnly(name));