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.v1beta1;
20 import "google/api/annotations.proto";
21 import "google/firestore/v1beta1/common.proto";
22 import "google/firestore/v1beta1/document.proto";
23 import "google/firestore/v1beta1/query.proto";
24 import "google/firestore/v1beta1/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.V1Beta1";
30 option go_package = "google.golang.org/genproto/googleapis/firestore/v1beta1;firestore";
31 option java_multiple_files = true;
32 option java_outer_classname = "FirestoreProto";
33 option java_package = "com.google.firestore.v1beta1";
34 option objc_class_prefix = "GCFS";
35 option php_namespace = "Google\\Cloud\\Firestore\\V1beta1";
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: "/v1beta1/{name=projects/*/databases/*/documents/*/**}"
64 rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) {
65 option (google.api.http) = {
66 get: "/v1beta1/{parent=projects/*/databases/*/documents/*/**}/{collection_id}"
70 // Creates a new document.
71 rpc CreateDocument(CreateDocumentRequest) returns (Document) {
72 option (google.api.http) = {
73 post: "/v1beta1/{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: "/v1beta1/{document.name=projects/*/databases/*/documents/*/**}"
86 // Deletes a document.
87 rpc DeleteDocument(DeleteDocumentRequest) returns (google.protobuf.Empty) {
88 option (google.api.http) = {
89 delete: "/v1beta1/{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: "/v1beta1/{database=projects/*/databases/*}/documents:batchGet"
105 // Starts a new transaction.
106 rpc BeginTransaction(BeginTransactionRequest)
107 returns (BeginTransactionResponse) {
108 option (google.api.http) = {
109 post: "/v1beta1/{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: "/v1beta1/{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: "/v1beta1/{database=projects/*/databases/*}/documents:rollback"
131 rpc RunQuery(RunQueryRequest) returns (stream RunQueryResponse) {
132 option (google.api.http) = {
133 post: "/v1beta1/{parent=projects/*/databases/*/documents}:runQuery"
135 additional_bindings {
136 post: "/v1beta1/{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: "/v1beta1/{database=projects/*/databases/*}/documents:write"
150 // Listens to changes.
151 rpc Listen(stream ListenRequest) returns (stream ListenResponse) {
152 option (google.api.http) = {
153 post: "/v1beta1/{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: "/v1beta1/{parent=projects/*/databases/*/documents}:listCollectionIds"
164 additional_bindings {
165 post: "/v1beta1/{parent=projects/*/databases/*/documents/*/**}:listCollectionIds"
173 // [Firestore.GetDocument][google.firestore.v1beta1.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.v1beta1.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.v1beta1.Document.create_time], or
242 // [Document.update_time][google.firestore.v1beta1.Document.update_time] set.
244 // Requests with `show_missing` may not specify `where` or
246 bool show_missing = 12;
250 // [Firestore.ListDocuments][google.firestore.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.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.v1beta1.Firestore.BeginTransaction].
402 message BeginTransactionResponse {
403 // The transaction that was started.
404 bytes transaction = 1;
408 // [Firestore.Commit][google.firestore.v1beta1.Firestore.Commit].
409 message CommitRequest {
410 // The database name. In the format:
411 // `projects/{project_id}/databases/{database_id}`.
414 // The writes to apply.
416 // Always executed atomically and in order.
417 repeated Write writes = 2;
419 // If set, applies all writes in this transaction, and commits it.
420 bytes transaction = 3;
424 // [Firestore.Commit][google.firestore.v1beta1.Firestore.Commit].
425 message CommitResponse {
426 // The result of applying the writes.
428 // This i-th write result corresponds to the i-th write in the
430 repeated WriteResult write_results = 1;
432 // The time at which the commit occurred.
433 google.protobuf.Timestamp commit_time = 2;
437 // [Firestore.Rollback][google.firestore.v1beta1.Firestore.Rollback].
438 message RollbackRequest {
439 // The database name. In the format:
440 // `projects/{project_id}/databases/{database_id}`.
443 // The transaction to roll back.
444 bytes transaction = 2;
448 // [Firestore.RunQuery][google.firestore.v1beta1.Firestore.RunQuery].
449 message RunQueryRequest {
450 // The parent resource name. In the format:
451 // `projects/{project_id}/databases/{database_id}/documents` or
452 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
454 // `projects/my-project/databases/my-database/documents` or
455 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
460 // A structured query.
461 StructuredQuery structured_query = 2;
464 // The consistency mode for this transaction.
465 // If not set, defaults to strong consistency.
466 oneof consistency_selector {
467 // Reads documents in a transaction.
468 bytes transaction = 5;
470 // Starts a new transaction and reads the documents.
471 // Defaults to a read-only transaction.
472 // The new transaction ID will be returned as the first response in the
474 TransactionOptions new_transaction = 6;
476 // Reads documents as they were at the given time.
477 // This may not be older than 60 seconds.
478 google.protobuf.Timestamp read_time = 7;
483 // [Firestore.RunQuery][google.firestore.v1beta1.Firestore.RunQuery].
484 message RunQueryResponse {
485 // The transaction that was started as part of this request.
486 // Can only be set in the first response, and only if
487 // [RunQueryRequest.new_transaction][google.firestore.v1beta1.RunQueryRequest.new_transaction]
488 // was set in the request. If set, no other fields will be set in this
490 bytes transaction = 2;
493 // Not set when reporting partial progress.
494 Document document = 1;
496 // The time at which the document was read. This may be monotonically
497 // increasing; in this case, the previous documents in the result stream are
498 // guaranteed not to have changed between their `read_time` and this one.
500 // If the query returns no results, a response with `read_time` and no
501 // `document` will be sent, and this represents the time at which the query
503 google.protobuf.Timestamp read_time = 3;
505 // The number of results that have been skipped due to an offset between
506 // the last response and the current response.
507 int32 skipped_results = 4;
510 // The request for [Firestore.Write][google.firestore.v1beta1.Firestore.Write].
512 // The first request creates a stream, or resumes an existing one from a token.
514 // When creating a new stream, the server replies with a response containing
515 // only an ID and a token, to use in the next request.
517 // When resuming a stream, the server first streams any responses later than the
518 // given token, then a response containing only an up-to-date token, to use in
520 message WriteRequest {
521 // The database name. In the format:
522 // `projects/{project_id}/databases/{database_id}`.
523 // This is only required in the first message.
526 // The ID of the write stream to resume.
527 // This may only be set in the first message. When left empty, a new write
528 // stream will be created.
529 string stream_id = 2;
531 // The writes to apply.
533 // Always executed atomically and in order.
534 // This must be empty on the first request.
535 // This may be empty on the last request.
536 // This must not be empty on all other requests.
537 repeated Write writes = 3;
539 // A stream token that was previously sent by the server.
541 // The client should set this field to the token from the most recent
542 // [WriteResponse][google.firestore.v1beta1.WriteResponse] it has received.
543 // This acknowledges that the client has received responses up to this token.
544 // After sending this token, earlier tokens may not be used anymore.
546 // The server may close the stream if there are too many unacknowledged
549 // Leave this field unset when creating a new stream. To resume a stream at
550 // a specific point, set this field and the `stream_id` field.
552 // Leave this field unset when creating a new stream.
553 bytes stream_token = 4;
555 // Labels associated with this write request.
556 map<string, string> labels = 5;
559 // The response for [Firestore.Write][google.firestore.v1beta1.Firestore.Write].
560 message WriteResponse {
561 // The ID of the stream.
562 // Only set on the first message, when a new stream was created.
563 string stream_id = 1;
565 // A token that represents the position of this response in the stream.
566 // This can be used by a client to resume the stream at this point.
568 // This field is always set.
569 bytes stream_token = 2;
571 // The result of applying the writes.
573 // This i-th write result corresponds to the i-th write in the
575 repeated WriteResult write_results = 3;
577 // The time at which the commit occurred.
578 google.protobuf.Timestamp commit_time = 4;
581 // A request for [Firestore.Listen][google.firestore.v1beta1.Firestore.Listen]
582 message ListenRequest {
583 // The database name. In the format:
584 // `projects/{project_id}/databases/{database_id}`.
587 // The supported target changes.
588 oneof target_change {
589 // A target to add to this stream.
590 Target add_target = 2;
592 // The ID of a target to remove from this stream.
593 int32 remove_target = 3;
596 // Labels associated with this target change.
597 map<string, string> labels = 4;
601 // [Firestore.Listen][google.firestore.v1beta1.Firestore.Listen].
602 message ListenResponse {
603 // The supported responses.
604 oneof response_type {
605 // Targets have changed.
606 TargetChange target_change = 2;
608 // A [Document][google.firestore.v1beta1.Document] has changed.
609 DocumentChange document_change = 3;
611 // A [Document][google.firestore.v1beta1.Document] has been deleted.
612 DocumentDelete document_delete = 4;
614 // A [Document][google.firestore.v1beta1.Document] has been removed from a
615 // target (because it is no longer relevant to that target).
616 DocumentRemove document_remove = 6;
618 // A filter to apply to the set of documents previously returned for the
621 // Returned when documents may have been removed from the given target, but
622 // the exact documents are unknown.
623 ExistenceFilter filter = 5;
627 // A specification of a set of documents to listen to.
629 // A target specified by a set of documents names.
630 message DocumentsTarget {
631 // The names of the documents to retrieve. In the format:
632 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
633 // The request will fail if any of the document is not a child resource of
634 // the given `database`. Duplicate names will be elided.
635 repeated string documents = 2;
638 // A target specified by a query.
639 message QueryTarget {
640 // The parent resource name. In the format:
641 // `projects/{project_id}/databases/{database_id}/documents` or
642 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
644 // `projects/my-project/databases/my-database/documents` or
645 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
650 // A structured query.
651 StructuredQuery structured_query = 2;
655 // The type of target to listen to.
657 // A target specified by a query.
658 QueryTarget query = 2;
660 // A target specified by a set of document names.
661 DocumentsTarget documents = 3;
664 // When to start listening.
666 // If not specified, all matching Documents are returned before any
667 // subsequent changes.
669 // A resume token from a prior
670 // [TargetChange][google.firestore.v1beta1.TargetChange] for an identical
673 // Using a resume token with a different target is unsupported and may fail.
674 bytes resume_token = 4;
676 // Start listening after a specific `read_time`.
678 // The client must know the state of matching documents at this time.
679 google.protobuf.Timestamp read_time = 11;
682 // A client provided target ID.
684 // If not set, the server will assign an ID for the target.
686 // Used for resuming a target without changing IDs. The IDs can either be
687 // client-assigned or be server-assigned in a previous stream. All targets
688 // with client provided IDs must be added before adding a target that needs
689 // a server-assigned id.
692 // If the target should be removed once it is current and consistent.
696 // Targets being watched have changed.
697 message TargetChange {
698 // The type of change.
699 enum TargetChangeType {
700 // No change has occurred. Used only to send an updated `resume_token`.
703 // The targets have been added.
706 // The targets have been removed.
709 // The targets reflect all changes committed before the targets were added
712 // This will be sent after or with a `read_time` that is greater than or
713 // equal to the time at which the targets were added.
715 // Listeners can wait for this change if read-after-write semantics
719 // The targets have been reset, and a new initial state for the targets
720 // will be returned in subsequent changes.
722 // After the initial state is complete, `CURRENT` will be returned even
723 // if the target was previously indicated to be `CURRENT`.
727 // The type of change that occurred.
728 TargetChangeType target_change_type = 1;
730 // The target IDs of targets that have changed.
732 // If empty, the change applies to all targets.
734 // For `target_change_type=ADD`, the order of the target IDs matches the order
735 // of the requests to add the targets. This allows clients to unambiguously
736 // associate server-assigned target IDs with added targets.
738 // For other states, the order of the target IDs is not defined.
739 repeated int32 target_ids = 2;
741 // The error that resulted in this change, if applicable.
742 google.rpc.Status cause = 3;
744 // A token that can be used to resume the stream for the given `target_ids`,
745 // or all targets if `target_ids` is empty.
747 // Not set on every target change.
748 bytes resume_token = 4;
750 // The consistent `read_time` for the given `target_ids` (omitted when the
751 // target_ids are not at a consistent snapshot).
753 // The stream is guaranteed to send a `read_time` with `target_ids` empty
754 // whenever the entire stream reaches a new consistent snapshot. ADD,
755 // CURRENT, and RESET messages are guaranteed to (eventually) result in a
756 // new consistent snapshot (while NO_CHANGE and REMOVE messages are not).
758 // For a given stream, `read_time` is guaranteed to be monotonically
760 google.protobuf.Timestamp read_time = 6;
764 // [Firestore.ListCollectionIds][google.firestore.v1beta1.Firestore.ListCollectionIds].
765 message ListCollectionIdsRequest {
766 // The parent document. In the format:
767 // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
769 // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
772 // The maximum number of results to return.
775 // A page token. Must be a value from
776 // [ListCollectionIdsResponse][google.firestore.v1beta1.ListCollectionIdsResponse].
777 string page_token = 3;
781 // [Firestore.ListCollectionIds][google.firestore.v1beta1.Firestore.ListCollectionIds].
782 message ListCollectionIdsResponse {
783 // The collection ids.
784 repeated string collection_ids = 1;
786 // A page token that may be used to continue the list.
787 string next_page_token = 2;