/
query.proto
542 lines (464 loc) · 16.9 KB
/
query.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
// Copyright 2023 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.datastore.v1;
import "google/api/field_behavior.proto";
import "google/datastore/v1/entity.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";
option csharp_namespace = "Google.Cloud.Datastore.V1";
option go_package = "google.golang.org/genproto/googleapis/datastore/v1;datastore";
option java_multiple_files = true;
option java_outer_classname = "QueryProto";
option java_package = "com.google.datastore.v1";
option php_namespace = "Google\\Cloud\\Datastore\\V1";
option ruby_package = "Google::Cloud::Datastore::V1";
// The result of fetching an entity from Datastore.
message EntityResult {
// Specifies what data the 'entity' field contains.
// A `ResultType` is either implied (for example, in `LookupResponse.missing`
// from `datastore.proto`, it is always `KEY_ONLY`) or specified by context
// (for example, in message `QueryResultBatch`, field `entity_result_type`
// specifies a `ResultType` for all the values in field `entity_results`).
enum ResultType {
// Unspecified. This value is never used.
RESULT_TYPE_UNSPECIFIED = 0;
// The key and properties.
FULL = 1;
// A projected subset of properties. The entity may have no key.
PROJECTION = 2;
// Only the key.
KEY_ONLY = 3;
}
// The resulting entity.
Entity entity = 1;
// The version of the entity, a strictly positive number that monotonically
// increases with changes to the entity.
//
// This field is set for
// [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
//
// For [missing][google.datastore.v1.LookupResponse.missing] entities in
// `LookupResponse`, this is the version of the snapshot that was used to look
// up the entity, and it is always set except for eventually consistent reads.
int64 version = 4;
// The time at which the entity was created.
// This field is set for
// [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
// If this entity is missing, this field will not be set.
google.protobuf.Timestamp create_time = 6;
// The time at which the entity was last changed.
// This field is set for
// [`FULL`][google.datastore.v1.EntityResult.ResultType.FULL] entity results.
// If this entity is missing, this field will not be set.
google.protobuf.Timestamp update_time = 5;
// A cursor that points to the position after the result entity.
// Set only when the `EntityResult` is part of a `QueryResultBatch` message.
bytes cursor = 3;
}
// A query for entities.
message Query {
// The projection to return. Defaults to returning all properties.
repeated Projection projection = 2;
// The kinds to query (if empty, returns entities of all kinds).
// Currently at most 1 kind may be specified.
repeated KindExpression kind = 3;
// The filter to apply.
Filter filter = 4;
// The order to apply to the query results (if empty, order is unspecified).
repeated PropertyOrder order = 5;
// The properties to make distinct. The query results will contain the first
// result for each distinct combination of values for the given properties
// (if empty, all results are returned).
//
// Requires:
//
// * If `order` is specified, the set of distinct on properties must appear
// before the non-distinct on properties in `order`.
repeated PropertyReference distinct_on = 6;
// A starting point for the query results. Query cursors are
// returned in query result batches and
// [can only be used to continue the same
// query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets).
bytes start_cursor = 7;
// An ending point for the query results. Query cursors are
// returned in query result batches and
// [can only be used to limit the same
// query](https://cloud.google.com/datastore/docs/concepts/queries#cursors_limits_and_offsets).
bytes end_cursor = 8;
// The number of results to skip. Applies before limit, but after all other
// constraints. Optional. Must be >= 0 if specified.
int32 offset = 10;
// The maximum number of results to return. Applies after all other
// constraints. Optional.
// Unspecified is interpreted as no limit.
// Must be >= 0 if specified.
google.protobuf.Int32Value limit = 12;
}
// Datastore query for running an aggregation over a
// [Query][google.datastore.v1.Query].
message AggregationQuery {
// Defines an aggregation that produces a single result.
message Aggregation {
// Count of entities that match the query.
//
// The `COUNT(*)` aggregation function operates on the entire entity
// so it does not require a field reference.
message Count {
// Optional. Optional constraint on the maximum number of entities to
// count.
//
// This provides a way to set an upper bound on the number of entities
// to scan, limiting latency, and cost.
//
// Unspecified is interpreted as no bound.
//
// If a zero value is provided, a count result of zero should always be
// expected.
//
// High-Level Example:
//
// ```
// AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
// ```
//
// Requires:
//
// * Must be non-negative when present.
google.protobuf.Int64Value up_to = 1
[(google.api.field_behavior) = OPTIONAL];
}
// Sum of the values of the requested property.
//
// * 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 property to aggregate on.
PropertyReference property = 1;
}
// Average of the values of the requested property.
//
// * 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 property to aggregate on.
PropertyReference property = 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 property to store the result of the
// aggregation.
//
// If not provided, Datastore will pick a default name following the format
// `property_<incremental_id++>`. For example:
//
// ```
// AGGREGATE
// COUNT_UP_TO(1) AS count_up_to_1,
// COUNT_UP_TO(2),
// COUNT_UP_TO(3) AS count_up_to_3,
// COUNT(*)
// OVER (
// ...
// );
// ```
//
// becomes:
//
// ```
// AGGREGATE
// COUNT_UP_TO(1) AS count_up_to_1,
// COUNT_UP_TO(2) AS property_1,
// COUNT_UP_TO(3) AS count_up_to_3,
// COUNT(*) AS property_2
// OVER (
// ...
// );
// ```
//
// Requires:
//
// * Must be unique across all aggregation aliases.
// * Conform to [entity property
// name][google.datastore.v1.Entity.properties] limitations.
string alias = 7 [(google.api.field_behavior) = OPTIONAL];
}
// The base query to aggregate over.
oneof query_type {
// Nested query for aggregation
Query nested_query = 1;
}
// Optional. Series of aggregations to apply over the results of the
// `nested_query`.
//
// Requires:
//
// * A minimum of one and maximum of five aggregations per query.
repeated Aggregation aggregations = 3
[(google.api.field_behavior) = OPTIONAL];
}
// A representation of a kind.
message KindExpression {
// The name of the kind.
string name = 1;
}
// A reference to a property relative to the kind expressions.
message PropertyReference {
// A reference to a property.
//
// Requires:
//
// * MUST be a dot-delimited (`.`) string of segments, where each segment
// conforms to [entity property name][google.datastore.v1.Entity.properties]
// limitations.
string name = 2;
}
// A representation of a property in a projection.
message Projection {
// The property to project.
PropertyReference property = 1;
}
// The desired order for a specific property.
message PropertyOrder {
// The sort direction.
enum Direction {
// Unspecified. This value must not be used.
DIRECTION_UNSPECIFIED = 0;
// Ascending.
ASCENDING = 1;
// Descending.
DESCENDING = 2;
}
// The property to order by.
PropertyReference property = 1;
// The direction to order by. Defaults to `ASCENDING`.
Direction direction = 2;
}
// A holder for any type of filter.
message Filter {
// The type of filter.
oneof filter_type {
// A composite filter.
CompositeFilter composite_filter = 1;
// A filter on a property.
PropertyFilter property_filter = 2;
}
}
// A filter that merges multiple other filters using the given operator.
message CompositeFilter {
// A composite filter operator.
enum Operator {
// Unspecified. This value must not be used.
OPERATOR_UNSPECIFIED = 0;
// The results are required to satisfy each of the combined filters.
AND = 1;
// Documents are required to satisfy at least one of the combined filters.
OR = 2;
}
// The operator for combining multiple filters.
Operator op = 1;
// The list of filters to combine.
//
// Requires:
//
// * At least one filter is present.
repeated Filter filters = 2;
}
// A filter on a specific property.
message PropertyFilter {
// A property filter operator.
enum Operator {
// Unspecified. This value must not be used.
OPERATOR_UNSPECIFIED = 0;
// The given `property` is less than the given `value`.
//
// Requires:
//
// * That `property` comes first in `order_by`.
LESS_THAN = 1;
// The given `property` is less than or equal to the given `value`.
//
// Requires:
//
// * That `property` comes first in `order_by`.
LESS_THAN_OR_EQUAL = 2;
// The given `property` is greater than the given `value`.
//
// Requires:
//
// * That `property` comes first in `order_by`.
GREATER_THAN = 3;
// The given `property` is greater than or equal to the given `value`.
//
// Requires:
//
// * That `property` comes first in `order_by`.
GREATER_THAN_OR_EQUAL = 4;
// The given `property` is equal to the given `value`.
EQUAL = 5;
// The given `property` is equal to at least one value in the given array.
//
// Requires:
//
// * That `value` is a non-empty `ArrayValue`, subject to disjunction
// limits.
// * No `NOT_IN` is in the same query.
IN = 6;
// The given `property` is not equal to the given `value`.
//
// Requires:
//
// * No other `NOT_EQUAL` or `NOT_IN` is in the same query.
// * That `property` comes first in the `order_by`.
NOT_EQUAL = 9;
// Limit the result set to the given entity and its descendants.
//
// Requires:
//
// * That `value` is an entity key.
// * All evaluated disjunctions must have the same `HAS_ANCESTOR` filter.
HAS_ANCESTOR = 11;
// The value of the `property` is not in the given array.
//
// Requires:
//
// * That `value` is a non-empty `ArrayValue` with at most 10 values.
// * No other `OR`, `IN`, `NOT_IN`, `NOT_EQUAL` is in the same query.
// * That `field` comes first in the `order_by`.
NOT_IN = 13;
}
// The property to filter by.
PropertyReference property = 1;
// The operator to filter by.
Operator op = 2;
// The value to compare the property to.
Value value = 3;
}
// A [GQL
// query](https://cloud.google.com/datastore/docs/apis/gql/gql_reference).
message GqlQuery {
// A string of the format described
// [here](https://cloud.google.com/datastore/docs/apis/gql/gql_reference).
string query_string = 1;
// When false, the query string must not contain any literals and instead must
// bind all values. For example,
// `SELECT * FROM Kind WHERE a = 'string literal'` is not allowed, while
// `SELECT * FROM Kind WHERE a = @value` is.
bool allow_literals = 2;
// For each non-reserved named binding site in the query string, there must be
// a named parameter with that name, but not necessarily the inverse.
//
// Key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex
// `__.*__`, and must not be `""`.
map<string, GqlQueryParameter> named_bindings = 5;
// Numbered binding site @1 references the first numbered parameter,
// effectively using 1-based indexing, rather than the usual 0.
//
// For each binding site numbered i in `query_string`, there must be an i-th
// numbered parameter. The inverse must also be true.
repeated GqlQueryParameter positional_bindings = 4;
}
// A binding parameter for a GQL query.
message GqlQueryParameter {
// The type of parameter.
oneof parameter_type {
// A value parameter.
Value value = 2;
// A query cursor. Query cursors are returned in query
// result batches.
bytes cursor = 3;
}
}
// A batch of results produced by a query.
message QueryResultBatch {
// The possible values for the `more_results` field.
enum MoreResultsType {
// Unspecified. This value is never used.
MORE_RESULTS_TYPE_UNSPECIFIED = 0;
// There may be additional batches to fetch from this query.
NOT_FINISHED = 1;
// The query is finished, but there may be more results after the limit.
MORE_RESULTS_AFTER_LIMIT = 2;
// The query is finished, but there may be more results after the end
// cursor.
MORE_RESULTS_AFTER_CURSOR = 4;
// The query is finished, and there are no more results.
NO_MORE_RESULTS = 3;
}
// The number of results skipped, typically because of an offset.
int32 skipped_results = 6;
// A cursor that points to the position after the last skipped result.
// Will be set when `skipped_results` != 0.
bytes skipped_cursor = 3;
// The result type for every entity in `entity_results`.
EntityResult.ResultType entity_result_type = 1;
// The results for this batch.
repeated EntityResult entity_results = 2;
// A cursor that points to the position after the last result in the batch.
bytes end_cursor = 4;
// The state of the query after the current batch.
MoreResultsType more_results = 5;
// The version number of the snapshot this batch was returned from.
// This applies to the range of results from the query's `start_cursor` (or
// the beginning of the query if no cursor was given) to this batch's
// `end_cursor` (not the query's `end_cursor`).
//
// In a single transaction, subsequent query result batches for the same query
// can have a greater snapshot version number. Each batch's snapshot version
// is valid for all preceding batches.
// The value will be zero for eventually consistent queries.
int64 snapshot_version = 7;
// Read timestamp this batch was returned from.
// This applies to the range of results from the query's `start_cursor` (or
// the beginning of the query if no cursor was given) to this batch's
// `end_cursor` (not the query's `end_cursor`).
//
// In a single transaction, subsequent query result batches for the same query
// can have a greater timestamp. Each batch's read timestamp
// is valid for all preceding batches.
// This value will not be set for eventually consistent queries in Cloud
// Datastore.
google.protobuf.Timestamp read_time = 8;
}