ESQL: Load timezone query settings (SET x=y) into configuration (#136637)

Continuation of #136205

- Load the timezone query setting to the Configuration  (Snapshot only, as SET is snapshot)
- Add a time_zone request body param as a fallback (Snapshot only)

The `Configuration.zoneId` field where this is being stored is already used by 3 functions:
- `DateExtract`
- `DayName`
- `MonthName`

And also, by a rule, `ReplaceRoundToWithQueryAndTags`, recently added, that propagates it, in some cases, to:
- `LessThan`
- `GreaterThanOrEqual`
- `Range`

Author: ivancea

benchmarks/src/main/java/org/elasticsearch/benchmark/_nightly/esql/QueryPlanningBenchmark.java

@@ -76,7 +76,7 @@ public void setup() {
             Locale.US,
             null,
             null,
-            new QueryPragmas(Settings.EMPTY),
+            QueryPragmas.EMPTY,
             AnalyzerSettings.QUERY_RESULT_TRUNCATION_MAX_SIZE.getDefault(Settings.EMPTY),
             AnalyzerSettings.QUERY_RESULT_TRUNCATION_DEFAULT_SIZE.getDefault(Settings.EMPTY),
             "",

benchmarks/src/main/java/org/elasticsearch/benchmark/compute/operator/EvalBenchmark.java

@@ -56,6 +56,7 @@
 import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.Equals;
 import org.elasticsearch.xpack.esql.expression.predicate.operator.comparison.LessThan;
 import org.elasticsearch.xpack.esql.planner.Layout;
+import org.elasticsearch.xpack.esql.plugin.QueryPragmas;
 import org.elasticsearch.xpack.esql.session.Configuration;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
@@ -358,7 +359,7 @@ private static Configuration configuration() {
             Locale.ROOT,
             null,
             null,
-            null,
+            QueryPragmas.EMPTY,
             AnalyzerSettings.QUERY_RESULT_TRUNCATION_MAX_SIZE.get(Settings.EMPTY),
             AnalyzerSettings.QUERY_RESULT_TRUNCATION_DEFAULT_SIZE.get(Settings.EMPTY),
             null,

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlQueryRequest.java

@@ -28,6 +28,7 @@
 import org.elasticsearch.xpack.esql.plugin.QueryPragmas;
 
 import java.io.IOException;
+import java.time.ZoneId;
 import java.util.Iterator;
 import java.util.Locale;
 import java.util.Map;
@@ -47,6 +48,7 @@ public class EsqlQueryRequest extends org.elasticsearch.xpack.core.esql.action.E
     private boolean profile;
     private Boolean includeCCSMetadata;
     private Boolean includeExecutionMetadata;
+    private ZoneId timeZone;
     private Locale locale;
     private QueryBuilder filter;
     private QueryPragmas pragmas = new QueryPragmas(Settings.EMPTY);
@@ -87,6 +89,12 @@ public ActionRequestValidationException validate() {
         }
 
         if (onSnapshotBuild == false) {
+            if (timeZone != null) {
+                validationException = addValidationError(
+                    "[" + RequestXContent.TIME_ZONE_FIELD + "] only allowed in snapshot builds",
+                    validationException
+                );
+            }
             if (pragmas.isEmpty() == false && acceptedPragmaRisks == false) {
                 validationException = addValidationError(
                     "[" + RequestXContent.PRAGMA_FIELD + "] only allowed in snapshot builds",
@@ -158,6 +166,14 @@ public boolean profile() {
         return profile;
     }
 
+    public void timeZone(ZoneId timeZone) {
+        this.timeZone = timeZone;
+    }
+
+    public ZoneId timeZone() {
+        return timeZone;
+    }
+
     public void locale(Locale locale) {
         this.locale = locale;
     }

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/RequestXContent.java

@@ -22,6 +22,7 @@
 import org.elasticsearch.xpack.esql.plugin.QueryPragmas;
 
 import java.io.IOException;
+import java.time.ZoneId;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.HashMap;
@@ -76,6 +77,7 @@ String fields() {
     private static final ParseField FILTER_FIELD = new ParseField("filter");
     static final ParseField PRAGMA_FIELD = new ParseField("pragma");
     private static final ParseField PARAMS_FIELD = new ParseField("params");
+    static final ParseField TIME_ZONE_FIELD = new ParseField("time_zone");
     private static final ParseField LOCALE_FIELD = new ParseField("locale");
     private static final ParseField PROFILE_FIELD = new ParseField("profile");
     private static final ParseField ACCEPT_PRAGMA_RISKS = new ParseField("accept_pragma_risks");
@@ -113,6 +115,7 @@ private static void objectParserCommon(ObjectParser<EsqlQueryRequest, ?> parser)
             PRAGMA_FIELD
         );
         parser.declareField(EsqlQueryRequest::params, RequestXContent::parseParams, PARAMS_FIELD, VALUE_OBJECT_ARRAY);
+        parser.declareString((request, timeZone) -> request.timeZone(ZoneId.of(timeZone)), TIME_ZONE_FIELD);
         parser.declareString((request, localeTag) -> request.locale(Locale.forLanguageTag(localeTag)), LOCALE_FIELD);
         parser.declareBoolean(EsqlQueryRequest::profile, PROFILE_FIELD);
         parser.declareField((p, r, c) -> new ParseTables(r, p).parseTables(), TABLES_FIELD, ObjectParser.ValueType.OBJECT);

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/EsqlStatement.java

@@ -8,28 +8,71 @@
 package org.elasticsearch.xpack.esql.plan;
 
 import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.expression.Literal;
 import org.elasticsearch.xpack.esql.plan.logical.LogicalPlan;
 
 import java.util.List;
 
 public record EsqlStatement(LogicalPlan plan, List<QuerySetting> settings) {
+    /**
+     * Returns the value of a setting, or the setting default value if the setting is not set.
+     * If the setting name appears multiple times, this will return last occurrence.
+     * <p>
+     *     Use it like:
+     * </p>
+     * <pre><code>
+     *     var value = statement.setting(QuerySettings.MY_SETTING);
+     * </code></pre>
+     *
+     * @param settingDef the setting to retrieve
+     */
+    public <T> T setting(QuerySettings.QuerySettingDef<T> settingDef) {
+        return settingOrDefault(settingDef, settingDef.defaultValue());
+    }
+
+    /**
+     * Returns the value of a setting, but returns the given default value if the setting is not set.
+     * <p>
+     *     Use it like:
+     * </p>
+     * <pre><code>
+     *     var value = statement.settingOrDefault(QuerySettings.MY_SETTING, "default");
+     * </code></pre>
+     * <p>
+     *     To be used when a fallback is available.
+     * </p>
+     *
+     * @param settingDef the setting to retrieve
+     * @param defaultValue the value to return if the setting is not set
+     */
+    public <T> T settingOrDefault(QuerySettings.QuerySettingDef<T> settingDef, T defaultValue) {
+        Expression expression = setting(settingDef.name());
+        if (expression == null) {
+            return defaultValue;
+        }
+        return settingDef.parse((Literal) expression);
+    }
+
     /**
      * Returns the expression corresponding to a setting value.
      * If the setting name appears multiple times, this will return last occurrence.
+     * <p>
+     *     For testing purposes; use {@link #setting(QuerySettings.QuerySettingDef)} instead.
+     * </p>
      *
      * @param name the setting name
      */
     public Expression setting(String name) {
         if (settings == null) {
             return null;
         }
-        Expression result = null;
+        Expression expression = null;
         for (QuerySetting setting : settings) {
             if (setting.name().equals(name)) {
-                result = setting.value();
+                expression = setting.value();
             }
         }
-        return result;
+        return expression;
     }
 
     @Override

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/QuerySettings.java

@@ -9,7 +9,7 @@
 
 import org.elasticsearch.core.Nullable;
 import org.elasticsearch.transport.RemoteClusterService;
-import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.expression.Literal;
 import org.elasticsearch.xpack.esql.core.type.DataType;
 import org.elasticsearch.xpack.esql.expression.Foldables;
 import org.elasticsearch.xpack.esql.parser.ParsingException;
@@ -34,8 +34,8 @@ public class QuerySettings {
         "A project routing expression, "
             + "used to define which projects to route the query to. "
             + "Only supported if Cross-Project Search is enabled.",
-        (value, settings) -> Foldables.stringLiteralValueOf(value, "Unexpected value"),
-        (_rcs) -> null
+        (value) -> Foldables.stringLiteralValueOf(value, "Unexpected value"),
+        null
     );
 
     public static final QuerySettingDef<ZoneId> TIME_ZONE = new QuerySettingDef<>(
@@ -45,19 +45,19 @@ public class QuerySettings {
         true,
         true,
         "The default timezone to be used in the query, by the functions and commands that require it. Defaults to UTC",
-        (value, _rcs) -> {
+        (value) -> {
             String timeZone = Foldables.stringLiteralValueOf(value, "Unexpected value");
             try {
                 return ZoneId.of(timeZone);
             } catch (Exception exc) {
                 throw new IllegalArgumentException("Invalid time zone [" + timeZone + "]");
             }
         },
-        (_rcs) -> ZoneOffset.UTC
+        ZoneOffset.UTC
     );
 
     public static final Map<String, QuerySettingDef<?>> SETTINGS_BY_NAME = Stream.of(PROJECT_ROUTING, TIME_ZONE)
-        .collect(Collectors.toMap(QuerySettingDef::name, Function.identity()));;
+        .collect(Collectors.toMap(QuerySettingDef::name, Function.identity()));
 
     public static void validate(EsqlStatement statement, RemoteClusterService clusterService) {
         for (QuerySetting setting : statement.settings()) {
@@ -70,7 +70,14 @@ public static void validate(EsqlStatement statement, RemoteClusterService cluste
                 throw new ParsingException(setting.source(), "Setting [" + setting.name() + "] must be of type " + def.type());
             }
 
-            String error = def.validator().validate(setting.value(), clusterService);
+            Literal literal;
+            if (setting.value() instanceof Literal l) {
+                literal = l;
+            } else {
+                throw new ParsingException(setting.source(), "Setting [" + setting.name() + "] must have a literal value");
+            }
+
+            String error = def.validator().validate(literal, clusterService);
             if (error != null) {
                 throw new ParsingException("Error validating setting [" + setting.name() + "]: " + error);
             }
@@ -89,7 +96,7 @@ public static void validate(EsqlStatement statement, RemoteClusterService cluste
      * @param validator A validation function to check the setting value.
      *                  Defaults to calling the {@link #parser} and returning the error message of any exception it throws.
      * @param parser A function to parse the setting value into the final object.
-     * @param defaultValueSupplier A supplier of the default value to be used when the setting is not set.
+     * @param defaultValue A default value to be used when the setting is not set.
      * @param <T> The type of the setting value.
      */
     public record QuerySettingDef<T>(
@@ -101,8 +108,11 @@ public record QuerySettingDef<T>(
         String description,
         Validator validator,
         Parser<T> parser,
-        Function<RemoteClusterService, T> defaultValueSupplier
+        T defaultValue
     ) {
+        /**
+         * Constructor with a default validator that delegates to the parser.
+         */
         public QuerySettingDef(
             String name,
             DataType type,
@@ -111,23 +121,23 @@ public QuerySettingDef(
             boolean snapshotOnly,
             String description,
             Parser<T> parser,
-            Function<RemoteClusterService, T> defaultValueSupplier
+            T defaultValue
         ) {
             this(name, type, serverlessOnly, preview, snapshotOnly, description, (value, rcs) -> {
                 try {
-                    parser.parse(value, rcs);
+                    parser.parse(value);
                     return null;
                 } catch (Exception exc) {
                     return exc.getMessage();
                 }
-            }, parser, defaultValueSupplier);
+            }, parser, defaultValue);
         }
 
-        public T get(Expression value, RemoteClusterService clusterService) {
+        public T parse(@Nullable Literal value) {
             if (value == null) {
-                return defaultValueSupplier.apply(clusterService);
+                return defaultValue;
             }
-            return parser.parse(value, clusterService);
+            return parser.parse(value);
         }
 
         @FunctionalInterface
@@ -136,15 +146,15 @@ public interface Validator {
              * Validates the setting value and returns the error message if there's an error, or null otherwise.
              */
             @Nullable
-            String validate(Expression value, RemoteClusterService clusterService);
+            String validate(Literal value, RemoteClusterService clusterService);
         }
 
         @FunctionalInterface
         public interface Parser<T> {
             /**
-             * Parses an already validated expression.
+             * Parses an already validated literal.
              */
-            T parse(Expression value, RemoteClusterService clusterService);
+            T parse(Literal value);
         }
     }
 }

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/Configuration.java

@@ -333,6 +333,8 @@ public String toString() {
             + ",timeseries="
             + resultTruncationDefaultSize(true)
             + "]"
+            + ", zoneId="
+            + zoneId
             + ", locale="
             + locale
             + ", query='"

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/session/EsqlSession.java

@@ -84,7 +84,6 @@
 import org.elasticsearch.xpack.esql.plugin.TransportActionServices;
 import org.elasticsearch.xpack.esql.telemetry.PlanTelemetry;
 
-import java.time.ZoneOffset;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
@@ -184,7 +183,9 @@ public void execute(EsqlQueryRequest request, EsqlExecutionInfo executionInfo, P
         LOGGER.debug("ESQL query:\n{}", request.query());
         EsqlStatement statement = parse(request.query(), request.params());
         Configuration configuration = new Configuration(
-            ZoneOffset.UTC, // TODO: Use the time_zone setting instead?
+            request.timeZone() == null
+                ? statement.setting(QuerySettings.TIME_ZONE)
+                : statement.settingOrDefault(QuerySettings.TIME_ZONE, request.timeZone()),
             request.locale() != null ? request.locale() : Locale.US,
             // TODO: plug-in security
             null,