samples: query profile

README.md

@@ -280,6 +280,10 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-datastore/tre
 | Sum Aggregation With Order By | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/SumAggregationWithOrderBy.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/aggregation/SumAggregationWithOrderBy.java) |
 | Sum Aggregation With Property Filter | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/SumAggregationWithPropertyFilter.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/aggregation/SumAggregationWithPropertyFilter.java) |
 | Create a union between two filters | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/filters/OrFilterQuery.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/filters/OrFilterQuery.java) |
+| Query Profile Explain | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplain.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplain.java) |
+| Query Profile Explain Aggregation | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAggregation.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAggregation.java) |
+| Query Profile Explain Analyze | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAnalyze.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAnalyze.java) |
+| Query Profile Explain Analyze Aggregation | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAnalyzeAggregation.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAnalyzeAggregation.java) |
 | Task List | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/google/datastore/snippets/TaskList.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-datastore&page=editor&open_in_editor=samples/snippets/src/main/java/com/google/datastore/snippets/TaskList.java) |
 
 

samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplain.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2024 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.example.datastore.queryprofile;
+
+// [START datastore_query_explain_entity]
+
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.QueryResults;
+import com.google.cloud.datastore.models.ExplainMetrics;
+import com.google.cloud.datastore.models.ExplainOptions;
+import com.google.cloud.datastore.models.PlanSummary;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+public class QueryProfileExplain {
+  public static void invoke() throws Exception {
+    // Instantiates a client
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // Build the query
+    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();
+
+    // Set the explain options to get back *only* the plan summary
+    QueryResults<Entity> results = datastore.run(query, ExplainOptions.newBuilder().build());
+
+    // Get the explain metrics
+    Optional<ExplainMetrics> explainMetrics = results.getExplainMetrics();
+    if (!explainMetrics.isPresent()) {
+      throw new Exception("No explain metrics returned");
+    }
+    PlanSummary planSummary = explainMetrics.get().getPlanSummary();
+    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
+    System.out.println("----- Indexes Used -----");
+    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));
+  }
+}
+// [END datastore_query_explain_entity]

samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAggregation.java

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2024 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.example.datastore.queryprofile;
+
+// [START datastore_query_explain_aggregation]
+
+import static com.google.cloud.datastore.aggregation.Aggregation.count;
+
+import com.google.cloud.datastore.AggregationQuery;
+import com.google.cloud.datastore.AggregationResults;
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.StructuredQuery;
+import com.google.cloud.datastore.models.ExplainMetrics;
+import com.google.cloud.datastore.models.ExplainOptions;
+import com.google.cloud.datastore.models.PlanSummary;
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+public class QueryProfileExplainAggregation {
+  public static void invoke() throws Exception {
+    // Instantiates a client
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // Build the query
+    StructuredQuery<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();
+
+    // Build the aggregation query
+    AggregationQuery aggregationQuery =
+        Query.newAggregationQueryBuilder().over(query).addAggregation(count()).build();
+
+    // Set the explain options to get back *only* the plan summary
+    AggregationResults results =
+        datastore.runAggregation(aggregationQuery, ExplainOptions.newBuilder().build());
+
+    // Get the explain metrics
+    Optional<ExplainMetrics> explainMetrics = results.getExplainMetrics();
+    if (!explainMetrics.isPresent()) {
+      throw new Exception("No explain metrics returned");
+    }
+    PlanSummary planSummary = explainMetrics.get().getPlanSummary();
+    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
+    System.out.println("----- Indexes Used -----");
+    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));
+  }
+}
+// [END datastore_query_explain_aggregation]

samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAnalyze.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2024 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.example.datastore.queryprofile;
+
+// [START datastore_query_explain_analyze_entity]
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.QueryResults;
+import com.google.cloud.datastore.models.ExecutionStats;
+import com.google.cloud.datastore.models.ExplainMetrics;
+import com.google.cloud.datastore.models.ExplainOptions;
+import com.google.cloud.datastore.models.PlanSummary;
+import java.util.List;
+import java.util.Map;
+
+public class QueryProfileExplainAnalyze {
+  public static void invoke() throws Exception {
+    // Instantiates a client
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // Build the query
+    Query<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();
+
+    // Set explain options with analzye = true to get back the query stats, plan info, and query
+    // results
+    QueryResults<Entity> results =
+        datastore.run(query, ExplainOptions.newBuilder().setAnalyze(true).build());
+
+    // Get the result set stats
+    if (!results.getExplainMetrics().isPresent()) {
+      throw new Exception("No explain metrics returned");
+    }
+    ExplainMetrics explainMetrics = results.getExplainMetrics().get();
+
+    // Get the execution stats
+    if (!explainMetrics.getExecutionStats().isPresent()) {
+      throw new Exception("No execution stats returned");
+    }
+
+    ExecutionStats executionStats = explainMetrics.getExecutionStats().get();
+    Map<String, Object> debugStats = executionStats.getDebugStats();
+    System.out.println("----- Debug Stats -----");
+    debugStats.forEach((key, val) -> System.out.println(key + ": " + val));
+    System.out.println("----------");
+
+    long resultsReturned = executionStats.getResultsReturned();
+    System.out.println("Results returned: " + resultsReturned);
+
+    // Get the plan summary
+    PlanSummary planSummary = explainMetrics.getPlanSummary();
+    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
+    System.out.println("----- Indexes Used -----");
+    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));
+
+    if (!results.hasNext()) {
+      throw new Exception("query yielded no results");
+    }
+
+    // Get the query results
+    System.out.println("----- Query Results -----");
+    while (results.hasNext()) {
+      Entity entity = results.next();
+      System.out.printf("Entity: %s%n", entity);
+    }
+  }
+}
+// [END datastore_query_explain_analyze_entity]

