1// Copyright 2020 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// 15 16// This file defines the format of Firestore bundle file/stream. It is not a part of the 17// Firestore API, only a specification used by Server and Client SDK to write and read 18// bundles. 19 20syntax = "proto3"; 21 22package google.firestore.bundle; 23 24import "google/firestore/v1/document.proto"; 25import "google/firestore/v1/query.proto"; 26import "google/protobuf/timestamp.proto"; 27 28option csharp_namespace = "Firestore.Bundle"; 29option go_package = "cloud.google.com/go/firestore/bundle/bundlepb;bundlepb"; 30option java_multiple_files = true; 31option java_outer_classname = "BundleProto"; 32option java_package = "com.google.firestore.bundle"; 33option objc_class_prefix = "FSTPB"; 34option php_namespace = "Firestore\\Bundle"; 35 36// Encodes a query saved in the bundle. 37message BundledQuery { 38 // The parent resource name. 39 string parent = 1; 40 41 // The query to run. 42 oneof query_type { 43 // A structured query. 44 google.firestore.v1.StructuredQuery structured_query = 2; 45 } 46 47 // If the query is a limit query, should the limit be applied to the beginning or 48 // the end of results. 49 enum LimitType { 50 FIRST = 0; 51 LAST = 1; 52 } 53 LimitType limit_type = 3; 54} 55 56// A Query associated with a name, created as part of the bundle file, and can be read 57// by client SDKs once the bundle containing them is loaded. 58message NamedQuery { 59 // Name of the query, such that client can use the name to load this query 60 // from bundle, and resume from when the query results are materialized 61 // into this bundle. 62 string name = 1; 63 64 // The query saved in the bundle. 65 BundledQuery bundled_query = 2; 66 67 // The read time of the query, when it is used to build the bundle. This is useful to 68 // resume the query from the bundle, once it is loaded by client SDKs. 69 google.protobuf.Timestamp read_time = 3; 70} 71 72// Metadata describing a Firestore document saved in the bundle. 73message BundledDocumentMetadata { 74 // The document key of a bundled document. 75 string name = 1; 76 77 // The snapshot version of the document data bundled. 78 google.protobuf.Timestamp read_time = 2; 79 80 // Whether the document exists. 81 bool exists = 3; 82 83 // The names of the queries in this bundle that this document matches to. 84 repeated string queries = 4; 85} 86 87// Metadata describing the bundle file/stream. 88message BundleMetadata { 89 // The ID of the bundle. 90 string id = 1; 91 92 // Time at which the documents snapshot is taken for this bundle. 93 google.protobuf.Timestamp create_time = 2; 94 95 // The schema version of the bundle. 96 uint32 version = 3; 97 98 // The number of documents in the bundle. 99 uint32 total_documents = 4; 100 101 // The size of the bundle in bytes, excluding this `BundleMetadata`. 102 uint64 total_bytes = 5; 103} 104 105// A Firestore bundle is a length-prefixed stream of JSON representations of 106// `BundleElement`. 107// Only one `BundleMetadata` is expected, and it should be the first element. 108// The named queries follow after `metadata`. Every `document_metadata` is 109// immediately followed by a `document`. 110message BundleElement { 111 oneof element_type { 112 BundleMetadata metadata = 1; 113 114 NamedQuery named_query = 2; 115 116 BundledDocumentMetadata document_metadata = 3; 117 118 google.firestore.v1.Document document = 4; 119 } 120} 121