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/firestore/v1/query.proto";
24 import "google/firestore/v1/write.proto";
25 import "google/protobuf/empty.proto";
26 import "google/protobuf/timestamp.proto";
27 import "google/rpc/status.proto";
29 option csharp_namespace = "Google.Cloud.Firestore.V1";
30 option go_package = "google.golang.org/genproto/googleapis/firestore/v1;firestore";
31 option java_multiple_files = true;
32 option java_outer_classname = "FirestoreProto";
33 option java_package = "com.google.firestore.v1";
34 option objc_class_prefix = "GCFS";
35 option php_namespace = "Google\\Cloud\\Firestore\\V1";
37 // Specification of the Firestore API.
39 // The Cloud Firestore service.
41 // This service exposes several types of comparable timestamps:
43 // * `create_time` - The time at which a document was created. Changes only
44 // when a document is deleted, then re-created. Increases in a strict
46 // * `update_time` - The time at which a document was last updated. Changes
47 // every time a document is modified. Does not change when a write results
48 // in no modifications. Increases in a strict monotonic fashion.
49 // * `read_time` - The time at which a particular state was observed. Used
50 // to denote a consistent snapshot of the database or the time at which a
51 // Document was observed to not exist.
52 // * `commit_time` - The time at which the writes in a transaction were
53 // committed. Any read with an equal or greater `read_time` is guaranteed
54 // to see the effects of the transaction.
56 // Gets a single document.
57 rpc GetDocument(GetDocumentRequest) returns (Document) {
58 option (google.api.http) = {
59 get: "/v1/{name=projects/*/databases/*/documents/*/**}"
64 rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) {
65 option (google.api.http) = {
66 get: "/v1/{parent=projects/*/databases/*/documents/*/**}/{collection_id}"
70 // Creates a new document.
71 rpc CreateDocument(CreateDocumentRequest) returns (Document) {
72 option (google.api.http) = {
73 post: "/v1/{parent=projects/*/databases/*/documents/**}/{collection_id}"
78 // Updates or inserts a document.
79 rpc UpdateDocument(UpdateDocumentRequest) returns (Document) {
80 option (google.api.http) = {
81 patch: "/v1/{document.name=projects/*/databases/*/documents/*/**}"
86 // Deletes a document.
87 rpc DeleteDocument(DeleteDocumentRequest) returns (google.protobuf.Empty) {
88 option (google.api.http) = {
89 delete: "/v1/{name=projects/*/databases/*/documents/*/**}"
93 // Gets multiple documents.
95 // Documents returned by this method are not guaranteed to be returned in the
96 // same order that they were requested.
97 rpc BatchGetDocuments(BatchGetDocumentsRequest)
98 returns (stream BatchGetDocumentsResponse) {
99 option (google.api.http) = {
100 post: "/v1/{database=projects/*/databases/*}/documents:batchGet"
105 // Starts a new transaction.
106 rpc BeginTransaction(BeginTransactionRequest)
107 returns (BeginTransactionResponse) {
108 option (google.api.http) = {
109 post: "/v1/{database=projects/*/databases/*}/documents:beginTransaction"
114 // Commits a transaction, while optionally updating documents.
115 rpc Commit(CommitRequest) returns (CommitResponse) {
116 option (google.api.http) = {
117 post: "/v1/{database=projects/*/databases/*}/documents:commit"
122 // Rolls back a transaction.
123 rpc Rollback(RollbackRequest) returns (google.protobuf.Empty) {
124 option (google.api.http) = {
125 post: "/v1/{database=projects/*/databases/*}/documents:rollback"
131 rpc RunQuery(RunQueryRequest) returns (stream RunQueryResponse) {
132 option (google.api.http) = {
133 post: "/v1/{parent=projects/*/databases/*/documents}:runQuery"
135 additional_bindings {
136 post: "/v1/{parent=projects/*/databases/*/documents/*/**}:runQuery"
142 // Streams batches of document updates and deletes, in order.
143 rpc Write(stream WriteRequest) returns (stream WriteResponse) {
144 option (google.api.http) = {
145 post: "/v1/{database=projects/*/databases/*}/documents:write"
150 // Listens to changes.
151 rpc Listen(stream ListenRequest) returns (stream ListenResponse) {
152 option (google.api.http) = {
153 post: "/v1/{database=projects/*/databases/*}/documents:listen"
158 // Lists all the collection IDs underneath a document.
159 rpc ListCollectionIds(ListCollectionIdsRequest)
160 returns (ListCollectionIdsResponse) {
161 option (google.api.http) = {
162 post: "/v1/{parent=projects/*/databases/*/documents}:listCollectionIds"
164 additional_bindings {
165 post: "/v1/{parent=projects/*/databases/*/documents/*/**}:listCollectionIds"
173 // [Firestore.GetDocument][google.firestore.v1.Firestore.GetDocument].
174 message GetDocumentRequest {
175 // The resource name of the Document to get. In the format:
176 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
179 // The fields to return. If not set, returns all fields.
181 // If the document has a field that is not present in this mask, that field
182 // will not be returned in the response.
183 DocumentMask mask = 2;
185 // The consistency mode for this transaction.
186 // If not set, defaults to strong consistency.
187 oneof consistency_selector {
188 // Reads the document in a transaction.
189 bytes transaction = 3;
191 // Reads the version of the document at the given time.
192 // This may not be older than 60 seconds.
193 google.protobuf.Timestamp read_time = 5;
198 // [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].
199 message ListDocumentsRequest {
200 // The parent resource name. In the format:
201 // `projects/{project_id}/databases/{database_id}/documents` or
202 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
204 // `projects/my-project/databases/my-database/documents` or
205 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
208 // The collection ID, relative to `parent`, to list. For example: `chatrooms`
210 string collection_id = 2;
212 // The maximum number of documents to return.
215 // The `next_page_token` value returned from a previous List request, if any.
216 string page_token = 4;
218 // The order to sort results by. For example: `priority desc, name`.
221 // The fields to return. If not set, returns all fields.
223 // If a document has a field that is not present in this mask, that field
224 // will not be returned in the response.
225 DocumentMask mask = 7;
227 // The consistency mode for this transaction.
228 // If not set, defaults to strong consistency.
229 oneof consistency_selector {
230 // Reads documents in a transaction.
231 bytes transaction = 8;
233 // Reads documents as they were at the given time.
234 // This may not be older than 60 seconds.
235 google.protobuf.Timestamp read_time = 10;
238 // If the list should show missing documents. A missing document is a
239 // document that does not exist but has sub-documents. These documents will
240 // be returned with a key but will not have fields,
241 // [Document.create_time][google.firestore.v1.Document.create_time], or
242 // [Document.update_time][google.firestore.v1.Document.update_time] set.
244 // Requests with `show_missing` may not specify `where` or
246 bool show_missing = 12;
250 // [Firestore.ListDocuments][google.firestore.v1.Firestore.ListDocuments].
251 message ListDocumentsResponse {
252 // The Documents found.
253 repeated Document documents = 1;
255 // The next page token.
256 string next_page_token = 2;
260 // [Firestore.CreateDocument][google.firestore.v1.Firestore.CreateDocument].
261 message CreateDocumentRequest {
262 // The parent resource. For example:
263 // `projects/{project_id}/databases/{database_id}/documents` or
264 // `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}`
267 // The collection ID, relative to `parent`, to list. For example: `chatrooms`.
268 string collection_id = 2;
270 // The client-assigned document ID to use for this document.
272 // Optional. If not specified, an ID will be assigned by the service.
273 string document_id = 3;
275 // The document to create. `name` must not be set.
276 Document document = 4;
278 // The fields to return. If not set, returns all fields.
280 // If the document has a field that is not present in this mask, that field
281 // will not be returned in the response.
282 DocumentMask mask = 5;
286 // [Firestore.UpdateDocument][google.firestore.v1.Firestore.UpdateDocument].
287 message UpdateDocumentRequest {
288 // The updated document.
289 // Creates the document if it does not already exist.
290 Document document = 1;
292 // The fields to update.
293 // None of the field paths in the mask may contain a reserved name.
295 // If the document exists on the server and has fields not referenced in the
296 // mask, they are left unchanged.
297 // Fields referenced in the mask, but not present in the input document, are
298 // deleted from the document on the server.
299 DocumentMask update_mask = 2;
301 // The fields to return. If not set, returns all fields.
303 // If the document has a field that is not present in this mask, that field
304 // will not be returned in the response.
305 DocumentMask mask = 3;
307 // An optional precondition on the document.
308 // The request will fail if this is set and not met by the target document.
309 Precondition current_document = 4;
313 // [Firestore.DeleteDocument][google.firestore.v1.Firestore.DeleteDocument].
314 message DeleteDocumentRequest {
315 // The resource name of the Document to delete. In the format:
316 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
319 // An optional precondition on the document.
320 // The request will fail if this is set and not met by the target document.
321 Precondition current_document = 2;
325 // [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].
326 message BatchGetDocumentsRequest {
327 // The database name. In the format:
328 // `projects/{project_id}/databases/{database_id}`.
331 // The names of the documents to retrieve. In the format:
332 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
333 // The request will fail if any of the document is not a child resource of the
334 // given `database`. Duplicate names will be elided.
335 repeated string documents = 2;
337 // The fields to return. If not set, returns all fields.
339 // If a document has a field that is not present in this mask, that field will
340 // not be returned in the response.
341 DocumentMask mask = 3;
343 // The consistency mode for this transaction.
344 // If not set, defaults to strong consistency.
345 oneof consistency_selector {
346 // Reads documents in a transaction.
347 bytes transaction = 4;
349 // Starts a new transaction and reads the documents.
350 // Defaults to a read-only transaction.
351 // The new transaction ID will be returned as the first response in the
353 TransactionOptions new_transaction = 5;
355 // Reads documents as they were at the given time.
356 // This may not be older than 60 seconds.
357 google.protobuf.Timestamp read_time = 7;
361 // The streamed response for
362 // [Firestore.BatchGetDocuments][google.firestore.v1.Firestore.BatchGetDocuments].
363 message BatchGetDocumentsResponse {
365 // This can be empty if the server is just returning a transaction.
367 // A document that was requested.
370 // A document name that was requested but does not exist. In the format:
371 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
375 // The transaction that was started as part of this request.
376 // Will only be set in the first response, and only if
377 // [BatchGetDocumentsRequest.new_transaction][google.firestore.v1.BatchGetDocumentsRequest.new_transaction]
378 // was set in the request.
379 bytes transaction = 3;
381 // The time at which the document was read.
382 // This may be monotically increasing, in this case the previous documents in
383 // the result stream are guaranteed not to have changed between their
384 // read_time and this one.
385 google.protobuf.Timestamp read_time = 4;
389 // [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].
390 message BeginTransactionRequest {
391 // The database name. In the format:
392 // `projects/{project_id}/databases/{database_id}`.
395 // The options for the transaction.
396 // Defaults to a read-write transaction.
397 TransactionOptions options = 2;
401 // [Firestore.BeginTransaction][google.firestore.v1.Firestore.BeginTransaction].
402 message BeginTransactionResponse {
403 // The transaction that was started.
404 bytes transaction = 1;
407 // The request for [Firestore.Commit][google.firestore.v1.Firestore.Commit].
408 message CommitRequest {
409 // The database name. In the format:
410 // `projects/{project_id}/databases/{database_id}`.
413 // The writes to apply.
415 // Always executed atomically and in order.
416 repeated Write writes = 2;
418 // If set, applies all writes in this transaction, and commits it.
419 bytes transaction = 3;
422 // The response for [Firestore.Commit][google.firestore.v1.Firestore.Commit].
423 message CommitResponse {
424 // The result of applying the writes.
426 // This i-th write result corresponds to the i-th write in the
428 repeated WriteResult write_results = 1;
430 // The time at which the commit occurred.
431 google.protobuf.Timestamp commit_time = 2;
434 // The request for [Firestore.Rollback][google.firestore.v1.Firestore.Rollback].
435 message RollbackRequest {
436 // The database name. In the format:
437 // `projects/{project_id}/databases/{database_id}`.
440 // The transaction to roll back.
441 bytes transaction = 2;
444 // The request for [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].
445 message RunQueryRequest {
446 // The parent resource name. In the format:
447 // `projects/{project_id}/databases/{database_id}/documents` or
448 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
450 // `projects/my-project/databases/my-database/documents` or
451 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
456 // A structured query.
457 StructuredQuery structured_query = 2;
460 // The consistency mode for this transaction.
461 // If not set, defaults to strong consistency.
462 oneof consistency_selector {
463 // Reads documents in a transaction.
464 bytes transaction = 5;
466 // Starts a new transaction and reads the documents.
467 // Defaults to a read-only transaction.
468 // The new transaction ID will be returned as the first response in the
470 TransactionOptions new_transaction = 6;
472 // Reads documents as they were at the given time.
473 // This may not be older than 60 seconds.
474 google.protobuf.Timestamp read_time = 7;
479 // [Firestore.RunQuery][google.firestore.v1.Firestore.RunQuery].
480 message RunQueryResponse {
481 // The transaction that was started as part of this request.
482 // Can only be set in the first response, and only if
483 // [RunQueryRequest.new_transaction][google.firestore.v1.RunQueryRequest.new_transaction]
484 // was set in the request. If set, no other fields will be set in this
486 bytes transaction = 2;
489 // Not set when reporting partial progress.
490 Document document = 1;
492 // The time at which the document was read. This may be monotonically
493 // increasing; in this case, the previous documents in the result stream are
494 // guaranteed not to have changed between their `read_time` and this one.
496 // If the query returns no results, a response with `read_time` and no
497 // `document` will be sent, and this represents the time at which the query
499 google.protobuf.Timestamp read_time = 3;
501 // The number of results that have been skipped due to an offset between
502 // the last response and the current response.
503 int32 skipped_results = 4;
506 // The request for [Firestore.Write][google.firestore.v1.Firestore.Write].
508 // The first request creates a stream, or resumes an existing one from a token.
510 // When creating a new stream, the server replies with a response containing
511 // only an ID and a token, to use in the next request.
513 // When resuming a stream, the server first streams any responses later than the
514 // given token, then a response containing only an up-to-date token, to use in
516 message WriteRequest {
517 // The database name. In the format:
518 // `projects/{project_id}/databases/{database_id}`.
519 // This is only required in the first message.
522 // The ID of the write stream to resume.
523 // This may only be set in the first message. When left empty, a new write
524 // stream will be created.
525 string stream_id = 2;
527 // The writes to apply.
529 // Always executed atomically and in order.
530 // This must be empty on the first request.
531 // This may be empty on the last request.
532 // This must not be empty on all other requests.
533 repeated Write writes = 3;
535 // A stream token that was previously sent by the server.
537 // The client should set this field to the token from the most recent
538 // [WriteResponse][google.firestore.v1.WriteResponse] it has received. This
539 // acknowledges that the client has received responses up to this token. After
540 // sending this token, earlier tokens may not be used anymore.
542 // The server may close the stream if there are too many unacknowledged
545 // Leave this field unset when creating a new stream. To resume a stream at
546 // a specific point, set this field and the `stream_id` field.
548 // Leave this field unset when creating a new stream.
549 bytes stream_token = 4;
551 // Labels associated with this write request.
552 map<string, string> labels = 5;
555 // The response for [Firestore.Write][google.firestore.v1.Firestore.Write].
556 message WriteResponse {
557 // The ID of the stream.
558 // Only set on the first message, when a new stream was created.
559 string stream_id = 1;
561 // A token that represents the position of this response in the stream.
562 // This can be used by a client to resume the stream at this point.
564 // This field is always set.
565 bytes stream_token = 2;
567 // The result of applying the writes.
569 // This i-th write result corresponds to the i-th write in the
571 repeated WriteResult write_results = 3;
573 // The time at which the commit occurred.
574 google.protobuf.Timestamp commit_time = 4;
577 // A request for [Firestore.Listen][google.firestore.v1.Firestore.Listen]
578 message ListenRequest {
579 // The database name. In the format:
580 // `projects/{project_id}/databases/{database_id}`.
583 // The supported target changes.
584 oneof target_change {
585 // A target to add to this stream.
586 Target add_target = 2;
588 // The ID of a target to remove from this stream.
589 int32 remove_target = 3;
592 // Labels associated with this target change.
593 map<string, string> labels = 4;
596 // The response for [Firestore.Listen][google.firestore.v1.Firestore.Listen].
597 message ListenResponse {
598 // The supported responses.
599 oneof response_type {
600 // Targets have changed.
601 TargetChange target_change = 2;
603 // A [Document][google.firestore.v1.Document] has changed.
604 DocumentChange document_change = 3;
606 // A [Document][google.firestore.v1.Document] has been deleted.
607 DocumentDelete document_delete = 4;
609 // A [Document][google.firestore.v1.Document] has been removed from a target
610 // (because it is no longer relevant to that target).
611 DocumentRemove document_remove = 6;
613 // A filter to apply to the set of documents previously returned for the
616 // Returned when documents may have been removed from the given target, but
617 // the exact documents are unknown.
618 ExistenceFilter filter = 5;
622 // A specification of a set of documents to listen to.
624 // A target specified by a set of documents names.
625 message DocumentsTarget {
626 // The names of the documents to retrieve. In the format:
627 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
628 // The request will fail if any of the document is not a child resource of
629 // the given `database`. Duplicate names will be elided.
630 repeated string documents = 2;
633 // A target specified by a query.
634 message QueryTarget {
635 // The parent resource name. In the format:
636 // `projects/{project_id}/databases/{database_id}/documents` or
637 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
639 // `projects/my-project/databases/my-database/documents` or
640 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
645 // A structured query.
646 StructuredQuery structured_query = 2;
650 // The type of target to listen to.
652 // A target specified by a query.
653 QueryTarget query = 2;
655 // A target specified by a set of document names.
656 DocumentsTarget documents = 3;
659 // When to start listening.
661 // If not specified, all matching Documents are returned before any
662 // subsequent changes.
664 // A resume token from a prior
665 // [TargetChange][google.firestore.v1.TargetChange] for an identical target.
667 // Using a resume token with a different target is unsupported and may fail.
668 bytes resume_token = 4;
670 // Start listening after a specific `read_time`.
672 // The client must know the state of matching documents at this time.
673 google.protobuf.Timestamp read_time = 11;
676 // A client provided target ID.
678 // If not set, the server will assign an ID for the target.
680 // Used for resuming a target without changing IDs. The IDs can either be
681 // client-assigned or be server-assigned in a previous stream. All targets
682 // with client provided IDs must be added before adding a target that needs
683 // a server-assigned id.
686 // If the target should be removed once it is current and consistent.
690 // Targets being watched have changed.
691 message TargetChange {
692 // The type of change.
693 enum TargetChangeType {
694 // No change has occurred. Used only to send an updated `resume_token`.
697 // The targets have been added.
700 // The targets have been removed.
703 // The targets reflect all changes committed before the targets were added
706 // This will be sent after or with a `read_time` that is greater than or
707 // equal to the time at which the targets were added.
709 // Listeners can wait for this change if read-after-write semantics
713 // The targets have been reset, and a new initial state for the targets
714 // will be returned in subsequent changes.
716 // After the initial state is complete, `CURRENT` will be returned even
717 // if the target was previously indicated to be `CURRENT`.
721 // The type of change that occurred.
722 TargetChangeType target_change_type = 1;
724 // The target IDs of targets that have changed.
726 // If empty, the change applies to all targets.
728 // For `target_change_type=ADD`, the order of the target IDs matches the order
729 // of the requests to add the targets. This allows clients to unambiguously
730 // associate server-assigned target IDs with added targets.
732 // For other states, the order of the target IDs is not defined.
733 repeated int32 target_ids = 2;
735 // The error that resulted in this change, if applicable.
736 google.rpc.Status cause = 3;
738 // A token that can be used to resume the stream for the given `target_ids`,
739 // or all targets if `target_ids` is empty.
741 // Not set on every target change.
742 bytes resume_token = 4;
744 // The consistent `read_time` for the given `target_ids` (omitted when the
745 // target_ids are not at a consistent snapshot).
747 // The stream is guaranteed to send a `read_time` with `target_ids` empty
748 // whenever the entire stream reaches a new consistent snapshot. ADD,
749 // CURRENT, and RESET messages are guaranteed to (eventually) result in a
750 // new consistent snapshot (while NO_CHANGE and REMOVE messages are not).
752 // For a given stream, `read_time` is guaranteed to be monotonically
754 google.protobuf.Timestamp read_time = 6;
758 // [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].
759 message ListCollectionIdsRequest {
760 // The parent document. In the format:
761 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
763 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
766 // The maximum number of results to return.
769 // A page token. Must be a value from
770 // [ListCollectionIdsResponse][google.firestore.v1.ListCollectionIdsResponse].
771 string page_token = 3;
775 // [Firestore.ListCollectionIds][google.firestore.v1.Firestore.ListCollectionIds].
776 message ListCollectionIdsResponse {
777 // The collection ids.
778 repeated string collection_ids = 1;
780 // A page token that may be used to continue the list.
781 string next_page_token = 2;