Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2# Copyright 2025 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 The query stages are executed in the following order:
41 1. from
42 2. where
43 3. select
44 4. order_by + start_at + end_at
45 5. offset
46 6. limit
47 7. find_nearest
49 Attributes:
50 select (google.cloud.firestore_v1.types.StructuredQuery.Projection):
51 Optional sub-set of the fields to return.
53 This acts as a
54 [DocumentMask][google.firestore.v1.DocumentMask] over the
55 documents returned from a query. When not set, assumes that
56 the caller wants all fields returned.
57 from_ (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.CollectionSelector]):
58 The collections to query.
59 where (google.cloud.firestore_v1.types.StructuredQuery.Filter):
60 The filter to apply.
61 order_by (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.Order]):
62 The order to apply to the query results.
64 Firestore allows callers to provide a full ordering, a
65 partial ordering, or no ordering at all. In all cases,
66 Firestore guarantees a stable ordering through the following
67 rules:
69 - The ``order_by`` is required to reference all fields used
70 with an inequality filter.
71 - All fields that are required to be in the ``order_by``
72 but are not already present are appended in
73 lexicographical ordering of the field name.
74 - If an order on ``__name__`` is not specified, it is
75 appended by default.
77 Fields are appended with the same sort direction as the last
78 order specified, or 'ASCENDING' if no order was specified.
79 For example:
81 - ``ORDER BY a`` becomes ``ORDER BY a ASC, __name__ ASC``
82 - ``ORDER BY a DESC`` becomes
83 ``ORDER BY a DESC, __name__ DESC``
84 - ``WHERE a > 1`` becomes
85 ``WHERE a > 1 ORDER BY a ASC, __name__ ASC``
86 - ``WHERE __name__ > ... AND a > 1`` becomes
87 ``WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC``
88 start_at (google.cloud.firestore_v1.types.Cursor):
89 A potential prefix of a position in the result set to start
90 the query at.
92 The ordering of the result set is based on the ``ORDER BY``
93 clause of the original query.
95 ::
97 SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;
99 This query's results are ordered by
100 ``(b ASC, __name__ ASC)``.
102 Cursors can reference either the full ordering or a prefix
103 of the location, though it cannot reference more fields than
104 what are in the provided ``ORDER BY``.
106 Continuing off the example above, attaching the following
107 start cursors will have varying impact:
109 - ``START BEFORE (2, /k/123)``: start the query right
110 before ``a = 1 AND b > 2 AND __name__ > /k/123``.
111 - ``START AFTER (10)``: start the query right after
112 ``a = 1 AND b > 10``.
114 Unlike ``OFFSET`` which requires scanning over the first N
115 results to skip, a start cursor allows the query to begin at
116 a logical position. This position is not required to match
117 an actual result, it will scan forward from this position to
118 find the next document.
120 Requires:
122 - The number of values cannot be greater than the number of
123 fields specified in the ``ORDER BY`` clause.
124 end_at (google.cloud.firestore_v1.types.Cursor):
125 A potential prefix of a position in the result set to end
126 the query at.
128 This is similar to ``START_AT`` but with it controlling the
129 end position rather than the start position.
131 Requires:
133 - The number of values cannot be greater than the number of
134 fields specified in the ``ORDER BY`` clause.
135 offset (int):
136 The number of documents to skip before returning the first
137 result.
139 This applies after the constraints specified by the
140 ``WHERE``, ``START AT``, & ``END AT`` but before the
141 ``LIMIT`` clause.
143 Requires:
145 - The value must be greater than or equal to zero if
146 specified.
147 limit (google.protobuf.wrappers_pb2.Int32Value):
148 The maximum number of results to return.
150 Applies after all other constraints.
152 Requires:
154 - The value must be greater than or equal to zero if
155 specified.
156 find_nearest (google.cloud.firestore_v1.types.StructuredQuery.FindNearest):
157 Optional. A potential nearest neighbors
158 search.
159 Applies after all other filters and ordering.
161 Finds the closest vector embeddings to the given
162 query vector.
163 """
165 class Direction(proto.Enum):
166 r"""A sort direction.
168 Values:
169 DIRECTION_UNSPECIFIED (0):
170 Unspecified.
171 ASCENDING (1):
172 Ascending.
173 DESCENDING (2):
174 Descending.
175 """
176 DIRECTION_UNSPECIFIED = 0
177 ASCENDING = 1
178 DESCENDING = 2
180 class CollectionSelector(proto.Message):
181 r"""A selection of a collection, such as ``messages as m1``.
183 Attributes:
184 collection_id (str):
185 The collection ID.
186 When set, selects only collections with this ID.
187 all_descendants (bool):
188 When false, selects only collections that are immediate
189 children of the ``parent`` specified in the containing
190 ``RunQueryRequest``. When true, selects all descendant
191 collections.
192 """
194 collection_id: str = proto.Field(
195 proto.STRING,
196 number=2,
197 )
198 all_descendants: bool = proto.Field(
199 proto.BOOL,
200 number=3,
201 )
203 class Filter(proto.Message):
204 r"""A filter.
206 This message has `oneof`_ fields (mutually exclusive fields).
207 For each oneof, at most one member field can be set at the same time.
208 Setting any member of the oneof automatically clears all other
209 members.
211 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
213 Attributes:
214 composite_filter (google.cloud.firestore_v1.types.StructuredQuery.CompositeFilter):
215 A composite filter.
217 This field is a member of `oneof`_ ``filter_type``.
218 field_filter (google.cloud.firestore_v1.types.StructuredQuery.FieldFilter):
219 A filter on a document field.
221 This field is a member of `oneof`_ ``filter_type``.
222 unary_filter (google.cloud.firestore_v1.types.StructuredQuery.UnaryFilter):
223 A filter that takes exactly one argument.
225 This field is a member of `oneof`_ ``filter_type``.
226 """
228 composite_filter: "StructuredQuery.CompositeFilter" = proto.Field(
229 proto.MESSAGE,
230 number=1,
231 oneof="filter_type",
232 message="StructuredQuery.CompositeFilter",
233 )
234 field_filter: "StructuredQuery.FieldFilter" = proto.Field(
235 proto.MESSAGE,
236 number=2,
237 oneof="filter_type",
238 message="StructuredQuery.FieldFilter",
239 )
240 unary_filter: "StructuredQuery.UnaryFilter" = proto.Field(
241 proto.MESSAGE,
242 number=3,
243 oneof="filter_type",
244 message="StructuredQuery.UnaryFilter",
245 )
247 class CompositeFilter(proto.Message):
248 r"""A filter that merges multiple other filters using the given
249 operator.
251 Attributes:
252 op (google.cloud.firestore_v1.types.StructuredQuery.CompositeFilter.Operator):
253 The operator for combining multiple filters.
254 filters (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.Filter]):
255 The list of filters to combine.
257 Requires:
259 - At least one filter is present.
260 """
262 class Operator(proto.Enum):
263 r"""A composite filter operator.
265 Values:
266 OPERATOR_UNSPECIFIED (0):
267 Unspecified. This value must not be used.
268 AND (1):
269 Documents are required to satisfy all of the
270 combined filters.
271 OR (2):
272 Documents are required to satisfy at least
273 one of the combined filters.
274 """
275 OPERATOR_UNSPECIFIED = 0
276 AND = 1
277 OR = 2
279 op: "StructuredQuery.CompositeFilter.Operator" = proto.Field(
280 proto.ENUM,
281 number=1,
282 enum="StructuredQuery.CompositeFilter.Operator",
283 )
284 filters: MutableSequence["StructuredQuery.Filter"] = proto.RepeatedField(
285 proto.MESSAGE,
286 number=2,
287 message="StructuredQuery.Filter",
288 )
290 class FieldFilter(proto.Message):
291 r"""A filter on a specific field.
293 Attributes:
294 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
295 The field to filter by.
296 op (google.cloud.firestore_v1.types.StructuredQuery.FieldFilter.Operator):
297 The operator to filter by.
298 value (google.cloud.firestore_v1.types.Value):
299 The value to compare to.
300 """
302 class Operator(proto.Enum):
303 r"""A field filter operator.
305 Values:
306 OPERATOR_UNSPECIFIED (0):
307 Unspecified. This value must not be used.
308 LESS_THAN (1):
309 The given ``field`` is less than the given ``value``.
311 Requires:
313 - That ``field`` come first in ``order_by``.
314 LESS_THAN_OR_EQUAL (2):
315 The given ``field`` is less than or equal to the given
316 ``value``.
318 Requires:
320 - That ``field`` come first in ``order_by``.
321 GREATER_THAN (3):
322 The given ``field`` is greater than the given ``value``.
324 Requires:
326 - That ``field`` come first in ``order_by``.
327 GREATER_THAN_OR_EQUAL (4):
328 The given ``field`` is greater than or equal to the given
329 ``value``.
331 Requires:
333 - That ``field`` come first in ``order_by``.
334 EQUAL (5):
335 The given ``field`` is equal to the given ``value``.
336 NOT_EQUAL (6):
337 The given ``field`` is not equal to the given ``value``.
339 Requires:
341 - No other ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or
342 ``IS_NOT_NAN``.
343 - That ``field`` comes first in the ``order_by``.
344 ARRAY_CONTAINS (7):
345 The given ``field`` is an array that contains the given
346 ``value``.
347 IN (8):
348 The given ``field`` is equal to at least one value in the
349 given array.
351 Requires:
353 - That ``value`` is a non-empty ``ArrayValue``, subject to
354 disjunction limits.
355 - No ``NOT_IN`` filters in the same query.
356 ARRAY_CONTAINS_ANY (9):
357 The given ``field`` is an array that contains any of the
358 values in the given array.
360 Requires:
362 - That ``value`` is a non-empty ``ArrayValue``, subject to
363 disjunction limits.
364 - No other ``ARRAY_CONTAINS_ANY`` filters within the same
365 disjunction.
366 - No ``NOT_IN`` filters in the same query.
367 NOT_IN (10):
368 The value of the ``field`` is not in the given array.
370 Requires:
372 - That ``value`` is a non-empty ``ArrayValue`` with at most
373 10 values.
374 - No other ``OR``, ``IN``, ``ARRAY_CONTAINS_ANY``,
375 ``NOT_IN``, ``NOT_EQUAL``, ``IS_NOT_NULL``, or
376 ``IS_NOT_NAN``.
377 - That ``field`` comes first in the ``order_by``.
378 """
379 OPERATOR_UNSPECIFIED = 0
380 LESS_THAN = 1
381 LESS_THAN_OR_EQUAL = 2
382 GREATER_THAN = 3
383 GREATER_THAN_OR_EQUAL = 4
384 EQUAL = 5
385 NOT_EQUAL = 6
386 ARRAY_CONTAINS = 7
387 IN = 8
388 ARRAY_CONTAINS_ANY = 9
389 NOT_IN = 10
391 field: "StructuredQuery.FieldReference" = proto.Field(
392 proto.MESSAGE,
393 number=1,
394 message="StructuredQuery.FieldReference",
395 )
396 op: "StructuredQuery.FieldFilter.Operator" = proto.Field(
397 proto.ENUM,
398 number=2,
399 enum="StructuredQuery.FieldFilter.Operator",
400 )
401 value: document.Value = proto.Field(
402 proto.MESSAGE,
403 number=3,
404 message=document.Value,
405 )
407 class UnaryFilter(proto.Message):
408 r"""A filter with a single operand.
410 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
412 Attributes:
413 op (google.cloud.firestore_v1.types.StructuredQuery.UnaryFilter.Operator):
414 The unary operator to apply.
415 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
416 The field to which to apply the operator.
418 This field is a member of `oneof`_ ``operand_type``.
419 """
421 class Operator(proto.Enum):
422 r"""A unary operator.
424 Values:
425 OPERATOR_UNSPECIFIED (0):
426 Unspecified. This value must not be used.
427 IS_NAN (2):
428 The given ``field`` is equal to ``NaN``.
429 IS_NULL (3):
430 The given ``field`` is equal to ``NULL``.
431 IS_NOT_NAN (4):
432 The given ``field`` is not equal to ``NaN``.
434 Requires:
436 - No other ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or
437 ``IS_NOT_NAN``.
438 - That ``field`` comes first in the ``order_by``.
439 IS_NOT_NULL (5):
440 The given ``field`` is not equal to ``NULL``.
442 Requires:
444 - A single ``NOT_EQUAL``, ``NOT_IN``, ``IS_NOT_NULL``, or
445 ``IS_NOT_NAN``.
446 - That ``field`` comes first in the ``order_by``.
447 """
448 OPERATOR_UNSPECIFIED = 0
449 IS_NAN = 2
450 IS_NULL = 3
451 IS_NOT_NAN = 4
452 IS_NOT_NULL = 5
454 op: "StructuredQuery.UnaryFilter.Operator" = proto.Field(
455 proto.ENUM,
456 number=1,
457 enum="StructuredQuery.UnaryFilter.Operator",
458 )
459 field: "StructuredQuery.FieldReference" = proto.Field(
460 proto.MESSAGE,
461 number=2,
462 oneof="operand_type",
463 message="StructuredQuery.FieldReference",
464 )
466 class Order(proto.Message):
467 r"""An order on a field.
469 Attributes:
470 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
471 The field to order by.
472 direction (google.cloud.firestore_v1.types.StructuredQuery.Direction):
473 The direction to order by. Defaults to ``ASCENDING``.
474 """
476 field: "StructuredQuery.FieldReference" = proto.Field(
477 proto.MESSAGE,
478 number=1,
479 message="StructuredQuery.FieldReference",
480 )
481 direction: "StructuredQuery.Direction" = proto.Field(
482 proto.ENUM,
483 number=2,
484 enum="StructuredQuery.Direction",
485 )
487 class FieldReference(proto.Message):
488 r"""A reference to a field in a document, ex: ``stats.operations``.
490 Attributes:
491 field_path (str):
492 A reference to a field in a document.
494 Requires:
496 - MUST be a dot-delimited (``.``) string of segments, where
497 each segment conforms to [document field
498 name][google.firestore.v1.Document.fields] limitations.
499 """
501 field_path: str = proto.Field(
502 proto.STRING,
503 number=2,
504 )
506 class Projection(proto.Message):
507 r"""The projection of document's fields to return.
509 Attributes:
510 fields (MutableSequence[google.cloud.firestore_v1.types.StructuredQuery.FieldReference]):
511 The fields to return.
513 If empty, all fields are returned. To only return the name
514 of the document, use ``['__name__']``.
515 """
517 fields: MutableSequence["StructuredQuery.FieldReference"] = proto.RepeatedField(
518 proto.MESSAGE,
519 number=2,
520 message="StructuredQuery.FieldReference",
521 )
523 class FindNearest(proto.Message):
524 r"""Nearest Neighbors search config. The ordering provided by
525 FindNearest supersedes the order_by stage. If multiple documents
526 have the same vector distance, the returned document order is not
527 guaranteed to be stable between queries.
529 Attributes:
530 vector_field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
531 Required. An indexed vector field to search upon. Only
532 documents which contain vectors whose dimensionality match
533 the query_vector can be returned.
534 query_vector (google.cloud.firestore_v1.types.Value):
535 Required. The query vector that we are
536 searching on. Must be a vector of no more than
537 2048 dimensions.
538 distance_measure (google.cloud.firestore_v1.types.StructuredQuery.FindNearest.DistanceMeasure):
539 Required. The distance measure to use,
540 required.
541 limit (google.protobuf.wrappers_pb2.Int32Value):
542 Required. The number of nearest neighbors to
543 return. Must be a positive integer of no more
544 than 1000.
545 distance_result_field (str):
546 Optional. Optional name of the field to output the result of
547 the vector distance calculation. Must conform to [document
548 field name][google.firestore.v1.Document.fields]
549 limitations.
550 distance_threshold (google.protobuf.wrappers_pb2.DoubleValue):
551 Optional. Option to specify a threshold for which no less
552 similar documents will be returned. The behavior of the
553 specified ``distance_measure`` will affect the meaning of
554 the distance threshold. Since DOT_PRODUCT distances increase
555 when the vectors are more similar, the comparison is
556 inverted.
558 - For EUCLIDEAN, COSINE: WHERE distance <=
559 distance_threshold
560 - For DOT_PRODUCT: WHERE distance >= distance_threshold
561 """
563 class DistanceMeasure(proto.Enum):
564 r"""The distance measure to use when comparing vectors.
566 Values:
567 DISTANCE_MEASURE_UNSPECIFIED (0):
568 Should not be set.
569 EUCLIDEAN (1):
570 Measures the EUCLIDEAN distance between the vectors. See
571 `Euclidean <https://en.wikipedia.org/wiki/Euclidean_distance>`__
572 to learn more. The resulting distance decreases the more
573 similar two vectors are.
574 COSINE (2):
575 COSINE distance compares vectors based on the angle between
576 them, which allows you to measure similarity that isn't
577 based on the vectors magnitude. We recommend using
578 DOT_PRODUCT with unit normalized vectors instead of COSINE
579 distance, which is mathematically equivalent with better
580 performance. See `Cosine
581 Similarity <https://en.wikipedia.org/wiki/Cosine_similarity>`__
582 to learn more about COSINE similarity and COSINE distance.
583 The resulting COSINE distance decreases the more similar two
584 vectors are.
585 DOT_PRODUCT (3):
586 Similar to cosine but is affected by the magnitude of the
587 vectors. See `Dot
588 Product <https://en.wikipedia.org/wiki/Dot_product>`__ to
589 learn more. The resulting distance increases the more
590 similar two vectors are.
591 """
592 DISTANCE_MEASURE_UNSPECIFIED = 0
593 EUCLIDEAN = 1
594 COSINE = 2
595 DOT_PRODUCT = 3
597 vector_field: "StructuredQuery.FieldReference" = proto.Field(
598 proto.MESSAGE,
599 number=1,
600 message="StructuredQuery.FieldReference",
601 )
602 query_vector: document.Value = proto.Field(
603 proto.MESSAGE,
604 number=2,
605 message=document.Value,
606 )
607 distance_measure: "StructuredQuery.FindNearest.DistanceMeasure" = proto.Field(
608 proto.ENUM,
609 number=3,
610 enum="StructuredQuery.FindNearest.DistanceMeasure",
611 )
612 limit: wrappers_pb2.Int32Value = proto.Field(
613 proto.MESSAGE,
614 number=4,
615 message=wrappers_pb2.Int32Value,
616 )
617 distance_result_field: str = proto.Field(
618 proto.STRING,
619 number=5,
620 )
621 distance_threshold: wrappers_pb2.DoubleValue = proto.Field(
622 proto.MESSAGE,
623 number=6,
624 message=wrappers_pb2.DoubleValue,
625 )
627 select: Projection = proto.Field(
628 proto.MESSAGE,
629 number=1,
630 message=Projection,
631 )
632 from_: MutableSequence[CollectionSelector] = proto.RepeatedField(
633 proto.MESSAGE,
634 number=2,
635 message=CollectionSelector,
636 )
637 where: Filter = proto.Field(
638 proto.MESSAGE,
639 number=3,
640 message=Filter,
641 )
642 order_by: MutableSequence[Order] = proto.RepeatedField(
643 proto.MESSAGE,
644 number=4,
645 message=Order,
646 )
647 start_at: "Cursor" = proto.Field(
648 proto.MESSAGE,
649 number=7,
650 message="Cursor",
651 )
652 end_at: "Cursor" = proto.Field(
653 proto.MESSAGE,
654 number=8,
655 message="Cursor",
656 )
657 offset: int = proto.Field(
658 proto.INT32,
659 number=6,
660 )
661 limit: wrappers_pb2.Int32Value = proto.Field(
662 proto.MESSAGE,
663 number=5,
664 message=wrappers_pb2.Int32Value,
665 )
666 find_nearest: FindNearest = proto.Field(
667 proto.MESSAGE,
668 number=9,
669 message=FindNearest,
670 )
673class StructuredAggregationQuery(proto.Message):
674 r"""Firestore query for running an aggregation over a
675 [StructuredQuery][google.firestore.v1.StructuredQuery].
678 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
680 Attributes:
681 structured_query (google.cloud.firestore_v1.types.StructuredQuery):
682 Nested structured query.
684 This field is a member of `oneof`_ ``query_type``.
685 aggregations (MutableSequence[google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation]):
686 Optional. Series of aggregations to apply over the results
687 of the ``structured_query``.
689 Requires:
691 - A minimum of one and maximum of five aggregations per
692 query.
693 """
695 class Aggregation(proto.Message):
696 r"""Defines an aggregation that produces a single result.
698 This message has `oneof`_ fields (mutually exclusive fields).
699 For each oneof, at most one member field can be set at the same time.
700 Setting any member of the oneof automatically clears all other
701 members.
703 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
705 Attributes:
706 count (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Count):
707 Count aggregator.
709 This field is a member of `oneof`_ ``operator``.
710 sum (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Sum):
711 Sum aggregator.
713 This field is a member of `oneof`_ ``operator``.
714 avg (google.cloud.firestore_v1.types.StructuredAggregationQuery.Aggregation.Avg):
715 Average aggregator.
717 This field is a member of `oneof`_ ``operator``.
718 alias (str):
719 Optional. Optional name of the field to store the result of
720 the aggregation into.
722 If not provided, Firestore will pick a default name
723 following the format ``field_<incremental_id++>``. For
724 example:
726 ::
728 AGGREGATE
729 COUNT_UP_TO(1) AS count_up_to_1,
730 COUNT_UP_TO(2),
731 COUNT_UP_TO(3) AS count_up_to_3,
732 COUNT(*)
733 OVER (
734 ...
735 );
737 becomes:
739 ::
741 AGGREGATE
742 COUNT_UP_TO(1) AS count_up_to_1,
743 COUNT_UP_TO(2) AS field_1,
744 COUNT_UP_TO(3) AS count_up_to_3,
745 COUNT(*) AS field_2
746 OVER (
747 ...
748 );
750 Requires:
752 - Must be unique across all aggregation aliases.
753 - Conform to [document field
754 name][google.firestore.v1.Document.fields] limitations.
755 """
757 class Count(proto.Message):
758 r"""Count of documents that match the query.
760 The ``COUNT(*)`` aggregation function operates on the entire
761 document so it does not require a field reference.
763 Attributes:
764 up_to (google.protobuf.wrappers_pb2.Int64Value):
765 Optional. Optional constraint on the maximum number of
766 documents to count.
768 This provides a way to set an upper bound on the number of
769 documents to scan, limiting latency, and cost.
771 Unspecified is interpreted as no bound.
773 High-Level Example:
775 ::
777 AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );
779 Requires:
781 - Must be greater than zero when present.
782 """
784 up_to: wrappers_pb2.Int64Value = proto.Field(
785 proto.MESSAGE,
786 number=1,
787 message=wrappers_pb2.Int64Value,
788 )
790 class Sum(proto.Message):
791 r"""Sum of the values of the requested field.
793 - Only numeric values will be aggregated. All non-numeric values
794 including ``NULL`` are skipped.
796 - If the aggregated values contain ``NaN``, returns ``NaN``.
797 Infinity math follows IEEE-754 standards.
799 - If the aggregated value set is empty, returns 0.
801 - Returns a 64-bit integer if all aggregated numbers are integers
802 and the sum result does not overflow. Otherwise, the result is
803 returned as a double. Note that even if all the aggregated values
804 are integers, the result is returned as a double if it cannot fit
805 within a 64-bit signed integer. When this occurs, the returned
806 value will lose precision.
808 - When underflow occurs, floating-point aggregation is
809 non-deterministic. This means that running the same query
810 repeatedly without any changes to the underlying values could
811 produce slightly different results each time. In those cases,
812 values should be stored as integers over floating-point numbers.
814 Attributes:
815 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
816 The field to aggregate on.
817 """
819 field: "StructuredQuery.FieldReference" = proto.Field(
820 proto.MESSAGE,
821 number=1,
822 message="StructuredQuery.FieldReference",
823 )
825 class Avg(proto.Message):
826 r"""Average of the values of the requested field.
828 - Only numeric values will be aggregated. All non-numeric values
829 including ``NULL`` are skipped.
831 - If the aggregated values contain ``NaN``, returns ``NaN``.
832 Infinity math follows IEEE-754 standards.
834 - If the aggregated value set is empty, returns ``NULL``.
836 - Always returns the result as a double.
838 Attributes:
839 field (google.cloud.firestore_v1.types.StructuredQuery.FieldReference):
840 The field to aggregate on.
841 """
843 field: "StructuredQuery.FieldReference" = proto.Field(
844 proto.MESSAGE,
845 number=1,
846 message="StructuredQuery.FieldReference",
847 )
849 count: "StructuredAggregationQuery.Aggregation.Count" = proto.Field(
850 proto.MESSAGE,
851 number=1,
852 oneof="operator",
853 message="StructuredAggregationQuery.Aggregation.Count",
854 )
855 sum: "StructuredAggregationQuery.Aggregation.Sum" = proto.Field(
856 proto.MESSAGE,
857 number=2,
858 oneof="operator",
859 message="StructuredAggregationQuery.Aggregation.Sum",
860 )
861 avg: "StructuredAggregationQuery.Aggregation.Avg" = proto.Field(
862 proto.MESSAGE,
863 number=3,
864 oneof="operator",
865 message="StructuredAggregationQuery.Aggregation.Avg",
866 )
867 alias: str = proto.Field(
868 proto.STRING,
869 number=7,
870 )
872 structured_query: "StructuredQuery" = proto.Field(
873 proto.MESSAGE,
874 number=1,
875 oneof="query_type",
876 message="StructuredQuery",
877 )
878 aggregations: MutableSequence[Aggregation] = proto.RepeatedField(
879 proto.MESSAGE,
880 number=3,
881 message=Aggregation,
882 )
885class Cursor(proto.Message):
886 r"""A position in a query result set.
888 Attributes:
889 values (MutableSequence[google.cloud.firestore_v1.types.Value]):
890 The values that represent a position, in the
891 order they appear in the order by clause of a
892 query.
894 Can contain fewer values than specified in the
895 order by clause.
896 before (bool):
897 If the position is just before or just after
898 the given values, relative to the sort order
899 defined by the query.
900 """
902 values: MutableSequence[document.Value] = proto.RepeatedField(
903 proto.MESSAGE,
904 number=1,
905 message=document.Value,
906 )
907 before: bool = proto.Field(
908 proto.BOOL,
909 number=2,
910 )
913__all__ = tuple(sorted(__protobuf__.manifest))