samples: Add sample snippets for count aggregations

README.md

@@ -234,6 +234,13 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-datastore/tre
 | --------------------------- | --------------------------------- | ------ |
 | Native Image Datastore Sample | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/native-image-sample/src/main/java/com/example/datastore/NativeImageDatastoreSample.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/native-image-sample/src/main/java/com/example/datastore/NativeImageDatastoreSample.java) |
 | Quickstart Sample | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/QuickstartSample.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/QuickstartSample.java) |
+| Count Aggregation In Transaction | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationInTransaction.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/CountAggregationInTransaction.java) |
+| Count Aggregation On Kind | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationOnKind.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/CountAggregationOnKind.java) |
+| Count Aggregation With Gql Query | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithGqlQuery.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/CountAggregationWithGqlQuery.java) |
+| Count Aggregation With Limit | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithLimit.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/CountAggregationWithLimit.java) |
+| Count Aggregation With Order By | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithOrderBy.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/CountAggregationWithOrderBy.java) |
+| Count Aggregation With Property Filter | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithPropertyFilter.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/CountAggregationWithPropertyFilter.java) |
+| Count Aggregation With Stale Read | [source code](https://github.com/googleapis/java-datastore/blob/main/samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithStaleRead.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/CountAggregationWithStaleRead.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/aggregation/CountAggregationInTransaction.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2022 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.aggregation;
+
+// [START datastore_count_aggregation_query_in_transaction]
+
+import static com.google.cloud.datastore.aggregation.Aggregation.count;
+
+import com.google.cloud.datastore.AggregationQuery;
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.Datastore.TransactionCallable;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.EntityQuery;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.Query;
+import com.google.cloud.datastore.StructuredQuery.PropertyFilter;
+import com.google.common.collect.Iterables;
+
+public class CountAggregationInTransaction {
+
+  public static void invoke() {
+    // Instantiates a client.
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // The kind for the new entity.
+    String kind = "Task";
+
+    Key task1Key = datastore.newKeyFactory().setKind(kind).newKey("task1");
+    Key task2Key = datastore.newKeyFactory().setKind(kind).newKey("task2");
+
+    // Save all the tasks.
+    datastore.put(
+        Entity.newBuilder(task1Key).set("owner", "john").build(),
+        Entity.newBuilder(task2Key).set("owner", "john").build());
+
+    // Using transactions to maintain consistent application state.
+    datastore.runInTransaction(
+        (TransactionCallable<Void>)
+            transaction -> {
+              // Create a query to get the count of all tasks of owner 'John'.
+              EntityQuery tasksOfJohn =
+                  Query.newEntityQueryBuilder()
+                      .setKind(kind)
+                      .setFilter(PropertyFilter.eq("owner", "john"))
+                      .build();
+              AggregationQuery totalTasksQuery =
+                  Query.newAggregationQueryBuilder()
+                      .over(tasksOfJohn)
+                      .addAggregation(count().as("tasks_count"))
+                      .build();
+
+              // Executing aggregation query in the ongoing transaction.
+              Long tasksCount =
+                  Iterables.getOnlyElement(transaction.runAggregation(totalTasksQuery))
+                      .get("tasks_count");
+
+              if (tasksCount < 2) {
+                Key newTaskKey = datastore.newKeyFactory().setKind(kind).newKey("task3");
+                Entity newTask = Entity.newBuilder(newTaskKey).set("owner", "john").build();
+                // Inserting a new entity in the transaction.
+                transaction.put(newTask);
+              } else {
+                System.out.printf("Found existing %d tasks, rolling back", tasksCount);
+                throw new Exception("User 'John' cannot have more than 2 tasks");
+              }
+              return null;
+            });
+  }
+}
+// [END datastore_count_aggregation_query_in_transaction]

samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationOnKind.java

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2022 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.aggregation;
+
+// [START datastore_count_aggregation_query_on_kind]
+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.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.EntityQuery;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.Query;
+import com.google.common.collect.Iterables;
+
+public class CountAggregationOnKind {
+  // Instantiates a client.
+  private static final Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+  // The kind for the new entity.
+  private static final String kind = "Task";
+
+  // Setting up Tasks in database
+  private static void setUpTasks() {
+    Key task1Key = datastore.newKeyFactory().setKind(kind).newKey("task1");
+    Key task2Key = datastore.newKeyFactory().setKind(kind).newKey("task2");
+    Key task3Key = datastore.newKeyFactory().setKind(kind).newKey("task3");
+
+    // Save all the tasks.
+    datastore.put(
+        Entity.newBuilder(task1Key).set("done", true).build(),
+        Entity.newBuilder(task2Key).set("done", false).build(),
+        Entity.newBuilder(task3Key).set("done", true).build());
+  }
+
+  // Accessing aggregation result by the generated alias.
+  private static void usageWithGeneratedAlias() {
+    EntityQuery selectAllTasks = Query.newEntityQueryBuilder().setKind(kind).build();
+    // Creating an aggregation query to get the count of all tasks.
+    AggregationQuery allTasksCountQuery =
+        Query.newAggregationQueryBuilder()
+            .over(selectAllTasks)
+            .addAggregation(count())
+            .build();
+    // Executing aggregation query.
+    AggregationResult aggregationResult =
+        Iterables.getOnlyElement(datastore.runAggregation(allTasksCountQuery));
+
+    System.out.printf(
+        "Total tasks (accessible from default alias) is %d",
+        aggregationResult.get("property_1")); // 3
+  }
+
+  // Accessing aggregation result by the provided custom alias.
+  private static void usageWithCustomAlias() {
+    EntityQuery selectAllTasks = Query.newEntityQueryBuilder().setKind(kind).build();
+    // Creating an aggregation query to get the count of all tasks.
+    AggregationQuery allTasksCountQuery =
+        Query.newAggregationQueryBuilder()
+            .over(selectAllTasks)
+            // passing 'total_count' as alias in the aggregation query.
+            .addAggregation(count().as("total_count"))
+            .build();
+    // Executing aggregation query.
+    AggregationResult aggregationResult =
+        Iterables.getOnlyElement(datastore.runAggregation(allTasksCountQuery));
+
+    System.out.printf("Total tasks count is %d", aggregationResult.get("total_count")); // 3
+  }
+
+  public static void invoke() {
+    setUpTasks();
+    usageWithGeneratedAlias();
+    usageWithCustomAlias();
+  }
+}
+// [END datastore_count_aggregation_query_on_kind]

samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithGqlQuery.java

@@ -0,0 +1,87 @@
+/*
+ * Copyright 2022 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.aggregation;
+
+// [START datastore_count_aggregation_query_gql]
+import com.google.cloud.datastore.AggregationQuery;
+import com.google.cloud.datastore.AggregationResult;
+import com.google.cloud.datastore.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.GqlQuery;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.Query;
+import com.google.common.collect.Iterables;
+
+public class CountAggregationWithGqlQuery {
+
+  public static void invoke() {
+    // Instantiates a client.
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // The kind for the new entity.
+    String kind = "Task";
+
+    Key task1Key = datastore.newKeyFactory().setKind(kind).newKey("task1");
+    Key task2Key = datastore.newKeyFactory().setKind(kind).newKey("task2");
+    Key task3Key = datastore.newKeyFactory().setKind(kind).newKey("task3");
+
+    // Save all the tasks.
+    datastore.put(
+        Entity.newBuilder(task1Key).set("done", true).build(),
+        Entity.newBuilder(task2Key).set("done", false).build(),
+        Entity.newBuilder(task3Key).set("done", true).build());
+
+    // Create a GQL query to get the count of all tasks.
+    GqlQuery<?> selectAllTasks =
+        Query.newGqlQueryBuilder(
+                "AGGREGATE COUNT(*) AS total_count, COUNT_UP_TO(2) AS count_with_limit "
+                    + "OVER (SELECT * FROM Task)")
+            .setAllowLiteral(true)
+            .build();
+    // Create the aggregation query builder and set the query.
+    AggregationQuery allTasksCountQuery =
+        Query.newAggregationQueryBuilder().over(selectAllTasks).build();
+    // Executing aggregation query.
+    AggregationResult allTasksCountQueryResult =
+        Iterables.getOnlyElement(datastore.runAggregation(allTasksCountQuery));
+
+    System.out.printf(
+        "We have at least %d tasks", allTasksCountQueryResult.get("count_with_limit")); // 2
+    System.out.printf("Total tasks count is %d", allTasksCountQueryResult.get("total_count")); // 3
+
+    // Create a query to get the count of all completed tasks.
+    GqlQuery<?> completedTasks =
+        Query.newGqlQueryBuilder(
+                "AGGREGATE COUNT(*) AS total_completed_count "
+                    + "OVER (SELECT * FROM Task WHERE done = true)")
+            .setAllowLiteral(true)
+            .build();
+    // Create the aggregation query builder and set the query.
+    AggregationQuery completedTasksCountQuery =
+        Query.newAggregationQueryBuilder().over(completedTasks).build();
+
+    // Executing aggregation query.
+    AggregationResult completedTasksCountQueryResult =
+        Iterables.getOnlyElement(datastore.runAggregation(completedTasksCountQuery));
+
+    System.out.printf(
+        "Total completed tasks count is %d",
+        completedTasksCountQueryResult.get("total_completed_count")); // 2
+  }
+}
+// [END datastore_count_aggregation_query_gql]

samples/snippets/src/main/java/com/example/datastore/aggregation/CountAggregationWithLimit.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2022 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.aggregation;
+
+// [START datastore_count_aggregation_query_with_limit]
+
+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.Datastore;
+import com.google.cloud.datastore.DatastoreOptions;
+import com.google.cloud.datastore.Entity;
+import com.google.cloud.datastore.EntityQuery;
+import com.google.cloud.datastore.Key;
+import com.google.cloud.datastore.Query;
+import com.google.common.collect.Iterables;
+
+public class CountAggregationWithLimit {
+  public static void invoke() {
+    // Instantiates a client.
+    Datastore datastore = DatastoreOptions.getDefaultInstance().getService();
+
+    // The kind for the new entity.
+    String kind = "Task";
+
+    Key task1Key = datastore.newKeyFactory().setKind(kind).newKey("task1");
+    Key task2Key = datastore.newKeyFactory().setKind(kind).newKey("task2");
+    Key task3Key = datastore.newKeyFactory().setKind(kind).newKey("task3");
+
+    // Save all the tasks.
+    datastore.put(
+        Entity.newBuilder(task1Key).set("done", true).build(),
+        Entity.newBuilder(task2Key).set("done", false).build(),
+        Entity.newBuilder(task3Key).set("done", true).build());
+
+    EntityQuery selectAllTasks = Query.newEntityQueryBuilder()
+        .setKind(kind)
+        .setLimit(2)
+        .build();
+    // Creating an aggregation query to get the count of all tasks.
+    AggregationQuery allTasksCountQuery =
+        Query.newAggregationQueryBuilder()
+            .over(selectAllTasks)
+            .addAggregation(count().as("at_least"))
+            .build();
+    // Executing aggregation query.
+    AggregationResult limitQueryResult =
+        Iterables.getOnlyElement(datastore.runAggregation(allTasksCountQuery));
+
+    System.out.printf("We have at least %d tasks", limitQueryResult.get("at_least")); // 2
+  }
+}
+// [END datastore_count_aggregation_query_with_limit]