1// Copyright 2021 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.v1beta1; 18 19import "google/firestore/v1beta1/document.proto"; 20import "google/protobuf/wrappers.proto"; 21 22option csharp_namespace = "Google.Cloud.Firestore.V1Beta1"; 23option go_package = "cloud.google.com/go/firestore/apiv1beta1/firestorepb;firestorepb"; 24option java_multiple_files = true; 25option java_outer_classname = "QueryProto"; 26option java_package = "com.google.firestore.v1beta1"; 27option objc_class_prefix = "GCFS"; 28option php_namespace = "Google\\Cloud\\Firestore\\V1beta1"; 29option ruby_package = "Google::Cloud::Firestore::V1beta1"; 30 31// A Firestore query. 32message StructuredQuery { 33 // A selection of a collection, such as `messages as m1`. 34 message CollectionSelector { 35 // The collection ID. 36 // When set, selects only collections with this ID. 37 string collection_id = 2; 38 39 // When false, selects only collections that are immediate children of 40 // the `parent` specified in the containing `RunQueryRequest`. 41 // When true, selects all descendant collections. 42 bool all_descendants = 3; 43 } 44 45 // A filter. 46 message Filter { 47 // The type of filter. 48 oneof filter_type { 49 // A composite filter. 50 CompositeFilter composite_filter = 1; 51 52 // A filter on a document field. 53 FieldFilter field_filter = 2; 54 55 // A filter that takes exactly one argument. 56 UnaryFilter unary_filter = 3; 57 } 58 } 59 60 // A filter that merges multiple other filters using the given operator. 61 message CompositeFilter { 62 // A composite filter operator. 63 enum Operator { 64 // Unspecified. This value must not be used. 65 OPERATOR_UNSPECIFIED = 0; 66 67 // The results are required to satisfy each of the combined filters. 68 AND = 1; 69 } 70 71 // The operator for combining multiple filters. 72 Operator op = 1; 73 74 // The list of filters to combine. 75 // Must contain at least one filter. 76 repeated Filter filters = 2; 77 } 78 79 // A filter on a specific field. 80 message FieldFilter { 81 // A field filter operator. 82 enum Operator { 83 // Unspecified. This value must not be used. 84 OPERATOR_UNSPECIFIED = 0; 85 86 // The given `field` is less than the given `value`. 87 // 88 // Requires: 89 // 90 // * That `field` come first in `order_by`. 91 LESS_THAN = 1; 92 93 // The given `field` is less than or equal to the given `value`. 94 // 95 // Requires: 96 // 97 // * That `field` come first in `order_by`. 98 LESS_THAN_OR_EQUAL = 2; 99 100 // The given `field` is greater than the given `value`. 101 // 102 // Requires: 103 // 104 // * That `field` come first in `order_by`. 105 GREATER_THAN = 3; 106 107 // The given `field` is greater than or equal to the given `value`. 108 // 109 // Requires: 110 // 111 // * That `field` come first in `order_by`. 112 GREATER_THAN_OR_EQUAL = 4; 113 114 // The given `field` is equal to the given `value`. 115 EQUAL = 5; 116 117 // The given `field` is not equal to the given `value`. 118 // 119 // Requires: 120 // 121 // * No other `NOT_EQUAL`, `NOT_IN`, `IS_NOT_NULL`, or `IS_NOT_NAN`. 122 // * That `field` comes first in the `order_by`. 123 NOT_EQUAL = 6; 124 125 // The given `field` is an array that contains the given `value`. 126 ARRAY_CONTAINS = 7; 127 128 // The given `field` is equal to at least one value in the given array. 129 // 130 // Requires: 131 // 132 // * That `value` is a non-empty `ArrayValue` with at most 10 values. 133 // * No other `IN` or `ARRAY_CONTAINS_ANY` or `NOT_IN`. 134 IN = 8; 135 136 // The given `field` is an array that contains any of the values in the 137 // given array. 138 // 139 // Requires: 140 // 141 // * That `value` is a non-empty `ArrayValue` with at most 10 values. 142 // * No other `IN` or `ARRAY_CONTAINS_ANY` or `NOT_IN`. 143 ARRAY_CONTAINS_ANY = 9; 144 145 // The value of the `field` is not in the given array. 146 // 147 // Requires: 148 // 149 // * That `value` is a non-empty `ArrayValue` with at most 10 values. 150 // * No other `IN`, `ARRAY_CONTAINS_ANY`, `NOT_IN`, `NOT_EQUAL`, 151 // `IS_NOT_NULL`, or `IS_NOT_NAN`. 152 // * That `field` comes first in the `order_by`. 153 NOT_IN = 10; 154 } 155 156 // The field to filter by. 157 FieldReference field = 1; 158 159 // The operator to filter by. 160 Operator op = 2; 161 162 // The value to compare to. 163 Value value = 3; 164 } 165 166 // A filter with a single operand. 167 message UnaryFilter { 168 // A unary operator. 169 enum Operator { 170 // Unspecified. This value must not be used. 171 OPERATOR_UNSPECIFIED = 0; 172 173 // The given `field` is equal to `NaN`. 174 IS_NAN = 2; 175 176 // The given `field` is equal to `NULL`. 177 IS_NULL = 3; 178 179 // The given `field` is not equal to `NaN`. 180 // 181 // Requires: 182 // 183 // * No other `NOT_EQUAL`, `NOT_IN`, `IS_NOT_NULL`, or `IS_NOT_NAN`. 184 // * That `field` comes first in the `order_by`. 185 IS_NOT_NAN = 4; 186 187 // The given `field` is not equal to `NULL`. 188 // 189 // Requires: 190 // 191 // * A single `NOT_EQUAL`, `NOT_IN`, `IS_NOT_NULL`, or `IS_NOT_NAN`. 192 // * That `field` comes first in the `order_by`. 193 IS_NOT_NULL = 5; 194 } 195 196 // The unary operator to apply. 197 Operator op = 1; 198 199 // The argument to the filter. 200 oneof operand_type { 201 // The field to which to apply the operator. 202 FieldReference field = 2; 203 } 204 } 205 206 // A reference to a field, such as `max(messages.time) as max_time`. 207 message FieldReference { 208 string field_path = 2; 209 } 210 211 // An order on a field. 212 message Order { 213 // The field to order by. 214 FieldReference field = 1; 215 216 // The direction to order by. Defaults to `ASCENDING`. 217 Direction direction = 2; 218 } 219 220 // The projection of document's fields to return. 221 message Projection { 222 // The fields to return. 223 // 224 // If empty, all fields are returned. To only return the name 225 // of the document, use `['__name__']`. 226 repeated FieldReference fields = 2; 227 } 228 229 // A sort direction. 230 enum Direction { 231 // Unspecified. 232 DIRECTION_UNSPECIFIED = 0; 233 234 // Ascending. 235 ASCENDING = 1; 236 237 // Descending. 238 DESCENDING = 2; 239 } 240 241 // The projection to return. 242 Projection select = 1; 243 244 // The collections to query. 245 repeated CollectionSelector from = 2; 246 247 // The filter to apply. 248 Filter where = 3; 249 250 // The order to apply to the query results. 251 // 252 // Firestore guarantees a stable ordering through the following rules: 253 // 254 // * Any field required to appear in `order_by`, that is not already 255 // specified in `order_by`, is appended to the order in field name order 256 // by default. 257 // * If an order on `__name__` is not specified, it is appended by default. 258 // 259 // Fields are appended with the same sort direction as the last order 260 // specified, or 'ASCENDING' if no order was specified. For example: 261 // 262 // * `SELECT * FROM Foo ORDER BY A` becomes 263 // `SELECT * FROM Foo ORDER BY A, __name__` 264 // * `SELECT * FROM Foo ORDER BY A DESC` becomes 265 // `SELECT * FROM Foo ORDER BY A DESC, __name__ DESC` 266 // * `SELECT * FROM Foo WHERE A > 1` becomes 267 // `SELECT * FROM Foo WHERE A > 1 ORDER BY A, __name__` 268 repeated Order order_by = 4; 269 270 // A starting point for the query results. 271 Cursor start_at = 7; 272 273 // A end point for the query results. 274 Cursor end_at = 8; 275 276 // The number of results to skip. 277 // 278 // Applies before limit, but after all other constraints. Must be >= 0 if 279 // specified. 280 int32 offset = 6; 281 282 // The maximum number of results to return. 283 // 284 // Applies after all other constraints. 285 // Must be >= 0 if specified. 286 google.protobuf.Int32Value limit = 5; 287} 288 289// A position in a query result set. 290message Cursor { 291 // The values that represent a position, in the order they appear in 292 // the order by clause of a query. 293 // 294 // Can contain fewer values than specified in the order by clause. 295 repeated Value values = 1; 296 297 // If the position is just before or just after the given values, relative 298 // to the sort order defined by the query. 299 bool before = 2; 300} 301