From 42e8e68b90855a3bceacc316036f23e1a6754414 Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Fri, 8 Dec 2023 09:57:49 -0500 Subject: [PATCH] ESQL: Add type tables for operators to docs This adds a tiny blurb for each operator to the docs with a railroad diagram of the operator's syntax and a table of the input and output types. This also fixes the tests to correctly generate the tables for operators. --- docs/reference/esql/functions/binary.asciidoc | 88 +++++++++++++++++-- .../signature/greater_than_or_equal.svg | 1 + .../signature/less_than_or_equal.svg | 1 + .../esql/functions/signature/to_degrees.svg | 1 - .../esql/functions/types/add.asciidoc | 12 +++ .../esql/functions/types/div.asciidoc | 7 ++ .../esql/functions/types/equals.asciidoc | 5 ++ .../functions/types/greater_than.asciidoc | 5 ++ .../types/greater_than_or_equal.asciidoc | 5 ++ .../esql/functions/types/less_than.asciidoc | 5 ++ .../types/less_than_or_equal.asciidoc | 5 ++ .../esql/functions/types/mod.asciidoc | 7 ++ .../esql/functions/types/mul.asciidoc | 7 ++ .../{to_degrees.asciidoc => neg.asciidoc} | 7 +- .../esql/functions/types/not_equals.asciidoc | 5 ++ .../esql/functions/types/sub.asciidoc | 11 +++ docs/reference/esql/functions/unary.asciidoc | 6 +- .../function/AbstractFunctionTestCase.java | 26 ++++-- 18 files changed, 183 insertions(+), 21 deletions(-) create mode 100644 docs/reference/esql/functions/signature/greater_than_or_equal.svg create mode 100644 docs/reference/esql/functions/signature/less_than_or_equal.svg delete mode 100644 docs/reference/esql/functions/signature/to_degrees.svg create mode 100644 docs/reference/esql/functions/types/add.asciidoc create mode 100644 docs/reference/esql/functions/types/div.asciidoc create mode 100644 docs/reference/esql/functions/types/equals.asciidoc create mode 100644 docs/reference/esql/functions/types/greater_than.asciidoc create mode 100644 docs/reference/esql/functions/types/greater_than_or_equal.asciidoc create mode 100644 docs/reference/esql/functions/types/less_than.asciidoc create mode 100644 docs/reference/esql/functions/types/less_than_or_equal.asciidoc create mode 100644 docs/reference/esql/functions/types/mod.asciidoc create mode 100644 docs/reference/esql/functions/types/mul.asciidoc rename docs/reference/esql/functions/types/{to_degrees.asciidoc => neg.asciidoc} (50%) create mode 100644 docs/reference/esql/functions/types/not_equals.asciidoc create mode 100644 docs/reference/esql/functions/types/sub.asciidoc diff --git a/docs/reference/esql/functions/binary.asciidoc b/docs/reference/esql/functions/binary.asciidoc index 32e97b7316d84..2d4daa6ad2eca 100644 --- a/docs/reference/esql/functions/binary.asciidoc +++ b/docs/reference/esql/functions/binary.asciidoc @@ -2,19 +2,91 @@ [[esql-binary-operators]] === Binary operators -These binary comparison operators are supported: +[[esql-binary-operators-equality]] +==== Equality +[.text-center] +image::esql/functions/signature/equals.svg[Embedded,opts=inline] + +Supported types: + +include::types/equals.asciidoc[] + +==== Inequality `!=` +[.text-center] +image::esql/functions/signature/not_equals.svg[Embedded,opts=inline] -* equality: `==` -* inequality: `!=` -* less than: `<` -* less than or equal: `<=` -* larger than: `>` -* larger than or equal: `>=` +Supported types: -And these mathematical operators are supported: +include::types/not_equals.asciidoc[] +==== Less than `<` +[.text-center] +image::esql/functions/signature/less_than.svg[Embedded,opts=inline] + +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] + +Supported types: + +include::types/less_than_or_equal.asciidoc[] + +==== Greater than `>` +[.text-center] +image::esql/functions/signature/greater_than.svg[Embedded,opts=inline] + +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] + +Supported types: + +include::types/greater_than_or_equal.asciidoc[] + +==== Add `+` [.text-center] image::esql/functions/signature/add.svg[Embedded,opts=inline] +Supported types: + +include::types/add.asciidoc[] + +==== Subtract `-` [.text-center] image::esql/functions/signature/sub.svg[Embedded,opts=inline] + +Supported types: + +include::types/sub.asciidoc[] + +==== Multiply `*` +[.text-center] +image::esql/functions/signature/mul.svg[Embedded,opts=inline] + +Supported types: + +include::types/mul.asciidoc[] + +==== Divide `/` +[.text-center] +image::esql/functions/signature/div.svg[Embedded,opts=inline] + +Supported types: + +include::types/div.asciidoc[] + +==== Modulus `%` +[.text-center] +image::esql/functions/signature/mod.svg[Embedded,opts=inline] + +Supported types: + +include::types/mod.asciidoc[] diff --git a/docs/reference/esql/functions/signature/greater_than_or_equal.svg b/docs/reference/esql/functions/signature/greater_than_or_equal.svg new file mode 100644 index 0000000000000..6afb36d4b4eff --- /dev/null +++ b/docs/reference/esql/functions/signature/greater_than_or_equal.svg @@ -0,0 +1 @@ +lhs>=rhs \ No newline at end of file diff --git a/docs/reference/esql/functions/signature/less_than_or_equal.svg b/docs/reference/esql/functions/signature/less_than_or_equal.svg new file mode 100644 index 0000000000000..da93c172b7136 --- /dev/null +++ b/docs/reference/esql/functions/signature/less_than_or_equal.svg @@ -0,0 +1 @@ +lhs<=rhs \ No newline at end of file diff --git a/docs/reference/esql/functions/signature/to_degrees.svg b/docs/reference/esql/functions/signature/to_degrees.svg deleted file mode 100644 index 01fe0a4770156..0000000000000 --- a/docs/reference/esql/functions/signature/to_degrees.svg +++ /dev/null @@ -1 +0,0 @@ -TO_DEGREES(v) \ No newline at end of file diff --git a/docs/reference/esql/functions/types/add.asciidoc b/docs/reference/esql/functions/types/add.asciidoc new file mode 100644 index 0000000000000..7783d08bc3aaa --- /dev/null +++ b/docs/reference/esql/functions/types/add.asciidoc @@ -0,0 +1,12 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +date_period | date_period | date_period +date_period | datetime | datetime +datetime | date_period | datetime +datetime | time_duration | datetime +double | double | double +integer | integer | integer +long | long | long +time_duration | time_duration | time_duration +|=== diff --git a/docs/reference/esql/functions/types/div.asciidoc b/docs/reference/esql/functions/types/div.asciidoc new file mode 100644 index 0000000000000..eee2d68e4653f --- /dev/null +++ b/docs/reference/esql/functions/types/div.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +double | double | double +integer | integer | integer +long | long | long +|=== diff --git a/docs/reference/esql/functions/types/equals.asciidoc b/docs/reference/esql/functions/types/equals.asciidoc new file mode 100644 index 0000000000000..27fb19b6d38a2 --- /dev/null +++ b/docs/reference/esql/functions/types/equals.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/docs/reference/esql/functions/types/greater_than.asciidoc b/docs/reference/esql/functions/types/greater_than.asciidoc new file mode 100644 index 0000000000000..27fb19b6d38a2 --- /dev/null +++ b/docs/reference/esql/functions/types/greater_than.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/docs/reference/esql/functions/types/greater_than_or_equal.asciidoc b/docs/reference/esql/functions/types/greater_than_or_equal.asciidoc new file mode 100644 index 0000000000000..27fb19b6d38a2 --- /dev/null +++ b/docs/reference/esql/functions/types/greater_than_or_equal.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/docs/reference/esql/functions/types/less_than.asciidoc b/docs/reference/esql/functions/types/less_than.asciidoc new file mode 100644 index 0000000000000..27fb19b6d38a2 --- /dev/null +++ b/docs/reference/esql/functions/types/less_than.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/docs/reference/esql/functions/types/less_than_or_equal.asciidoc b/docs/reference/esql/functions/types/less_than_or_equal.asciidoc new file mode 100644 index 0000000000000..27fb19b6d38a2 --- /dev/null +++ b/docs/reference/esql/functions/types/less_than_or_equal.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/docs/reference/esql/functions/types/mod.asciidoc b/docs/reference/esql/functions/types/mod.asciidoc new file mode 100644 index 0000000000000..eee2d68e4653f --- /dev/null +++ b/docs/reference/esql/functions/types/mod.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +double | double | double +integer | integer | integer +long | long | long +|=== diff --git a/docs/reference/esql/functions/types/mul.asciidoc b/docs/reference/esql/functions/types/mul.asciidoc new file mode 100644 index 0000000000000..eee2d68e4653f --- /dev/null +++ b/docs/reference/esql/functions/types/mul.asciidoc @@ -0,0 +1,7 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +double | double | double +integer | integer | integer +long | long | long +|=== diff --git a/docs/reference/esql/functions/types/to_degrees.asciidoc b/docs/reference/esql/functions/types/neg.asciidoc similarity index 50% rename from docs/reference/esql/functions/types/to_degrees.asciidoc rename to docs/reference/esql/functions/types/neg.asciidoc index 7cb7ca46022c2..1b841483fb22e 100644 --- a/docs/reference/esql/functions/types/to_degrees.asciidoc +++ b/docs/reference/esql/functions/types/neg.asciidoc @@ -1,8 +1,9 @@ [%header.monospaced.styled,format=dsv,separator=|] |=== v | result +date_period | date_period double | double -integer | double -long | double -unsigned_long | double +integer | integer +long | long +time_duration | time_duration |=== diff --git a/docs/reference/esql/functions/types/not_equals.asciidoc b/docs/reference/esql/functions/types/not_equals.asciidoc new file mode 100644 index 0000000000000..27fb19b6d38a2 --- /dev/null +++ b/docs/reference/esql/functions/types/not_equals.asciidoc @@ -0,0 +1,5 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +integer | integer | boolean +|=== diff --git a/docs/reference/esql/functions/types/sub.asciidoc b/docs/reference/esql/functions/types/sub.asciidoc new file mode 100644 index 0000000000000..ed26adf06ecde --- /dev/null +++ b/docs/reference/esql/functions/types/sub.asciidoc @@ -0,0 +1,11 @@ +[%header.monospaced.styled,format=dsv,separator=|] +|=== +lhs | rhs | result +date_period | date_period | date_period +datetime | date_period | datetime +datetime | time_duration | datetime +double | double | double +integer | integer | integer +long | long | long +time_duration | time_duration | time_duration +|=== diff --git a/docs/reference/esql/functions/unary.asciidoc b/docs/reference/esql/functions/unary.asciidoc index 2ee35b6c6256f..69ce754c1b4a0 100644 --- a/docs/reference/esql/functions/unary.asciidoc +++ b/docs/reference/esql/functions/unary.asciidoc @@ -2,7 +2,11 @@ [[esql-unary-operators]] === Unary operators -These unary mathematical operators are supported: +The only unary operators is negation (`-`): [.text-center] image::esql/functions/signature/neg.svg[Embedded,opts=inline] + +Supported types: + +include::types/neg.asciidoc[] diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java index 8b4a126d8a0c7..fe31fc79f761a 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java @@ -976,23 +976,33 @@ public static void renderTypesTable() throws IOException { if (System.getProperty("generateDocs") == null) { return; } - String name = functionName(); // TODO types table for operators + String name = functionName(); + if (binaryOperator(name) != null) { + renderTypesTable(List.of("lhs", "rhs")); + return; + } + if (unaryOperator(name) != null) { + renderTypesTable(List.of("v")); + return; + } FunctionDefinition definition = definition(name); - if (definition == null) { - LogManager.getLogger(getTestClass()).info("Skipping rendering types because the function isn't registered"); + if (definition != null) { + renderTypesTable(EsqlFunctionRegistry.description(definition).argNames()); return; } + LogManager.getLogger(getTestClass()).info("Skipping rendering types because the function isn't registered"); + } - List args = EsqlFunctionRegistry.description(definition).argNames(); + private static void renderTypesTable(List argNames) throws IOException { StringBuilder header = new StringBuilder(); - for (String arg : args) { + for (String arg : argNames) { header.append(arg).append(" | "); } header.append("result"); List table = new ArrayList<>(); for (Map.Entry, DataType> sig : signatures.entrySet()) { - if (sig.getKey().size() != args.size()) { + if (sig.getKey().size() != argNames.size()) { continue; } StringBuilder b = new StringBuilder(); @@ -1035,9 +1045,9 @@ private static String binaryOperator(String name) { case "div" -> "/"; case "equals" -> "=="; case "greater_than" -> ">"; - case "greater_than_or_equal_to" -> ">="; + case "greater_than_or_equal" -> ">="; case "less_than" -> "<"; - case "less_than_or_equal_to" -> "<="; + case "less_than_or_equal" -> "<="; case "mod" -> "%"; case "mul" -> "*"; case "not_equals" -> "!=";