[Backport 8.14] [ES|QL] Document return value for locate in case substring is not found

docs/reference/esql/functions/description/locate.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns an integer that indicates the position of a keyword substring within another string
+Returns an integer that indicates the position of a keyword substring within another string. Returns `0` if the substring cannot be found. Note that string positions start from `1`.

docs/reference/esql/functions/kibana/definition/locate.json

@@ -2,7 +2,7 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "locate",
-  "description" : "Returns an integer that indicates the position of a keyword substring within another string",
+  "description" : "Returns an integer that indicates the position of a keyword substring within another string.\nReturns `0` if the substring cannot be found.\nNote that string positions start from `1`.",
   "signatures" : [
     {
       "params" : [

docs/reference/esql/functions/kibana/docs/locate.md

@@ -3,5 +3,7 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### LOCATE
-Returns an integer that indicates the position of a keyword substring within another string
+Returns an integer that indicates the position of a keyword substring within another string.
+Returns `0` if the substring cannot be found.
+Note that string positions start from `1`.
 

x-pack/plugin/esql/qa/testFixtures/src/main/resources/meta.csv-spec

@@ -259,7 +259,7 @@ greatest      |Returns the maximum value from many columns.
 least         |Returns the minimum value from many columns.
 left          |Returns the substring that extracts 'length' chars from 'string' starting from the left.
 length        |Returns the character length of a string.
-locate        |Returns an integer that indicates the position of a keyword substring within another string
+locate        |Returns an integer that indicates the position of a keyword substring within another string. Returns `0` if the substring cannot be found. Note that string positions start from `1`.
 log           |Returns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double.  Logs of zero, negative numbers, and base of one return `null` as well as a warning.
 log10         |Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double.  Logs of 0 and negative numbers return `null` as well as a warning.
 ltrim         |Removes leading whitespaces from a string.

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Locate.java

@@ -40,10 +40,10 @@ public class Locate extends EsqlScalarFunction implements OptionalArgument {
     private final Expression substr;
     private final Expression start;
 
-    @FunctionInfo(
-        returnType = "integer",
-        description = "Returns an integer that indicates the position of a keyword substring within another string"
-    )
+    @FunctionInfo(returnType = "integer", description = """
+        Returns an integer that indicates the position of a keyword substring within another string.
+        Returns `0` if the substring cannot be found.
+        Note that string positions start from `1`.""")
     public Locate(
         Source source,
         @Param(name = "string", type = { "keyword", "text" }, description = "An input string") Expression str,