*
*
* Make sure to commit them. Add a reference to the
@@ -194,6 +196,9 @@
* for your function. Now add something like {@code required_capability: my_function}
* to all of your csv-spec tests. Run those csv-spec tests as integration tests to double
* check that they run on the main branch.
+ *
+ * **Note:** you may notice tests gated based on Elasticsearch version. This was the old way
+ * of doing things. Now, we use specific capabilities for each function.
*
*
* Open the PR. The subject and description of the PR are important because those'll turn
@@ -201,7 +206,7 @@
* happy. But functions don't need an essay.
*
*
- * Add the {@code >enhancement} and {@code :Query Languages/ES|QL} tags if you are able.
+ * Add the {@code >enhancement} and {@code :Analytics/ES|QL} tags if you are able.
* Request a review if you can, probably from one of the folks that github proposes to you.
*
*
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Reverse.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Reverse.java
new file mode 100644
index 0000000000000..bf4e47d8d0de4
--- /dev/null
+++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Reverse.java
@@ -0,0 +1,140 @@
+/*
+ * 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.function.scalar.string;
+
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.common.lucene.BytesRefs;
+import org.elasticsearch.compute.ann.Evaluator;
+import org.elasticsearch.compute.operator.EvalOperator.ExpressionEvaluator;
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+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.UnaryScalarFunction;
+
+import java.io.IOException;
+import java.text.BreakIterator;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+
+import static org.elasticsearch.common.util.ArrayUtils.reverseArray;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.DEFAULT;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isString;
+
+/**
+ * Function that reverses a string.
+ */
+public class Reverse extends UnaryScalarFunction {
+ public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(Expression.class, "Reverse", Reverse::new);
+
+ @FunctionInfo(
+ returnType = { "keyword", "text" },
+ description = "Returns a new string representing the input string in reverse order.",
+ examples = {
+ @Example(file = "string", tag = "reverse"),
+ @Example(
+ file = "string",
+ tag = "reverseEmoji",
+ description = "`REVERSE` works with unicode, too! It keeps unicode grapheme clusters together during reversal."
+ ) }
+ )
+ public Reverse(
+ Source source,
+ @Param(
+ name = "str",
+ type = { "keyword", "text" },
+ description = "String expression. If `null`, the function returns `null`."
+ ) Expression field
+ ) {
+ super(source, field);
+ }
+
+ private Reverse(StreamInput in) throws IOException {
+ super(in);
+ }
+
+ @Override
+ public String getWriteableName() {
+ return ENTRY.name;
+ }
+
+ @Override
+ protected TypeResolution resolveType() {
+ if (childrenResolved() == false) {
+ return new TypeResolution("Unresolved children");
+ }
+
+ return isString(field, sourceText(), DEFAULT);
+ }
+
+ /**
+ * Reverses a unicode string, keeping grapheme clusters together
+ * @param str
+ * @return
+ */
+ public static String reverseStringWithUnicodeCharacters(String str) {
+ BreakIterator boundary = BreakIterator.getCharacterInstance(Locale.ROOT);
+ boundary.setText(str);
+
+ List characters = new ArrayList<>();
+ int start = boundary.first();
+ for (int end = boundary.next(); end != BreakIterator.DONE; start = end, end = boundary.next()) {
+ characters.add(str.substring(start, end));
+ }
+
+ StringBuilder reversed = new StringBuilder(str.length());
+ for (int i = characters.size() - 1; i >= 0; i--) {
+ reversed.append(characters.get(i));
+ }
+
+ return reversed.toString();
+ }
+
+ private static boolean isOneByteUTF8(BytesRef ref) {
+ int end = ref.offset + ref.length;
+ for (int i = ref.offset; i < end; i++) {
+ if (ref.bytes[i] < 0) {
+ return false;
+ }
+ }
+ return true;
+ }
+
+ @Evaluator
+ static BytesRef process(BytesRef val) {
+ if (isOneByteUTF8(val)) {
+ // this is the fast path. we know we can just reverse the bytes.
+ BytesRef reversed = BytesRef.deepCopyOf(val);
+ reverseArray(reversed.bytes, reversed.offset, reversed.length);
+ return reversed;
+ }
+ return BytesRefs.toBytesRef(reverseStringWithUnicodeCharacters(val.utf8ToString()));
+ }
+
+ @Override
+ public ExpressionEvaluator.Factory toEvaluator(ToEvaluator toEvaluator) {
+ var fieldEvaluator = toEvaluator.apply(field);
+ return new ReverseEvaluator.Factory(source(), fieldEvaluator);
+ }
+
+ @Override
+ public Expression replaceChildren(List newChildren) {
+ assert newChildren.size() == 1;
+ return new Reverse(source(), newChildren.get(0));
+ }
+
+ @Override
+ protected NodeInfo info() {
+ return NodeInfo.create(this, Reverse::new, field);
+ }
+}
diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ReverseSerializationTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ReverseSerializationTests.java
new file mode 100644
index 0000000000000..7b1ad8c9dffd0
--- /dev/null
+++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ReverseSerializationTests.java
@@ -0,0 +1,19 @@
+/*
+ * 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.function.scalar.string;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.expression.AbstractUnaryScalarSerializationTests;
+
+public class ReverseSerializationTests extends AbstractUnaryScalarSerializationTests {
+ @Override
+ protected Reverse create(Source source, Expression child) {
+ return new Reverse(source, child);
+ }
+}
diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ReverseTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ReverseTests.java
new file mode 100644
index 0000000000000..2873f18d53957
--- /dev/null
+++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/ReverseTests.java
@@ -0,0 +1,65 @@
+/*
+ * 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.function.scalar.string;
+
+import com.carrotsearch.randomizedtesting.annotations.Name;
+import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
+
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.common.lucene.BytesRefs;
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.AbstractScalarFunctionTestCase;
+import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.Supplier;
+
+import static org.hamcrest.Matchers.equalTo;
+
+public class ReverseTests extends AbstractScalarFunctionTestCase {
+ public ReverseTests(@Name("TestCase") Supplier testCaseSupplier) {
+ this.testCase = testCaseSupplier.get();
+ }
+
+ @ParametersFactory
+ public static Iterable parameters() {
+ List suppliers = new ArrayList<>();
+
+ for (DataType stringType : new DataType[] { DataType.KEYWORD, DataType.TEXT }) {
+ for (var supplier : TestCaseSupplier.stringCases(stringType)) {
+ suppliers.add(makeSupplier(supplier));
+ }
+ }
+
+ return parameterSuppliersFromTypedData(suppliers);
+ }
+
+ @Override
+ protected Expression build(Source source, List args) {
+ return new Reverse(source, args.get(0));
+ }
+
+ private static TestCaseSupplier makeSupplier(TestCaseSupplier.TypedDataSupplier fieldSupplier) {
+ return new TestCaseSupplier(fieldSupplier.name(), List.of(fieldSupplier.type()), () -> {
+ var fieldTypedData = fieldSupplier.get();
+ String expectedToString = "ReverseEvaluator[val=Attribute[channel=0]]";
+ String value = BytesRefs.toString(fieldTypedData.data());
+ String expectedValue = Reverse.reverseStringWithUnicodeCharacters(value);
+
+ return new TestCaseSupplier.TestCase(
+ List.of(fieldTypedData),
+ expectedToString,
+ fieldSupplier.type(),
+ equalTo(new BytesRef(expectedValue))
+ );
+ });
+ }
+}
diff --git a/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/80_text.yml b/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/80_text.yml
index 9607b64385721..939f153b8b0ea 100644
--- a/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/80_text.yml
+++ b/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/80_text.yml
@@ -3,7 +3,7 @@ setup:
- requires:
cluster_features: ["gte_v8.11.0"]
reason: "ESQL is available in 8.11+"
- test_runner_features: allowed_warnings_regex
+ test_runner_features: [allowed_warnings_regex, capabilities]
- do:
indices.create:
@@ -385,8 +385,31 @@ setup:
- length: { values: 2 }
- match: { values.0: [ [ "foo", "bar" ] ] }
- match: { values.1: [ "baz" ] }
+---
+"reverse text":
+ - requires:
+ capabilities:
+ - method: POST
+ path: /_query
+ parameters: [method, path, parameters, capabilities]
+ capabilities: [fn_reverse]
+ reason: "reverse not yet added"
+ - do:
+ allowed_warnings_regex:
+ - "No limit defined, adding default limit of \\[.*\\]"
+ esql.query:
+ body:
+ query: 'FROM test | SORT name | EVAL job_reversed = REVERSE(job), tag_reversed = REVERSE(tag) | KEEP job_reversed, tag_reversed'
+
+ - match: { columns.0.name: "job_reversed" }
+ - match: { columns.0.type: "text" }
+ - match: { columns.1.name: "tag_reversed" }
+ - match: { columns.1.type: "text" }
+ - length: { values: 2 }
+ - match: { values.0: [ "rotceriD TI", "rab oof" ] }
+ - match: { values.1: [ "tsilaicepS lloryaP", "zab" ] }
---
"stats text with raw":
- do: