refactor(datastore): extract DatastoreExecutionOptions for query execution options

Author: rahulmane-goog

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/Datastore.java

@@ -495,28 +495,10 @@ interface TransactionCallable<T> {
   <T> QueryResults<T> run(Query<T> query, ExplainOptions explainOptions, ReadOption... options);
 
   /**
-   * Submits a {@link Query} with specified {@link com.google.datastore.v1.RequestOptions} and
-   * returns its result.
-   */
-  <T> QueryResults<T> run(Query<T> query, RequestOptions requestOptions);
-
-  /**
-   * Submits a {@link Query} with specified {@link com.google.datastore.v1.RequestOptions} and
-   * returns its result. {@link ReadOption}s can be specified if desired.
-   */
-  <T> QueryResults<T> run(Query<T> query, RequestOptions requestOptions, ReadOption... options);
-
-  /**
-   * Submits a {@link Query} with specified {@link com.google.cloud.datastore.models.ExplainOptions}
-   * and {@link com.google.datastore.v1.RequestOptions} and returns its result. {@link ReadOption}s
-   * can be specified if desired.
+   * Submits a {@link Query} with specified {@link DatastoreExecutionOptions} and returns its result.
    */
   @BetaApi
-  <T> QueryResults<T> run(
-      Query<T> query,
-      ExplainOptions explainOptions,
-      RequestOptions requestOptions,
-      ReadOption... options);
+  <T> QueryResults<T> run(Query<T> query, DatastoreExecutionOptions executionOptions);
 
   /**
    * Submits a {@link AggregationQuery} and returns {@link AggregationResults}. {@link ReadOption}s
@@ -563,20 +545,6 @@ <T> QueryResults<T> run(
    */
   AggregationResults runAggregation(AggregationQuery query, ReadOption... options);
 
-  /**
-   * Submits an {@link AggregationQuery} with specified {@link
-   * com.google.datastore.v1.RequestOptions} and returns {@link AggregationResults}.
-   */
-  AggregationResults runAggregation(AggregationQuery query, RequestOptions requestOptions);
-
-  /**
-   * Submits an {@link AggregationQuery} with specified {@link
-   * com.google.datastore.v1.RequestOptions} and returns {@link AggregationResults}. {@link
-   * ReadOption}s can be specified if desired.
-   */
-  AggregationResults runAggregation(
-      AggregationQuery query, RequestOptions requestOptions, ReadOption... options);
-
   /**
    * Submits a {@link AggregationQuery} with specified {@link
    * com.google.cloud.datastore.models.ExplainOptions} and returns {@link AggregationResults}.
@@ -605,26 +573,12 @@ AggregationResults runAggregation(
       AggregationQuery query, ExplainOptions explainOptions, ReadOption... options);
 
   /**
-   * Submits an {@link AggregationQuery} with specified {@link
-   * com.google.cloud.datastore.models.ExplainOptions} and {@link
-   * com.google.datastore.v1.RequestOptions} and returns {@link AggregationResults}.
-   */
-  @BetaApi
-  AggregationResults runAggregation(
-      AggregationQuery query, ExplainOptions explainOptions, RequestOptions requestOptions);
-
-  /**
-   * Submits an {@link AggregationQuery} with specified {@link
-   * com.google.cloud.datastore.models.ExplainOptions} and {@link
-   * com.google.datastore.v1.RequestOptions} and returns {@link AggregationResults}. {@link
-   * ReadOption}s can be specified if desired.
+   * Submits an {@link AggregationQuery} with specified {@link DatastoreExecutionOptions} and returns
+   * {@link AggregationResults}.
    */
   @BetaApi
   AggregationResults runAggregation(
-      AggregationQuery query,
-      ExplainOptions explainOptions,
-      RequestOptions requestOptions,
-      ReadOption... options);
+      AggregationQuery query, DatastoreExecutionOptions executionOptions);
 
   /**
    * Closes the gRPC channels associated with this instance and frees up their resources. This

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreExecutionOptions.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.cloud.datastore;
+
+import com.google.api.core.BetaApi;
+import com.google.cloud.datastore.models.ExplainOptions;
+import com.google.common.base.Objects;
+import com.google.common.collect.ImmutableList;
+import com.google.datastore.v1.RequestOptions;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Class representing options for query execution in Google Cloud Datastore. Combines {@link
+ * ExplainOptions}, {@link RequestOptions}, and {@link ReadOption}s.
+ */
+@BetaApi
+public class DatastoreExecutionOptions {
+
+  private final ExplainOptions explainOptions;
+  private final RequestOptions requestOptions;
+  private final List<ReadOption> readOptions;
+
+  private DatastoreExecutionOptions(Builder builder) {
+    this.explainOptions = builder.explainOptions;
+    this.requestOptions = builder.requestOptions;
+    this.readOptions = ImmutableList.copyOf(builder.readOptions);
+  }
+
+  public ExplainOptions getExplainOptions() {
+    return explainOptions;
+  }
+
+  public RequestOptions getRequestOptions() {
+    return requestOptions;
+  }
+
+  public List<ReadOption> getReadOptions() {
+    return readOptions;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof DatastoreExecutionOptions)) return false;
+    DatastoreExecutionOptions that = (DatastoreExecutionOptions) o;
+    return Objects.equal(explainOptions, that.explainOptions)
+        && Objects.equal(requestOptions, that.requestOptions)
+        && Objects.equal(readOptions, that.readOptions);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(explainOptions, requestOptions, readOptions);
+  }
+
+  public static Builder newBuilder() {
+    return new Builder();
+  }
+
+  public static DatastoreExecutionOptions of(RequestOptions requestOptions) {
+    return newBuilder().setRequestOptions(requestOptions).build();
+  }
+
+  public static DatastoreExecutionOptions of(ExplainOptions explainOptions) {
+    return newBuilder().setExplainOptions(explainOptions).build();
+  }
+
+  public static DatastoreExecutionOptions of(ReadOption... readOptions) {
+    return newBuilder().setReadOptions(readOptions).build();
+  }
+
+  public static DatastoreExecutionOptions of(
+      RequestOptions requestOptions, ReadOption... readOptions) {
+    return newBuilder().setRequestOptions(requestOptions).setReadOptions(readOptions).build();
+  }
+
+  public static DatastoreExecutionOptions of(
+      ExplainOptions explainOptions, RequestOptions requestOptions, ReadOption... readOptions) {
+    return newBuilder()
+        .setExplainOptions(explainOptions)
+        .setRequestOptions(requestOptions)
+        .setReadOptions(readOptions)
+        .build();
+  }
+
+  /** Builder for {@link DatastoreExecutionOptions}. */
+  public static class Builder {
+    private ExplainOptions explainOptions;
+    private RequestOptions requestOptions;
+    private List<ReadOption> readOptions = Collections.emptyList();
+
+    private Builder() {}
+
+    public Builder setExplainOptions(ExplainOptions explainOptions) {
+      this.explainOptions = explainOptions;
+      return this;
+    }
+
+    public Builder setRequestOptions(RequestOptions requestOptions) {
+      this.requestOptions = requestOptions;
+      return this;
+    }
+
+    public Builder setReadOptions(ReadOption... readOptions) {
+      this.readOptions = readOptions != null ? Arrays.asList(readOptions) : Collections.emptyList();
+      return this;
+    }
+
+    public Builder setReadOptions(List<ReadOption> readOptions) {
+      this.readOptions = readOptions != null ? readOptions : Collections.emptyList();
+      return this;
+    }
+
+    public DatastoreExecutionOptions build() {
+      return new DatastoreExecutionOptions(this);
+    }
+  }
+}

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/DatastoreImpl.java

