Skip to content

Commit d5c2cb1

Browse files
gcf-owl-bot[bot]gcf-owl-bot[bot]
authored
feat: add datastore aggregation query APIs (#1008)
* feat: add datastore aggregation query APIs PiperOrigin-RevId: 477890345 Source-Link: googleapis/googleapis@82bf674 Source-Link: googleapis/googleapis-gen@5fb8115 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNWZiODExNTE2MWVhMTRhNWM1NTE4ODVjNjgxYzM2MjdjMmY2NjYzMCJ9 * 🦉 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>
1 parent 2855743 commit d5c2cb1

10 files changed

+12903
-10166
lines changed

‎protos/google/datastore/v1/aggregation_result.proto

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
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.datastore.v1;
18+
19+
import "google/datastore/v1/entity.proto";
20+
import "google/datastore/v1/query.proto";
21+
import "google/protobuf/timestamp.proto";
22+
23+
option csharp_namespace = "Google.Cloud.Datastore.V1";
24+
option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
25+
option java_multiple_files = true;
26+
option java_outer_classname = "AggregationResultProto";
27+
option java_package = "com.google.datastore.v1";
28+
option php_namespace = "Google\\Cloud\\Datastore\\V1";
29+
option ruby_package = "Google::Cloud::Datastore::V1";
30+
31+
// The result of a single bucket from a Datastore aggregation query.
32+
//
33+
// The keys of `aggregate_properties` are the same for all results in an
34+
// aggregation query, unlike entity queries which can have different fields
35+
// present for each result.
36+
message AggregationResult {
37+
// The result of the aggregation functions, ex: `COUNT(*) AS total_entities`.
38+
//
39+
// The key is the [alias][google.datastore.v1.AggregationQuery.Aggregation.alias]
40+
// assigned to the aggregation function on input and the size of this map
41+
// equals the number of aggregation functions in the query.
42+
map<string, Value> aggregate_properties = 2;
43+
}
44+
45+
// A batch of aggregation results produced by an aggregation query.
46+
message AggregationResultBatch {
47+
// The aggregation results for this batch.
48+
repeated AggregationResult aggregation_results = 1;
49+
50+
// The state of the query after the current batch.
51+
// Only COUNT(*) aggregations are supported in the initial launch. Therefore,
52+
// expected result type is limited to `NO_MORE_RESULTS`.
53+
QueryResultBatch.MoreResultsType more_results = 2;
54+
55+
// Read timestamp this batch was returned from.
56+
//
57+
// In a single transaction, subsequent query result batches for the same query
58+
// can have a greater timestamp. Each batch's read timestamp
59+
// is valid for all preceding batches.
60+
google.protobuf.Timestamp read_time = 3;
61+
}

‎protos/google/datastore/v1/datastore.proto

+48
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ package google.datastore.v1;
1919
import "google/api/annotations.proto";
2020
import "google/api/client.proto";
2121
import "google/api/field_behavior.proto";
22+
import "google/datastore/v1/aggregation_result.proto";
2223
import "google/datastore/v1/entity.proto";
2324
import "google/datastore/v1/query.proto";
2425
import "google/protobuf/timestamp.proto";
@@ -61,6 +62,14 @@ service Datastore {
6162
};
6263
}
6364

