feat: Add SUM/AVG aggregation query support in the preview branch and improve query API documentation (#1094)

* feat: Add SUM/AVG aggregation query support in the preview branch and improve query API documentation

PiperOrigin-RevId: 518940761

Source-Link: googleapis/googleapis@b1efb32

Source-Link: googleapis/googleapis-gen@f7c2054
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZjdjMjA1NDE0YTVjNjU3OTQzOGI1ODA2ZDNkYzVmMjBkMDllZjgzYyJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

---------

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

Author: gcf-owl-bot[bot]

protos/google/datastore/v1/aggregation_result.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

protos/google/datastore/v1/datastore.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

protos/google/datastore/v1/entity.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -213,7 +213,7 @@ message Entity {
   // The map's keys are property names.
   // A property name matching regex `__.*__` is reserved.
   // A reserved property name is forbidden in certain documented contexts.
-  // The name must not contain more than 500 characters.
-  // The name cannot be `""`.
+  // The map keys, represented as UTF-8, must not exceed 1,500 bytes and cannot
+  // be empty.
   map<string, Value> properties = 3;
 }

protos/google/datastore/v1/query.proto

@@ -1,4 +1,4 @@
-// Copyright 2022 Google LLC
+// Copyright 2023 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -99,6 +99,11 @@ message Query {
   // The properties to make distinct. The query results will contain the first
   // result for each distinct combination of values for the given properties
   // (if empty, all results are returned).
+  //
+  // Requires:
+  //
+  // * If `order` is specified, the set of distinct on properties must appear
+  // before the non-distinct on properties in `order`.
   repeated PropertyReference distinct_on = 6;
 
   // A starting point for the query results. Query cursors are
@@ -127,7 +132,7 @@ message Query {
 // Datastore query for running an aggregation over a
 // [Query][google.datastore.v1.Query].
 message AggregationQuery {
-  // Defines a aggregation that produces a single result.
+  // Defines an aggregation that produces a single result.
   message Aggregation {
     // Count of entities that match the query.
     //
@@ -138,7 +143,7 @@ message AggregationQuery {
       // count.
       //
       // This provides a way to set an upper bound on the number of entities
-      // to scan, limiting latency and cost.
+      // to scan, limiting latency, and cost.
       //
       // Unspecified is interpreted as no bound.
       //
@@ -175,7 +180,7 @@ message AggregationQuery {
     //   COUNT_UP_TO(1) AS count_up_to_1,
     //   COUNT_UP_TO(2),
     //   COUNT_UP_TO(3) AS count_up_to_3,
-    //   COUNT_UP_TO(4)
+    //   COUNT(*)
     // OVER (
     //   ...
     // );
@@ -188,7 +193,7 @@ message AggregationQuery {
     //   COUNT_UP_TO(1) AS count_up_to_1,
     //   COUNT_UP_TO(2) AS property_1,
     //   COUNT_UP_TO(3) AS count_up_to_3,
-    //   COUNT_UP_TO(4) AS property_2
+    //   COUNT(*) AS property_2
     // OVER (
     //   ...
     // );