docs: improve query API documentation (#430)

gcf-owl-bot[bot] · web-flow · commit 915daf5443c7 · 2023-03-24T07:25:58.000-07:00
* 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>
diff --git a/google/cloud/datastore_v1/types/entity.py b/google/cloud/datastore_v1/types/entity.py
@@ -373,8 +373,8 @@ class Entity(proto.Message):
             The entity's properties. 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 ``""``.
+            contexts. The map keys, represented as UTF-8, must not
+            exceed 1,500 bytes and cannot be empty.
     """
 
     key: "Key" = proto.Field(
diff --git a/google/cloud/datastore_v1/types/query.py b/google/cloud/datastore_v1/types/query.py
@@ -146,10 +146,16 @@ class Query(proto.Message):
             The order to apply to the query results (if
             empty, order is unspecified).
         distinct_on (MutableSequence[google.cloud.datastore_v1.types.PropertyReference]):
-            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).
+            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``.
         start_cursor (bytes):
             A starting point for the query results. Query cursors are
             returned in query result batches and `can only be used to
@@ -238,7 +244,7 @@ class AggregationQuery(proto.Message):
     """
 
     class Aggregation(proto.Message):
-        r"""Defines a aggregation that produces a single result.
+        r"""Defines an aggregation that produces a single result.
 
         .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
 
@@ -261,7 +267,7 @@ class Aggregation(proto.Message):
                      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 (
                      ...
                    );
@@ -274,7 +280,7 @@ class Aggregation(proto.Message):
                      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 (
                      ...
                    );
@@ -298,7 +304,7 @@ class Count(proto.Message):
                     entities to count.
 
                     This provides a way to set an upper bound on the number of
-                    entities to scan, limiting latency and cost.
+                    entities to scan, limiting latency, and cost.
 
                     Unspecified is interpreted as no bound.
 
