1 // Copyright 2018 Google LLC.
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
7 // http://www.apache.org/licenses/LICENSE-2.0
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
18 package google.firestore.v1;
20 import "google/api/annotations.proto";
21 import "google/firestore/v1/common.proto";
22 import "google/firestore/v1/document.proto";
23 import "google/protobuf/timestamp.proto";
25 option csharp_namespace = "Google.Cloud.Firestore.V1";
26 option go_package = "google.golang.org/genproto/googleapis/firestore/v1;firestore";
27 option java_multiple_files = true;
28 option java_outer_classname = "WriteProto";
29 option java_package = "com.google.firestore.v1";
30 option objc_class_prefix = "GCFS";
31 option php_namespace = "Google\\Cloud\\Firestore\\V1";
33 // A write on a document.
35 // The operation to execute.
37 // A document to write.
40 // A document name to delete. In the format:
41 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
44 // Applies a tranformation to a document.
45 // At most one `transform` per document is allowed in a given request.
46 // An `update` cannot follow a `transform` on the same document in a given
48 DocumentTransform transform = 6;
51 // The fields to update in this write.
53 // This field can be set only when the operation is `update`.
54 // If the mask is not set for an `update` and the document exists, any
55 // existing data will be overwritten.
56 // If the mask is set and the document on the server has fields not covered by
57 // the mask, they are left unchanged.
58 // Fields referenced in the mask, but not present in the input document, are
59 // deleted from the document on the server.
60 // The field paths in this mask must not contain a reserved field name.
61 DocumentMask update_mask = 3;
63 // An optional precondition on the document.
65 // The write will fail if this is set and not met by the target document.
66 Precondition current_document = 4;
69 // A transformation of a document.
70 message DocumentTransform {
71 // A transformation of a field of the document.
72 message FieldTransform {
73 // A value that is calculated by the server.
75 // Unspecified. This value must not be used.
76 SERVER_VALUE_UNSPECIFIED = 0;
78 // The time at which the server processed the request, with millisecond
83 // The path of the field. See
84 // [Document.fields][google.firestore.v1.Document.fields] for the field path
86 string field_path = 1;
88 // The transformation to apply on the field.
89 oneof transform_type {
90 // Sets the field to the given server value.
91 ServerValue set_to_server_value = 2;
93 // Adds the given value to the field's current value.
95 // This must be an integer or a double value.
96 // If the field is not an integer or double, or if the field does not yet
97 // exist, the transformation will set the field to the given value.
98 // If either of the given value or the current field value are doubles,
99 // both values will be interpreted as doubles. Double arithmetic and
100 // representation of double values follow IEEE 754 semantics.
101 // If there is positive/negative integer overflow, the field is resolved
102 // to the largest magnitude positive/negative integer.
105 // Sets the field to the maximum of its current value and the given value.
107 // This must be an integer or a double value.
108 // If the field is not an integer or double, or if the field does not yet
109 // exist, the transformation will set the field to the given value.
110 // If a maximum operation is applied where the field and the input value
111 // are of mixed types (that is - one is an integer and one is a double)
112 // the field takes on the type of the larger operand. If the operands are
113 // equivalent (e.g. 3 and 3.0), the field does not change.
114 // 0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and
115 // zero input value is always the stored value.
116 // The maximum of any numeric value x and NaN is NaN.
119 // Sets the field to the minimum of its current value and the given value.
121 // This must be an integer or a double value.
122 // If the field is not an integer or double, or if the field does not yet
123 // exist, the transformation will set the field to the input value.
124 // If a minimum operation is applied where the field and the input value
125 // are of mixed types (that is - one is an integer and one is a double)
126 // the field takes on the type of the smaller operand. If the operands are
127 // equivalent (e.g. 3 and 3.0), the field does not change.
128 // 0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and
129 // zero input value is always the stored value.
130 // The minimum of any numeric value x and NaN is NaN.
133 // Append the given elements in order if they are not already present in
134 // the current field value.
135 // If the field is not an array, or if the field does not yet exist, it is
136 // first set to the empty array.
138 // Equivalent numbers of different types (e.g. 3L and 3.0) are
139 // considered equal when checking if a value is missing.
140 // NaN is equal to NaN, and Null is equal to Null.
141 // If the input contains multiple equivalent values, only the first will
144 // The corresponding transform_result will be the null value.
145 ArrayValue append_missing_elements = 6;
147 // Remove all of the given elements from the array in the field.
148 // If the field is not an array, or if the field does not yet exist, it is
149 // set to the empty array.
151 // Equivalent numbers of the different types (e.g. 3L and 3.0) are
152 // considered equal when deciding whether an element should be removed.
153 // NaN is equal to NaN, and Null is equal to Null.
154 // This will remove all equivalent values if there are duplicates.
156 // The corresponding transform_result will be the null value.
157 ArrayValue remove_all_from_array = 7;
161 // The name of the document to transform.
164 // The list of transformations to apply to the fields of the document, in
166 // This must not be empty.
167 repeated FieldTransform field_transforms = 2;
170 // The result of applying a write.
171 message WriteResult {
172 // The last update time of the document after applying the write. Not set
175 // If the write did not actually change the document, this will be the
176 // previous update_time.
177 google.protobuf.Timestamp update_time = 1;
179 // The results of applying each
180 // [DocumentTransform.FieldTransform][google.firestore.v1.DocumentTransform.FieldTransform],
181 // in the same order.
182 repeated Value transform_results = 2;
185 // A [Document][google.firestore.v1.Document] has changed.
187 // May be the result of multiple [writes][google.firestore.v1.Write], including
188 // deletes, that ultimately resulted in a new value for the
189 // [Document][google.firestore.v1.Document].
191 // Multiple [DocumentChange][google.firestore.v1.DocumentChange] messages may be
192 // returned for the same logical change, if multiple targets are affected.
193 message DocumentChange {
194 // The new state of the [Document][google.firestore.v1.Document].
196 // If `mask` is set, contains only fields that were updated or added.
197 Document document = 1;
199 // A set of target IDs of targets that match this document.
200 repeated int32 target_ids = 5;
202 // A set of target IDs for targets that no longer match this document.
203 repeated int32 removed_target_ids = 6;
206 // A [Document][google.firestore.v1.Document] has been deleted.
208 // May be the result of multiple [writes][google.firestore.v1.Write], including
209 // updates, the last of which deleted the
210 // [Document][google.firestore.v1.Document].
212 // Multiple [DocumentDelete][google.firestore.v1.DocumentDelete] messages may be
213 // returned for the same logical delete, if multiple targets are affected.
214 message DocumentDelete {
215 // The resource name of the [Document][google.firestore.v1.Document] that was
219 // A set of target IDs for targets that previously matched this entity.
220 repeated int32 removed_target_ids = 6;
222 // The read timestamp at which the delete was observed.
224 // Greater or equal to the `commit_time` of the delete.
225 google.protobuf.Timestamp read_time = 4;
228 // A [Document][google.firestore.v1.Document] has been removed from the view of
231 // Sent if the document is no longer relevant to a target and is out of view.
232 // Can be sent instead of a DocumentDelete or a DocumentChange if the server
233 // can not send the new value of the document.
235 // Multiple [DocumentRemove][google.firestore.v1.DocumentRemove] messages may be
236 // returned for the same logical write or delete, if multiple targets are
238 message DocumentRemove {
239 // The resource name of the [Document][google.firestore.v1.Document] that has
243 // A set of target IDs for targets that previously matched this document.
244 repeated int32 removed_target_ids = 2;
246 // The read timestamp at which the remove was observed.
248 // Greater or equal to the `commit_time` of the change/delete/remove.
249 google.protobuf.Timestamp read_time = 4;
252 // A digest of all the documents that match a given target.
253 message ExistenceFilter {
254 // The target ID to which this filter applies.
257 // The total count of documents that match
258 // [target_id][google.firestore.v1.ExistenceFilter.target_id].
260 // If different from the count of documents in the client that match, the
261 // client must manually determine which documents no longer match the target.