Spec drift: update for elasticsearch#149206 (new settings object in ES|QL query request body)

[github-actions]

Summary

Elasticsearch PR #149206 — "ES|QL: unify SET and request-body parameters" — adds a new top-level settings object to the _query and _query/async request bodies, giving tooling a named namespace to supply per-query configuration knobs that previously had no uniform home.

Field	Value
ES PR	elastic/elasticsearch#149206
Author	@quackaplop
Merge commit	5cf8e8797ab96b2131297050c81f53d0f97dd1f0
Merged	2026-07-03
ES version labels	v9.5.0
Implied spec branches	main (backport to 9.5 once released)

---

API impact

New request-body field: settings

Both POST /_query and POST /_query/async now accept an optional top-level settings object:

POST /_query
{
  "query": "FROM logs | WHERE status == 500",
  "settings": {
    "time_zone": "Europe/Paris"
  }
}

Keys inside settings are the canonical ES|QL SET key=value; names. Currently exposed settings:

Key	Type	Notes
time_zone	string	Same as existing top-level time_zone; permanent alias kept at root for BWC
project_routing	string	Same as existing top-level project_routing; permanent alias kept at root for BWC
approximation	object (ApproximationSettings)	Same as existing top-level approximation; permanent alias kept at root for BWC

Backwards compatibility: The three existing top-level fields (time_zone, project_routing, approximation) continue to work unchanged — they are permanent aliases, not deprecated. Sending the same setting both at the top level and inside settings with conflicting values returns HTTP 400; identical values are accepted.

Unknown keys inside settings are rejected with HTTP 400.

Resolution order: SET in query > settings in request body > server default.

---

Specification files to edit

1. specification/esql/query/QueryRequest.ts — add settings?: EsqlQuerySettings to the body type.
2. specification/esql/async_query/AsyncQueryRequest.ts — add settings?: EsqlQuerySettings to the body type.
3. specification/esql/_types/ — add a new EsqlQuerySettings type (or inline it) capturing time_zone?, project_routing?, and approximation? with appropriate availability annotations. The approximation value type may need a sub-type ApproximationSettings if one does not already exist.

Since time_zone and project_routing already appear as top-level body fields, the triager may choose to model settings as a separate named type that mirrors those fields, or reference existing types.

---

Notes / questions for the triager

• The three settings inside settings mirror the existing top-level fields; double-check whether availability annotations (e.g. @availability serverless) should match the top-level counterparts exactly.
• Future settings will be added to settings only (no new top-level aliases), so this type will grow over time. Consider whether to document that extensibility intent.
• Consider assigning the original ES PR author @quackaplop.

Generated by Weekly Elasticsearch Specification Drift · ● 4.1M · ◷