Package org.elasticsearch.xpack.esql.plan

Class QuerySettingDef.Builder<T>

java.lang.Object

org.elasticsearch.xpack.esql.plan.QuerySettingDef.Builder<T>

Enclosing class:

QuerySettingDef<T>

public static final class QuerySettingDef.Builder<T>
extends Object

Fluent builder for QuerySettingDef. Terminates in build(), which validates the combination of flags and constructs the immutable setting.

Method Summary

Modifier and Type	Method	Description
QuerySettingDef<T>	build()	Validate the builder state and construct the immutable definition.
QuerySettingDef.Builder<T>	canonicalize(UnaryOperator<T> canonicalizer)	Coerce every value of this setting into a canonical form on write (see QuerySettingDef.canonicalize(T)).
QuerySettingDef.Builder<T>	withAliasAt(String parentPath, String aliasName)	Body alias at a JSON path.
QuerySettingDef.Builder<T>	withAliasAtRoot()	Body alias at the top level of the request body, named after the SET key.
QuerySettingDef.Builder<T>	withDefault(T value)
QuerySettingDef.Builder<T>	withDeprecated(String message)	Mark this setting deprecated.
QuerySettingDef.Builder<T>	withPreview()
QuerySettingDef.Builder<T>	withReconciler(QuerySettingDef.SettingReconciler<T> reconciler)	Custom merge function.
QuerySettingDef.Builder<T>	withRequestBody()	Opt in: the setting is reachable from the _query request body under settings.<name>.
QuerySettingDef.Builder<T>	withServerlessOnly()	Deployment marker for serverless-only settings.
QuerySettingDef.Builder<T>	withSnapshotOnly()	Hard availability gate: supplying this setting on a non-snapshot build is rejected at validate/resolve.
QuerySettingDef.Builder<T>	withValidator(QuerySettingDef.Validator<T> validator)

Methods inherited from class java.lang.Object

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

Method Details

withDefault

public QuerySettingDef.Builder<T> withDefault(@Nullable
 T value)

withValidator

public QuerySettingDef.Builder<T> withValidator(QuerySettingDef.Validator<T> validator)

withRequestBody

public QuerySettingDef.Builder<T> withRequestBody()

Opt in: the setting is reachable from the _query request body under settings.<name>.

withAliasAtRoot

public QuerySettingDef.Builder<T> withAliasAtRoot()

Body alias at the top level of the request body, named after the SET key. Implies withRequestBody().

withAliasAt

public QuerySettingDef.Builder<T> withAliasAt(String parentPath,
 String aliasName)

Body alias at a JSON path. parentPath is a dotted path to the parent object ("" = root). Implies withRequestBody(). May be called multiple times.

Only root aliases (parentPath == "") are wired in the request parser today; declaring a non-root alias makes RequestXContent fail at parser-build time. Nested-path parsing is tracked in #149283.

withReconciler

public QuerySettingDef.Builder<T> withReconciler(QuerySettingDef.SettingReconciler<T> reconciler)

Custom merge function. Default is "highest-precedence non-null wins" — correct for scalars. Override only for settings whose value is a multi-field object where partial contributions from different sources should combine instead of overwriting.

withPreview

public QuerySettingDef.Builder<T> withPreview()

withSnapshotOnly

public QuerySettingDef.Builder<T> withSnapshotOnly()

Hard availability gate: supplying this setting on a non-snapshot build is rejected at validate/resolve.

withServerlessOnly

public QuerySettingDef.Builder<T> withServerlessOnly()

Deployment marker for serverless-only settings. Unlike withSnapshotOnly() this is NOT a parse/resolve gate — it only drives telemetry (QuerySettings.applicableIn(boolean, boolean)). A serverless-only setting that must be hard-rejected on a stateful cluster enforces that through its withValidator(org.elasticsearch.xpack.esql.plan.QuerySettingDef.Validator<T>) (as project_routing does via its cross-project check).

withDeprecated

public QuerySettingDef.Builder<T> withDeprecated(String message)

Mark this setting deprecated. It keeps working (still resolved and applied), but supplying it emits message as a deprecation warning. Use this instead of dropping a setting from the registry when you want to steer clients away from it without breaking the ones that still send it.

canonicalize

public QuerySettingDef.Builder<T> canonicalize(UnaryOperator<T> canonicalizer)

Coerce every value of this setting into a canonical form on write (see QuerySettingDef.canonicalize(T)). Use it when equal values can be spelled differently — e.g. time_zone normalizes ZoneIds — so consumers never see two forms of the same value.

build

public QuerySettingDef<T> build()

Validate the builder state and construct the immutable definition. The setting is not self-registered; register it by adding its constant to QuerySettings.ALL (duplicate names are caught there).