Skip to content

ES|QL: Require all functions to provide examples #135094

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 26, 2025
+43 −5
Merged

ES|QL: Require all functions to provide examples #135094

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
395586d
Require all functions to provide examples
ioanatia Sep 19, 2025
d65a6b5
Merge branch 'main' into fail_for_no_examples
ioanatia Sep 22, 2025
f8c9f69
Merge branch 'main' into fail_for_no_examples
ioanatia Sep 25, 2025
b6e3728
Merge branch 'main' into fail_for_no_examples
ioanatia Sep 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/reference/query-languages/esql/_snippets/functions/examples/copy_sign.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions docs/reference/query-languages/esql/_snippets/functions/layout/copy_sign.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions docs/reference/query-languages/esql/kibana/definition/functions/copy_sign.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 5 additions & 0 deletions docs/reference/query-languages/esql/kibana/docs/functions/copy_sign.md
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

12 changes: 8 additions & 4 deletions x-pack/plugin/esql/qa/testFixtures/src/main/resources/math.csv-spec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[]
;
4 changes: 3 additions & 1 deletion .../src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CopySign.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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,
Expand Down
5 changes: 5 additions & 0 deletions ...in/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1402,6 +1402,11 @@ void renderKibanaFunctionDefinition(
builder.value(loadExample(example.file(), example.tag()));
}
builder.endArray();
} else if (info.operator().isEmpty()) {
Copy link
Contributor Author

@ioanatia ioanatia Sep 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

operators also use FunctionInfo - and not all of them have examples, and AFAIU unlike functions, operators are not required to have examples for Kibana Discover.
checking for info.operator().isEmpty() seemed the easiest way to differentiate between the functions and operators.

// 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));
Expand Down