diff --git a/google/firestore/v1/common.proto b/google/firestore/v1/common.proto index 29cde08d34498..2a562aa6ecb6a 100644 --- a/google/firestore/v1/common.proto +++ b/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; } } diff --git a/google/firestore/v1/firestore.proto b/google/firestore/v1/firestore.proto index c6f7b921c8657..a4447d1676a83 100644 --- a/google/firestore/v1/firestore.proto +++ b/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; } } diff --git a/google/firestore/v1/query.proto b/google/firestore/v1/query.proto index 8f89c48d971cd..4a4919634ac4a 100644 --- a/google/firestore/v1/query.proto +++ b/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 diff --git a/google/firestore/v1/write.proto b/google/firestore/v1/write.proto index 90db49f52da92..4b46595ce4983 100644 --- a/google/firestore/v1/write.proto +++ b/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