ESQL: Locale and timezone argument for date_parse

[flash1293]

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.

[github-actions]

ℹ️ Important: Docs version tagging

👋 Thanks for updating the docs! Just a friendly reminder that our docs are now cumulative. This means all 9.x versions are documented on the same page and published off of the main branch, instead of creating separate pages for each minor version.

We use applies_to tags to mark version-specific features and changes.

Expand for a quick overview

When to use applies_to tags:

✅ At the page level to indicate which products/deployments the content applies to (mandatory)
✅ When features change state (e.g. preview, ga) in a specific version
✅ When availability differs across deployments and environments

What NOT to do:

❌ Don't remove or replace information that applies to an older version
❌ Don't add new information that applies to a specific version without an applies_to tag
❌ Don't forget that applies_to tags can be used at the page, section, and inline level

🤔 Need help?

• Check out the cumulative docs guidelines
• Reach out in the #docs Slack channel

[elasticsearchmachine]

Pinging @elastic/es-analytical-engine (Team:Analytics)

[elasticsearchmachine]

Hi @flash1293, I've created a changelog YAML for you.

[ivancea]

Can you add those tests as TestCaseSuppliers in the parameters() method? They automatically execute a bunch of cases.
I'm not sure of how map parameters work there really, but if it works like other params,you would be able to just test that it returns null with a warning with the error, which is what the user would see

[ivancea]

We usually use a switch here, to only change 1 field. For example:

elasticsearch/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/aggregate/TopSerializationTests.java

Lines 26 to 38 in c40c5a6

	@Override
	protected Top mutateInstance(Top instance) throws IOException {
	Source source = instance.source();
	Expression field = instance.field();
	Expression limit = instance.limitField();
	Expression order = instance.orderField();
	switch (between(0, 2)) {
	case 0 -> field = randomValueOtherThan(field, AbstractExpressionSerializationTests::randomChild);
	case 1 -> limit = randomValueOtherThan(limit, AbstractExpressionSerializationTests::randomChild);
	case 2 -> order = randomValueOtherThan(order, AbstractExpressionSerializationTests::randomChild);
	}
	return new Top(source, field, limit, order);
	}

[ivancea]

Can't we create the options even if "second" is null?

[ivancea]

This troubles me a bit. We're only allowing the options if the 2 previous parameters are present, even knowing that the format is optional too. That means, we're not allowing something like: DATE_PARSE(date, {})

However, the SVG (docs) shows it correctly.

Now, I don't know if we did something like this before, or if we should allow it. Our function overriding detection is quite manual right now, to begin with. I would like if somebody else from the team can review this first.

The worse that could happen if we ship this is that:

• We would have incorrect docs
• We would probably give meaningless errors, as users would expect the map parameter to "work"

[flash1293]

Good call... To me both allowing DATE_PARSE(date, {}) or enforcing three params for options make sense, if we clearly communicate this to the user.

Happy for someone else to make the call.

[flash1293]

For reference, DATE_PARSE(date_string, {\"time_zone\": \"Europe/Paris\",\"locale\":\"fr\"}) yields

{
  "error": {
    "root_cause": [
      {
        "type": "verification_exception",
        "reason": "Found 1 problem\nline 1:51: second argument of [DATE_PARSE(date_string, {\"time_zone\": \"Europe/Paris\",\"locale\":\"fr\"})] must be [string], found value [{\"time_zone\": \"Europe/Paris\",\"locale\":\"fr\"}] type [unsupported]"
      }
    ],
    "type": "verification_exception",
    "reason": "Found 1 problem\nline 1:51: second argument of [DATE_PARSE(date_string, {\"time_zone\": \"Europe/Paris\",\"locale\":\"fr\"})] must be [string], found value [{\"time_zone\": \"Europe/Paris\",\"locale\":\"fr\"}] type [unsupported]"
  },
  "status": 400
}

right now.

Your call of course, but if you feel comfortable with this behavior, we can get it in, then follow up later with supporting a more flexible calling pattern - we are lucky that the existing behavior on this PR is a subset of what could realistically be supported.

[ivancea]

I'm fine with closing this as-is. I would try to follow up soon though, as to not have the wrong docs there.

Btw, I was discussing this a bit, and I think we could make a working check here. Something like:

if (options == null) {
    if (second == null) {
        // 1 parameter, it's the date
    } else {
        if (second instanceof MapExpression) {
            // Second and options params, no format
        } else {
            // First and second params, no options
        }
    }
} else {
    // 3 params available, no doubt here
}

In general, having an optional param before a required is quite weird. But this is ""historical"" already, so here we are. For this special case, I think the logic to check it shouldn't be too complex, and we can manage to do it.
If there's some weird planning error after doing it, we can check it 👀