Skip to content

Commit b92e492

Browse files
milaGGLmilaGGL
authored
Mila/count update proto (#6482)
* update firestore.proto and query.proto * add aggregation_result.proto
1 parent f5426a5 commit b92e492

3 files changed

Lines changed: 173 additions & 0 deletions

File tree

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// Copyright 2022 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package google.firestore.v1;
18+
19+
import "google/firestore/v1/document.proto";
20+
21+
option csharp_namespace = "Google.Cloud.Firestore.V1";
22+
option go_package = "google.golang.org/genproto/googleapis/firestore/v1;firestore";
23+
option java_multiple_files = true;
24+
option java_outer_classname = "AggregationResultProto";
25+
option java_package = "com.google.firestore.v1";
26+
option objc_class_prefix = "GCFS";
27+
option php_namespace = "Google\\Cloud\\Firestore\\V1";
28+
option ruby_package = "Google::Cloud::Firestore::V1";
29+
30+
// The result of a single bucket from a Firestore aggregation query.
31+
//
32+
// The keys of `aggregate_fields` are the same for all results in an aggregation
33+
// query, unlike document queries which can have different fields present for
34+
// each result.
35+
message AggregationResult {
36+
// The result of the aggregation functions, ex: `COUNT(*) AS total_docs`.
37+
//
38+
// The key is the [alias][google.firestore.v1.StructuredAggregationQuery.Aggregation.alias]
39+
// assigned to the aggregation function on input and the size of this map
40+
// equals the number of aggregation functions in the query.
41+
map<string, Value> aggregate_fields = 2;
42+
}

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

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ package google.firestore.v1;
1919
import "google/api/annotations.proto";
2020
import "google/api/client.proto";
2121
import "google/api/field_behavior.proto";
22+
import "google/firestore/v1/aggregation_result.proto";
2223
import "google/firestore/v1/common.proto";
2324
import "google/firestore/v1/document.proto";
2425
import "google/firestore/v1/query.proto";
@@ -133,6 +134,29 @@ service Firestore {
133134
};
134135
}
135136

137+
// Runs an aggregation query.
138+
//
139+
// Rather than producing [Document][google.firestore.v1.Document] results like [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery],
140+
// this API allows running an aggregation to produce a series of
141+
// [AggregationResult][google.firestore.v1.AggregationResult] server-side.
142+
//
143+
// High-Level Example:
144+
//
145+
// ```
146+
// -- Return the number of documents in table given a filter.
147+
// SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
148+
// ```
149+
rpc RunAggregationQuery(RunAggregationQueryRequest) returns (stream RunAggregationQueryResponse) {
150+
option (google.api.http) = {
151+
post: "/v1/{parent=projects/*/databases/*/documents}:runAggregationQuery"
152+
body: "*"
153+
additional_bindings {
154+
post: "/v1/{parent=projects/*/databases/*/documents/*/**}:runAggregationQuery"
155+
body: "*"
156+
}
157+
};
158+
}
159+
136160
// Partitions a query by returning partition cursors that can be used to run
137161
// the query in parallel. The returned partition cursors are split points that
138162
// can be used by RunQuery as starting/end points for the query results.
@@ -522,6 +546,62 @@ message RunQueryResponse {
522546
int32 skipped_results = 4;
523547
}
524548

549+
// The request for [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
550+
message RunAggregationQueryRequest {
551+
// Required. The parent resource name. In the format:
552+
// `projects/{project_id}/databases/{database_id}/documents` or
553+
// `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
554+
// For example:
555+
// `projects/my-project/databases/my-database/documents` or
556+
// `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
557+
string parent = 1 [(google.api.field_behavior) = REQUIRED];
558+
559+
// The query to run.
560+
oneof query_type {
561+
// An aggregation query.
562+
StructuredAggregationQuery structured_aggregation_query = 2;
563+
}
564+
565+
// The consistency mode for the query, defaults to strong consistency.
566+
oneof consistency_selector {
567+
// Run the aggregation within an already active transaction.
568+
//
569+
// The value here is the opaque transaction ID to execute the query in.
570+
bytes transaction = 4;
571+
572+
// Starts a new transaction as part of the query, defaulting to read-only.
573+
//
574+
// The new transaction ID will be returned as the first response in the
575+
// stream.
576+
TransactionOptions new_transaction = 5;
577+
578+
// Executes the query at the given timestamp.
579+
//
580+
// Requires:
581+
//
582+
// * Cannot be more than 270 seconds in the past.
583+
google.protobuf.Timestamp read_time = 6;
584+
}
585+
}
586+
587+
// The response for [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
588+
message RunAggregationQueryResponse {
589+
// A single aggregation result.
590+
//
591+
// Not present when reporting partial progress or when the query produced
592+
// zero results.
593+
AggregationResult result = 1;
594+
595+
// The transaction that was started as part of this request.
596+
//
597+
// Only present on the first response when the request requested to start
598+
// a new transaction.
599+
bytes transaction = 2;
600+
601+
// The time at which the aggregate value is valid for.
602+
google.protobuf.Timestamp read_time = 3;
603+
}
604+
525605
// The request for [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].
526606
message PartitionQueryRequest {
527607
// Required. The parent resource name. In the format:

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

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,57 @@ message StructuredQuery {
287287
google.protobuf.Int32Value limit = 5;
288288
}
289289

290+
message StructuredAggregationQuery {
291+
// Defines a aggregation that produces a single result.
292+
message Aggregation {
293+
// Count of documents that match the query.
294+
//
295+
// The `COUNT(*)` aggregation function operates on the entire document
296+
// so it does not require a field reference.
297+
message Count {
298+
// Optional. Optional constraint on the maximum number of documents to count.
299+
//
300+
// This provides a way to set an upper bound on the number of documents
301+
// to scan, limiting latency and cost.
302+
//
303+
// High-Level Example:
304+
//
305+
// ```
306+
// SELECT COUNT_UP_TO(1000) FROM ( SELECT * FROM k );
307+
// ```
308+
//
309+
// Requires:
310+
//
311+
// * Must be greater than zero when present.
312+
int32 up_to = 1;
313+
}
314+
315+
// The type of aggregation to perform, required.
316+
oneof operator {
317+
// Count aggregator.
318+
Count count = 1;
319+
}
320+
321+
// Required. The name of the field to store the result of the aggregation into.
322+
//
323+
// Requires:
324+
//
325+
// * Must be present.
326+
// * Must be unique across all aggregation aliases.
327+
// * Conform to existing [document field name][google.firestore.v1.Document.fields] limitations.
328+
string alias = 7;
329+
}
330+
331+
// The base query to aggregate over.
332+
oneof query_type {
333+
// Nested structured query.
334+
StructuredQuery structured_query = 1;
335+
}
336+
337+
// Optional. Series of aggregations to apply on top of the `structured_query`.
338+
repeated Aggregation aggregations = 3;
339+
}
340+
290341
// A position in a query result set.
291342
message Cursor {
292343
// The values that represent a position, in the order they appear in

0 commit comments

Comments
 (0)