/
query.proto
567 lines (497 loc) · 17.5 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
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
// 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.firestore.v1;
import "google/api/field_behavior.proto";
import "google/firestore/v1/document.proto";
import "google/protobuf/wrappers.proto";
option csharp_namespace = "Google.Cloud.Firestore.V1";
option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
option java_multiple_files = true;
option java_outer_classname = "QueryProto";
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";
// A Firestore query.
//
// The query stages are executed in the following order:
// 1. from
// 2. where
// 3. select
// 4. order_by + start_at + end_at
// 5. offset
// 6. limit
message StructuredQuery {
// A selection of a collection, such as `messages as m1`.
message CollectionSelector {
// The collection ID.
// When set, selects only collections with this ID.
string collection_id = 2;
// When false, selects only collections that are immediate children of
// the `parent` specified in the containing `RunQueryRequest`.
// When true, selects all descendant collections.
bool all_descendants = 3;
}
// A filter.
message Filter {
// The type of filter.
oneof filter_type {
// A composite filter.
CompositeFilter composite_filter = 1;
// A filter on a document field.
FieldFilter field_filter = 2;
// A filter that takes exactly one argument.
UnaryFilter unary_filter = 3;
}
}
// 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;
// Documents are required to satisfy all 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 field.
message FieldFilter {
// A field filter operator.
enum Operator {
// Unspecified. This value must not be used.
OPERATOR_UNSPECIFIED = 0;
// The given `field` is less than the given `value`.
//
// Requires:
//
// * That `field` come first in `order_by`.
LESS_THAN = 1;
// The given `field` is less than or equal to the given `value`.
//
// Requires:
//
// * That `field` come first in `order_by`.
LESS_THAN_OR_EQUAL = 2;
// The given `field` is greater than the given `value`.
//
// Requires:
//
// * That `field` come first in `order_by`.
GREATER_THAN = 3;
// The given `field` is greater than or equal to the given `value`.
//
// Requires:
//
// * That `field` come first in `order_by`.
GREATER_THAN_OR_EQUAL = 4;
// The given `field` is equal to the given `value`.
EQUAL = 5;
// The given `field` is not equal to the given `value`.
//
// Requires:
//
// * No other `NOT_EQUAL`, `NOT_IN`, `IS_NOT_NULL`, or `IS_NOT_NAN`.
// * That `field` comes first in the `order_by`.
NOT_EQUAL = 6;
// The given `field` is an array that contains the given `value`.
ARRAY_CONTAINS = 7;
// The given `field` 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` filters in the same query.
IN = 8;
// The given `field` is an array that contains any of the values in the
// given array.
//
// Requires:
//
// * That `value` is a non-empty `ArrayValue`, subject to disjunction
// limits.
// * No other `ARRAY_CONTAINS_ANY` filters within the same disjunction.
// * No `NOT_IN` filters in the same query.
ARRAY_CONTAINS_ANY = 9;
// The value of the `field` is not in the given array.
//
// Requires:
//
// * That `value` is a non-empty `ArrayValue` with at most 10 values.
// * No other `OR`, `IN`, `ARRAY_CONTAINS_ANY`, `NOT_IN`, `NOT_EQUAL`,
// `IS_NOT_NULL`, or `IS_NOT_NAN`.
// * That `field` comes first in the `order_by`.
NOT_IN = 10;
}
// The field to filter by.
FieldReference field = 1;
// The operator to filter by.
Operator op = 2;
// The value to compare to.
Value value = 3;
}
// A filter with a single operand.
message UnaryFilter {
// A unary operator.
enum Operator {
// Unspecified. This value must not be used.
OPERATOR_UNSPECIFIED = 0;
// The given `field` is equal to `NaN`.
IS_NAN = 2;
// The given `field` is equal to `NULL`.
IS_NULL = 3;
// The given `field` is not equal to `NaN`.
//
// Requires:
//
// * No other `NOT_EQUAL`, `NOT_IN`, `IS_NOT_NULL`, or `IS_NOT_NAN`.
// * That `field` comes first in the `order_by`.
IS_NOT_NAN = 4;
// The given `field` is not equal to `NULL`.
//
// Requires:
//
// * A single `NOT_EQUAL`, `NOT_IN`, `IS_NOT_NULL`, or `IS_NOT_NAN`.
// * That `field` comes first in the `order_by`.
IS_NOT_NULL = 5;
}
// The unary operator to apply.
Operator op = 1;
// The argument to the filter.
oneof operand_type {
// The field to which to apply the operator.
FieldReference field = 2;
}
}
// An order on a field.
message Order {
// The field to order by.
FieldReference field = 1;
// The direction to order by. Defaults to `ASCENDING`.
Direction direction = 2;
}
// A sort direction.
enum Direction {
// Unspecified.
DIRECTION_UNSPECIFIED = 0;
// Ascending.
ASCENDING = 1;
// Descending.
DESCENDING = 2;
}
// A reference to a field in a document, ex: `stats.operations`.
message FieldReference {
// A reference to a field in a document.
//
// Requires:
//
// * MUST be a dot-delimited (`.`) string of segments, where each segment
// conforms to [document field name][google.firestore.v1.Document.fields]
// limitations.
string field_path = 2;
}
// The projection of document's fields to return.
message Projection {
// The fields to return.
//
// If empty, all fields are returned. To only return the name
// of the document, use `['__name__']`.
repeated FieldReference fields = 2;
}
// Nearest Neighbors search config.
message FindNearest {
// The distance measure to use when comparing vectors.
enum DistanceMeasure {
// Should not be set.
DISTANCE_MEASURE_UNSPECIFIED = 0;
// Measures the EUCLIDEAN distance between the vectors. See
// [Euclidean](https://en.wikipedia.org/wiki/Euclidean_distance) to learn
// more
EUCLIDEAN = 1;
// Compares vectors based on the angle between them, which allows you to
// measure similarity that isn't based on the vectors magnitude.
// We recommend using DOT_PRODUCT with unit normalized vectors instead of
// COSINE distance, which is mathematically equivalent with better
// performance. See [Cosine
// Similarity](https://en.wikipedia.org/wiki/Cosine_similarity) to learn
// more.
COSINE = 2;
// Similar to cosine but is affected by the magnitude of the vectors. See
// [Dot Product](https://en.wikipedia.org/wiki/Dot_product) to learn more.
DOT_PRODUCT = 3;
}
// Required. An indexed vector field to search upon. Only documents which
// contain vectors whose dimensionality match the query_vector can be
// returned.
FieldReference vector_field = 1 [(google.api.field_behavior) = REQUIRED];
// Required. The query vector that we are searching on. Must be a vector of
// no more than 2048 dimensions.
Value query_vector = 2 [(google.api.field_behavior) = REQUIRED];
// Required. The Distance Measure to use, required.
DistanceMeasure distance_measure = 3
[(google.api.field_behavior) = REQUIRED];
// Required. The number of nearest neighbors to return. Must be a positive
// integer of no more than 1000.
google.protobuf.Int32Value limit = 4
[(google.api.field_behavior) = REQUIRED];
}
// Optional sub-set of the fields to return.
//
// This acts as a [DocumentMask][google.firestore.v1.DocumentMask] over the
// documents returned from a query. When not set, assumes that the caller
// wants all fields returned.
Projection select = 1;
// The collections to query.
repeated CollectionSelector from = 2;
// The filter to apply.
Filter where = 3;
// The order to apply to the query results.
//
// Firestore allows callers to provide a full ordering, a partial ordering, or
// no ordering at all. In all cases, Firestore guarantees a stable ordering
// through the following rules:
//
// * The `order_by` is required to reference all fields used with an
// inequality filter.
// * All fields that are required to be in the `order_by` but are not already
// present are appended in lexicographical ordering of the field name.
// * If an order on `__name__` is not specified, it is appended by default.
//
// Fields are appended with the same sort direction as the last order
// specified, or 'ASCENDING' if no order was specified. For example:
//
// * `ORDER BY a` becomes `ORDER BY a ASC, __name__ ASC`
// * `ORDER BY a DESC` becomes `ORDER BY a DESC, __name__ DESC`
// * `WHERE a > 1` becomes `WHERE a > 1 ORDER BY a ASC, __name__ ASC`
// * `WHERE __name__ > ... AND a > 1` becomes
// `WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC`
repeated Order order_by = 4;
// A potential prefix of a position in the result set to start the query at.
//
// The ordering of the result set is based on the `ORDER BY` clause of the
// original query.
//
// ```
// SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;
// ```
//
// This query's results are ordered by `(b ASC, __name__ ASC)`.
//
// Cursors can reference either the full ordering or a prefix of the location,
// though it cannot reference more fields than what are in the provided
// `ORDER BY`.
//
// Continuing off the example above, attaching the following start cursors
// will have varying impact:
//
// - `START BEFORE (2, /k/123)`: start the query right before `a = 1 AND
// b > 2 AND __name__ > /k/123`.
// - `START AFTER (10)`: start the query right after `a = 1 AND b > 10`.
//
// Unlike `OFFSET` which requires scanning over the first N results to skip,
// a start cursor allows the query to begin at a logical position. This
// position is not required to match an actual result, it will scan forward
// from this position to find the next document.
//
// Requires:
//
// * The number of values cannot be greater than the number of fields
// specified in the `ORDER BY` clause.
Cursor start_at = 7;
// A potential prefix of a position in the result set to end the query at.
//
// This is similar to `START_AT` but with it controlling the end position
// rather than the start position.
//
// Requires:
//
// * The number of values cannot be greater than the number of fields
// specified in the `ORDER BY` clause.
Cursor end_at = 8;
// The number of documents to skip before returning the first result.
//
// This applies after the constraints specified by the `WHERE`, `START AT`, &
// `END AT` but before the `LIMIT` clause.
//
// Requires:
//
// * The value must be greater than or equal to zero if specified.
int32 offset = 6;
// The maximum number of results to return.
//
// Applies after all other constraints.
//
// Requires:
//
// * The value must be greater than or equal to zero if specified.
google.protobuf.Int32Value limit = 5;
// Optional. A potential Nearest Neighbors Search.
//
// Applies after all other filters and ordering.
//
// Finds the closest vector embeddings to the given query vector.
FindNearest find_nearest = 9 [(google.api.field_behavior) = OPTIONAL];
}
// Firestore query for running an aggregation over a
// [StructuredQuery][google.firestore.v1.StructuredQuery].
message StructuredAggregationQuery {
// Defines an 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.
//
// Unspecified is interpreted as no bound.
//
// High-Level Example:
//
// ```
// AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
// ```
//
// Requires:
//
// * Must be greater than zero when present.
google.protobuf.Int64Value up_to = 1
[(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
// aggregation into.
//
// If not provided, Firestore will pick a default name following the format
// `field_<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 field_1,
// COUNT_UP_TO(3) AS count_up_to_3,
// COUNT(*) AS field_2
// OVER (
// ...
// );
// ```
//
// Requires:
//
// * Must be unique across all aggregation aliases.
// * Conform to [document field name][google.firestore.v1.Document.fields]
// limitations.
string alias = 7 [(google.api.field_behavior) = OPTIONAL];
}
// The base query to aggregate over.
oneof query_type {
// Nested structured query.
StructuredQuery structured_query = 1;
}
// Optional. Series of aggregations to apply over the results of the
// `structured_query`.
//
// Requires:
//
// * A minimum of one and maximum of five aggregations per query.
repeated Aggregation aggregations = 3
[(google.api.field_behavior) = OPTIONAL];
}
// A position in a query result set.
message Cursor {
// The values that represent a position, in the order they appear in
// the order by clause of a query.
//
// Can contain fewer values than specified in the order by clause.
repeated Value values = 1;
// If the position is just before or just after the given values, relative
// to the sort order defined by the query.
bool before = 2;
}