@@ -345,28 +345,17 @@ public <T> QueryResults<T> run(
     return run(toReadOptionsPb(options), query, explainOptions.toPb());
   }
 
-  /** Implements run query with request options. */
-  @Override
-  public <T> QueryResults<T> run(Query<T> query, RequestOptions requestOptions) {
-    return run(Optional.empty(), query, null, requestOptions);
-  }
-
-  /** Implements run query with request options and read options. */
-  @Override
-  public <T> QueryResults<T> run(
-      Query<T> query, RequestOptions requestOptions, ReadOption... options) {
-    return run(toReadOptionsPb(options), query, null, requestOptions);
-  }
-
-  /** Implements run query with explain options, request options and read options. */
+  /** Implements run query with execution options. */
   @Override
   @BetaApi
-  public <T> QueryResults<T> run(
-      Query<T> query,
-      com.google.cloud.datastore.models.ExplainOptions explainOptions,
-      RequestOptions requestOptions,
-      ReadOption... options) {
-    return run(toReadOptionsPb(options), query, explainOptions.toPb(), requestOptions);
+  public <T> QueryResults<T> run(Query<T> query, DatastoreExecutionOptions executionOptions) {
+    com.google.cloud.datastore.models.ExplainOptions explainOptions =
+        executionOptions.getExplainOptions();
+    return run(
+        toReadOptionsPb(executionOptions.getReadOptions().toArray(new ReadOption[0])),
+        query,
+        explainOptions != null ? explainOptions.toPb() : null,
+        executionOptions.getRequestOptions());
   }
 
   @SuppressWarnings("unchecked")
@@ -396,41 +385,18 @@ public AggregationResults runAggregation(AggregationQuery query) {
     return aggregationQueryExecutor.execute(query, null);
   }
 
-  /** Implements run aggregation query with request options. */
-  @Override
-  public AggregationResults runAggregation(AggregationQuery query, RequestOptions requestOptions) {
-    return aggregationQueryExecutor.execute(query, null, requestOptions);
-  }
-
   @Override
   public AggregationResults runAggregation(AggregationQuery query, ReadOption... options) {
     return aggregationQueryExecutor.execute(query, null, options);
   }
 
-  /** Implements run aggregation query with request options and read options. */
-  @Override
-  public AggregationResults runAggregation(
-      AggregationQuery query, RequestOptions requestOptions, ReadOption... options) {
-    return aggregationQueryExecutor.execute(query, null, requestOptions, options);
-  }
-
   @Override
   @BetaApi
   public AggregationResults runAggregation(
       AggregationQuery query, com.google.cloud.datastore.models.ExplainOptions explainOptions) {
     return aggregationQueryExecutor.execute(query, explainOptions);
   }
 
-  /** Implements run aggregation query with explain options and request options. */
-  @Override
-  @BetaApi
-  public AggregationResults runAggregation(
-      AggregationQuery query,
-      com.google.cloud.datastore.models.ExplainOptions explainOptions,
-      RequestOptions requestOptions) {
-    return aggregationQueryExecutor.execute(query, explainOptions, requestOptions);
-  }
-
   @Override
   @BetaApi
   public AggregationResults runAggregation(
@@ -440,15 +406,12 @@ public AggregationResults runAggregation(
     return aggregationQueryExecutor.execute(query, explainOptions, options);
   }
 
-  /** Implements run aggregation query with explain options, request options and read options. */
+  /** Implements run aggregation query with execution options. */
   @Override
   @BetaApi
   public AggregationResults runAggregation(
-      AggregationQuery query,
-      com.google.cloud.datastore.models.ExplainOptions explainOptions,
-      RequestOptions requestOptions,
-      ReadOption... options) {
-    return aggregationQueryExecutor.execute(query, explainOptions, requestOptions, options);
+      AggregationQuery query, DatastoreExecutionOptions executionOptions) {
+    return aggregationQueryExecutor.execute(query, executionOptions);
   }
 
   RunQueryResponse runQuery(final RunQueryRequest requestPb) {

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/QueryResultsImpl.java

@@ -130,7 +130,7 @@ private void sendRequest() {
     if (explainOptions != null) {
       requestPb.setExplainOptions(explainOptions);
     }
-    if (requestOptions != null || !datastore.getOptions().getRequestTags().isEmpty()) {
+    if (requestOptions != null) {
       requestPb.setRequestOptions(
           RequestOptionsHelper.createRequestOptions(datastore.getOptions(), requestOptions));
     }

java-datastore/google-cloud-datastore/src/main/java/com/google/cloud/datastore/ReadOption.java

@@ -207,6 +207,20 @@ public static <Q extends Query<?>> QueryConfig<Q> create(
           .build();
     }
 
+    public static <Q extends Query<?>> QueryConfig<Q> createWithExecutionOptions(
+        Q query, DatastoreExecutionOptions executionOptions) {
+      if (executionOptions == null) {
+        return create(query, (com.google.datastore.v1.ExplainOptions) null);
+      }
+      return create(
+          query,
+          executionOptions.getExplainOptions() != null
+              ? executionOptions.getExplainOptions().toPb()
+              : null,
+          executionOptions.getReadOptions(),
+          executionOptions.getRequestOptions());
+    }
+
     /** Creates a new builder for {@link QueryConfig}. */
     public static <Q extends Query<?>> Builder<Q> newBuilder() {
       return new Builder<>();