@google-cloud/firestore-api 0.1.0

package/build/protos/google/firestore/v1/bloom_filter.proto

@@ -0,0 +1,73 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.firestore.v1;
+
+option csharp_namespace = "Google.Cloud.Firestore.V1";
+option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
+option java_multiple_files = true;
+option java_outer_classname = "BloomFilterProto";
+option java_package = "com.google.firestore.v1";
+option objc_class_prefix = "GCFS";
+option php_namespace = "Google\\Cloud\\Firestore\\V1";
+option ruby_package = "Google::Cloud::Firestore::V1";
+
+// A sequence of bits, encoded in a byte array.
+//
+// Each byte in the `bitmap` byte array stores 8 bits of the sequence. The only
+// exception is the last byte, which may store 8 _or fewer_ bits. The `padding`
+// defines the number of bits of the last byte to be ignored as "padding". The
+// values of these "padding" bits are unspecified and must be ignored.
+//
+// To retrieve the first bit, bit 0, calculate: `(bitmap[0] & 0x01) != 0`.
+// To retrieve the second bit, bit 1, calculate: `(bitmap[0] & 0x02) != 0`.
+// To retrieve the third bit, bit 2, calculate: `(bitmap[0] & 0x04) != 0`.
+// To retrieve the fourth bit, bit 3, calculate: `(bitmap[0] & 0x08) != 0`.
+// To retrieve bit n, calculate: `(bitmap[n / 8] & (0x01 << (n % 8))) != 0`.
+//
+// The "size" of a `BitSequence` (the number of bits it contains) is calculated
+// by this formula: `(bitmap.length * 8) - padding`.
+message BitSequence {
+  // The bytes that encode the bit sequence.
+  // May have a length of zero.
+  bytes bitmap = 1;
+
+  // The number of bits of the last byte in `bitmap` to ignore as "padding".
+  // If the length of `bitmap` is zero, then this value must be `0`.
+  // Otherwise, this value must be between 0 and 7, inclusive.
+  int32 padding = 2;
+}
+
+// A bloom filter (https://en.wikipedia.org/wiki/Bloom_filter).
+//
+// The bloom filter hashes the entries with MD5 and treats the resulting 128-bit
+// hash as 2 distinct 64-bit hash values, interpreted as unsigned integers
+// using 2's complement encoding.
+//
+// These two hash values, named `h1` and `h2`, are then used to compute the
+// `hash_count` hash values using the formula, starting at `i=0`:
+//
+//     h(i) = h1 + (i * h2)
+//
+// These resulting values are then taken modulo the number of bits in the bloom
+// filter to get the bits of the bloom filter to test for the given entry.
+message BloomFilter {
+  // The bloom filter data.
+  BitSequence bits = 1;
+
+  // The number of hashes used by the algorithm.
+  int32 hash_count = 2;
+}

package/build/protos/google/firestore/v1/common.proto

