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 },
35)
38class Document(proto.Message):
39 r"""A Firestore document.
41 Must not exceed 1 MiB - 4 bytes.
43 Attributes:
44 name (str):
45 The resource name of the document, for example
46 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
47 fields (MutableMapping[str, google.cloud.firestore_v1.types.Value]):
48 The document's fields.
50 The map keys represent field names.
52 Field names matching the regular expression ``__.*__`` are
53 reserved. Reserved field names are forbidden except in
54 certain documented contexts. The field names, represented as
55 UTF-8, must not exceed 1,500 bytes and cannot be empty.
57 Field paths may be used in other contexts to refer to
58 structured fields defined here. For ``map_value``, the field
59 path is represented by a dot-delimited (``.``) string of
60 segments. Each segment is either a simple field name
61 (defined below) or a quoted field name. For example, the
62 structured field
63 ``"foo" : { map_value: { "x&y" : { string_value: "hello" }}}``
64 would be represented by the field path
65 :literal:`foo.`x&y\``.
67 A simple field name contains only characters ``a`` to ``z``,
68 ``A`` to ``Z``, ``0`` to ``9``, or ``_``, and must not start
69 with ``0`` to ``9``. For example, ``foo_bar_17``.
71 A quoted field name starts and ends with :literal:`\`` and
72 may contain any character. Some characters, including
73 :literal:`\``, must be escaped using a ``\``. For example,
74 :literal:`\`x&y\`` represents ``x&y`` and
75 :literal:`\`bak\`tik\`` represents :literal:`bak`tik`.
76 create_time (google.protobuf.timestamp_pb2.Timestamp):
77 Output only. The time at which the document was created.
79 This value increases monotonically when a document is
80 deleted then recreated. It can also be compared to values
81 from other documents and the ``read_time`` of a query.
82 update_time (google.protobuf.timestamp_pb2.Timestamp):
83 Output only. The time at which the document was last
84 changed.
86 This value is initially set to the ``create_time`` then
87 increases monotonically with each change to the document. It
88 can also be compared to values from other documents and the
89 ``read_time`` of a query.
90 """
92 name: str = proto.Field(
93 proto.STRING,
94 number=1,
95 )
96 fields: MutableMapping[str, "Value"] = proto.MapField(
97 proto.STRING,
98 proto.MESSAGE,
99 number=2,
100 message="Value",
101 )
102 create_time: timestamp_pb2.Timestamp = proto.Field(
103 proto.MESSAGE,
104 number=3,
105 message=timestamp_pb2.Timestamp,
106 )
107 update_time: timestamp_pb2.Timestamp = proto.Field(
108 proto.MESSAGE,
109 number=4,
110 message=timestamp_pb2.Timestamp,
111 )
114class Value(proto.Message):
115 r"""A message that can hold any of the supported value types.
117 This message has `oneof`_ fields (mutually exclusive fields).
118 For each oneof, at most one member field can be set at the same time.
119 Setting any member of the oneof automatically clears all other
120 members.
122 .. _oneof: https://proto-plus-python.readthedocs.io/en/stable/fields.html#oneofs-mutually-exclusive-fields
124 Attributes:
125 null_value (google.protobuf.struct_pb2.NullValue):
126 A null value.
128 This field is a member of `oneof`_ ``value_type``.
129 boolean_value (bool):
130 A boolean value.
132 This field is a member of `oneof`_ ``value_type``.
133 integer_value (int):
134 An integer value.
136 This field is a member of `oneof`_ ``value_type``.
137 double_value (float):
138 A double value.
140 This field is a member of `oneof`_ ``value_type``.
141 timestamp_value (google.protobuf.timestamp_pb2.Timestamp):
142 A timestamp value.
144 Precise only to microseconds. When stored, any
145 additional precision is rounded down.
147 This field is a member of `oneof`_ ``value_type``.
148 string_value (str):
149 A string value.
151 The string, represented as UTF-8, must not
152 exceed 1 MiB - 89 bytes. Only the first 1,500
153 bytes of the UTF-8 representation are considered
154 by queries.
156 This field is a member of `oneof`_ ``value_type``.
157 bytes_value (bytes):
158 A bytes value.
160 Must not exceed 1 MiB - 89 bytes.
161 Only the first 1,500 bytes are considered by
162 queries.
164 This field is a member of `oneof`_ ``value_type``.
165 reference_value (str):
166 A reference to a document. For example:
167 ``projects/{project_id}/databases/{database_id}/documents/{document_path}``.
169 This field is a member of `oneof`_ ``value_type``.
170 geo_point_value (google.type.latlng_pb2.LatLng):
171 A geo point value representing a point on the
172 surface of Earth.
174 This field is a member of `oneof`_ ``value_type``.
175 array_value (google.cloud.firestore_v1.types.ArrayValue):
176 An array value.
178 Cannot directly contain another array value,
179 though can contain a map which contains another
180 array.
182 This field is a member of `oneof`_ ``value_type``.
183 map_value (google.cloud.firestore_v1.types.MapValue):
184 A map value.
186 This field is a member of `oneof`_ ``value_type``.
187 """
189 null_value: struct_pb2.NullValue = proto.Field(
190 proto.ENUM,
191 number=11,
192 oneof="value_type",
193 enum=struct_pb2.NullValue,
194 )
195 boolean_value: bool = proto.Field(
196 proto.BOOL,
197 number=1,
198 oneof="value_type",
199 )
200 integer_value: int = proto.Field(
201 proto.INT64,
202 number=2,
203 oneof="value_type",
204 )
205 double_value: float = proto.Field(
206 proto.DOUBLE,
207 number=3,
208 oneof="value_type",
209 )
210 timestamp_value: timestamp_pb2.Timestamp = proto.Field(
211 proto.MESSAGE,
212 number=10,
213 oneof="value_type",
214 message=timestamp_pb2.Timestamp,
215 )
216 string_value: str = proto.Field(
217 proto.STRING,
218 number=17,
219 oneof="value_type",
220 )
221 bytes_value: bytes = proto.Field(
222 proto.BYTES,
223 number=18,
224 oneof="value_type",
225 )
226 reference_value: str = proto.Field(
227 proto.STRING,
228 number=5,
229 oneof="value_type",
230 )
231 geo_point_value: latlng_pb2.LatLng = proto.Field(
232 proto.MESSAGE,
233 number=8,
234 oneof="value_type",
235 message=latlng_pb2.LatLng,
236 )
237 array_value: "ArrayValue" = proto.Field(
238 proto.MESSAGE,
239 number=9,
240 oneof="value_type",
241 message="ArrayValue",
242 )
243 map_value: "MapValue" = proto.Field(
244 proto.MESSAGE,
245 number=6,
246 oneof="value_type",
247 message="MapValue",
248 )
251class ArrayValue(proto.Message):
252 r"""An array value.
254 Attributes:
255 values (MutableSequence[google.cloud.firestore_v1.types.Value]):
256 Values in the array.
257 """
259 values: MutableSequence["Value"] = proto.RepeatedField(
260 proto.MESSAGE,
261 number=1,
262 message="Value",
263 )
266class MapValue(proto.Message):
267 r"""A map value.
269 Attributes:
270 fields (MutableMapping[str, google.cloud.firestore_v1.types.Value]):
271 The map's fields.
273 The map keys represent field names. Field names matching the
274 regular expression ``__.*__`` are reserved. Reserved field
275 names are forbidden except in certain documented contexts.
276 The map keys, represented as UTF-8, must not exceed 1,500
277 bytes and cannot be empty.
278 """
280 fields: MutableMapping[str, "Value"] = proto.MapField(
281 proto.STRING,
282 proto.MESSAGE,
283 number=1,
284 message="Value",
285 )
288__all__ = tuple(sorted(__protobuf__.manifest))