samples/snippets/src/main/java/com/example/datastore/queryprofile/QueryProfileExplainAnalyzeAggregation.java

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2024 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.example.datastore.queryprofile;
+
+// [START datastore_query_explain_analyze_aggregation]
+
+import static com.google.cloud.datastore.aggregation.Aggregation.count;
+
+import com.google.cloud.datastore.AggregationQuery;
+import com.google.cloud.datastore.AggregationResult;
+import com.google.cloud.datastore.AggregationResults;
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.StructuredQuery;
+import com.google.cloud.datastore.models.ExecutionStats;
+import com.google.cloud.datastore.models.ExplainMetrics;
+import com.google.cloud.datastore.models.ExplainOptions;
+import com.google.cloud.datastore.models.PlanSummary;
+import com.google.common.collect.Iterables;
+import java.util.List;
+import java.util.Map;
+
+public class QueryProfileExplainAnalyzeAggregation {
+  public static void invoke() throws Exception {
+    // Instantiates a client
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // Build the query
+    StructuredQuery<Entity> query = Query.newEntityQueryBuilder().setKind("Task").build();
+
+    // Build the aggregation query
+    AggregationQuery aggregationQuery =
+        Query.newAggregationQueryBuilder()
+            .over(query)
+            .addAggregation(count().as("countVal"))
+            .build();
+
+    // Set the explain options with analyze = true to get back the query stats, plan info, and
+    // aggregation results
+    AggregationResults results =
+        datastore.runAggregation(
+            aggregationQuery, ExplainOptions.newBuilder().setAnalyze(true).build());
+
+    if (!results.getExplainMetrics().isPresent()) {
+      throw new Exception("No explain metrics returned");
+    }
+    ExplainMetrics explainMetrics = results.getExplainMetrics().get();
+
+    if (!explainMetrics.getExecutionStats().isPresent()) {
+      throw new Exception("No execution stats returned");
+    }
+    ExecutionStats executionStats = explainMetrics.getExecutionStats().get();
+    Map<String, Object> debugStats = executionStats.getDebugStats();
+    System.out.println("----- Debug Stats -----");
+    debugStats.forEach((key, val) -> System.out.println(key + ": " + val));
+    System.out.println("----------");
+
+    long resultsReturned = executionStats.getResultsReturned();
+    System.out.println("Results returned: " + resultsReturned);
+
+    // Get the plan summary
+    PlanSummary planSummary = explainMetrics.getPlanSummary();
+    List<Map<String, Object>> indexesUsed = planSummary.getIndexesUsed();
+    System.out.println("----- Indexes Used -----");
+    indexesUsed.forEach(map -> map.forEach((key, val) -> System.out.println(key + ": " + val)));
+
+    System.out.println("----- Aggregation Results -----");
+    AggregationResult result = Iterables.getOnlyElement(results);
+    System.out.println("Count: " + result.getLong("countVal"));
+  }
+}
+// [END datastore_query_explain_analyze_aggregation]

samples/snippets/src/test/java/com/example/datastore/AggregationQuerySampleTestIT.java → samples/snippets/src/test/java/com/example/datastore/aggregation/AggregationQuerySampleTestIT.java

@@ -14,27 +14,10 @@
  * limitations under the License.
  */
 
-package com.example.datastore;
+package com.example.datastore.aggregation;
 
 import static org.junit.Assert.assertThrows;
 
-import com.example.datastore.aggregation.AvgAggregationOnKind;
-import com.example.datastore.aggregation.AvgAggregationWithLimit;
-import com.example.datastore.aggregation.AvgAggregationWithOrderBy;
-import com.example.datastore.aggregation.AvgAggregationWithPropertyFilter;
-import com.example.datastore.aggregation.CountAggregationInTransaction;
-import com.example.datastore.aggregation.CountAggregationOnKind;
-import com.example.datastore.aggregation.CountAggregationWithGqlQuery;
-import com.example.datastore.aggregation.CountAggregationWithLimit;
-import com.example.datastore.aggregation.CountAggregationWithOrderBy;
-import com.example.datastore.aggregation.CountAggregationWithPropertyFilter;
-import com.example.datastore.aggregation.CountAggregationWithStaleRead;
-import com.example.datastore.aggregation.MultipleAggregationsInGqlQuery;
-import com.example.datastore.aggregation.MultipleAggregationsInStructuredQuery;
-import com.example.datastore.aggregation.SumAggregationOnKind;
-import com.example.datastore.aggregation.SumAggregationWithLimit;
-import com.example.datastore.aggregation.SumAggregationWithOrderBy;
-import com.example.datastore.aggregation.SumAggregationWithPropertyFilter;
 import com.google.cloud.datastore.Datastore;
 import com.google.cloud.datastore.DatastoreOptions;
 import com.google.cloud.datastore.Key;

samples/snippets/src/test/java/com/example/datastore/OrFilterQuerySampleIT.java → samples/snippets/src/test/java/com/example/datastore/filters/OrFilterQuerySampleIT.java

@@ -14,9 +14,8 @@
  * limitations under the License.
  */
 
-package com.example.datastore;
+package com.example.datastore.filters;
 
-import com.example.datastore.filters.OrFilterQuery;
 import com.google.cloud.datastore.Datastore;
 import com.google.cloud.datastore.DatastoreOptions;
 import com.google.cloud.datastore.Entity;