1// Copyright 2023 Google LLC 2// 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 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 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. 14 15syntax = "proto3"; 16 17package google.firestore.v1; 18 19import "google/firestore/v1/bloom_filter.proto"; 20import "google/firestore/v1/common.proto"; 21import "google/firestore/v1/document.proto"; 22import "google/protobuf/timestamp.proto"; 23 24option csharp_namespace = "Google.Cloud.Firestore.V1"; 25option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb"; 26option java_multiple_files = true; 27option java_outer_classname = "WriteProto"; 28option java_package = "com.google.firestore.v1"; 29option objc_class_prefix = "GCFS"; 30option php_namespace = "Google\\Cloud\\Firestore\\V1"; 31option ruby_package = "Google::Cloud::Firestore::V1"; 32 33// A write on a document. 34message Write { 35 // The operation to execute. 36 oneof operation { 37 // A document to write. 38 Document update = 1; 39 40 // A document name to delete. In the format: 41 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. 42 string delete = 2; 43 44 // Applies a transformation to a document. 45 DocumentTransform transform = 6; 46 } 47 48 // The fields to update in this write. 49 // 50 // This field can be set only when the operation is `update`. 51 // If the mask is not set for an `update` and the document exists, any 52 // existing data will be overwritten. 53 // If the mask is set and the document on the server has fields not covered by 54 // the mask, they are left unchanged. 55 // Fields referenced in the mask, but not present in the input document, are 56 // deleted from the document on the server. 57 // The field paths in this mask must not contain a reserved field name. 58 DocumentMask update_mask = 3; 59 60 // The transforms to perform after update. 61 // 62 // This field can be set only when the operation is `update`. If present, this 63 // write is equivalent to performing `update` and `transform` to the same 64 // document atomically and in order. 65 repeated DocumentTransform.FieldTransform update_transforms = 7; 66 67 // An optional precondition on the document. 68 // 69 // The write will fail if this is set and not met by the target document. 70 Precondition current_document = 4; 71} 72 73// A transformation of a document. 74message DocumentTransform { 75 // A transformation of a field of the document. 76 message FieldTransform { 77 // A value that is calculated by the server. 78 enum ServerValue { 79 // Unspecified. This value must not be used. 80 SERVER_VALUE_UNSPECIFIED = 0; 81 82 // The time at which the server processed the request, with millisecond 83 // precision. If used on multiple fields (same or different documents) in 84 // a transaction, all the fields will get the same server timestamp. 85 REQUEST_TIME = 1; 86 } 87 88 // The path of the field. See 89 // [Document.fields][google.firestore.v1.Document.fields] for the field path 90 // syntax reference. 91 string field_path = 1; 92 93 // The transformation to apply on the field. 94 oneof transform_type { 95 // Sets the field to the given server value. 96 ServerValue set_to_server_value = 2; 97 98 // Adds the given value to the field's current value. 99 // 100 // This must be an integer or a double value. 101 // If the field is not an integer or double, or if the field does not yet 102 // exist, the transformation will set the field to the given value. 103 // If either of the given value or the current field value are doubles, 104 // both values will be interpreted as doubles. Double arithmetic and 105 // representation of double values follow IEEE 754 semantics. 106 // If there is positive/negative integer overflow, the field is resolved 107 // to the largest magnitude positive/negative integer. 108 Value increment = 3; 109 110 // Sets the field to the maximum of its current value and the given value. 111 // 112 // This must be an integer or a double value. 113 // If the field is not an integer or double, or if the field does not yet 114 // exist, the transformation will set the field to the given value. 115 // If a maximum operation is applied where the field and the input value 116 // are of mixed types (that is - one is an integer and one is a double) 117 // the field takes on the type of the larger operand. If the operands are 118 // equivalent (e.g. 3 and 3.0), the field does not change. 119 // 0, 0.0, and -0.0 are all zero. The maximum of a zero stored value and 120 // zero input value is always the stored value. 121 // The maximum of any numeric value x and NaN is NaN. 122 Value maximum = 4; 123 124 // Sets the field to the minimum of its current value and the given value. 125 // 126 // This must be an integer or a double value. 127 // If the field is not an integer or double, or if the field does not yet 128 // exist, the transformation will set the field to the input value. 129 // If a minimum operation is applied where the field and the input value 130 // are of mixed types (that is - one is an integer and one is a double) 131 // the field takes on the type of the smaller operand. If the operands are 132 // equivalent (e.g. 3 and 3.0), the field does not change. 133 // 0, 0.0, and -0.0 are all zero. The minimum of a zero stored value and 134 // zero input value is always the stored value. 135 // The minimum of any numeric value x and NaN is NaN. 136 Value minimum = 5; 137 138 // Append the given elements in order if they are not already present in 139 // the current field value. 140 // If the field is not an array, or if the field does not yet exist, it is 141 // first set to the empty array. 142 // 143 // Equivalent numbers of different types (e.g. 3L and 3.0) are 144 // considered equal when checking if a value is missing. 145 // NaN is equal to NaN, and Null is equal to Null. 146 // If the input contains multiple equivalent values, only the first will 147 // be considered. 148 // 149 // The corresponding transform_result will be the null value. 150 ArrayValue append_missing_elements = 6; 151 152 // Remove all of the given elements from the array in the field. 153 // If the field is not an array, or if the field does not yet exist, it is 154 // set to the empty array. 155 // 156 // Equivalent numbers of the different types (e.g. 3L and 3.0) are 157 // considered equal when deciding whether an element should be removed. 158 // NaN is equal to NaN, and Null is equal to Null. 159 // This will remove all equivalent values if there are duplicates. 160 // 161 // The corresponding transform_result will be the null value. 162 ArrayValue remove_all_from_array = 7; 163 } 164 } 165 166 // The name of the document to transform. 167 string document = 1; 168 169 // The list of transformations to apply to the fields of the document, in 170 // order. 171 // This must not be empty. 172 repeated FieldTransform field_transforms = 2; 173} 174 175// The result of applying a write. 176message WriteResult { 177 // The last update time of the document after applying the write. Not set 178 // after a `delete`. 179 // 180 // If the write did not actually change the document, this will be the 181 // previous update_time. 182 google.protobuf.Timestamp update_time = 1; 183 184 // The results of applying each 185 // [DocumentTransform.FieldTransform][google.firestore.v1.DocumentTransform.FieldTransform], 186 // in the same order. 187 repeated Value transform_results = 2; 188} 189 190// A [Document][google.firestore.v1.Document] has changed. 191// 192// May be the result of multiple [writes][google.firestore.v1.Write], including 193// deletes, that ultimately resulted in a new value for the 194// [Document][google.firestore.v1.Document]. 195// 196// Multiple [DocumentChange][google.firestore.v1.DocumentChange] messages may be 197// returned for the same logical change, if multiple targets are affected. 198message DocumentChange { 199 // The new state of the [Document][google.firestore.v1.Document]. 200 // 201 // If `mask` is set, contains only fields that were updated or added. 202 Document document = 1; 203 204 // A set of target IDs of targets that match this document. 205 repeated int32 target_ids = 5; 206 207 // A set of target IDs for targets that no longer match this document. 208 repeated int32 removed_target_ids = 6; 209} 210 211// A [Document][google.firestore.v1.Document] has been deleted. 212// 213// May be the result of multiple [writes][google.firestore.v1.Write], including 214// updates, the last of which deleted the 215// [Document][google.firestore.v1.Document]. 216// 217// Multiple [DocumentDelete][google.firestore.v1.DocumentDelete] messages may be 218// returned for the same logical delete, if multiple targets are affected. 219message DocumentDelete { 220 // The resource name of the [Document][google.firestore.v1.Document] that was 221 // deleted. 222 string document = 1; 223 224 // A set of target IDs for targets that previously matched this entity. 225 repeated int32 removed_target_ids = 6; 226 227 // The read timestamp at which the delete was observed. 228 // 229 // Greater or equal to the `commit_time` of the delete. 230 google.protobuf.Timestamp read_time = 4; 231} 232 233// A [Document][google.firestore.v1.Document] has been removed from the view of 234// the targets. 235// 236// Sent if the document is no longer relevant to a target and is out of view. 237// Can be sent instead of a DocumentDelete or a DocumentChange if the server 238// can not send the new value of the document. 239// 240// Multiple [DocumentRemove][google.firestore.v1.DocumentRemove] messages may be 241// returned for the same logical write or delete, if multiple targets are 242// affected. 243message DocumentRemove { 244 // The resource name of the [Document][google.firestore.v1.Document] that has 245 // gone out of view. 246 string document = 1; 247 248 // A set of target IDs for targets that previously matched this document. 249 repeated int32 removed_target_ids = 2; 250 251 // The read timestamp at which the remove was observed. 252 // 253 // Greater or equal to the `commit_time` of the change/delete/remove. 254 google.protobuf.Timestamp read_time = 4; 255} 256 257// A digest of all the documents that match a given target. 258message ExistenceFilter { 259 // The target ID to which this filter applies. 260 int32 target_id = 1; 261 262 // The total count of documents that match 263 // [target_id][google.firestore.v1.ExistenceFilter.target_id]. 264 // 265 // If different from the count of documents in the client that match, the 266 // client must manually determine which documents no longer match the target. 267 // 268 // The client can use the `unchanged_names` bloom filter to assist with 269 // this determination by testing ALL the document names against the filter; 270 // if the document name is NOT in the filter, it means the document no 271 // longer matches the target. 272 int32 count = 2; 273 274 // A bloom filter that, despite its name, contains the UTF-8 byte encodings of 275 // the resource names of ALL the documents that match 276 // [target_id][google.firestore.v1.ExistenceFilter.target_id], in the form 277 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. 278 // 279 // This bloom filter may be omitted at the server's discretion, such as if it 280 // is deemed that the client will not make use of it or if it is too 281 // computationally expensive to calculate or transmit. Clients must gracefully 282 // handle this field being absent by falling back to the logic used before 283 // this field existed; that is, re-add the target without a resume token to 284 // figure out which documents in the client's cache are out of sync. 285 BloomFilter unchanged_names = 3; 286} 287