feat: publish proto definitions for SUM/AVG in Firestore (#746)

* feat: publish proto definitions for SUM/AVG in Firestore

PiperOrigin-RevId: 552607134

Source-Link: googleapis/googleapis@88a9a5f

Source-Link: googleapis/googleapis-gen@047d73a
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDQ3ZDczYWUyZmQ0ZTUyNmI0NzRhNjE3ZTE2ODMzOWQ2OTFiMjUxMCJ9

* 🦉 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>
Co-authored-by: Anthonios Partheniou <partheniou@google.com>

google/cloud/firestore_v1/types/common.py

@@ -116,6 +116,8 @@ class TransactionOptions(proto.Message):
     class ReadWrite(proto.Message):
         r"""Options for a transaction that can be used to read and write
         documents.
+        Firestore does not allow 3rd party auth requests to create
+        read-write. transactions.
 
         Attributes:
             retry_transaction (bytes):
@@ -137,7 +139,10 @@ class ReadOnly(proto.Message):
         Attributes:
             read_time (google.protobuf.timestamp_pb2.Timestamp):
                 Reads documents at the given time.
-                This may not be older than 60 seconds.
+                This must be a microsecond precision timestamp
+                within the past one hour, or if Point-in-Time
+                Recovery is enabled, can additionally be a whole
+                minute timestamp within the past 7 days.
 
                 This field is a member of `oneof`_ ``consistency_selector``.
         """

google/cloud/firestore_v1/types/firestore.py

@@ -93,8 +93,11 @@ class GetDocumentRequest(proto.Message):
             This field is a member of `oneof`_ ``consistency_selector``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Reads the version of the document at the
-            given time. This may not be older than 270
-            seconds.
+            given time.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
     """
@@ -186,7 +189,10 @@ class ListDocumentsRequest(proto.Message):
             This field is a member of `oneof`_ ``consistency_selector``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Perform the read at the provided time.
-            This may not be older than 270 seconds.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
         show_missing (bool):
@@ -447,7 +453,11 @@ class BatchGetDocumentsRequest(proto.Message):
             This field is a member of `oneof`_ ``consistency_selector``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Reads documents as they were at the given
-            time. This may not be older than 270 seconds.
+            time.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
     """
@@ -699,7 +709,11 @@ class RunQueryRequest(proto.Message):
             This field is a member of `oneof`_ ``consistency_selector``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Reads documents as they were at the given
-            time. This may not be older than 270 seconds.
+            time.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
     """
@@ -836,10 +850,10 @@ class RunAggregationQueryRequest(proto.Message):
             This field is a member of `oneof`_ ``consistency_selector``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Executes the query at the given timestamp.
-
-            Requires:
-
-            -  Cannot be more than 270 seconds in the past.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
     """
@@ -975,7 +989,11 @@ class PartitionQueryRequest(proto.Message):
             ``partition_count``.
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Reads documents as they were at the given
-            time. This may not be older than 270 seconds.
+            time.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
     """
@@ -1550,7 +1568,11 @@ class ListCollectionIdsRequest(proto.Message):
             [ListCollectionIdsResponse][google.firestore.v1.ListCollectionIdsResponse].
         read_time (google.protobuf.timestamp_pb2.Timestamp):
             Reads documents as they were at the given
-            time. This may not be older than 270 seconds.
+            time.
+            This must be a microsecond precision timestamp
+            within the past one hour, or if Point-in-Time
+            Recovery is enabled, can additionally be a whole
+            minute timestamp within the past 7 days.
 
             This field is a member of `oneof`_ ``consistency_selector``.
     """

google/cloud/firestore_v1/types/query.py

@@ -568,12 +568,25 @@ class StructuredAggregationQuery(proto.Message):
     class Aggregation(proto.Message):
         r"""Defines an aggregation that produces a single result.
 
+        This message has `oneof`_ fields (mutually exclusive fields).
+        For each oneof, at most one member field can be set at the same time.
+        Setting any member of the oneof automatically clears all other
+        members.
+
         .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
 
         Attributes:
             count (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Count):
                 Count aggregator.
 
+                This field is a member of `oneof`_ ``operator``.
+            sum (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Sum):
+                Sum aggregator.
+
+                This field is a member of `oneof`_ ``operator``.
+            avg (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Avg):
+                Average aggregator.
+
                 This field is a member of `oneof`_ ``operator``.
             alias (str):
                 Optional. Optional name of the field to store the result of
@@ -647,12 +660,83 @@ class Count(proto.Message):
                 message=wrappers_pb2.Int64Value,
             )
 
+        class Sum(proto.Message):
+            r"""Sum of the values of the requested field.
+
+            -  Only numeric values will be aggregated. All non-numeric values
+               including ``NULL`` are skipped.
+
+            -  If the aggregated values contain ``NaN``, returns ``NaN``.
+               Infinity math follows IEEE-754 standards.
+
+            -  If the aggregated value set is empty, returns 0.
+
+            -  Returns a 64-bit integer if all aggregated numbers are integers
+               and the sum result does not overflow. Otherwise, the result is
+               returned as a double. Note that even if all the aggregated values
+               are integers, the result is returned as a double if it cannot fit
+               within a 64-bit signed integer. When this occurs, the returned
+               value will lose precision.
+
+            -  When underflow occurs, floating-point aggregation is
+               non-deterministic. This means that running the same query
+               repeatedly without any changes to the underlying values could
+               produce slightly different results each time. In those cases,
+               values should be stored as integers over floating-point numbers.
+
+            Attributes:
+                field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
+                    The field to aggregate on.
+            """
+
+            field: "StructuredQuery.FieldReference" = proto.Field(
+                proto.MESSAGE,
+                number=1,
+                message="StructuredQuery.FieldReference",
+            )
+
+        class Avg(proto.Message):
+            r"""Average of the values of the requested field.
+
+            -  Only numeric values will be aggregated. All non-numeric values
+               including ``NULL`` are skipped.
+
+            -  If the aggregated values contain ``NaN``, returns ``NaN``.
+               Infinity math follows IEEE-754 standards.
+
+            -  If the aggregated value set is empty, returns ``NULL``.
+
+            -  Always returns the result as a double.
+
+            Attributes:
+                field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
+                    The field to aggregate on.
+            """
+
+            field: "StructuredQuery.FieldReference" = proto.Field(
+                proto.MESSAGE,
+                number=1,
+                message="StructuredQuery.FieldReference",
+            )
+
         count: "StructuredAggregationQuery.Aggregation.Count" = proto.Field(
             proto.MESSAGE,
             number=1,
             oneof="operator",
             message="StructuredAggregationQuery.Aggregation.Count",
         )
+        sum: "StructuredAggregationQuery.Aggregation.Sum" = proto.Field(
+            proto.MESSAGE,
+            number=2,
+            oneof="operator",
+            message="StructuredAggregationQuery.Aggregation.Sum",
+        )
+        avg: "StructuredAggregationQuery.Aggregation.Avg" = proto.Field(
+            proto.MESSAGE,
+            number=3,
+            oneof="operator",
+            message="StructuredAggregationQuery.Aggregation.Avg",
+        )
         alias: str = proto.Field(
             proto.STRING,
             number=7,

google/cloud/firestore_v1/types/write.py

@@ -474,16 +474,16 @@ class ExistenceFilter(proto.Message):
             longer match the target.
 
             The client can use the ``unchanged_names`` bloom filter to
-            assist with this determination.
+            assist with this determination by testing ALL the document
+            names against the filter; if the document name is NOT in the
+            filter, it means the document no longer matches the target.
         unchanged_names (google.cloud.firestore_v1.types.BloomFilter):
-            A bloom filter that contains the UTF-8 byte encodings of the
-            resource names of the documents that match
+            A bloom filter that, despite its name, contains the UTF-8
+            byte encodings of the resource names of ALL the documents
+            that match
             [target_id][google.firestore.v1.ExistenceFilter.target_id],
             in the form
-            ``projects/{project_id}/databases/{database_id}/documents/{document_path}``
-            that have NOT changed since the query results indicated by
-            the resume token or timestamp given in
-            ``Target.resume_type``.
+            ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
 
             This bloom filter may be omitted at the server's discretion,
             such as if it is deemed that the client will not make use of