Mila/count update proto

packages/firestore/src/protos/google/firestore/v1/aggregation_result.proto

@@ -0,0 +1,42 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.firestore.v1;
+
+import "google/firestore/v1/document.proto";
+
+option csharp_namespace = "Google.Cloud.Firestore.V1";
+option go_package = "google.golang.org/genproto/googleapis/firestore/v1;firestore";
+option java_multiple_files = true;
+option java_outer_classname = "AggregationResultProto";
+option java_package = "com.google.firestore.v1";
+option objc_class_prefix = "GCFS";
+option php_namespace = "Google\\Cloud\\Firestore\\V1";
+option ruby_package = "Google::Cloud::Firestore::V1";
+
+// The result of a single bucket from a Firestore aggregation query.
+//
+// The keys of `aggregate_fields` are the same for all results in an aggregation
+// query, unlike document queries which can have different fields present for
+// each result.
+message AggregationResult {
+  // The result of the aggregation functions, ex: `COUNT(*) AS total_docs`.
+  //
+  // The key is the [alias][google.firestore.v1.StructuredAggregationQuery.Aggregation.alias]
+  // assigned to the aggregation function on input and the size of this map
+  // equals the number of aggregation functions in the query.
+  map<string, Value> aggregate_fields = 2;
+}

packages/firestore/src/protos/google/firestore/v1/firestore.proto

@@ -19,6 +19,7 @@ package google.firestore.v1;
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
+import "google/firestore/v1/aggregation_result.proto";
 import "google/firestore/v1/common.proto";
 import "google/firestore/v1/document.proto";
 import "google/firestore/v1/query.proto";
@@ -133,6 +134,28 @@ service Firestore {
     };
   }
 
+  // Runs an aggregation query.
+  //
+  // Rather than producing [Document][google.firestore.v1.Document] results like [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery],
+  // this API allows running an aggregation to produce a series of
+  // [AggregationResult][google.firestore.v1.AggregationResult] server-side.
+  //
+  // High-Level Example:
+  //
+  // ```
+  // -- Return the number of documents in table given a filter.
+  // SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
+  // ```
+  rpc RunAggregationQuery(RunAggregationQueryRequest) returns (stream RunAggregationQueryResponse) {
+    option (google.api.http) = {
+      post: "/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery"
+      body: "*"
+      additional_bindings {
+        post: "/v1/{parent=projects/*/databases/*/documents/*/**}:runAggregationQuery"
+        body: "*"
+      }
+    };
+  }
   // Partitions a query by returning partition cursors that can be used to run
   // the query in parallel. The returned partition cursors are split points that
   // can be used by RunQuery as starting/end points for the query results.
@@ -522,6 +545,62 @@ message RunQueryResponse {
   int32 skipped_results = 4;
 }
 
+// The request for [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
+message RunAggregationQueryRequest {
+  // Required. The parent resource name. In the format:
+  // `projects/{project_id}/databases/{database_id}/documents` or
+  // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+  // For example:
+  // `projects/my-project/databases/my-database/documents` or
+  // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
+  string parent = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // The query to run.
+  oneof query_type {
+    // An aggregation query.
+    StructuredAggregationQuery structured_aggregation_query = 2;
+  }
+
+  // The consistency mode for the query, defaults to strong consistency.
+  oneof consistency_selector {
+    // Run the aggregation within an already active transaction.
+    //
+    // The value here is the opaque transaction ID to execute the query in.
+    bytes transaction = 4;
+
+    // Starts a new transaction as part of the query, defaulting to read-only.
+    //
+    // The new transaction ID will be returned as the first response in the
+    // stream.
+    TransactionOptions new_transaction = 5;
+
+    // Executes the query at the given timestamp.
+    //
+    // Requires:
+    //
+    // * Cannot be more than 270 seconds in the past.
+    google.protobuf.Timestamp read_time = 6;
+  }
+}
+
+// The response for [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
+message RunAggregationQueryResponse {
+  // A single aggregation result.
+  //
+  // Not present when reporting partial progress or when the query produced
+  // zero results.
+  AggregationResult result = 1;
+
+  // The transaction that was started as part of this request.
+  //
+  // Only present on the first response when the request requested to start
+  // a new transaction.
+  bytes transaction = 2;
+
+  // The time at which the aggregate value is valid for.
+  google.protobuf.Timestamp read_time = 3;
+}
+
 // The request for [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].
 message PartitionQueryRequest {
   // Required. The parent resource name. In the format:

packages/firestore/src/protos/google/firestore/v1/query.proto

@@ -287,6 +287,57 @@ message StructuredQuery {
   google.protobuf.Int32Value limit = 5;
 }
 
+message StructuredAggregationQuery {
+  // Defines a aggregation that produces a single result.
+  message Aggregation {
+    // Count of documents that match the query.
+    //
+    // The `COUNT(*)` aggregation function operates on the entire document
+    // so it does not require a field reference.
+    message Count {
+      // Optional. Optional constraint on the maximum number of documents to count.
+      //
+      // This provides a way to set an upper bound on the number of documents
+      // to scan, limiting latency and cost.
+      //
+      // High-Level Example:
+      //
+      // ```
+      // SELECT COUNT_UP_TO(1000) FROM ( SELECT * FROM k );
+      // ```
+      //
+      // Requires:
+      //
+      // * Must be greater than zero when present.
+      int32 up_to = 1;
+    }
+
+    // The type of aggregation to perform, required.
+    oneof operator {
+      // Count aggregator.
+      Count count = 1;
+    }
+
+    // Required. The name of the field to store the result of the aggregation into.
+    //
+    // Requires:
+    //
+    // * Must be present.
+    // * Must be unique across all aggregation aliases.
+    // * Conform to existing [document field name][google.firestore.v1.Document.fields] limitations.
+    string alias = 7;
+  }
+
+  // The base query to aggregate over.
+  oneof query_type {
+    // Nested structured query.
+    StructuredQuery structured_query = 1;
+  }
+
+  // Optional. Series of aggregations to apply on top of the `structured_query`.
+  repeated Aggregation aggregations = 3;
+}
+
 // A position in a query result set.
 message Cursor {
   // The values that represent a position, in the order they appear in