feat: Add bloom filter related proto fields

PiperOrigin-RevId: 529511263
googleapis · May 4, 2023 · b071320 · b071320
1 parent 0037ff6
commit b071320
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 0 deletions.
diff --git a/google/firestore/v1/BUILD.bazel b/google/firestore/v1/BUILD.bazel
@@ -22,6 +22,7 @@ proto_library(
     name = "firestore_proto",
     srcs = [
         "aggregation_result.proto",
+        "bloom_filter.proto",
         "common.proto",
         "document.proto",
         "firestore.proto",

diff --git a/google/firestore/v1/bloom_filter.proto b/google/firestore/v1/bloom_filter.proto
@@ -0,0 +1,73 @@
+// Copyright 2023 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;
+}
diff --git a/google/firestore/v1/firestore.proto b/google/firestore/v1/firestore.proto
@@ -26,6 +26,7 @@ import "google/firestore/v1/query.proto";
 import "google/firestore/v1/write.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/timestamp.proto";
+import "google/protobuf/wrappers.proto";
 import "google/rpc/status.proto";
 
 option csharp_namespace = "Google.Cloud.Firestore.V1";
@@ -932,6 +933,14 @@ message Target {
 
   // If the target should be removed once it is current and consistent.
   bool once = 6;
+
+  // The number of documents that last matched the query at the resume token or
+  // read time.
+  //
+  // This value is only relevant when a `resume_type` is provided. This value
+  // being present and greater than zero signals that the client wants
+  // `ExistenceFilter.unchanged_names` to be included in the response.
+  google.protobuf.Int32Value expected_count = 12;
 }
 
 // Targets being watched have changed.

diff --git a/google/firestore/v1/write.proto b/google/firestore/v1/write.proto
@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.firestore.v1;
 
+import "google/firestore/v1/bloom_filter.proto";
 import "google/firestore/v1/common.proto";
 import "google/firestore/v1/document.proto";
 import "google/protobuf/timestamp.proto";
@@ -264,4 +265,19 @@ message ExistenceFilter {
   // If different from the count of documents in the client that match, the
   // client must manually determine which documents no longer match the target.
   int32 count = 2;
+
+  // A bloom filter that contains the UTF-8 byte encodings of the resource names
+  // of the documents that match
+  // [target_id][google.firestore.v1.ExistenceFilter.target_id], in the form
+  // `projects/{project_id}/databases/{database_id}/documents/{document_path}`
+  // that have NOT changed since the query results indicated by the resume token
+  // or timestamp given in `Target.resume_type`.
+  //
+  // This bloom filter may be omitted at the server's discretion, such as if it
+  // is deemed that the client will not make use of it or if it is too
+  // computationally expensive to calculate or transmit. Clients must gracefully
+  // handle this field being absent by falling back to the logic used before
+  // this field existed; that is, re-add the target without a resume token to
+  // figure out which documents in the client's cache are out of sync.
+  BloomFilter unchanged_names = 3;
 }