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>

Author: gcf-owl-bot[bot]

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