feat: publish proto definitions for SUM/AVG in Firestore

PiperOrigin-RevId: 552607134

google/firestore/v1/common.proto

@@ -57,6 +57,9 @@ message Precondition {
 // Options for creating a new transaction.
 message TransactionOptions {
   // 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.
   message ReadWrite {
     // An optional transaction to retry.
     bytes retry_transaction = 1;
@@ -68,7 +71,10 @@ message TransactionOptions {
     // consistency.
     oneof consistency_selector {
       // 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.
       google.protobuf.Timestamp read_time = 2;
     }
   }

google/firestore/v1/firestore.proto

@@ -256,7 +256,10 @@ message GetDocumentRequest {
     bytes transaction = 3;
 
     // Reads the version of the document at the given 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.
     google.protobuf.Timestamp read_time = 5;
   }
 }
@@ -316,7 +319,9 @@ message ListDocumentsRequest {
 
     // 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.
     google.protobuf.Timestamp read_time = 10;
   }
 
@@ -442,7 +447,10 @@ message BatchGetDocumentsRequest {
     TransactionOptions new_transaction = 5;
 
     // Reads documents as they were at the given 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.
     google.protobuf.Timestamp read_time = 7;
   }
 }
@@ -562,7 +570,10 @@ message RunQueryRequest {
     TransactionOptions new_transaction = 6;
 
     // Reads documents as they were at the given 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.
     google.protobuf.Timestamp read_time = 7;
   }
 }
@@ -635,9 +646,9 @@ message RunAggregationQueryRequest {
 
     // 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.
     google.protobuf.Timestamp read_time = 6;
   }
 }
@@ -723,7 +734,10 @@ message PartitionQueryRequest {
   // If not set, defaults to strong consistency.
   oneof consistency_selector {
     // Reads documents as they were at the given 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.
     google.protobuf.Timestamp read_time = 6;
   }
 }
@@ -912,8 +926,9 @@ message Target {
 
   // When to start listening.
   //
-  // If not specified, all matching Documents are returned before any
-  // subsequent changes.
+  // If specified, only the matching Documents that have been updated AFTER the
+  // `resume_token` or `read_time` will be returned. Otherwise, all matching
+  // Documents are returned before any subsequent changes.
   oneof resume_type {
     // A resume token from a prior
     // [TargetChange][google.firestore.v1.TargetChange] for an identical target.
@@ -1026,7 +1041,10 @@ message ListCollectionIdsRequest {
   // If not set, defaults to strong consistency.
   oneof consistency_selector {
     // Reads documents as they were at the given 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.
     google.protobuf.Timestamp read_time = 4;
   }
 }

google/firestore/v1/query.proto

@@ -384,10 +384,58 @@ message StructuredAggregationQuery {
           [(google.api.field_behavior) = OPTIONAL];
     }
 
+    // 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.
+    message Sum {
+      // The field to aggregate on.
+      StructuredQuery.FieldReference field = 1;
+    }
+
+    // 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.
+    message Avg {
+      // The field to aggregate on.
+      StructuredQuery.FieldReference field = 1;
+    }
+
     // The type of aggregation to perform, required.
     oneof operator {
       // Count aggregator.
       Count count = 1;
+
+      // Sum aggregator.
+      Sum sum = 2;
+
+      // Average aggregator.
+      Avg avg = 3;
     }
 
     // Optional. Optional name of the field to store the result of the

google/firestore/v1/write.proto

@@ -266,15 +266,15 @@ message ExistenceFilter {
   // client must manually determine which documents no longer match the target.
   //
   // The client can use the `unchanged_names` bloom filter to assist with
-  // this determination.
+  // 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.
   int32 count = 2;
 
-  // 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 it or if it is too