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 aggregation_result
23from google.cloud.firestore_v1.types import common
24from google.cloud.firestore_v1.types import document as gf_document
25from google.cloud.firestore_v1.types import explain_stats as gf_explain_stats
26from google.cloud.firestore_v1.types import pipeline
27from google.cloud.firestore_v1.types import query as gf_query
28from google.cloud.firestore_v1.types import query_profile
29from google.cloud.firestore_v1.types import write
30from google.protobuf import timestamp_pb2 # type: ignore
31from google.protobuf import wrappers_pb2 # type: ignore
32from google.rpc import status_pb2 # type: ignore
35__protobuf__ = proto.module(
36 package="google.firestore.v1",
37 manifest={
38 "GetDocumentRequest",
39 "ListDocumentsRequest",
40 "ListDocumentsResponse",
41 "CreateDocumentRequest",
42 "UpdateDocumentRequest",
43 "DeleteDocumentRequest",
44 "BatchGetDocumentsRequest",
45 "BatchGetDocumentsResponse",
46 "BeginTransactionRequest",
47 "BeginTransactionResponse",
48 "CommitRequest",
49 "CommitResponse",
50 "RollbackRequest",
51 "RunQueryRequest",
52 "RunQueryResponse",
53 "ExecutePipelineRequest",
54 "ExecutePipelineResponse",
55 "RunAggregationQueryRequest",
56 "RunAggregationQueryResponse",
57 "PartitionQueryRequest",
58 "PartitionQueryResponse",
59 "WriteRequest",
60 "WriteResponse",
61 "ListenRequest",
62 "ListenResponse",
63 "Target",
64 "TargetChange",
65 "ListCollectionIdsRequest",
66 "ListCollectionIdsResponse",
67 "BatchWriteRequest",
68 "BatchWriteResponse",
69 },
70)
73class GetDocumentRequest(proto.Message):
74 r"""The request for
75 [Firestore.GetDocument][google.firestore.v1.Firestore.GetDocument].
77 This message has `oneof`_ fields (mutually exclusive fields).
78 For each oneof, at most one member field can be set at the same time.
79 Setting any member of the oneof automatically clears all other
80 members.
82 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
84 Attributes:
85 name (str):
86 Required. The resource name of the Document to get. In the
87 format:
88 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
89 mask (google.cloud.firestore_v1.types.DocumentMask):
90 The fields to return. If not set, returns all
91 fields.
92 If the document has a field that is not present
93 in this mask, that field will not be returned in
94 the response.
95 transaction (bytes):
96 Reads the document in a transaction.
98 This field is a member of `oneof`_ ``consistency_selector``.
99 read_time (google.protobuf.timestamp_pb2.Timestamp):
100 Reads the version of the document at the
101 given time.
102 This must be a microsecond precision timestamp
103 within the past one hour, or if Point-in-Time
104 Recovery is enabled, can additionally be a whole
105 minute timestamp within the past 7 days.
107 This field is a member of `oneof`_ ``consistency_selector``.
108 """
110 name: str = proto.Field(
111 proto.STRING,
112 number=1,
113 )
114 mask: common.DocumentMask = proto.Field(
115 proto.MESSAGE,
116 number=2,
117 message=common.DocumentMask,
118 )
119 transaction: bytes = proto.Field(
120 proto.BYTES,
121 number=3,
122 oneof="consistency_selector",
123 )
124 read_time: timestamp_pb2.Timestamp = proto.Field(
125 proto.MESSAGE,
126 number=5,
127 oneof="consistency_selector",
128 message=timestamp_pb2.Timestamp,
129 )
132class ListDocumentsRequest(proto.Message):
133 r"""The request for
134 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].
136 This message has `oneof`_ fields (mutually exclusive fields).
137 For each oneof, at most one member field can be set at the same time.
138 Setting any member of the oneof automatically clears all other
139 members.
141 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
143 Attributes:
144 parent (str):
145 Required. The parent resource name. In the format:
146 ``projects/{project_id}/databases/{database_id}/documents``
147 or
148 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
150 For example:
151 ``projects/my-project/databases/my-database/documents`` or
152 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
153 collection_id (str):
154 Optional. The collection ID, relative to ``parent``, to
155 list.
157 For example: ``chatrooms`` or ``messages``.
159 This is optional, and when not provided, Firestore will list
160 documents from all collections under the provided
161 ``parent``.
162 page_size (int):
163 Optional. The maximum number of documents to
164 return in a single response.
165 Firestore may return fewer than this value.
166 page_token (str):
167 Optional. A page token, received from a previous
168 ``ListDocuments`` response.
170 Provide this to retrieve the subsequent page. When
171 paginating, all other parameters (with the exception of
172 ``page_size``) must match the values set in the request that
173 generated the page token.
174 order_by (str):
175 Optional. The optional ordering of the documents to return.
177 For example: ``priority desc, __name__ desc``.
179 This mirrors the
180 [``ORDER BY``][google.firestore.v1.StructuredQuery.order_by]
181 used in Firestore queries but in a string representation.
182 When absent, documents are ordered based on
183 ``__name__ ASC``.
184 mask (google.cloud.firestore_v1.types.DocumentMask):
185 Optional. The fields to return. If not set,
186 returns all fields.
187 If a document has a field that is not present in
188 this mask, that field will not be returned in
189 the response.
190 transaction (bytes):
191 Perform the read as part of an already active
192 transaction.
194 This field is a member of `oneof`_ ``consistency_selector``.
195 read_time (google.protobuf.timestamp_pb2.Timestamp):
196 Perform the read at the provided time.
198 This must be a microsecond precision timestamp
199 within the past one hour, or if Point-in-Time
200 Recovery is enabled, can additionally be a whole
201 minute timestamp within the past 7 days.
203 This field is a member of `oneof`_ ``consistency_selector``.
204 show_missing (bool):
205 If the list should show missing documents.
207 A document is missing if it does not exist, but there are
208 sub-documents nested underneath it. When true, such missing
209 documents will be returned with a key but will not have
210 fields,
211 [``create_time``][google.firestore.v1.Document.create_time],
212 or
213 [``update_time``][google.firestore.v1.Document.update_time]
214 set.
216 Requests with ``show_missing`` may not specify ``where`` or
217 ``order_by``.
218 """
220 parent: str = proto.Field(
221 proto.STRING,
222 number=1,
223 )
224 collection_id: str = proto.Field(
225 proto.STRING,
226 number=2,
227 )
228 page_size: int = proto.Field(
229 proto.INT32,
230 number=3,
231 )
232 page_token: str = proto.Field(
233 proto.STRING,
234 number=4,
235 )
236 order_by: str = proto.Field(
237 proto.STRING,
238 number=6,
239 )
240 mask: common.DocumentMask = proto.Field(
241 proto.MESSAGE,
242 number=7,
243 message=common.DocumentMask,
244 )
245 transaction: bytes = proto.Field(
246 proto.BYTES,
247 number=8,
248 oneof="consistency_selector",
249 )
250 read_time: timestamp_pb2.Timestamp = proto.Field(
251 proto.MESSAGE,
252 number=10,
253 oneof="consistency_selector",
254 message=timestamp_pb2.Timestamp,
255 )
256 show_missing: bool = proto.Field(
257 proto.BOOL,
258 number=12,
259 )
262class ListDocumentsResponse(proto.Message):
263 r"""The response for
264 [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].
266 Attributes:
267 documents (MutableSequence[google.cloud.firestore_v1.types.Document]):
268 The Documents found.
269 next_page_token (str):
270 A token to retrieve the next page of
271 documents.
272 If this field is omitted, there are no
273 subsequent pages.
274 """
276 @property
277 def raw_page(self):
278 return self
280 documents: MutableSequence[gf_document.Document] = proto.RepeatedField(
281 proto.MESSAGE,
282 number=1,
283 message=gf_document.Document,
284 )
285 next_page_token: str = proto.Field(
286 proto.STRING,
287 number=2,
288 )
291class CreateDocumentRequest(proto.Message):
292 r"""The request for
293 [Firestore.CreateDocument][google.firestore.v1.Firestore.CreateDocument].
295 Attributes:
296 parent (str):
297 Required. The parent resource. For example:
298 ``projects/{project_id}/databases/{database_id}/documents``
299 or
300 ``projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}``
301 collection_id (str):
302 Required. The collection ID, relative to ``parent``, to
303 list. For example: ``chatrooms``.
304 document_id (str):
305 The client-assigned document ID to use for
306 this document.
307 Optional. If not specified, an ID will be
308 assigned by the service.
309 document (google.cloud.firestore_v1.types.Document):
310 Required. The document to create. ``name`` must not be set.
311 mask (google.cloud.firestore_v1.types.DocumentMask):
312 The fields to return. If not set, returns all
313 fields.
314 If the document has a field that is not present
315 in this mask, that field will not be returned in
316 the response.
317 """
319 parent: str = proto.Field(
320 proto.STRING,
321 number=1,
322 )
323 collection_id: str = proto.Field(
324 proto.STRING,
325 number=2,
326 )
327 document_id: str = proto.Field(
328 proto.STRING,
329 number=3,
330 )
331 document: gf_document.Document = proto.Field(
332 proto.MESSAGE,
333 number=4,
334 message=gf_document.Document,
335 )
336 mask: common.DocumentMask = proto.Field(
337 proto.MESSAGE,
338 number=5,
339 message=common.DocumentMask,
340 )
343class UpdateDocumentRequest(proto.Message):
344 r"""The request for
345 [Firestore.UpdateDocument][google.firestore.v1.Firestore.UpdateDocument].
347 Attributes:
348 document (google.cloud.firestore_v1.types.Document):
349 Required. The updated document.
350 Creates the document if it does not already
351 exist.
352 update_mask (google.cloud.firestore_v1.types.DocumentMask):
353 The fields to update.
354 None of the field paths in the mask may contain
355 a reserved name.
357 If the document exists on the server and has
358 fields not referenced in the mask, they are left
359 unchanged.
360 Fields referenced in the mask, but not present
361 in the input document, are deleted from the
362 document on the server.
363 mask (google.cloud.firestore_v1.types.DocumentMask):
364 The fields to return. If not set, returns all
365 fields.
366 If the document has a field that is not present
367 in this mask, that field will not be returned in
368 the response.
369 current_document (google.cloud.firestore_v1.types.Precondition):
370 An optional precondition on the document.
371 The request will fail if this is set and not met
372 by the target document.
373 """
375 document: gf_document.Document = proto.Field(
376 proto.MESSAGE,
377 number=1,
378 message=gf_document.Document,
379 )
380 update_mask: common.DocumentMask = proto.Field(
381 proto.MESSAGE,
382 number=2,
383 message=common.DocumentMask,
384 )
385 mask: common.DocumentMask = proto.Field(
386 proto.MESSAGE,
387 number=3,
388 message=common.DocumentMask,
389 )
390 current_document: common.Precondition = proto.Field(
391 proto.MESSAGE,
392 number=4,
393 message=common.Precondition,
394 )
397class DeleteDocumentRequest(proto.Message):
398 r"""The request for
399 [Firestore.DeleteDocument][google.firestore.v1.Firestore.DeleteDocument].
401 Attributes:
402 name (str):
403 Required. The resource name of the Document to delete. In
404 the format:
405 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
406 current_document (google.cloud.firestore_v1.types.Precondition):
407 An optional precondition on the document.
408 The request will fail if this is set and not met
409 by the target document.
410 """
412 name: str = proto.Field(
413 proto.STRING,
414 number=1,
415 )
416 current_document: common.Precondition = proto.Field(
417 proto.MESSAGE,
418 number=2,
419 message=common.Precondition,
420 )
423class BatchGetDocumentsRequest(proto.Message):
424 r"""The request for
425 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].
427 This message has `oneof`_ fields (mutually exclusive fields).
428 For each oneof, at most one member field can be set at the same time.
429 Setting any member of the oneof automatically clears all other
430 members.
432 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
434 Attributes:
435 database (str):
436 Required. The database name. In the format:
437 ``projects/{project_id}/databases/{database_id}``.
438 documents (MutableSequence[str]):
439 The names of the documents to retrieve. In the format:
440 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
441 The request will fail if any of the document is not a child
442 resource of the given ``database``. Duplicate names will be
443 elided.
444 mask (google.cloud.firestore_v1.types.DocumentMask):
445 The fields to return. If not set, returns all
446 fields.
447 If a document has a field that is not present in
448 this mask, that field will not be returned in
449 the response.
450 transaction (bytes):
451 Reads documents in a transaction.
453 This field is a member of `oneof`_ ``consistency_selector``.
454 new_transaction (google.cloud.firestore_v1.types.TransactionOptions):
455 Starts a new transaction and reads the
456 documents. Defaults to a read-only transaction.
457 The new transaction ID will be returned as the
458 first response in the stream.
460 This field is a member of `oneof`_ ``consistency_selector``.
461 read_time (google.protobuf.timestamp_pb2.Timestamp):
462 Reads documents as they were at the given
463 time.
464 This must be a microsecond precision timestamp
465 within the past one hour, or if Point-in-Time
466 Recovery is enabled, can additionally be a whole
467 minute timestamp within the past 7 days.
469 This field is a member of `oneof`_ ``consistency_selector``.
470 """
472 database: str = proto.Field(
473 proto.STRING,
474 number=1,
475 )
476 documents: MutableSequence[str] = proto.RepeatedField(
477 proto.STRING,
478 number=2,
479 )
480 mask: common.DocumentMask = proto.Field(
481 proto.MESSAGE,
482 number=3,
483 message=common.DocumentMask,
484 )
485 transaction: bytes = proto.Field(
486 proto.BYTES,
487 number=4,
488 oneof="consistency_selector",
489 )
490 new_transaction: common.TransactionOptions = proto.Field(
491 proto.MESSAGE,
492 number=5,
493 oneof="consistency_selector",
494 message=common.TransactionOptions,
495 )
496 read_time: timestamp_pb2.Timestamp = proto.Field(
497 proto.MESSAGE,
498 number=7,
499 oneof="consistency_selector",
500 message=timestamp_pb2.Timestamp,
501 )
504class BatchGetDocumentsResponse(proto.Message):
505 r"""The streamed response for
506 [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].
508 This message has `oneof`_ fields (mutually exclusive fields).
509 For each oneof, at most one member field can be set at the same time.
510 Setting any member of the oneof automatically clears all other
511 members.
513 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
515 Attributes:
516 found (google.cloud.firestore_v1.types.Document):
517 A document that was requested.
519 This field is a member of `oneof`_ ``result``.
520 missing (str):
521 A document name that was requested but does not exist. In
522 the format:
523 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
525 This field is a member of `oneof`_ ``result``.
526 transaction (bytes):
527 The transaction that was started as part of this request.
528 Will only be set in the first response, and only if
529 [BatchGetDocumentsRequest.new_transaction][google.firestore.v1.BatchGetDocumentsRequest.new_transaction]
530 was set in the request.
531 read_time (google.protobuf.timestamp_pb2.Timestamp):
532 The time at which the document was read. This may be
533 monotically increasing, in this case the previous documents
534 in the result stream are guaranteed not to have changed
535 between their read_time and this one.
536 """
538 found: gf_document.Document = proto.Field(
539 proto.MESSAGE,
540 number=1,
541 oneof="result",
542 message=gf_document.Document,
543 )
544 missing: str = proto.Field(
545 proto.STRING,
546 number=2,
547 oneof="result",
548 )
549 transaction: bytes = proto.Field(
550 proto.BYTES,
551 number=3,
552 )
553 read_time: timestamp_pb2.Timestamp = proto.Field(
554 proto.MESSAGE,
555 number=4,
556 message=timestamp_pb2.Timestamp,
557 )
560class BeginTransactionRequest(proto.Message):
561 r"""The request for
562 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].
564 Attributes:
565 database (str):
566 Required. The database name. In the format:
567 ``projects/{project_id}/databases/{database_id}``.
568 options (google.cloud.firestore_v1.types.TransactionOptions):
569 The options for the transaction.
570 Defaults to a read-write transaction.
571 """
573 database: str = proto.Field(
574 proto.STRING,
575 number=1,
576 )
577 options: common.TransactionOptions = proto.Field(
578 proto.MESSAGE,
579 number=2,
580 message=common.TransactionOptions,
581 )
584class BeginTransactionResponse(proto.Message):
585 r"""The response for
586 [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].
588 Attributes:
589 transaction (bytes):
590 The transaction that was started.
591 """
593 transaction: bytes = proto.Field(
594 proto.BYTES,
595 number=1,
596 )
599class CommitRequest(proto.Message):
600 r"""The request for
601 [Firestore.Commit][google.firestore.v1.Firestore.Commit].
603 Attributes:
604 database (str):
605 Required. The database name. In the format:
606 ``projects/{project_id}/databases/{database_id}``.
607 writes (MutableSequence[google.cloud.firestore_v1.types.Write]):
608 The writes to apply.
610 Always executed atomically and in order.
611 transaction (bytes):
612 If set, applies all writes in this
613 transaction, and commits it.
614 """
616 database: str = proto.Field(
617 proto.STRING,
618 number=1,
619 )
620 writes: MutableSequence[write.Write] = proto.RepeatedField(
621 proto.MESSAGE,
622 number=2,
623 message=write.Write,
624 )
625 transaction: bytes = proto.Field(
626 proto.BYTES,
627 number=3,
628 )
631class CommitResponse(proto.Message):
632 r"""The response for
633 [Firestore.Commit][google.firestore.v1.Firestore.Commit].
635 Attributes:
636 write_results (MutableSequence[google.cloud.firestore_v1.types.WriteResult]):
637 The result of applying the writes.
639 This i-th write result corresponds to the i-th
640 write in the request.
641 commit_time (google.protobuf.timestamp_pb2.Timestamp):
642 The time at which the commit occurred. Any read with an
643 equal or greater ``read_time`` is guaranteed to see the
644 effects of the commit.
645 """
647 write_results: MutableSequence[write.WriteResult] = proto.RepeatedField(
648 proto.MESSAGE,
649 number=1,
650 message=write.WriteResult,
651 )
652 commit_time: timestamp_pb2.Timestamp = proto.Field(
653 proto.MESSAGE,
654 number=2,
655 message=timestamp_pb2.Timestamp,
656 )
659class RollbackRequest(proto.Message):
660 r"""The request for
661 [Firestore.Rollback][google.firestore.v1.Firestore.Rollback].
663 Attributes:
664 database (str):
665 Required. The database name. In the format:
666 ``projects/{project_id}/databases/{database_id}``.
667 transaction (bytes):
668 Required. The transaction to roll back.
669 """
671 database: str = proto.Field(
672 proto.STRING,
673 number=1,
674 )
675 transaction: bytes = proto.Field(
676 proto.BYTES,
677 number=2,
678 )
681class RunQueryRequest(proto.Message):
682 r"""The request for
683 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].
685 This message has `oneof`_ fields (mutually exclusive fields).
686 For each oneof, at most one member field can be set at the same time.
687 Setting any member of the oneof automatically clears all other
688 members.
690 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
692 Attributes:
693 parent (str):
694 Required. The parent resource name. In the format:
695 ``projects/{project_id}/databases/{database_id}/documents``
696 or
697 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
698 For example:
699 ``projects/my-project/databases/my-database/documents`` or
700 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
701 structured_query (google.cloud.firestore_v1.types.StructuredQuery):
702 A structured query.
704 This field is a member of `oneof`_ ``query_type``.
705 transaction (bytes):
706 Run the query within an already active
707 transaction.
708 The value here is the opaque transaction ID to
709 execute the query in.
711 This field is a member of `oneof`_ ``consistency_selector``.
712 new_transaction (google.cloud.firestore_v1.types.TransactionOptions):
713 Starts a new transaction and reads the
714 documents. Defaults to a read-only transaction.
715 The new transaction ID will be returned as the
716 first response in the stream.
718 This field is a member of `oneof`_ ``consistency_selector``.
719 read_time (google.protobuf.timestamp_pb2.Timestamp):
720 Reads documents as they were at the given
721 time.
722 This must be a microsecond precision timestamp
723 within the past one hour, or if Point-in-Time
724 Recovery is enabled, can additionally be a whole
725 minute timestamp within the past 7 days.
727 This field is a member of `oneof`_ ``consistency_selector``.
728 explain_options (google.cloud.firestore_v1.types.ExplainOptions):
729 Optional. Explain options for the query. If
730 set, additional query statistics will be
731 returned. If not, only query results will be
732 returned.
733 """
735 parent: str = proto.Field(
736 proto.STRING,
737 number=1,
738 )
739 structured_query: gf_query.StructuredQuery = proto.Field(
740 proto.MESSAGE,
741 number=2,
742 oneof="query_type",
743 message=gf_query.StructuredQuery,
744 )
745 transaction: bytes = proto.Field(
746 proto.BYTES,
747 number=5,
748 oneof="consistency_selector",
749 )
750 new_transaction: common.TransactionOptions = proto.Field(
751 proto.MESSAGE,
752 number=6,
753 oneof="consistency_selector",
754 message=common.TransactionOptions,
755 )
756 read_time: timestamp_pb2.Timestamp = proto.Field(
757 proto.MESSAGE,
758 number=7,
759 oneof="consistency_selector",
760 message=timestamp_pb2.Timestamp,
761 )
762 explain_options: query_profile.ExplainOptions = proto.Field(
763 proto.MESSAGE,
764 number=10,
765 message=query_profile.ExplainOptions,
766 )
769class RunQueryResponse(proto.Message):
770 r"""The response for
771 [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].
774 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
776 Attributes:
777 transaction (bytes):
778 The transaction that was started as part of this request.
779 Can only be set in the first response, and only if
780 [RunQueryRequest.new_transaction][google.firestore.v1.RunQueryRequest.new_transaction]
781 was set in the request. If set, no other fields will be set
782 in this response.
783 document (google.cloud.firestore_v1.types.Document):
784 A query result, not set when reporting
785 partial progress.
786 read_time (google.protobuf.timestamp_pb2.Timestamp):
787 The time at which the document was read. This may be
788 monotonically increasing; in this case, the previous
789 documents in the result stream are guaranteed not to have
790 changed between their ``read_time`` and this one.
792 If the query returns no results, a response with
793 ``read_time`` and no ``document`` will be sent, and this
794 represents the time at which the query was run.
795 skipped_results (int):
796 The number of results that have been skipped
797 due to an offset between the last response and
798 the current response.
799 done (bool):
800 If present, Firestore has completely finished
801 the request and no more documents will be
802 returned.
804 This field is a member of `oneof`_ ``continuation_selector``.
805 explain_metrics (google.cloud.firestore_v1.types.ExplainMetrics):
806 Query explain metrics. This is only present when the
807 [RunQueryRequest.explain_options][google.firestore.v1.RunQueryRequest.explain_options]
808 is provided, and it is sent only once with the last response
809 in the stream.
810 """
812 transaction: bytes = proto.Field(
813 proto.BYTES,
814 number=2,
815 )
816 document: gf_document.Document = proto.Field(
817 proto.MESSAGE,
818 number=1,
819 message=gf_document.Document,
820 )
821 read_time: timestamp_pb2.Timestamp = proto.Field(
822 proto.MESSAGE,
823 number=3,
824 message=timestamp_pb2.Timestamp,
825 )
826 skipped_results: int = proto.Field(
827 proto.INT32,
828 number=4,
829 )
830 done: bool = proto.Field(
831 proto.BOOL,
832 number=6,
833 oneof="continuation_selector",
834 )
835 explain_metrics: query_profile.ExplainMetrics = proto.Field(
836 proto.MESSAGE,
837 number=11,
838 message=query_profile.ExplainMetrics,
839 )
842class ExecutePipelineRequest(proto.Message):
843 r"""The request for
844 [Firestore.ExecutePipeline][google.firestore.v1.Firestore.ExecutePipeline].
846 This message has `oneof`_ fields (mutually exclusive fields).
847 For each oneof, at most one member field can be set at the same time.
848 Setting any member of the oneof automatically clears all other
849 members.
851 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
853 Attributes:
854 database (str):
855 Required. Database identifier, in the form
856 ``projects/{project}/databases/{database}``.
857 structured_pipeline (google.cloud.firestore_v1.types.StructuredPipeline):
858 A pipelined operation.
860 This field is a member of `oneof`_ ``pipeline_type``.
861 transaction (bytes):
862 Run the query within an already active
863 transaction.
864 The value here is the opaque transaction ID to
865 execute the query in.
867 This field is a member of `oneof`_ ``consistency_selector``.
868 new_transaction (google.cloud.firestore_v1.types.TransactionOptions):
869 Execute the pipeline in a new transaction.
871 The identifier of the newly created transaction
872 will be returned in the first response on the
873 stream. This defaults to a read-only
874 transaction.
876 This field is a member of `oneof`_ ``consistency_selector``.
877 read_time (google.protobuf.timestamp_pb2.Timestamp):
878 Execute the pipeline in a snapshot
879 transaction at the given time.
880 This must be a microsecond precision timestamp
881 within the past one hour, or if Point-in-Time
882 Recovery is enabled, can additionally be a whole
883 minute timestamp within the past 7 days.
885 This field is a member of `oneof`_ ``consistency_selector``.
886 """
888 database: str = proto.Field(
889 proto.STRING,
890 number=1,
891 )
892 structured_pipeline: pipeline.StructuredPipeline = proto.Field(
893 proto.MESSAGE,
894 number=2,
895 oneof="pipeline_type",
896 message=pipeline.StructuredPipeline,
897 )
898 transaction: bytes = proto.Field(
899 proto.BYTES,
900 number=5,
901 oneof="consistency_selector",
902 )
903 new_transaction: common.TransactionOptions = proto.Field(
904 proto.MESSAGE,
905 number=6,
906 oneof="consistency_selector",
907 message=common.TransactionOptions,
908 )
909 read_time: timestamp_pb2.Timestamp = proto.Field(
910 proto.MESSAGE,
911 number=7,
912 oneof="consistency_selector",
913 message=timestamp_pb2.Timestamp,
914 )
917class ExecutePipelineResponse(proto.Message):
918 r"""The response for [Firestore.Execute][].
920 Attributes:
921 transaction (bytes):
922 Newly created transaction identifier.
924 This field is only specified as part of the first response
925 from the server, alongside the ``results`` field when the
926 original request specified
927 [ExecuteRequest.new_transaction][].
928 results (MutableSequence[google.cloud.firestore_v1.types.Document]):
929 An ordered batch of results returned executing a pipeline.
931 The batch size is variable, and can even be zero for when
932 only a partial progress message is returned.
934 The fields present in the returned documents are only those
935 that were explicitly requested in the pipeline, this
936 includes those like
937 [``__name__``][google.firestore.v1.Document.name] and
938 [``__update_time__``][google.firestore.v1.Document.update_time].
939 This is explicitly a divergence from ``Firestore.RunQuery``
940 / ``Firestore.GetDocument`` RPCs which always return such
941 fields even when they are not specified in the
942 [``mask``][google.firestore.v1.DocumentMask].
943 execution_time (google.protobuf.timestamp_pb2.Timestamp):
944 The time at which the results are valid.
946 This is a (not strictly) monotonically increasing value
947 across multiple responses in the same stream. The API
948 guarantees that all previously returned results are still
949 valid at the latest ``execution_time``. This allows the API
950 consumer to treat the query if it ran at the latest
951 ``execution_time`` returned.
953 If the query returns no results, a response with
954 ``execution_time`` and no ``results`` will be sent, and this
955 represents the time at which the operation was run.
956 explain_stats (google.cloud.firestore_v1.types.ExplainStats):
957 Query explain stats.
959 This is present on the **last** response if the request
960 configured explain to run in 'analyze' or 'explain' mode in
961 the pipeline options. If the query does not return any
962 results, a response with ``explain_stats`` and no
963 ``results`` will still be sent.
964 """
966 transaction: bytes = proto.Field(
967 proto.BYTES,
968 number=1,
969 )
970 results: MutableSequence[gf_document.Document] = proto.RepeatedField(
971 proto.MESSAGE,
972 number=2,
973 message=gf_document.Document,
974 )
975 execution_time: timestamp_pb2.Timestamp = proto.Field(
976 proto.MESSAGE,
977 number=3,
978 message=timestamp_pb2.Timestamp,
979 )
980 explain_stats: gf_explain_stats.ExplainStats = proto.Field(
981 proto.MESSAGE,
982 number=4,
983 message=gf_explain_stats.ExplainStats,
984 )
987class RunAggregationQueryRequest(proto.Message):
988 r"""The request for
989 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
991 This message has `oneof`_ fields (mutually exclusive fields).
992 For each oneof, at most one member field can be set at the same time.
993 Setting any member of the oneof automatically clears all other
994 members.
996 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
998 Attributes:
999 parent (str):
1000 Required. The parent resource name. In the format:
1001 ``projects/{project_id}/databases/{database_id}/documents``
1002 or
1003 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
1004 For example:
1005 ``projects/my-project/databases/my-database/documents`` or
1006 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
1007 structured_aggregation_query (google.cloud.firestore_v1.types.StructuredAggregationQuery):
1008 An aggregation query.
1010 This field is a member of `oneof`_ ``query_type``.
1011 transaction (bytes):
1012 Run the aggregation within an already active
1013 transaction.
1014 The value here is the opaque transaction ID to
1015 execute the query in.
1017 This field is a member of `oneof`_ ``consistency_selector``.
1018 new_transaction (google.cloud.firestore_v1.types.TransactionOptions):
1019 Starts a new transaction as part of the
1020 query, defaulting to read-only.
1021 The new transaction ID will be returned as the
1022 first response in the stream.
1024 This field is a member of `oneof`_ ``consistency_selector``.
1025 read_time (google.protobuf.timestamp_pb2.Timestamp):
1026 Executes the query at the given timestamp.
1028 This must be a microsecond precision timestamp
1029 within the past one hour, or if Point-in-Time
1030 Recovery is enabled, can additionally be a whole
1031 minute timestamp within the past 7 days.
1033 This field is a member of `oneof`_ ``consistency_selector``.
1034 explain_options (google.cloud.firestore_v1.types.ExplainOptions):
1035 Optional. Explain options for the query. If
1036 set, additional query statistics will be
1037 returned. If not, only query results will be
1038 returned.
1039 """
1041 parent: str = proto.Field(
1042 proto.STRING,
1043 number=1,
1044 )
1045 structured_aggregation_query: gf_query.StructuredAggregationQuery = proto.Field(
1046 proto.MESSAGE,
1047 number=2,
1048 oneof="query_type",
1049 message=gf_query.StructuredAggregationQuery,
1050 )
1051 transaction: bytes = proto.Field(
1052 proto.BYTES,
1053 number=4,
1054 oneof="consistency_selector",
1055 )
1056 new_transaction: common.TransactionOptions = proto.Field(
1057 proto.MESSAGE,
1058 number=5,
1059 oneof="consistency_selector",
1060 message=common.TransactionOptions,
1061 )
1062 read_time: timestamp_pb2.Timestamp = proto.Field(
1063 proto.MESSAGE,
1064 number=6,
1065 oneof="consistency_selector",
1066 message=timestamp_pb2.Timestamp,
1067 )
1068 explain_options: query_profile.ExplainOptions = proto.Field(
1069 proto.MESSAGE,
1070 number=8,
1071 message=query_profile.ExplainOptions,
1072 )
1075class RunAggregationQueryResponse(proto.Message):
1076 r"""The response for
1077 [Firestore.RunAggregationQuery][google.firestore.v1.Firestore.RunAggregationQuery].
1079 Attributes:
1080 result (google.cloud.firestore_v1.types.AggregationResult):
1081 A single aggregation result.
1083 Not present when reporting partial progress.
1084 transaction (bytes):
1085 The transaction that was started as part of
1086 this request.
1087 Only present on the first response when the
1088 request requested to start a new transaction.
1089 read_time (google.protobuf.timestamp_pb2.Timestamp):
1090 The time at which the aggregate result was computed. This is
1091 always monotonically increasing; in this case, the previous
1092 AggregationResult in the result stream are guaranteed not to
1093 have changed between their ``read_time`` and this one.
1095 If the query returns no results, a response with
1096 ``read_time`` and no ``result`` will be sent, and this
1097 represents the time at which the query was run.
1098 explain_metrics (google.cloud.firestore_v1.types.ExplainMetrics):
1099 Query explain metrics. This is only present when the
1100 [RunAggregationQueryRequest.explain_options][google.firestore.v1.RunAggregationQueryRequest.explain_options]
1101 is provided, and it is sent only once with the last response
1102 in the stream.
1103 """
1105 result: aggregation_result.AggregationResult = proto.Field(
1106 proto.MESSAGE,
1107 number=1,
1108 message=aggregation_result.AggregationResult,
1109 )
1110 transaction: bytes = proto.Field(
1111 proto.BYTES,
1112 number=2,
1113 )
1114 read_time: timestamp_pb2.Timestamp = proto.Field(
1115 proto.MESSAGE,
1116 number=3,
1117 message=timestamp_pb2.Timestamp,
1118 )
1119 explain_metrics: query_profile.ExplainMetrics = proto.Field(
1120 proto.MESSAGE,
1121 number=10,
1122 message=query_profile.ExplainMetrics,
1123 )
1126class PartitionQueryRequest(proto.Message):
1127 r"""The request for
1128 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].
1131 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1133 Attributes:
1134 parent (str):
1135 Required. The parent resource name. In the format:
1136 ``projects/{project_id}/databases/{database_id}/documents``.
1137 Document resource names are not supported; only database
1138 resource names can be specified.
1139 structured_query (google.cloud.firestore_v1.types.StructuredQuery):
1140 A structured query.
1141 Query must specify collection with all
1142 descendants and be ordered by name ascending.
1143 Other filters, order bys, limits, offsets, and
1144 start/end cursors are not supported.
1146 This field is a member of `oneof`_ ``query_type``.
1147 partition_count (int):
1148 The desired maximum number of partition
1149 points. The partitions may be returned across
1150 multiple pages of results. The number must be
1151 positive. The actual number of partitions
1152 returned may be fewer.
1154 For example, this may be set to one fewer than
1155 the number of parallel queries to be run, or in
1156 running a data pipeline job, one fewer than the
1157 number of workers or compute instances
1158 available.
1159 page_token (str):
1160 The ``next_page_token`` value returned from a previous call
1161 to PartitionQuery that may be used to get an additional set
1162 of results. There are no ordering guarantees between sets of
1163 results. Thus, using multiple sets of results will require
1164 merging the different result sets.
1166 For example, two subsequent calls using a page_token may
1167 return:
1169 - cursor B, cursor M, cursor Q
1170 - cursor A, cursor U, cursor W
1172 To obtain a complete result set ordered with respect to the
1173 results of the query supplied to PartitionQuery, the results
1174 sets should be merged: cursor A, cursor B, cursor M, cursor
1175 Q, cursor U, cursor W
1176 page_size (int):
1177 The maximum number of partitions to return in this call,
1178 subject to ``partition_count``.
1180 For example, if ``partition_count`` = 10 and ``page_size`` =
1181 8, the first call to PartitionQuery will return up to 8
1182 partitions and a ``next_page_token`` if more results exist.
1183 A second call to PartitionQuery will return up to 2
1184 partitions, to complete the total of 10 specified in
1185 ``partition_count``.
1186 read_time (google.protobuf.timestamp_pb2.Timestamp):
1187 Reads documents as they were at the given
1188 time.
1189 This must be a microsecond precision timestamp
1190 within the past one hour, or if Point-in-Time
1191 Recovery is enabled, can additionally be a whole
1192 minute timestamp within the past 7 days.
1194 This field is a member of `oneof`_ ``consistency_selector``.
1195 """
1197 parent: str = proto.Field(
1198 proto.STRING,
1199 number=1,
1200 )
1201 structured_query: gf_query.StructuredQuery = proto.Field(
1202 proto.MESSAGE,
1203 number=2,
1204 oneof="query_type",
1205 message=gf_query.StructuredQuery,
1206 )
1207 partition_count: int = proto.Field(
1208 proto.INT64,
1209 number=3,
1210 )
1211 page_token: str = proto.Field(
1212 proto.STRING,
1213 number=4,
1214 )
1215 page_size: int = proto.Field(
1216 proto.INT32,
1217 number=5,
1218 )
1219 read_time: timestamp_pb2.Timestamp = proto.Field(
1220 proto.MESSAGE,
1221 number=6,
1222 oneof="consistency_selector",
1223 message=timestamp_pb2.Timestamp,
1224 )
1227class PartitionQueryResponse(proto.Message):
1228 r"""The response for
1229 [Firestore.PartitionQuery][google.firestore.v1.Firestore.PartitionQuery].
1231 Attributes:
1232 partitions (MutableSequence[google.cloud.firestore_v1.types.Cursor]):
1233 Partition results. Each partition is a split point that can
1234 be used by RunQuery as a starting or end point for the query
1235 results. The RunQuery requests must be made with the same
1236 query supplied to this PartitionQuery request. The partition
1237 cursors will be ordered according to same ordering as the
1238 results of the query supplied to PartitionQuery.
1240 For example, if a PartitionQuery request returns partition
1241 cursors A and B, running the following three queries will
1242 return the entire result set of the original query:
1244 - query, end_at A
1245 - query, start_at A, end_at B
1246 - query, start_at B
1248 An empty result may indicate that the query has too few
1249 results to be partitioned, or that the query is not yet
1250 supported for partitioning.
1251 next_page_token (str):
1252 A page token that may be used to request an additional set
1253 of results, up to the number specified by
1254 ``partition_count`` in the PartitionQuery request. If blank,
1255 there are no more results.
1256 """
1258 @property
1259 def raw_page(self):
1260 return self
1262 partitions: MutableSequence[gf_query.Cursor] = proto.RepeatedField(
1263 proto.MESSAGE,
1264 number=1,
1265 message=gf_query.Cursor,
1266 )
1267 next_page_token: str = proto.Field(
1268 proto.STRING,
1269 number=2,
1270 )
1273class WriteRequest(proto.Message):
1274 r"""The request for
1275 [Firestore.Write][google.firestore.v1.Firestore.Write].
1277 The first request creates a stream, or resumes an existing one from
1278 a token.
1280 When creating a new stream, the server replies with a response
1281 containing only an ID and a token, to use in the next request.
1283 When resuming a stream, the server first streams any responses later
1284 than the given token, then a response containing only an up-to-date
1285 token, to use in the next request.
1287 Attributes:
1288 database (str):
1289 Required. The database name. In the format:
1290 ``projects/{project_id}/databases/{database_id}``. This is
1291 only required in the first message.
1292 stream_id (str):
1293 The ID of the write stream to resume.
1294 This may only be set in the first message. When
1295 left empty, a new write stream will be created.
1296 writes (MutableSequence[google.cloud.firestore_v1.types.Write]):
1297 The writes to apply.
1299 Always executed atomically and in order.
1300 This must be empty on the first request.
1301 This may be empty on the last request.
1302 This must not be empty on all other requests.
1303 stream_token (bytes):
1304 A stream token that was previously sent by the server.
1306 The client should set this field to the token from the most
1307 recent [WriteResponse][google.firestore.v1.WriteResponse] it
1308 has received. This acknowledges that the client has received
1309 responses up to this token. After sending this token,
1310 earlier tokens may not be used anymore.
1312 The server may close the stream if there are too many
1313 unacknowledged responses.
1315 Leave this field unset when creating a new stream. To resume
1316 a stream at a specific point, set this field and the
1317 ``stream_id`` field.
1319 Leave this field unset when creating a new stream.
1320 labels (MutableMapping[str, str]):
1321 Labels associated with this write request.
1322 """
1324 database: str = proto.Field(
1325 proto.STRING,
1326 number=1,
1327 )
1328 stream_id: str = proto.Field(
1329 proto.STRING,
1330 number=2,
1331 )
1332 writes: MutableSequence[write.Write] = proto.RepeatedField(
1333 proto.MESSAGE,
1334 number=3,
1335 message=write.Write,
1336 )
1337 stream_token: bytes = proto.Field(
1338 proto.BYTES,
1339 number=4,
1340 )
1341 labels: MutableMapping[str, str] = proto.MapField(
1342 proto.STRING,
1343 proto.STRING,
1344 number=5,
1345 )
1348class WriteResponse(proto.Message):
1349 r"""The response for
1350 [Firestore.Write][google.firestore.v1.Firestore.Write].
1352 Attributes:
1353 stream_id (str):
1354 The ID of the stream.
1355 Only set on the first message, when a new stream
1356 was created.
1357 stream_token (bytes):
1358 A token that represents the position of this
1359 response in the stream. This can be used by a
1360 client to resume the stream at this point.
1362 This field is always set.
1363 write_results (MutableSequence[google.cloud.firestore_v1.types.WriteResult]):
1364 The result of applying the writes.
1366 This i-th write result corresponds to the i-th
1367 write in the request.
1368 commit_time (google.protobuf.timestamp_pb2.Timestamp):
1369 The time at which the commit occurred. Any read with an
1370 equal or greater ``read_time`` is guaranteed to see the
1371 effects of the write.
1372 """
1374 stream_id: str = proto.Field(
1375 proto.STRING,
1376 number=1,
1377 )
1378 stream_token: bytes = proto.Field(
1379 proto.BYTES,
1380 number=2,
1381 )
1382 write_results: MutableSequence[write.WriteResult] = proto.RepeatedField(
1383 proto.MESSAGE,
1384 number=3,
1385 message=write.WriteResult,
1386 )
1387 commit_time: timestamp_pb2.Timestamp = proto.Field(
1388 proto.MESSAGE,
1389 number=4,
1390 message=timestamp_pb2.Timestamp,
1391 )
1394class ListenRequest(proto.Message):
1395 r"""A request for
1396 [Firestore.Listen][google.firestore.v1.Firestore.Listen]
1398 This message has `oneof`_ fields (mutually exclusive fields).
1399 For each oneof, at most one member field can be set at the same time.
1400 Setting any member of the oneof automatically clears all other
1401 members.
1403 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1405 Attributes:
1406 database (str):
1407 Required. The database name. In the format:
1408 ``projects/{project_id}/databases/{database_id}``.
1409 add_target (google.cloud.firestore_v1.types.Target):
1410 A target to add to this stream.
1412 This field is a member of `oneof`_ ``target_change``.
1413 remove_target (int):
1414 The ID of a target to remove from this
1415 stream.
1417 This field is a member of `oneof`_ ``target_change``.
1418 labels (MutableMapping[str, str]):
1419 Labels associated with this target change.
1420 """
1422 database: str = proto.Field(
1423 proto.STRING,
1424 number=1,
1425 )
1426 add_target: "Target" = proto.Field(
1427 proto.MESSAGE,
1428 number=2,
1429 oneof="target_change",
1430 message="Target",
1431 )
1432 remove_target: int = proto.Field(
1433 proto.INT32,
1434 number=3,
1435 oneof="target_change",
1436 )
1437 labels: MutableMapping[str, str] = proto.MapField(
1438 proto.STRING,
1439 proto.STRING,
1440 number=4,
1441 )
1444class ListenResponse(proto.Message):
1445 r"""The response for
1446 [Firestore.Listen][google.firestore.v1.Firestore.Listen].
1448 This message has `oneof`_ fields (mutually exclusive fields).
1449 For each oneof, at most one member field can be set at the same time.
1450 Setting any member of the oneof automatically clears all other
1451 members.
1453 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1455 Attributes:
1456 target_change (google.cloud.firestore_v1.types.TargetChange):
1457 Targets have changed.
1459 This field is a member of `oneof`_ ``response_type``.
1460 document_change (google.cloud.firestore_v1.types.DocumentChange):
1461 A [Document][google.firestore.v1.Document] has changed.
1463 This field is a member of `oneof`_ ``response_type``.
1464 document_delete (google.cloud.firestore_v1.types.DocumentDelete):
1465 A [Document][google.firestore.v1.Document] has been deleted.
1467 This field is a member of `oneof`_ ``response_type``.
1468 document_remove (google.cloud.firestore_v1.types.DocumentRemove):
1469 A [Document][google.firestore.v1.Document] has been removed
1470 from a target (because it is no longer relevant to that
1471 target).
1473 This field is a member of `oneof`_ ``response_type``.
1474 filter (google.cloud.firestore_v1.types.ExistenceFilter):
1475 A filter to apply to the set of documents
1476 previously returned for the given target.
1478 Returned when documents may have been removed
1479 from the given target, but the exact documents
1480 are unknown.
1482 This field is a member of `oneof`_ ``response_type``.
1483 """
1485 target_change: "TargetChange" = proto.Field(
1486 proto.MESSAGE,
1487 number=2,
1488 oneof="response_type",
1489 message="TargetChange",
1490 )
1491 document_change: write.DocumentChange = proto.Field(
1492 proto.MESSAGE,
1493 number=3,
1494 oneof="response_type",
1495 message=write.DocumentChange,
1496 )
1497 document_delete: write.DocumentDelete = proto.Field(
1498 proto.MESSAGE,
1499 number=4,
1500 oneof="response_type",
1501 message=write.DocumentDelete,
1502 )
1503 document_remove: write.DocumentRemove = proto.Field(
1504 proto.MESSAGE,
1505 number=6,
1506 oneof="response_type",
1507 message=write.DocumentRemove,
1508 )
1509 filter: write.ExistenceFilter = proto.Field(
1510 proto.MESSAGE,
1511 number=5,
1512 oneof="response_type",
1513 message=write.ExistenceFilter,
1514 )
1517class Target(proto.Message):
1518 r"""A specification of a set of documents to listen to.
1520 This message has `oneof`_ fields (mutually exclusive fields).
1521 For each oneof, at most one member field can be set at the same time.
1522 Setting any member of the oneof automatically clears all other
1523 members.
1525 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1527 Attributes:
1528 query (google.cloud.firestore_v1.types.Target.QueryTarget):
1529 A target specified by a query.
1531 This field is a member of `oneof`_ ``target_type``.
1532 documents (google.cloud.firestore_v1.types.Target.DocumentsTarget):
1533 A target specified by a set of document
1534 names.
1536 This field is a member of `oneof`_ ``target_type``.
1537 resume_token (bytes):
1538 A resume token from a prior
1539 [TargetChange][google.firestore.v1.TargetChange] for an
1540 identical target.
1542 Using a resume token with a different target is unsupported
1543 and may fail.
1545 This field is a member of `oneof`_ ``resume_type``.
1546 read_time (google.protobuf.timestamp_pb2.Timestamp):
1547 Start listening after a specific ``read_time``.
1549 The client must know the state of matching documents at this
1550 time.
1552 This field is a member of `oneof`_ ``resume_type``.
1553 target_id (int):
1554 The target ID that identifies the target on the stream. Must
1555 be a positive number and non-zero.
1557 If ``target_id`` is 0 (or unspecified), the server will
1558 assign an ID for this target and return that in a
1559 ``TargetChange::ADD`` event. Once a target with
1560 ``target_id=0`` is added, all subsequent targets must also
1561 have ``target_id=0``. If an ``AddTarget`` request with
1562 ``target_id != 0`` is sent to the server after a target with
1563 ``target_id=0`` is added, the server will immediately send a
1564 response with a ``TargetChange::Remove`` event.
1566 Note that if the client sends multiple ``AddTarget``
1567 requests without an ID, the order of IDs returned in
1568 ``TargetChange.target_ids`` are undefined. Therefore,
1569 clients should provide a target ID instead of relying on the
1570 server to assign one.
1572 If ``target_id`` is non-zero, there must not be an existing
1573 active target on this stream with the same ID.
1574 once (bool):
1575 If the target should be removed once it is
1576 current and consistent.
1577 expected_count (google.protobuf.wrappers_pb2.Int32Value):
1578 The number of documents that last matched the query at the
1579 resume token or read time.
1581 This value is only relevant when a ``resume_type`` is
1582 provided. This value being present and greater than zero
1583 signals that the client wants
1584 ``ExistenceFilter.unchanged_names`` to be included in the
1585 response.
1586 """
1588 class DocumentsTarget(proto.Message):
1589 r"""A target specified by a set of documents names.
1591 Attributes:
1592 documents (MutableSequence[str]):
1593 The names of the documents to retrieve. In the format:
1594 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
1595 The request will fail if any of the document is not a child
1596 resource of the given ``database``. Duplicate names will be
1597 elided.
1598 """
1600 documents: MutableSequence[str] = proto.RepeatedField(
1601 proto.STRING,
1602 number=2,
1603 )
1605 class QueryTarget(proto.Message):
1606 r"""A target specified by a query.
1608 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1610 Attributes:
1611 parent (str):
1612 The parent resource name. In the format:
1613 ``projects/{project_id}/databases/{database_id}/documents``
1614 or
1615 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
1616 For example:
1617 ``projects/my-project/databases/my-database/documents`` or
1618 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
1619 structured_query (google.cloud.firestore_v1.types.StructuredQuery):
1620 A structured query.
1622 This field is a member of `oneof`_ ``query_type``.
1623 """
1625 parent: str = proto.Field(
1626 proto.STRING,
1627 number=1,
1628 )
1629 structured_query: gf_query.StructuredQuery = proto.Field(
1630 proto.MESSAGE,
1631 number=2,
1632 oneof="query_type",
1633 message=gf_query.StructuredQuery,
1634 )
1636 query: QueryTarget = proto.Field(
1637 proto.MESSAGE,
1638 number=2,
1639 oneof="target_type",
1640 message=QueryTarget,
1641 )
1642 documents: DocumentsTarget = proto.Field(
1643 proto.MESSAGE,
1644 number=3,
1645 oneof="target_type",
1646 message=DocumentsTarget,
1647 )
1648 resume_token: bytes = proto.Field(
1649 proto.BYTES,
1650 number=4,
1651 oneof="resume_type",
1652 )
1653 read_time: timestamp_pb2.Timestamp = proto.Field(
1654 proto.MESSAGE,
1655 number=11,
1656 oneof="resume_type",
1657 message=timestamp_pb2.Timestamp,
1658 )
1659 target_id: int = proto.Field(
1660 proto.INT32,
1661 number=5,
1662 )
1663 once: bool = proto.Field(
1664 proto.BOOL,
1665 number=6,
1666 )
1667 expected_count: wrappers_pb2.Int32Value = proto.Field(
1668 proto.MESSAGE,
1669 number=12,
1670 message=wrappers_pb2.Int32Value,
1671 )
1674class TargetChange(proto.Message):
1675 r"""Targets being watched have changed.
1677 Attributes:
1678 target_change_type (google.cloud.firestore_v1.types.TargetChange.TargetChangeType):
1679 The type of change that occurred.
1680 target_ids (MutableSequence[int]):
1681 The target IDs of targets that have changed.
1683 If empty, the change applies to all targets.
1685 The order of the target IDs is not defined.
1686 cause (google.rpc.status_pb2.Status):
1687 The error that resulted in this change, if
1688 applicable.
1689 resume_token (bytes):
1690 A token that can be used to resume the stream for the given
1691 ``target_ids``, or all targets if ``target_ids`` is empty.
1693 Not set on every target change.
1694 read_time (google.protobuf.timestamp_pb2.Timestamp):
1695 The consistent ``read_time`` for the given ``target_ids``
1696 (omitted when the target_ids are not at a consistent
1697 snapshot).
1699 The stream is guaranteed to send a ``read_time`` with
1700 ``target_ids`` empty whenever the entire stream reaches a
1701 new consistent snapshot. ADD, CURRENT, and RESET messages
1702 are guaranteed to (eventually) result in a new consistent
1703 snapshot (while NO_CHANGE and REMOVE messages are not).
1705 For a given stream, ``read_time`` is guaranteed to be
1706 monotonically increasing.
1707 """
1709 class TargetChangeType(proto.Enum):
1710 r"""The type of change.
1712 Values:
1713 NO_CHANGE (0):
1714 No change has occurred. Used only to send an updated
1715 ``resume_token``.
1716 ADD (1):
1717 The targets have been added.
1718 REMOVE (2):
1719 The targets have been removed.
1720 CURRENT (3):
1721 The targets reflect all changes committed before the targets
1722 were added to the stream.
1724 This will be sent after or with a ``read_time`` that is
1725 greater than or equal to the time at which the targets were
1726 added.
1728 Listeners can wait for this change if read-after-write
1729 semantics are desired.
1730 RESET (4):
1731 The targets have been reset, and a new initial state for the
1732 targets will be returned in subsequent changes.
1734 After the initial state is complete, ``CURRENT`` will be
1735 returned even if the target was previously indicated to be
1736 ``CURRENT``.
1737 """
1738 NO_CHANGE = 0
1739 ADD = 1
1740 REMOVE = 2
1741 CURRENT = 3
1742 RESET = 4
1744 target_change_type: TargetChangeType = proto.Field(
1745 proto.ENUM,
1746 number=1,
1747 enum=TargetChangeType,
1748 )
1749 target_ids: MutableSequence[int] = proto.RepeatedField(
1750 proto.INT32,
1751 number=2,
1752 )
1753 cause: status_pb2.Status = proto.Field(
1754 proto.MESSAGE,
1755 number=3,
1756 message=status_pb2.Status,
1757 )
1758 resume_token: bytes = proto.Field(
1759 proto.BYTES,
1760 number=4,
1761 )
1762 read_time: timestamp_pb2.Timestamp = proto.Field(
1763 proto.MESSAGE,
1764 number=6,
1765 message=timestamp_pb2.Timestamp,
1766 )
1769class ListCollectionIdsRequest(proto.Message):
1770 r"""The request for
1771 [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].
1774 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
1776 Attributes:
1777 parent (str):
1778 Required. The parent document. In the format:
1779 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
1780 For example:
1781 ``projects/my-project/databases/my-database/documents/chatrooms/my-chatroom``
1782 page_size (int):
1783 The maximum number of results to return.
1784 page_token (str):
1785 A page token. Must be a value from
1786 [ListCollectionIdsResponse][google.firestore.v1.ListCollectionIdsResponse].
1787 read_time (google.protobuf.timestamp_pb2.Timestamp):
1788 Reads documents as they were at the given
1789 time.
1790 This must be a microsecond precision timestamp
1791 within the past one hour, or if Point-in-Time
1792 Recovery is enabled, can additionally be a whole
1793 minute timestamp within the past 7 days.
1795 This field is a member of `oneof`_ ``consistency_selector``.
1796 """
1798 parent: str = proto.Field(
1799 proto.STRING,
1800 number=1,
1801 )
1802 page_size: int = proto.Field(
1803 proto.INT32,
1804 number=2,
1805 )
1806 page_token: str = proto.Field(
1807 proto.STRING,
1808 number=3,
1809 )
1810 read_time: timestamp_pb2.Timestamp = proto.Field(
1811 proto.MESSAGE,
1812 number=4,
1813 oneof="consistency_selector",
1814 message=timestamp_pb2.Timestamp,
1815 )
1818class ListCollectionIdsResponse(proto.Message):
1819 r"""The response from
1820 [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].
1822 Attributes:
1823 collection_ids (MutableSequence[str]):
1824 The collection ids.
1825 next_page_token (str):
1826 A page token that may be used to continue the
1827 list.
1828 """
1830 @property
1831 def raw_page(self):
1832 return self
1834 collection_ids: MutableSequence[str] = proto.RepeatedField(
1835 proto.STRING,
1836 number=1,
1837 )
1838 next_page_token: str = proto.Field(
1839 proto.STRING,
1840 number=2,
1841 )
1844class BatchWriteRequest(proto.Message):
1845 r"""The request for
1846 [Firestore.BatchWrite][google.firestore.v1.Firestore.BatchWrite].
1848 Attributes:
1849 database (str):
1850 Required. The database name. In the format:
1851 ``projects/{project_id}/databases/{database_id}``.
1852 writes (MutableSequence[google.cloud.firestore_v1.types.Write]):
1853 The writes to apply.
1855 Method does not apply writes atomically and does
1856 not guarantee ordering. Each write succeeds or
1857 fails independently. You cannot write to the
1858 same document more than once per request.
1859 labels (MutableMapping[str, str]):
1860 Labels associated with this batch write.
1861 """
1863 database: str = proto.Field(
1864 proto.STRING,
1865 number=1,
1866 )
1867 writes: MutableSequence[write.Write] = proto.RepeatedField(
1868 proto.MESSAGE,
1869 number=2,
1870 message=write.Write,
1871 )
1872 labels: MutableMapping[str, str] = proto.MapField(
1873 proto.STRING,
1874 proto.STRING,
1875 number=3,
1876 )
1879class BatchWriteResponse(proto.Message):
1880 r"""The response from
1881 [Firestore.BatchWrite][google.firestore.v1.Firestore.BatchWrite].
1883 Attributes:
1884 write_results (MutableSequence[google.cloud.firestore_v1.types.WriteResult]):
1885 The result of applying the writes.
1887 This i-th write result corresponds to the i-th
1888 write in the request.
1889 status (MutableSequence[google.rpc.status_pb2.Status]):
1890 The status of applying the writes.
1892 This i-th write status corresponds to the i-th
1893 write in the request.
1894 """
1896 write_results: MutableSequence[write.WriteResult] = proto.RepeatedField(
1897 proto.MESSAGE,
1898 number=1,
1899 message=write.WriteResult,
1900 )
1901 status: MutableSequence[status_pb2.Status] = proto.RepeatedField(
1902 proto.MESSAGE,
1903 number=2,
1904 message=status_pb2.Status,
1905 )
1908__all__ = tuple(sorted(__protobuf__.manifest))