@@ -0,0 +1,111 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.firestore.v1;
+
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.Firestore.V1";
+option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
+option java_multiple_files = true;
+option java_outer_classname = "CommonProto";
+option java_package = "com.google.firestore.v1";
+option objc_class_prefix = "GCFS";
+option php_namespace = "Google\\Cloud\\Firestore\\V1";
+option ruby_package = "Google::Cloud::Firestore::V1";
+
+// A set of field paths on a document.
+// Used to restrict a get or update operation on a document to a subset of its
+// fields.
+// This is different from standard field masks, as this is always scoped to a
+// [Document][google.firestore.v1.Document], and takes in account the dynamic
+// nature of [Value][google.firestore.v1.Value].
+message DocumentMask {
+  // The list of field paths in the mask. See
+  // [Document.fields][google.firestore.v1.Document.fields] for a field path
+  // syntax reference.
+  repeated string field_paths = 1;
+}
+
+// A precondition on a document, used for conditional operations.
+message Precondition {
+  // The type of precondition.
+  oneof condition_type {
+    // When set to `true`, the target document must exist.
+    // When set to `false`, the target document must not exist.
+    bool exists = 1;
+
+    // When set, the target document must exist and have been last updated at
+    // that time. Timestamp must be microsecond aligned.
+    google.protobuf.Timestamp update_time = 2;
+  }
+}
+
+// Options for creating a new transaction.
+message TransactionOptions {
+  // The type of concurrency control mode for transactions.
+  enum ConcurrencyMode {
+    // Start the transaction with the database-level default concurrency mode.
+    CONCURRENCY_MODE_UNSPECIFIED = 0;
+
+    // Use optimistic concurrency control for the new transaction.
+    OPTIMISTIC = 1;
+
+    // Use pessimistic concurrency control for the new transaction.
+    PESSIMISTIC = 2;
+  }
+
+  // Options for a transaction that can be used to read and write documents.
+  message ReadWrite {
+    // An optional transaction to retry.
+    bytes retry_transaction = 1;
+
+    // Optional. The concurrency control mode to use for this transaction.
+    //
+    // A database is able to use different concurrency modes for different
+    // transactions simultaneously.
+    //
+    // 3rd party auth requests are only allowed to create optimistic
+    // read-write transactions and must specify that here even if the
+    // database-level setting is already configured to optimistic.
+    ConcurrencyMode concurrency_mode = 2
+        [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Options for a transaction that can only be used to read documents.
+  message ReadOnly {
+    // The consistency mode for this transaction. If not set, defaults to strong
+    // consistency.
+    oneof consistency_selector {
+      // Reads documents at the given time.
+      //
+      // This must be a microsecond precision timestamp within the past one
+      // hour, or if Point-in-Time Recovery is enabled, can additionally be a
+      // whole minute timestamp within the past 7 days.
+      google.protobuf.Timestamp read_time = 2;
+    }
+  }
+
+  // The mode of the transaction.
+  oneof mode {
+    // The transaction can only be used for read operations.
+    ReadOnly read_only = 2;
+
+    // The transaction can be used for both read and write operations.
+    ReadWrite read_write = 3;
+  }
+}

package/build/protos/google/firestore/v1/document.proto

@@ -0,0 +1,247 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.firestore.v1;
+
+import "google/api/field_behavior.proto";
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+import "google/type/latlng.proto";
+
+option csharp_namespace = "Google.Cloud.Firestore.V1";
+option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
+option java_multiple_files = true;
+option java_outer_classname = "DocumentProto";
+option java_package = "com.google.firestore.v1";
+option objc_class_prefix = "GCFS";
+option php_namespace = "Google\\Cloud\\Firestore\\V1";
+option ruby_package = "Google::Cloud::Firestore::V1";
+
+// A Firestore document.
+//
+// Must not exceed 1 MiB - 4 bytes.
+message Document {
+  // The resource name of the document, for example
+  // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+  string name = 1;
+
+  // The document's fields.
+  //
+  // The map keys represent field names.
+  //
+  // Field names matching the regular expression `__.*__` are reserved. Reserved
+  // field names are forbidden except in certain documented contexts. The field
+  // names, represented as UTF-8, must not exceed 1,500 bytes and cannot be
+  // empty.
+  //
+  // Field paths may be used in other contexts to refer to structured fields
+  // defined here. For `map_value`, the field path is represented by a
+  // dot-delimited (`.`) string of segments. Each segment is either a simple
+  // field name (defined below) or a quoted field name. For example, the
+  // structured field `"foo" : { map_value: { "x&y" : { string_value: "hello"
+  // }}}` would be represented by the field path `` foo.`x&y` ``.
+  //
+  // A simple field name contains only characters `a` to `z`, `A` to `Z`,
+  // `0` to `9`, or `_`, and must not start with `0` to `9`. For example,
+  // `foo_bar_17`.
+  //
+  // A quoted field name starts and ends with `` ` `` and
+  // may contain any character. Some characters, including `` ` ``, must be
+  // escaped using a `\`. For example, `` `x&y` `` represents `x&y` and
+  // `` `bak\`tik` `` represents `` bak`tik ``.
+  map<string, Value> fields = 2;
+
+  // Output only. The time at which the document was created.
+  //
+  // This value increases monotonically when a document is deleted then
+  // recreated. It can also be compared to values from other documents and
+  // the `read_time` of a query.
+  google.protobuf.Timestamp create_time = 3;
+
+  // Output only. The time at which the document was last changed.
+  //
+  // This value is initially set to the `create_time` then increases
+  // monotonically with each change to the document. It can also be
+  // compared to values from other documents and the `read_time` of a query.
+  google.protobuf.Timestamp update_time = 4;
+}
+
+// A message that can hold any of the supported value types.
+message Value {
+  // Must have a value set.
+  oneof value_type {
+    // A null value.
+    google.protobuf.NullValue null_value = 11;
+
+    // A boolean value.
+    bool boolean_value = 1;
+
+    // An integer value.
+    int64 integer_value = 2;
+
+    // A double value.
+    double double_value = 3;
+
+    // A timestamp value.
+    //
+    // Precise only to microseconds. When stored, any additional precision is
+    // rounded down.
+    google.protobuf.Timestamp timestamp_value = 10;
+
+    // A string value.
+    //
+    // The string, represented as UTF-8, must not exceed 1 MiB - 89 bytes.
+    // Only the first 1,500 bytes of the UTF-8 representation are considered by
+    // queries.
+    string string_value = 17;
+
+    // A bytes value.
+    //
+    // Must not exceed 1 MiB - 89 bytes.
+    // Only the first 1,500 bytes are considered by queries.
+    bytes bytes_value = 18;
+
+    // A reference to a document. For example:
+    // `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
+    string reference_value = 5;
+
+    // A geo point value representing a point on the surface of Earth.
+    google.type.LatLng geo_point_value = 8;
+
+    // An array value.
+    //
+    // Cannot directly contain another array value, though can contain a
+    // map which contains another array.
+    ArrayValue array_value = 9;
+
+    // A map value.
+    MapValue map_value = 6;
+
+    // Value which references a field.
+    //
+    // This is considered relative (vs absolute) since it only refers to a field
+    // and not a field within a particular document.
+    //
+    // **Requires:**
+    //
+    // * Must follow [field reference][FieldReference.field_path] limitations.
+    //
+    // * Not allowed to be used when writing documents.
+    string field_reference_value = 19;
+
+    // Pointer to a variable defined elsewhere in a pipeline.
+    //
+    // Unlike `field_reference_value` which references a field within a
+    // document, this refers to a variable, defined in a separate namespace than
+    // the fields of a document.
+    string variable_reference_value = 22;
+
+    // A value that represents an unevaluated expression.
+    //
+    // **Requires:**
+    //
+    // * Not allowed to be used when writing documents.
+    Function function_value = 20;
+
+    // A value that represents an unevaluated pipeline.
+    //
+    // **Requires:**
+    //
+    // * Not allowed to be used when writing documents.
+    Pipeline pipeline_value = 21;
+  }
+}
+
+// An array value.
+message ArrayValue {
+  // Values in the array.
+  repeated Value values = 1;
+}
+
+// A map value.
+message MapValue {
+  // The map's fields.
+  //
+  // The map keys represent field names. Field names matching the regular
+  // expression `__.*__` are reserved. Reserved field names are forbidden except
+  // in certain documented contexts. The map keys, represented as UTF-8, must
+  // not exceed 1,500 bytes and cannot be empty.
+  map<string, Value> fields = 1;
+}
+
+// Represents an unevaluated scalar expression.
+//
+// For example, the expression `like(user_name, "%alice%")` is represented as:
+//
+// ```
+// name: "like"
+// args { field_reference: "user_name" }
+// args { string_value: "%alice%" }
+// ```
+message Function {
+  // Required. The name of the function to evaluate.
+  //
+  // **Requires:**
+  //
+  // * must be in snake case (lower case with underscore separator).
+  string name = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Ordered list of arguments the given function expects.
+  repeated Value args = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Optional named arguments that certain functions may support.
+  map<string, Value> options = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// A Firestore query represented as an ordered list of operations / stages.
+message Pipeline {
+  // A single operation within a pipeline.
+  //
+  // A stage is made up of a unique name, and a list of arguments. The exact
+  // number of arguments & types is dependent on the stage type.
+  //
+  // To give an example, the stage `filter(state = "MD")` would be encoded as:
+  //
+  // ```
+  // name: "filter"
+  // args {
+  //   function_value {
+  //     name: "eq"
+  //     args { field_reference_value: "state" }
+  //     args { string_value: "MD" }
+  //   }
+  // }
+  // ```
+  //
+  // See public documentation for the full list.
+  message Stage {
+    // Required. The name of the stage to evaluate.
+    //
+    // **Requires:**
+    //
+    // * must be in snake case (lower case with underscore separator).
+    string name = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Optional. Ordered list of arguments the given stage expects.
+    repeated Value args = 2 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. Optional named arguments that certain functions may support.
+    map<string, Value> options = 3 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Required. Ordered list of stages to evaluate.
+  repeated Stage stages = 1 [(google.api.field_behavior) = REQUIRED];
+}

package/build/protos/google/firestore/v1/explain_stats.proto

@@ -0,0 +1,41 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.firestore.v1;
+
+import "google/protobuf/any.proto";
+
+option csharp_namespace = "Google.Cloud.Firestore.V1";
+option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
+option java_multiple_files = true;
+option java_outer_classname = "ExplainStatsProto";
+option java_package = "com.google.firestore.v1";
+option php_namespace = "Google\\Cloud\\Firestore\\V1";
+option ruby_package = "Google::Cloud::Firestore::V1";
+
+// Specification of Firestore Explain Stats fields.
+
+// Pipeline explain stats.
+//
+// Depending on the explain options in the original request, this can contain
+// the optimized plan and / or execution stats.
+message ExplainStats {
+  // The format depends on the `output_format` options in the request.
+  //
+  // Currently there are two supported options: `TEXT` and `JSON`.
+  // Both supply a `google.protobuf.StringValue`.
+  google.protobuf.Any data = 1;
+}