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 bloom_filter
23from google.cloud.firestore_v1.types import common
24from google.cloud.firestore_v1.types import document as gf_document
25from google.protobuf import timestamp_pb2 # type: ignore
28__protobuf__ = proto.module(
29 package="google.firestore.v1",
30 manifest={
31 "Write",
32 "DocumentTransform",
33 "WriteResult",
34 "DocumentChange",
35 "DocumentDelete",
36 "DocumentRemove",
37 "ExistenceFilter",
38 },
39)
42class Write(proto.Message):
43 r"""A write on a document.
45 This message has `oneof`_ fields (mutually exclusive fields).
46 For each oneof, at most one member field can be set at the same time.
47 Setting any member of the oneof automatically clears all other
48 members.
50 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
52 Attributes:
53 update (google.cloud.firestore_v1.types.Document):
54 A document to write.
56 This field is a member of `oneof`_ ``operation``.
57 delete (str):
58 A document name to delete. In the format:
59 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
61 This field is a member of `oneof`_ ``operation``.
62 transform (google.cloud.firestore_v1.types.DocumentTransform):
63 Applies a transformation to a document.
65 This field is a member of `oneof`_ ``operation``.
66 update_mask (google.cloud.firestore_v1.types.DocumentMask):
67 The fields to update in this write.
69 This field can be set only when the operation is ``update``.
70 If the mask is not set for an ``update`` and the document
71 exists, any existing data will be overwritten. If the mask
72 is set and the document on the server has fields not covered
73 by the mask, they are left unchanged. Fields referenced in
74 the mask, but not present in the input document, are deleted
75 from the document on the server. The field paths in this
76 mask must not contain a reserved field name.
77 update_transforms (MutableSequence[google.cloud.firestore_v1.types.DocumentTransform.FieldTransform]):
78 The transforms to perform after update.
80 This field can be set only when the operation is ``update``.
81 If present, this write is equivalent to performing
82 ``update`` and ``transform`` to the same document atomically
83 and in order.
84 current_document (google.cloud.firestore_v1.types.Precondition):
85 An optional precondition on the document.
87 The write will fail if this is set and not met
88 by the target document.
89 """
91 update: gf_document.Document = proto.Field(
92 proto.MESSAGE,
93 number=1,
94 oneof="operation",
95 message=gf_document.Document,
96 )
97 delete: str = proto.Field(
98 proto.STRING,
99 number=2,
100 oneof="operation",
101 )
102 transform: "DocumentTransform" = proto.Field(
103 proto.MESSAGE,
104 number=6,
105 oneof="operation",
106 message="DocumentTransform",
107 )
108 update_mask: common.DocumentMask = proto.Field(
109 proto.MESSAGE,
110 number=3,
111 message=common.DocumentMask,
112 )
113 update_transforms: MutableSequence[
114 "DocumentTransform.FieldTransform"
115 ] = proto.RepeatedField(
116 proto.MESSAGE,
117 number=7,
118 message="DocumentTransform.FieldTransform",
119 )
120 current_document: common.Precondition = proto.Field(
121 proto.MESSAGE,
122 number=4,
123 message=common.Precondition,
124 )
127class DocumentTransform(proto.Message):
128 r"""A transformation of a document.
130 Attributes:
131 document (str):
132 The name of the document to transform.
133 field_transforms (MutableSequence[google.cloud.firestore_v1.types.DocumentTransform.FieldTransform]):
134 The list of transformations to apply to the
135 fields of the document, in order.
136 This must not be empty.
137 """
139 class FieldTransform(proto.Message):
140 r"""A transformation of a field of the document.
142 This message has `oneof`_ fields (mutually exclusive fields).
143 For each oneof, at most one member field can be set at the same time.
144 Setting any member of the oneof automatically clears all other
145 members.
147 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
149 Attributes:
150 field_path (str):
151 The path of the field. See
152 [Document.fields][google.firestore.v1.Document.fields] for
153 the field path syntax reference.
154 set_to_server_value (google.cloud.firestore_v1.types.DocumentTransform.FieldTransform.ServerValue):
155 Sets the field to the given server value.
157 This field is a member of `oneof`_ ``transform_type``.
158 increment (google.cloud.firestore_v1.types.Value):
159 Adds the given value to the field's current
160 value.
161 This must be an integer or a double value.
162 If the field is not an integer or double, or if
163 the field does not yet exist, the transformation
164 will set the field to the given value. If either
165 of the given value or the current field value
166 are doubles, both values will be interpreted as
167 doubles. Double arithmetic and representation of
168 double values follow IEEE 754 semantics. If
169 there is positive/negative integer overflow, the
170 field is resolved to the largest magnitude
171 positive/negative integer.
173 This field is a member of `oneof`_ ``transform_type``.
174 maximum (google.cloud.firestore_v1.types.Value):
175 Sets the field to the maximum of its current
176 value and the given value.
177 This must be an integer or a double value.
178 If the field is not an integer or double, or if
179 the field does not yet exist, the transformation
180 will set the field to the given value. If a
181 maximum operation is applied where the field and
182 the input value are of mixed types (that is -
183 one is an integer and one is a double) the field
184 takes on the type of the larger operand. If the
185 operands are equivalent (e.g. 3 and 3.0), the
186 field does not change. 0, 0.0, and -0.0 are all
187 zero. The maximum of a zero stored value and
188 zero input value is always the stored value.
189 The maximum of any numeric value x and NaN is
190 NaN.
192 This field is a member of `oneof`_ ``transform_type``.
193 minimum (google.cloud.firestore_v1.types.Value):
194 Sets the field to the minimum of its current
195 value and the given value.
196 This must be an integer or a double value.
197 If the field is not an integer or double, or if
198 the field does not yet exist, the transformation
199 will set the field to the input value. If a
200 minimum operation is applied where the field and
201 the input value are of mixed types (that is -
202 one is an integer and one is a double) the field
203 takes on the type of the smaller operand. If the
204 operands are equivalent (e.g. 3 and 3.0), the
205 field does not change. 0, 0.0, and -0.0 are all
206 zero. The minimum of a zero stored value and
207 zero input value is always the stored value.
208 The minimum of any numeric value x and NaN is
209 NaN.
211 This field is a member of `oneof`_ ``transform_type``.
212 append_missing_elements (google.cloud.firestore_v1.types.ArrayValue):
213 Append the given elements in order if they are not already
214 present in the current field value. If the field is not an
215 array, or if the field does not yet exist, it is first set
216 to the empty array.
218 Equivalent numbers of different types (e.g. 3L and 3.0) are
219 considered equal when checking if a value is missing. NaN is
220 equal to NaN, and Null is equal to Null. If the input
221 contains multiple equivalent values, only the first will be
222 considered.
224 The corresponding transform_result will be the null value.
226 This field is a member of `oneof`_ ``transform_type``.
227 remove_all_from_array (google.cloud.firestore_v1.types.ArrayValue):
228 Remove all of the given elements from the array in the
229 field. If the field is not an array, or if the field does
230 not yet exist, it is set to the empty array.
232 Equivalent numbers of the different types (e.g. 3L and 3.0)
233 are considered equal when deciding whether an element should
234 be removed. NaN is equal to NaN, and Null is equal to Null.
235 This will remove all equivalent values if there are
236 duplicates.
238 The corresponding transform_result will be the null value.
240 This field is a member of `oneof`_ ``transform_type``.
241 """
243 class ServerValue(proto.Enum):
244 r"""A value that is calculated by the server.
246 Values:
247 SERVER_VALUE_UNSPECIFIED (0):
248 Unspecified. This value must not be used.
249 REQUEST_TIME (1):
250 The time at which the server processed the
251 request, with millisecond precision. If used on
252 multiple fields (same or different documents) in
253 a transaction, all the fields will get the same
254 server timestamp.
255 """
256 SERVER_VALUE_UNSPECIFIED = 0
257 REQUEST_TIME = 1
259 field_path: str = proto.Field(
260 proto.STRING,
261 number=1,
262 )
263 set_to_server_value: "DocumentTransform.FieldTransform.ServerValue" = (
264 proto.Field(
265 proto.ENUM,
266 number=2,
267 oneof="transform_type",
268 enum="DocumentTransform.FieldTransform.ServerValue",
269 )
270 )
271 increment: gf_document.Value = proto.Field(
272 proto.MESSAGE,
273 number=3,
274 oneof="transform_type",
275 message=gf_document.Value,
276 )
277 maximum: gf_document.Value = proto.Field(
278 proto.MESSAGE,
279 number=4,
280 oneof="transform_type",
281 message=gf_document.Value,
282 )
283 minimum: gf_document.Value = proto.Field(
284 proto.MESSAGE,
285 number=5,
286 oneof="transform_type",
287 message=gf_document.Value,
288 )
289 append_missing_elements: gf_document.ArrayValue = proto.Field(
290 proto.MESSAGE,
291 number=6,
292 oneof="transform_type",
293 message=gf_document.ArrayValue,
294 )
295 remove_all_from_array: gf_document.ArrayValue = proto.Field(
296 proto.MESSAGE,
297 number=7,
298 oneof="transform_type",
299 message=gf_document.ArrayValue,
300 )
302 document: str = proto.Field(
303 proto.STRING,
304 number=1,
305 )
306 field_transforms: MutableSequence[FieldTransform] = proto.RepeatedField(
307 proto.MESSAGE,
308 number=2,
309 message=FieldTransform,
310 )
313class WriteResult(proto.Message):
314 r"""The result of applying a write.
316 Attributes:
317 update_time (google.protobuf.timestamp_pb2.Timestamp):
318 The last update time of the document after applying the
319 write. Not set after a ``delete``.
321 If the write did not actually change the document, this will
322 be the previous update_time.
323 transform_results (MutableSequence[google.cloud.firestore_v1.types.Value]):
324 The results of applying each
325 [DocumentTransform.FieldTransform][google.firestore.v1.DocumentTransform.FieldTransform],
326 in the same order.
327 """
329 update_time: timestamp_pb2.Timestamp = proto.Field(
330 proto.MESSAGE,
331 number=1,
332 message=timestamp_pb2.Timestamp,
333 )
334 transform_results: MutableSequence[gf_document.Value] = proto.RepeatedField(
335 proto.MESSAGE,
336 number=2,
337 message=gf_document.Value,
338 )
341class DocumentChange(proto.Message):
342 r"""A [Document][google.firestore.v1.Document] has changed.
344 May be the result of multiple [writes][google.firestore.v1.Write],
345 including deletes, that ultimately resulted in a new value for the
346 [Document][google.firestore.v1.Document].
348 Multiple [DocumentChange][google.firestore.v1.DocumentChange]
349 messages may be returned for the same logical change, if multiple
350 targets are affected.
352 Attributes:
353 document (google.cloud.firestore_v1.types.Document):
354 The new state of the
355 [Document][google.firestore.v1.Document].
357 If ``mask`` is set, contains only fields that were updated
358 or added.
359 target_ids (MutableSequence[int]):
360 A set of target IDs of targets that match
361 this document.
362 removed_target_ids (MutableSequence[int]):
363 A set of target IDs for targets that no
364 longer match this document.
365 """
367 document: gf_document.Document = proto.Field(
368 proto.MESSAGE,
369 number=1,
370 message=gf_document.Document,
371 )
372 target_ids: MutableSequence[int] = proto.RepeatedField(
373 proto.INT32,
374 number=5,
375 )
376 removed_target_ids: MutableSequence[int] = proto.RepeatedField(
377 proto.INT32,
378 number=6,
379 )
382class DocumentDelete(proto.Message):
383 r"""A [Document][google.firestore.v1.Document] has been deleted.
385 May be the result of multiple [writes][google.firestore.v1.Write],
386 including updates, the last of which deleted the
387 [Document][google.firestore.v1.Document].
389 Multiple [DocumentDelete][google.firestore.v1.DocumentDelete]
390 messages may be returned for the same logical delete, if multiple
391 targets are affected.
393 Attributes:
394 document (str):
395 The resource name of the
396 [Document][google.firestore.v1.Document] that was deleted.
397 removed_target_ids (MutableSequence[int]):
398 A set of target IDs for targets that
399 previously matched this entity.
400 read_time (google.protobuf.timestamp_pb2.Timestamp):
401 The read timestamp at which the delete was observed.
403 Greater or equal to the ``commit_time`` of the delete.
404 """
406 document: str = proto.Field(
407 proto.STRING,
408 number=1,
409 )
410 removed_target_ids: MutableSequence[int] = proto.RepeatedField(
411 proto.INT32,
412 number=6,
413 )
414 read_time: timestamp_pb2.Timestamp = proto.Field(
415 proto.MESSAGE,
416 number=4,
417 message=timestamp_pb2.Timestamp,
418 )
421class DocumentRemove(proto.Message):
422 r"""A [Document][google.firestore.v1.Document] has been removed from the
423 view of the targets.
425 Sent if the document is no longer relevant to a target and is out of
426 view. Can be sent instead of a DocumentDelete or a DocumentChange if
427 the server can not send the new value of the document.
429 Multiple [DocumentRemove][google.firestore.v1.DocumentRemove]
430 messages may be returned for the same logical write or delete, if
431 multiple targets are affected.
433 Attributes:
434 document (str):
435 The resource name of the
436 [Document][google.firestore.v1.Document] that has gone out
437 of view.
438 removed_target_ids (MutableSequence[int]):
439 A set of target IDs for targets that
440 previously matched this document.
441 read_time (google.protobuf.timestamp_pb2.Timestamp):
442 The read timestamp at which the remove was observed.
444 Greater or equal to the ``commit_time`` of the
445 change/delete/remove.
446 """
448 document: str = proto.Field(
449 proto.STRING,
450 number=1,
451 )
452 removed_target_ids: MutableSequence[int] = proto.RepeatedField(
453 proto.INT32,
454 number=2,
455 )
456 read_time: timestamp_pb2.Timestamp = proto.Field(
457 proto.MESSAGE,
458 number=4,
459 message=timestamp_pb2.Timestamp,
460 )
463class ExistenceFilter(proto.Message):
464 r"""A digest of all the documents that match a given target.
466 Attributes:
467 target_id (int):
468 The target ID to which this filter applies.
469 count (int):
470 The total count of documents that match
471 [target_id][google.firestore.v1.ExistenceFilter.target_id].
473 If different from the count of documents in the client that
474 match, the client must manually determine which documents no
475 longer match the target.
477 The client can use the ``unchanged_names`` bloom filter to
478 assist with this determination by testing ALL the document
479 names against the filter; if the document name is NOT in the
480 filter, it means the document no longer matches the target.
481 unchanged_names (google.cloud.firestore_v1.types.BloomFilter):
482 A bloom filter that, despite its name, contains the UTF-8
483 byte encodings of the resource names of ALL the documents
484 that match
485 [target_id][google.firestore.v1.ExistenceFilter.target_id],
486 in the form
487 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
489 This bloom filter may be omitted at the server's discretion,
490 such as if it is deemed that the client will not make use of
491 it or if it is too computationally expensive to calculate or
492 transmit. Clients must gracefully handle this field being
493 absent by falling back to the logic used before this field
494 existed; that is, re-add the target without a resume token
495 to figure out which documents in the client's cache are out
496 of sync.
497 """
499 target_id: int = proto.Field(
500 proto.INT32,
501 number=1,
502 )
503 count: int = proto.Field(
504 proto.INT32,
505 number=2,
506 )
507 unchanged_names: bloom_filter.BloomFilter = proto.Field(
508 proto.MESSAGE,
509 number=3,
510 message=bloom_filter.BloomFilter,
511 )
514__all__ = tuple(sorted(__protobuf__.manifest))