65+
// Runs an aggregation query.
66+
rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse) {
67+
option (google.api.http) = {
68+
post: "/v1/projects/{project_id}:runAggregationQuery"
69+
body: "*"
70+
};
71+
}
72+
6473
// Begins a new transaction.
6574
rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) {
6675
option (google.api.http) = {
@@ -189,6 +198,45 @@ message RunQueryResponse {
189198
Query query = 2;
190199
}
191200

201+
// The request for [Datastore.RunAggregationQuery][google.datastore.v1.Datastore.RunAggregationQuery].
202+
message RunAggregationQueryRequest {
203+
// Required. The ID of the project against which to make the request.
204+
string project_id = 8 [(google.api.field_behavior) = REQUIRED];
205+
206+
// The ID of the database against which to make the request.
207+
//
208+
// '(default)' is not allowed; please use empty string '' to refer the default
209+
// database.
210+
string database_id = 9;
211+
212+
// Entities are partitioned into subsets, identified by a partition ID.
213+
// Queries are scoped to a single partition.
214+
// This partition ID is normalized with the standard default context
215+
// partition ID.
216+
PartitionId partition_id = 2;
217+
218+
// The options for this query.
219+
ReadOptions read_options = 1;
220+
221+
// The type of query.
222+
oneof query_type {
223+
// The query to run.
224+
AggregationQuery aggregation_query = 3;
225+
226+
// The GQL query to run. This query must be an aggregation query.
227+
GqlQuery gql_query = 7;
228+
}
229+
}
230+
231+
// The response for [Datastore.RunAggregationQuery][google.datastore.v1.Datastore.RunAggregationQuery].
232+
message RunAggregationQueryResponse {
233+
// A batch of aggregation results. Always present.
234+
AggregationResultBatch batch = 1;
235+
236+
// The parsed form of the `GqlQuery` from the request, if it was set.
237+
AggregationQuery query = 2;
238+
}
239+
192240
// The request for [Datastore.BeginTransaction][google.datastore.v1.Datastore.BeginTransaction].
193241
message BeginTransactionRequest {
194242
// Required. The ID of the project against which to make the request.

‎protos/google/datastore/v1/query.proto

+87
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,93 @@ message Query {
118118
google.protobuf.Int32Value limit = 12;
119119
}
120120

121+
// Datastore query for running an aggregation over a [Query][google.datastore.v1.Query].
122+
message AggregationQuery {
123+
// Defines a aggregation that produces a single result.
124+
message Aggregation {
125+
// Count of entities that match the query.
126+
//
127+
// The `COUNT(*)` aggregation function operates on the entire entity
128+
// so it does not require a field reference.
129+
message Count {
130+
// Optional. Optional constraint on the maximum number of entities to count.
131+
//
132+
// This provides a way to set an upper bound on the number of entities
133+
// to scan, limiting latency and cost.
134+
//
135+
// Unspecified is interpreted as no bound.
136+
//
137+
// If a zero value is provided, a count result of zero should always be
138+
// expected.
139+
//
140+
// High-Level Example:
141+
//
142+
// ```
143+
// AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
144+
// ```
145+
//
146+
// Requires:
147+
//
148+
// * Must be non-negative when present.
149+
google.protobuf.Int64Value up_to = 1 [(google.api.field_behavior) = OPTIONAL];
150+
}
151+
152+
// The type of aggregation to perform, required.
153+
oneof operator {
154+
// Count aggregator.
155+
Count count = 1;
156+
}
157+
158+
// Optional. Optional name of the property to store the result of the aggregation.
159+
//
160+
// If not provided, Datastore will pick a default name following the format
161+
// `property_<incremental_id++>`. For example:
162+
//
163+
// ```
164+
// AGGREGATE
165+
// COUNT_UP_TO(1) AS count_up_to_1,
166+
// COUNT_UP_TO(2),
167+
// COUNT_UP_TO(3) AS count_up_to_3,
168+
// COUNT_UP_TO(4)
169+
// OVER (
170+
// ...
171+
// );
172+
// ```
173+
//
174+
// becomes:
175+
//
176+
// ```
177+
// AGGREGATE
178+
// COUNT_UP_TO(1) AS count_up_to_1,
179+
// COUNT_UP_TO(2) AS property_1,
180+
// COUNT_UP_TO(3) AS count_up_to_3,
181+
// COUNT_UP_TO(4) AS property_2
182+
// OVER (
183+
// ...
184+
// );
185+
// ```
186+
//
187+
// Requires:
188+
//
189+
// * Must be unique across all aggregation aliases.
190+
// * Conform to [entity property name][google.datastore.v1.Entity.properties] limitations.
191+
string alias = 7 [(google.api.field_behavior) = OPTIONAL];
192+
}
193+
194+
// The base query to aggregate over.
195+
oneof query_type {
196+
// Nested query for aggregation
197+
Query nested_query = 1;
198+
}
199+
200+
// Optional. Series of aggregations to apply over the results of the `nested_query`.
201+
//
202+
// Requires:
203+
//
204+
// * A minimum of one and maximum of five aggregations per query.
205+
repeated Aggregation aggregations = 3 [(google.api.field_behavior) = OPTIONAL];
206+
}
207+
121208
// A representation of a kind.
122209
message KindExpression {
123210
// The name of the kind.

0 commit comments

Comments
 (0)