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.protobuf import struct_pb2 # type: ignore
23from google.protobuf import timestamp_pb2 # type: ignore
24from google.type import latlng_pb2 # type: ignore
27__protobuf__ = proto.module(
28 package="google.firestore.v1",
29 manifest={
30 "Document",
31 "Value",
32 "ArrayValue",
33 "MapValue",
34 "Function",
35 "Pipeline",
36 },
37)
40class Document(proto.Message):
41 r"""A Firestore document.
43 Must not exceed 1 MiB - 4 bytes.
45 Attributes:
46 name (str):
47 The resource name of the document, for example
48 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
49 fields (MutableMapping[str, google.cloud.firestore_v1.types.Value]):
50 The document's fields.
52 The map keys represent field names.
54 Field names matching the regular expression ``__.*__`` are
55 reserved. Reserved field names are forbidden except in
56 certain documented contexts. The field names, represented as
57 UTF-8, must not exceed 1,500 bytes and cannot be empty.
59 Field paths may be used in other contexts to refer to
60 structured fields defined here. For ``map_value``, the field
61 path is represented by a dot-delimited (``.``) string of
62 segments. Each segment is either a simple field name
63 (defined below) or a quoted field name. For example, the
64 structured field
65 ``"foo" : { map_value: { "x&y" : { string_value: "hello" }}}``
66 would be represented by the field path
67 :literal:`foo.`x&y\``.
69 A simple field name contains only characters ``a`` to ``z``,
70 ``A`` to ``Z``, ``0`` to ``9``, or ``_``, and must not start
71 with ``0`` to ``9``. For example, ``foo_bar_17``.
73 A quoted field name starts and ends with :literal:`\`` and
74 may contain any character. Some characters, including
75 :literal:`\``, must be escaped using a ``\``. For example,
76 :literal:`\`x&y\`` represents ``x&y`` and
77 :literal:`\`bak\\`tik\`` represents :literal:`bak`tik`.
78 create_time (google.protobuf.timestamp_pb2.Timestamp):
79 Output only. The time at which the document was created.
81 This value increases monotonically when a document is
82 deleted then recreated. It can also be compared to values
83 from other documents and the ``read_time`` of a query.
84 update_time (google.protobuf.timestamp_pb2.Timestamp):
85 Output only. The time at which the document was last
86 changed.
88 This value is initially set to the ``create_time`` then
89 increases monotonically with each change to the document. It
90 can also be compared to values from other documents and the
91 ``read_time`` of a query.
92 """
94 name: str = proto.Field(
95 proto.STRING,
96 number=1,
97 )
98 fields: MutableMapping[str, "Value"] = proto.MapField(
99 proto.STRING,
100 proto.MESSAGE,
101 number=2,
102 message="Value",
103 )
104 create_time: timestamp_pb2.Timestamp = proto.Field(
105 proto.MESSAGE,
106 number=3,
107 message=timestamp_pb2.Timestamp,
108 )
109 update_time: timestamp_pb2.Timestamp = proto.Field(
110 proto.MESSAGE,
111 number=4,
112 message=timestamp_pb2.Timestamp,
113 )
116class Value(proto.Message):
117 r"""A message that can hold any of the supported value types.
119 This message has `oneof`_ fields (mutually exclusive fields).
120 For each oneof, at most one member field can be set at the same time.
121 Setting any member of the oneof automatically clears all other
122 members.
124 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
126 Attributes:
127 null_value (google.protobuf.struct_pb2.NullValue):
128 A null value.
130 This field is a member of `oneof`_ ``value_type``.
131 boolean_value (bool):
132 A boolean value.
134 This field is a member of `oneof`_ ``value_type``.
135 integer_value (int):
136 An integer value.
138 This field is a member of `oneof`_ ``value_type``.
139 double_value (float):
140 A double value.
142 This field is a member of `oneof`_ ``value_type``.
143 timestamp_value (google.protobuf.timestamp_pb2.Timestamp):
144 A timestamp value.
146 Precise only to microseconds. When stored, any
147 additional precision is rounded down.
149 This field is a member of `oneof`_ ``value_type``.
150 string_value (str):
151 A string value.
153 The string, represented as UTF-8, must not
154 exceed 1 MiB - 89 bytes. Only the first 1,500
155 bytes of the UTF-8 representation are considered
156 by queries.
158 This field is a member of `oneof`_ ``value_type``.
159 bytes_value (bytes):
160 A bytes value.
162 Must not exceed 1 MiB - 89 bytes.
163 Only the first 1,500 bytes are considered by
164 queries.
166 This field is a member of `oneof`_ ``value_type``.
167 reference_value (str):
168 A reference to a document. For example:
169 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
171 This field is a member of `oneof`_ ``value_type``.
172 geo_point_value (google.type.latlng_pb2.LatLng):
173 A geo point value representing a point on the
174 surface of Earth.
176 This field is a member of `oneof`_ ``value_type``.
177 array_value (google.cloud.firestore_v1.types.ArrayValue):
178 An array value.
180 Cannot directly contain another array value,
181 though can contain a map which contains another
182 array.
184 This field is a member of `oneof`_ ``value_type``.
185 map_value (google.cloud.firestore_v1.types.MapValue):
186 A map value.
188 This field is a member of `oneof`_ ``value_type``.
189 field_reference_value (str):
190 Value which references a field.
192 This is considered relative (vs absolute) since it only
193 refers to a field and not a field within a particular
194 document.
196 **Requires:**
198 - Must follow [field reference][FieldReference.field_path]
199 limitations.
201 - Not allowed to be used when writing documents.
203 This field is a member of `oneof`_ ``value_type``.
204 function_value (google.cloud.firestore_v1.types.Function):
205 A value that represents an unevaluated expression.
207 **Requires:**
209 - Not allowed to be used when writing documents.
211 This field is a member of `oneof`_ ``value_type``.
212 pipeline_value (google.cloud.firestore_v1.types.Pipeline):
213 A value that represents an unevaluated pipeline.
215 **Requires:**
217 - Not allowed to be used when writing documents.
219 This field is a member of `oneof`_ ``value_type``.
220 """
222 null_value: struct_pb2.NullValue = proto.Field(
223 proto.ENUM,
224 number=11,
225 oneof="value_type",
226 enum=struct_pb2.NullValue,
227 )
228 boolean_value: bool = proto.Field(
229 proto.BOOL,
230 number=1,
231 oneof="value_type",
232 )
233 integer_value: int = proto.Field(
234 proto.INT64,
235 number=2,
236 oneof="value_type",
237 )
238 double_value: float = proto.Field(
239 proto.DOUBLE,
240 number=3,
241 oneof="value_type",
242 )
243 timestamp_value: timestamp_pb2.Timestamp = proto.Field(
244 proto.MESSAGE,
245 number=10,
246 oneof="value_type",
247 message=timestamp_pb2.Timestamp,
248 )
249 string_value: str = proto.Field(
250 proto.STRING,
251 number=17,
252 oneof="value_type",
253 )
254 bytes_value: bytes = proto.Field(
255 proto.BYTES,
256 number=18,
257 oneof="value_type",
258 )
259 reference_value: str = proto.Field(
260 proto.STRING,
261 number=5,
262 oneof="value_type",
263 )
264 geo_point_value: latlng_pb2.LatLng = proto.Field(
265 proto.MESSAGE,
266 number=8,
267 oneof="value_type",
268 message=latlng_pb2.LatLng,
269 )
270 array_value: "ArrayValue" = proto.Field(
271 proto.MESSAGE,
272 number=9,
273 oneof="value_type",
274 message="ArrayValue",
275 )
276 map_value: "MapValue" = proto.Field(
277 proto.MESSAGE,
278 number=6,
279 oneof="value_type",
280 message="MapValue",
281 )
282 field_reference_value: str = proto.Field(
283 proto.STRING,
284 number=19,
285 oneof="value_type",
286 )
287 function_value: "Function" = proto.Field(
288 proto.MESSAGE,
289 number=20,
290 oneof="value_type",
291 message="Function",
292 )
293 pipeline_value: "Pipeline" = proto.Field(
294 proto.MESSAGE,
295 number=21,
296 oneof="value_type",
297 message="Pipeline",
298 )
301class ArrayValue(proto.Message):
302 r"""An array value.
304 Attributes:
305 values (MutableSequence[google.cloud.firestore_v1.types.Value]):
306 Values in the array.
307 """
309 values: MutableSequence["Value"] = proto.RepeatedField(
310 proto.MESSAGE,
311 number=1,
312 message="Value",
313 )
316class MapValue(proto.Message):
317 r"""A map value.
319 Attributes:
320 fields (MutableMapping[str, google.cloud.firestore_v1.types.Value]):
321 The map's fields.
323 The map keys represent field names. Field names matching the
324 regular expression ``__.*__`` are reserved. Reserved field
325 names are forbidden except in certain documented contexts.
326 The map keys, represented as UTF-8, must not exceed 1,500
327 bytes and cannot be empty.
328 """
330 fields: MutableMapping[str, "Value"] = proto.MapField(
331 proto.STRING,
332 proto.MESSAGE,
333 number=1,
334 message="Value",
335 )
338class Function(proto.Message):
339 r"""Represents an unevaluated scalar expression.
341 For example, the expression ``like(user_name, "%alice%")`` is
342 represented as:
344 ::
346 name: "like"
347 args { field_reference: "user_name" }
348 args { string_value: "%alice%" }
350 Attributes:
351 name (str):
352 Required. The name of the function to evaluate.
354 **Requires:**
356 - must be in snake case (lower case with underscore
357 separator).
358 args (MutableSequence[google.cloud.firestore_v1.types.Value]):
359 Optional. Ordered list of arguments the given
360 function expects.
361 options (MutableMapping[str, google.cloud.firestore_v1.types.Value]):
362 Optional. Optional named arguments that
363 certain functions may support.
364 """
366 name: str = proto.Field(
367 proto.STRING,
368 number=1,
369 )
370 args: MutableSequence["Value"] = proto.RepeatedField(
371 proto.MESSAGE,
372 number=2,
373 message="Value",
374 )
375 options: MutableMapping[str, "Value"] = proto.MapField(
376 proto.STRING,
377 proto.MESSAGE,
378 number=3,
379 message="Value",
380 )
383class Pipeline(proto.Message):
384 r"""A Firestore query represented as an ordered list of
385 operations / stages.
387 Attributes:
388 stages (MutableSequence[google.cloud.firestore_v1.types.Pipeline.Stage]):
389 Required. Ordered list of stages to evaluate.
390 """
392 class Stage(proto.Message):
393 r"""A single operation within a pipeline.
395 A stage is made up of a unique name, and a list of arguments. The
396 exact number of arguments & types is dependent on the stage type.
398 To give an example, the stage ``filter(state = "MD")`` would be
399 encoded as:
401 ::
403 name: "filter"
404 args {
405 function_value {
406 name: "eq"
407 args { field_reference_value: "state" }
408 args { string_value: "MD" }
409 }
410 }
412 See public documentation for the full list.
414 Attributes:
415 name (str):
416 Required. The name of the stage to evaluate.
418 **Requires:**
420 - must be in snake case (lower case with underscore
421 separator).
422 args (MutableSequence[google.cloud.firestore_v1.types.Value]):
423 Optional. Ordered list of arguments the given
424 stage expects.
425 options (MutableMapping[str, google.cloud.firestore_v1.types.Value]):
426 Optional. Optional named arguments that
427 certain functions may support.
428 """
430 name: str = proto.Field(
431 proto.STRING,
432 number=1,
433 )
434 args: MutableSequence["Value"] = proto.RepeatedField(
435 proto.MESSAGE,
436 number=2,
437 message="Value",
438 )
439 options: MutableMapping[str, "Value"] = proto.MapField(
440 proto.STRING,
441 proto.MESSAGE,
442 number=3,
443 message="Value",
444 )
446 stages: MutableSequence[Stage] = proto.RepeatedField(
447 proto.MESSAGE,
448 number=1,
449 message=Stage,
450 )
453__all__ = tuple(sorted(__protobuf__.manifest))