Package org.elasticsearch.xpack.esql.plan

Class QuerySettings

java.lang.Object

org.elasticsearch.xpack.esql.plan.QuerySettings

public final class QuerySettings
extends Object

The catalog of registered ES|QL query settings.

Each entry is one fluent declaration. QuerySettingDef carries the schema and the read API; this class is a list of constants and two utility methods (validate(org.elasticsearch.xpack.esql.plan.EsqlStatement, org.elasticsearch.xpack.esql.plan.SettingsValidationContext) for the in-query SET pass, resolve(java.util.Map<org.elasticsearch.xpack.esql.plan.QuerySettingDef<?>, java.lang.Object>, org.elasticsearch.xpack.esql.plan.EsqlStatement, org.elasticsearch.xpack.esql.plan.SettingsValidationContext) for the merge step that produces an ResolvedSettings).

Adding a new setting

   public static final QuerySettingDef<String> MY_SETTING = QuerySettingDef
       .string("my_setting")
       .withDefault("foo")
       .withRequestBody()       // accept under settings.{my_setting}
       .build();
 

Then add the constant to ALL to register it. Read anywhere via MY_SETTING.get(resolvedSettings).

Field Summary

Fields

Modifier and Type	Field	Description
static final List<QuerySettingDef<?>>	ALL	The canonical, explicitly-enumerated set of all query settings.
static final QuerySettingDef<ApproximationSettings>	APPROXIMATION
static final QuerySettingDef<Boolean>	COLUMN_METADATA
static final QuerySettingDef<String>	PROJECT_ROUTING
static final QuerySettingDef<ZoneId>	TIME_ZONE
static final QuerySettingDef<UnmappedResolution>	UNMAPPED_FIELDS

Method Summary

Modifier and Type	Method	Description
static List<QuerySettingDef<?>>	all()	All declared settings.
static List<QuerySettingDef<?>>	applicableIn(boolean isSnapshot, boolean isServerless)	The registered settings whose availability matches the supplied snapshot/serverless environment.
static QuerySettingDef<?>	lookup(String name)	The setting with this name, or null if no such setting is declared.
static ResolvedSettings	resolve(Map<QuerySettingDef<?>,Object> requestParams, EsqlStatement statement, SettingsValidationContext ctx)	Folds registry default < request body < in-query SET into a single ResolvedSettings, applying each setting's QuerySettingDef.reconciler() at every step.
static void	validate(EsqlStatement statement, SettingsValidationContext ctx)	Validates the in-query SETs.
static void	warnIfDeprecated(QuerySettingDef<?> def)	Emits a deprecation warning if def is deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

PROJECT_ROUTING

public static final QuerySettingDef<String> PROJECT_ROUTING

TIME_ZONE

public static final QuerySettingDef<ZoneId> TIME_ZONE

UNMAPPED_FIELDS

public static final QuerySettingDef<UnmappedResolution> UNMAPPED_FIELDS

COLUMN_METADATA

public static final QuerySettingDef<Boolean> COLUMN_METADATA

APPROXIMATION

public static final QuerySettingDef<ApproximationSettings> APPROXIMATION

ALL

public static final List<QuerySettingDef<?>> ALL

The canonical, explicitly-enumerated set of all query settings. This is the single source of truth — the request parser, the resolver, and telemetry all iterate this list. Add a new setting's constant here when you declare it. Referencing this field initializes the class, so there is no load-order hazard.

Method Details

all

public static List<QuerySettingDef<?>> all()

All declared settings.

lookup

@Nullable
public static QuerySettingDef<?> lookup(String name)

The setting with this name, or null if no such setting is declared.

validate

public static void validate(EsqlStatement statement,
 SettingsValidationContext ctx)

Validates the in-query SETs. An unknown key is a typo the user can act on, so it fails loudly with a ParsingException — same as the request-body surface. A known-but-deprecated key is accepted with a deprecation warning (see warnIfDeprecated(org.elasticsearch.xpack.esql.plan.QuerySettingDef<?>)). Type and availability failures also throw early.

warnIfDeprecated

public static void warnIfDeprecated(QuerySettingDef<?> def)

Emits a deprecation warning if def is deprecated. Called from every settings surface (in-query SET, the request body, and the legacy root aliases) so a deprecated setting warns wherever it is supplied, while still being resolved and applied. Routed through DeprecationLogger (not a bare response header) so it also lands in the throttled operator-facing deprecation trail, matching how the rest of the module deprecates user-supplied knobs (e.g. the datasource auth aliases).

resolve

public static ResolvedSettings resolve(Map<QuerySettingDef<?>,Object> requestParams,
 @Nullable
 EsqlStatement statement,
 SettingsValidationContext ctx)

Folds registry default < request body < in-query SET into a single ResolvedSettings, applying each setting's QuerySettingDef.reconciler() at every step.

applicableIn

public static List<QuerySettingDef<?>> applicableIn(boolean isSnapshot,
 boolean isServerless)

The registered settings whose availability matches the supplied snapshot/serverless environment.