Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/cloud/firestore_v1/types/query.py: 100%
83 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-09 06:27 +0000
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-09 06:27 +0000
1# -*- coding: utf-8 -*-
2# Copyright 2023 Google LLC
3#
4# Licensed under the Apache License, Version 2.0 (the "License");
5# you may not use this file except in compliance with the License.
6# You may obtain a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS,
12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13# See the License for the specific language governing permissions and
14# limitations under the License.
15#
16from __future__ import annotations
18from typing import MutableMapping, MutableSequence
20import proto # type: ignore
22from google.cloud.firestore_v1.types import document
23from google.protobuf import wrappers_pb2 # type: ignore
26__protobuf__ = proto.module(
27 package="google.firestore.v1",
28 manifest={
29 "StructuredQuery",
30 "StructuredAggregationQuery",
31 "Cursor",
32 },
33)
36class StructuredQuery(proto.Message):
37 r"""A Firestore query.
39 Attributes:
40 select (google.cloud.firestore_v1.types.StructuredQuery.Projection):
41 Optional sub-set of the fields to return.
43 This acts as a
44 [DocumentMask][google.firestore.v1.DocumentMask] over the
45 documents returned from a query. When not set, assumes that
46 the caller wants all fields returned.
47 from_ (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.CollectionSelector]):
48 The collections to query.
49 where (google.cloud.firestore_v1.types.StructuredQuery.Filter):
50 The filter to apply.
51 order_by (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.Order]):
52 The order to apply to the query results.
54 Firestore allows callers to provide a full ordering, a
55 partial ordering, or no ordering at all. In all cases,
56 Firestore guarantees a stable ordering through the following
57 rules:
59 - The ``order_by`` is required to reference all fields used
60 with an inequality filter.
61 - All fields that are required to be in the ``order_by``
62 but are not already present are appended in
63 lexicographical ordering of the field name.
64 - If an order on ``__name__`` is not specified, it is
65 appended by default.
67 Fields are appended with the same sort direction as the last
68 order specified, or 'ASCENDING' if no order was specified.
69 For example:
71 - ``ORDER BY a`` becomes ``ORDER BY a ASC, __name__ ASC``
72 - ``ORDER BY a DESC`` becomes
73 ``ORDER BY a DESC, __name__ DESC``
74 - ``WHERE a > 1`` becomes
75 ``WHERE a > 1 ORDER BY a ASC, __name__ ASC``
76 - ``WHERE __name__ > ... AND a > 1`` becomes
77 ``WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC``
78 start_at (google.cloud.firestore_v1.types.Cursor):
79 A potential prefix of a position in the result set to start
80 the query at.
82 The ordering of the result set is based on the ``ORDER BY``
83 clause of the original query.
85 ::
87 SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;
89 This query's results are ordered by
90 ``(b ASC, __name__ ASC)``.
92 Cursors can reference either the full ordering or a prefix
93 of the location, though it cannot reference more fields than
94 what are in the provided ``ORDER BY``.
96 Continuing off the example above, attaching the following
97 start cursors will have varying impact:
99 - ``START BEFORE (2, /k/123)``: start the query right
100 before ``a = 1 AND b > 2 AND __name__ > /k/123``.
101 - ``START AFTER (10)``: start the query right after
102 ``a = 1 AND b > 10``.
104 Unlike ``OFFSET`` which requires scanning over the first N
105 results to skip, a start cursor allows the query to begin at
106 a logical position. This position is not required to match
107 an actual result, it will scan forward from this position to
108 find the next document.
110 Requires:
112 - The number of values cannot be greater than the number of
113 fields specified in the ``ORDER BY`` clause.
114 end_at (google.cloud.firestore_v1.types.Cursor):
115 A potential prefix of a position in the result set to end
116 the query at.
118 This is similar to ``START_AT`` but with it controlling the
119 end position rather than the start position.
121 Requires:
123 - The number of values cannot be greater than the number of
124 fields specified in the ``ORDER BY`` clause.
125 offset (int):
126 The number of documents to skip before returning the first
127 result.
129 This applies after the constraints specified by the
130 ``WHERE``, ``START AT``, & ``END AT`` but before the
131 ``LIMIT`` clause.
133 Requires:
135 - The value must be greater than or equal to zero if
136 specified.
137 limit (google.protobuf.wrappers_pb2.Int32Value):
138 The maximum number of results to return.
140 Applies after all other constraints.
142 Requires:
144 - The value must be greater than or equal to zero if
145 specified.
146 """
148 class Direction(proto.Enum):
149 r"""A sort direction.
151 Values:
152 DIRECTION_UNSPECIFIED (0):
153 Unspecified.
154 ASCENDING (1):
155 Ascending.
156 DESCENDING (2):
157 Descending.
158 """
159 DIRECTION_UNSPECIFIED = 0
160 ASCENDING = 1
161 DESCENDING = 2
163 class CollectionSelector(proto.Message):
164 r"""A selection of a collection, such as ``messages as m1``.
166 Attributes:
167 collection_id (str):
168 The collection ID.
169 When set, selects only collections with this ID.
170 all_descendants (bool):
171 When false, selects only collections that are immediate
172 children of the ``parent`` specified in the containing
173 ``RunQueryRequest``. When true, selects all descendant
174 collections.
175 """
177 collection_id: str = proto.Field(
178 proto.STRING,
179 number=2,
180 )
181 all_descendants: bool = proto.Field(
182 proto.BOOL,
183 number=3,
184 )
186 class Filter(proto.Message):
187 r"""A filter.
189 This message has `oneof`_ fields (mutually exclusive fields).
190 For each oneof, at most one member field can be set at the same time.
191 Setting any member of the oneof automatically clears all other
192 members.
194 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
196 Attributes:
197 composite_filter (google.cloud.firestore_v1.types.StructuredQuery.CompositeFilter):
198 A composite filter.
200 This field is a member of `oneof`_ ``filter_type``.
201 field_filter (google.cloud.firestore_v1.types.StructuredQuery.FieldFilter):
202 A filter on a document field.
204 This field is a member of `oneof`_ ``filter_type``.
205 unary_filter (google.cloud.firestore_v1.types.StructuredQuery.UnaryFilter):
206 A filter that takes exactly one argument.
208 This field is a member of `oneof`_ ``filter_type``.
209 """
211 composite_filter: "StructuredQuery.CompositeFilter" = proto.Field(
212 proto.MESSAGE,
213 number=1,
214 oneof="filter_type",
215 message="StructuredQuery.CompositeFilter",
216 )
217 field_filter: "StructuredQuery.FieldFilter" = proto.Field(
218 proto.MESSAGE,
219 number=2,
220 oneof="filter_type",
221 message="StructuredQuery.FieldFilter",
222 )
223 unary_filter: "StructuredQuery.UnaryFilter" = proto.Field(
224 proto.MESSAGE,
225 number=3,
226 oneof="filter_type",
227 message="StructuredQuery.UnaryFilter",
228 )
230 class CompositeFilter(proto.Message):
231 r"""A filter that merges multiple other filters using the given
232 operator.
234 Attributes:
235 op (google.cloud.firestore_v1.types.StructuredQuery.CompositeFilter.Operator):
236 The operator for combining multiple filters.
237 filters (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.Filter]):
238 The list of filters to combine.
240 Requires:
242 - At least one filter is present.
243 """
245 class Operator(proto.Enum):
246 r"""A composite filter operator.
248 Values:
249 OPERATOR_UNSPECIFIED (0):
250 Unspecified. This value must not be used.
251 AND (1):
252 Documents are required to satisfy all of the
253 combined filters.
254 OR (2):
255 Documents are required to satisfy at least
256 one of the combined filters.
257 """
258 OPERATOR_UNSPECIFIED = 0
259 AND = 1
260 OR = 2
262 op: "StructuredQuery.CompositeFilter.Operator" = proto.Field(
263 proto.ENUM,
264 number=1,
265 enum="StructuredQuery.CompositeFilter.Operator",
266 )
267 filters: MutableSequence["StructuredQuery.Filter"] = proto.RepeatedField(
268 proto.MESSAGE,
269 number=2,
270 message="StructuredQuery.Filter",
271 )
273 class FieldFilter(proto.Message):
274 r"""A filter on a specific field.
276 Attributes:
277 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
278 The field to filter by.
279 op (google.cloud.firestore_v1.types.StructuredQuery.FieldFilter.Operator):
280 The operator to filter by.
281 value (google.cloud.firestore_v1.types.Value):
282 The value to compare to.
283 """
285 class Operator(proto.Enum):
286 r"""A field filter operator.
288 Values:
289 OPERATOR_UNSPECIFIED (0):
290 Unspecified. This value must not be used.
291 LESS_THAN (1):
292 The given ``field`` is less than the given ``value``.
294 Requires:
296 - That ``field`` come first in ``order_by``.
297 LESS_THAN_OR_EQUAL (2):
298 The given ``field`` is less than or equal to the given
299 ``value``.
301 Requires:
303 - That ``field`` come first in ``order_by``.
304 GREATER_THAN (3):
305 The given ``field`` is greater than the given ``value``.
307 Requires:
309 - That ``field`` come first in ``order_by``.
310 GREATER_THAN_OR_EQUAL (4):
311 The given ``field`` is greater than or equal to the given
312 ``value``.
314 Requires:
316 - That ``field`` come first in ``order_by``.
317 EQUAL (5):
318 The given ``field`` is equal to the given ``value``.
319 NOT_EQUAL (6):
320 The given ``field`` is not equal to the given ``value``.
322 Requires:
324 - No other ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or
325 ``IS_NOT_NAN``.
326 - That ``field`` comes first in the ``order_by``.
327 ARRAY_CONTAINS (7):
328 The given ``field`` is an array that contains the given
329 ``value``.
330 IN (8):
331 The given ``field`` is equal to at least one value in the
332 given array.
334 Requires:
336 - That ``value`` is a non-empty ``ArrayValue``, subject to
337 disjunction limits.
338 - No ``NOT_IN`` filters in the same query.
339 ARRAY_CONTAINS_ANY (9):
340 The given ``field`` is an array that contains any of the
341 values in the given array.
343 Requires:
345 - That ``value`` is a non-empty ``ArrayValue``, subject to
346 disjunction limits.
347 - No other ``ARRAY_CONTAINS_ANY`` filters within the same
348 disjunction.
349 - No ``NOT_IN`` filters in the same query.
350 NOT_IN (10):
351 The value of the ``field`` is not in the given array.
353 Requires:
355 - That ``value`` is a non-empty ``ArrayValue`` with at most
356 10 values.
357 - No other ``OR``, ``IN``, ``ARRAY_CONTAINS_ANY``,
358 ``NOT_IN``, ``NOT_EQUAL``, ``IS_NOT_NULL``, or
359 ``IS_NOT_NAN``.
360 - That ``field`` comes first in the ``order_by``.
361 """
362 OPERATOR_UNSPECIFIED = 0
363 LESS_THAN = 1
364 LESS_THAN_OR_EQUAL = 2
365 GREATER_THAN = 3
366 GREATER_THAN_OR_EQUAL = 4
367 EQUAL = 5
368 NOT_EQUAL = 6
369 ARRAY_CONTAINS = 7
370 IN = 8
371 ARRAY_CONTAINS_ANY = 9
372 NOT_IN = 10
374 field: "StructuredQuery.FieldReference" = proto.Field(
375 proto.MESSAGE,
376 number=1,
377 message="StructuredQuery.FieldReference",
378 )
379 op: "StructuredQuery.FieldFilter.Operator" = proto.Field(
380 proto.ENUM,
381 number=2,
382 enum="StructuredQuery.FieldFilter.Operator",
383 )
384 value: document.Value = proto.Field(
385 proto.MESSAGE,
386 number=3,
387 message=document.Value,
388 )
390 class UnaryFilter(proto.Message):
391 r"""A filter with a single operand.
393 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
395 Attributes:
396 op (google.cloud.firestore_v1.types.StructuredQuery.UnaryFilter.Operator):
397 The unary operator to apply.
398 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
399 The field to which to apply the operator.
401 This field is a member of `oneof`_ ``operand_type``.
402 """
404 class Operator(proto.Enum):
405 r"""A unary operator.
407 Values:
408 OPERATOR_UNSPECIFIED (0):
409 Unspecified. This value must not be used.
410 IS_NAN (2):
411 The given ``field`` is equal to ``NaN``.
412 IS_NULL (3):
413 The given ``field`` is equal to ``NULL``.
414 IS_NOT_NAN (4):
415 The given ``field`` is not equal to ``NaN``.
417 Requires:
419 - No other ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or
420 ``IS_NOT_NAN``.
421 - That ``field`` comes first in the ``order_by``.
422 IS_NOT_NULL (5):
423 The given ``field`` is not equal to ``NULL``.
425 Requires:
427 - A single ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or
428 ``IS_NOT_NAN``.
429 - That ``field`` comes first in the ``order_by``.
430 """
431 OPERATOR_UNSPECIFIED = 0
432 IS_NAN = 2
433 IS_NULL = 3
434 IS_NOT_NAN = 4
435 IS_NOT_NULL = 5
437 op: "StructuredQuery.UnaryFilter.Operator" = proto.Field(
438 proto.ENUM,
439 number=1,
440 enum="StructuredQuery.UnaryFilter.Operator",
441 )
442 field: "StructuredQuery.FieldReference" = proto.Field(
443 proto.MESSAGE,
444 number=2,
445 oneof="operand_type",
446 message="StructuredQuery.FieldReference",
447 )
449 class Order(proto.Message):
450 r"""An order on a field.
452 Attributes:
453 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
454 The field to order by.
455 direction (google.cloud.firestore_v1.types.StructuredQuery.Direction):
456 The direction to order by. Defaults to ``ASCENDING``.
457 """
459 field: "StructuredQuery.FieldReference" = proto.Field(
460 proto.MESSAGE,
461 number=1,
462 message="StructuredQuery.FieldReference",
463 )
464 direction: "StructuredQuery.Direction" = proto.Field(
465 proto.ENUM,
466 number=2,
467 enum="StructuredQuery.Direction",
468 )
470 class FieldReference(proto.Message):
471 r"""A reference to a field in a document, ex: ``stats.operations``.
473 Attributes:
474 field_path (str):
475 A reference to a field in a document.
477 Requires:
479 - MUST be a dot-delimited (``.``) string of segments, where
480 each segment conforms to [document field
481 name][google.firestore.v1.Document.fields] limitations.
482 """
484 field_path: str = proto.Field(
485 proto.STRING,
486 number=2,
487 )
489 class Projection(proto.Message):
490 r"""The projection of document's fields to return.
492 Attributes:
493 fields (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.FieldReference]):
494 The fields to return.
496 If empty, all fields are returned. To only return the name
497 of the document, use ``['__name__']``.
498 """
500 fields: MutableSequence["StructuredQuery.FieldReference"] = proto.RepeatedField(
501 proto.MESSAGE,
502 number=2,
503 message="StructuredQuery.FieldReference",
504 )
506 select: Projection = proto.Field(
507 proto.MESSAGE,
508 number=1,
509 message=Projection,
510 )
511 from_: MutableSequence[CollectionSelector] = proto.RepeatedField(
512 proto.MESSAGE,
513 number=2,
514 message=CollectionSelector,
515 )
516 where: Filter = proto.Field(
517 proto.MESSAGE,
518 number=3,
519 message=Filter,
520 )
521 order_by: MutableSequence[Order] = proto.RepeatedField(
522 proto.MESSAGE,
523 number=4,
524 message=Order,
525 )
526 start_at: "Cursor" = proto.Field(
527 proto.MESSAGE,
528 number=7,
529 message="Cursor",
530 )
531 end_at: "Cursor" = proto.Field(
532 proto.MESSAGE,
533 number=8,
534 message="Cursor",
535 )
536 offset: int = proto.Field(
537 proto.INT32,
538 number=6,
539 )
540 limit: wrappers_pb2.Int32Value = proto.Field(
541 proto.MESSAGE,
542 number=5,
543 message=wrappers_pb2.Int32Value,
544 )
547class StructuredAggregationQuery(proto.Message):
548 r"""Firestore query for running an aggregation over a
549 [StructuredQuery][google.firestore.v1.StructuredQuery].
552 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
554 Attributes:
555 structured_query (google.cloud.firestore_v1.types.StructuredQuery):
556 Nested structured query.
558 This field is a member of `oneof`_ ``query_type``.
559 aggregations (MutableSequence[google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation]):
560 Optional. Series of aggregations to apply over the results
561 of the ``structured_query``.
563 Requires:
565 - A minimum of one and maximum of five aggregations per
566 query.
567 """
569 class Aggregation(proto.Message):
570 r"""Defines an aggregation that produces a single result.
572 This message has `oneof`_ fields (mutually exclusive fields).
573 For each oneof, at most one member field can be set at the same time.
574 Setting any member of the oneof automatically clears all other
575 members.
577 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
579 Attributes:
580 count (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Count):
581 Count aggregator.
583 This field is a member of `oneof`_ ``operator``.
584 sum (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Sum):
585 Sum aggregator.
587 This field is a member of `oneof`_ ``operator``.
588 avg (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Avg):
589 Average aggregator.
591 This field is a member of `oneof`_ ``operator``.
592 alias (str):
593 Optional. Optional name of the field to store the result of
594 the aggregation into.
596 If not provided, Firestore will pick a default name
597 following the format ``field_<incremental_id++>``. For
598 example:
600 ::
602 AGGREGATE
603 COUNT_UP_TO(1) AS count_up_to_1,
604 COUNT_UP_TO(2),
605 COUNT_UP_TO(3) AS count_up_to_3,
606 COUNT(*)
607 OVER (
608 ...
609 );
611 becomes:
613 ::
615 AGGREGATE
616 COUNT_UP_TO(1) AS count_up_to_1,
617 COUNT_UP_TO(2) AS field_1,
618 COUNT_UP_TO(3) AS count_up_to_3,
619 COUNT(*) AS field_2
620 OVER (
621 ...
622 );
624 Requires:
626 - Must be unique across all aggregation aliases.
627 - Conform to [document field
628 name][google.firestore.v1.Document.fields] limitations.
629 """
631 class Count(proto.Message):
632 r"""Count of documents that match the query.
634 The ``COUNT(*)`` aggregation function operates on the entire
635 document so it does not require a field reference.
637 Attributes:
638 up_to (google.protobuf.wrappers_pb2.Int64Value):
639 Optional. Optional constraint on the maximum number of
640 documents to count.
642 This provides a way to set an upper bound on the number of
643 documents to scan, limiting latency, and cost.
645 Unspecified is interpreted as no bound.
647 High-Level Example:
649 ::
651 AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
653 Requires:
655 - Must be greater than zero when present.
656 """
658 up_to: wrappers_pb2.Int64Value = proto.Field(
659 proto.MESSAGE,
660 number=1,
661 message=wrappers_pb2.Int64Value,
662 )
664 class Sum(proto.Message):
665 r"""Sum of the values of the requested field.
667 - Only numeric values will be aggregated. All non-numeric values
668 including ``NULL`` are skipped.
670 - If the aggregated values contain ``NaN``, returns ``NaN``.
671 Infinity math follows IEEE-754 standards.
673 - If the aggregated value set is empty, returns 0.
675 - Returns a 64-bit integer if all aggregated numbers are integers
676 and the sum result does not overflow. Otherwise, the result is
677 returned as a double. Note that even if all the aggregated values
678 are integers, the result is returned as a double if it cannot fit
679 within a 64-bit signed integer. When this occurs, the returned
680 value will lose precision.
682 - When underflow occurs, floating-point aggregation is
683 non-deterministic. This means that running the same query
684 repeatedly without any changes to the underlying values could
685 produce slightly different results each time. In those cases,
686 values should be stored as integers over floating-point numbers.
688 Attributes:
689 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
690 The field to aggregate on.
691 """
693 field: "StructuredQuery.FieldReference" = proto.Field(
694 proto.MESSAGE,
695 number=1,
696 message="StructuredQuery.FieldReference",
697 )
699 class Avg(proto.Message):
700 r"""Average of the values of the requested field.
702 - Only numeric values will be aggregated. All non-numeric values
703 including ``NULL`` are skipped.
705 - If the aggregated values contain ``NaN``, returns ``NaN``.
706 Infinity math follows IEEE-754 standards.
708 - If the aggregated value set is empty, returns ``NULL``.
710 - Always returns the result as a double.
712 Attributes:
713 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
714 The field to aggregate on.
715 """
717 field: "StructuredQuery.FieldReference" = proto.Field(
718 proto.MESSAGE,
719 number=1,
720 message="StructuredQuery.FieldReference",
721 )
723 count: "StructuredAggregationQuery.Aggregation.Count" = proto.Field(
724 proto.MESSAGE,
725 number=1,
726 oneof="operator",
727 message="StructuredAggregationQuery.Aggregation.Count",
728 )
729 sum: "StructuredAggregationQuery.Aggregation.Sum" = proto.Field(
730 proto.MESSAGE,
731 number=2,
732 oneof="operator",
733 message="StructuredAggregationQuery.Aggregation.Sum",
734 )
735 avg: "StructuredAggregationQuery.Aggregation.Avg" = proto.Field(
736 proto.MESSAGE,
737 number=3,
738 oneof="operator",
739 message="StructuredAggregationQuery.Aggregation.Avg",
740 )
741 alias: str = proto.Field(
742 proto.STRING,
743 number=7,
744 )
746 structured_query: "StructuredQuery" = proto.Field(
747 proto.MESSAGE,
748 number=1,
749 oneof="query_type",
750 message="StructuredQuery",
751 )
752 aggregations: MutableSequence[Aggregation] = proto.RepeatedField(
753 proto.MESSAGE,
754 number=3,
755 message=Aggregation,
756 )
759class Cursor(proto.Message):
760 r"""A position in a query result set.
762 Attributes:
763 values (MutableSequence[google.cloud.firestore_v1.types.Value]):
764 The values that represent a position, in the
765 order they appear in the order by clause of a
766 query.
768 Can contain fewer values than specified in the
769 order by clause.
770 before (bool):
771 If the position is just before or just after
772 the given values, relative to the sort order
773 defined by the query.
774 """
776 values: MutableSequence[document.Value] = proto.RepeatedField(
777 proto.MESSAGE,
778 number=1,
779 message=document.Value,
780 )
781 before: bool = proto.Field(
782 proto.BOOL,
783 number=2,
784 )
787__all__ = tuple(sorted(__protobuf__.manifest))