ESQL: Locale and timezone argument for date_parse (#136548)

Fixes #132487

```
POST _query
{
  "query": """
    ROW date_string="10 septembre 2025" | EVAL date = DATE_PARSE("dd MMMM yyyy", date_string, {"locale": "fr", "time_zone": "Europe/Paris" })
  """
}
```

returns

```
   date_string   |          date
-----------------+------------------------
10 septembre 2025|2025-09-09T22:00:00.000Z
```

In case the time zone or the locale can't be resolved, this throws an error.

Author: flash1293

docs/changelog/136548.yaml

@@ -0,0 +1,6 @@
+pr: 136548
+summary: Locale and timezone argument for `date_parse`
+area: ES|QL
+type: enhancement
+issues:
+ - 132487

docs/reference/query-languages/esql/_snippets/functions/functionNamedParams/date_parse.md

@@ -644,6 +644,46 @@ emp_no:integer  | new_date:datetime          | birth_date:datetime       | bool:
 10050           | 1958-05-21T00:00:00.000Z   | 1958-05-21T00:00:00.000Z  | true
 ;
 
+evalDateParseWithTimezoneOption
+required_capability: date_parse_options
+row a = "10-10-2025" | eval b = date_parse("dd-mm-yyyy", a, {"time_zone":"Europe/Paris"}) | keep b;
+
+b:datetime
+2024-12-31T23:00:00.000Z
+;
+
+evalDateParseWithLocaleOption
+required_capability: date_parse_options
+row a = "10 septembre 2025" | eval b = date_parse("dd MMMM yyyy", a, {"locale":"fr"}) | keep b;
+
+b:datetime
+2025-09-10T00:00:00.000Z
+;
+
+evalDateParseWithLocaleAndTimezoneOption
+required_capability: date_parse_options
+row a = "10 septembre 2025" | eval b = date_parse("dd MMMM yyyy", a, {"locale":"fr","time_zone":"Europe/Paris"}) | keep b;
+
+b:datetime
+2025-09-09T22:00:00.000Z
+;
+
+evalDateParseDefaultFormatWithTimezoneOption
+required_capability: date_parse_options
+row a = "2023-02-01T12:15:55.000+01:00" | eval b = date_parse(a, {"time_zone":"Europe/Paris"}) | keep b;
+
+b:datetime
+2023-02-01T11:15:55.000Z
+;
+
+evalDateParseDefaultFormatWithLocaleOption
+required_capability: date_parse_options
+row a = "2023-02-01T12:15:55.000Z" | eval b = date_parse(a, {"locale":"fr"}) | keep b;
+
+b:datetime
+2023-02-01T12:15:55.000Z
+;
+
 dateFields
 from employees | where emp_no == 10049 or emp_no == 10050 
 | eval year = date_extract("year", birth_date), month = date_extract("month_of_year", birth_date), day = date_extract("day_of_month", birth_date)

docs/reference/query-languages/esql/_snippets/functions/layout/date_parse.md

@@ -1532,6 +1532,11 @@ public enum Cap {
          */
         FIX_FILTER_ORDINALS,
 
+        /**
+         * Optional options argument for DATE_PARSE
+         */
+        DATE_PARSE_OPTIONS,
+
         /**
          * Allow multiple patterns for GROK command
          */

docs/reference/query-languages/esql/_snippets/functions/parameters/date_parse.md

@@ -1042,12 +1042,20 @@ public interface BinaryBuilder<T> {
     protected static <T extends Function> FunctionDefinition def(Class<T> function, TernaryBuilder<T> ctorRef, String... names) {
         FunctionBuilder builder = (source, children, cfg) -> {
             boolean hasMinimumTwo = OptionalArgument.class.isAssignableFrom(function);
-            if (hasMinimumTwo && (children.size() > 3 || children.size() < 2)) {
+            boolean hasMinimumOne = TwoOptionalArguments.class.isAssignableFrom(function);
+            if (hasMinimumOne && (children.size() > 3 || children.isEmpty())) {
+                throw new QlIllegalArgumentException("expects one, two or three arguments");
+            } else if (hasMinimumTwo && (children.size() > 3 || children.size() < 2)) {
                 throw new QlIllegalArgumentException("expects two or three arguments");
-            } else if (hasMinimumTwo == false && children.size() != 3) {
+            } else if (hasMinimumOne == false && hasMinimumTwo == false && children.size() != 3) {
                 throw new QlIllegalArgumentException("expects exactly three arguments");
             }
-            return ctorRef.build(source, children.get(0), children.get(1), children.size() == 3 ? children.get(2) : null);
+            return ctorRef.build(
+                source,
+                children.get(0),
+                children.size() > 1 ? children.get(1) : null,
+                children.size() == 3 ? children.get(2) : null
+            );
         };
         return def(function, builder, names);
     }