Skip to content

Commit b071320

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: Add bloom filter related proto fields
PiperOrigin-RevId: 529511263
1 parent 0037ff6 commit b071320

4 files changed

Lines changed: 99 additions & 0 deletions

File tree

‎google/firestore/v1/BUILD.bazel‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ proto_library(
2222
name = "firestore_proto",
2323
srcs = [
2424
"aggregation_result.proto",
25+
"bloom_filter.proto",
2526
"common.proto",
2627
"document.proto",
2728
"firestore.proto",

‎google/firestore/v1/bloom_filter.proto‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// Copyright 2023 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+
syntax = "proto3";
16+
17+
package google.firestore.v1;
18+
19+
option csharp_namespace = "Google.Cloud.Firestore.V1";
20+
option go_package = "cloud.google.com/go/firestore/apiv1/firestorepb;firestorepb";
21+
option java_multiple_files = true;
22+
option java_outer_classname = "BloomFilterProto";
23+
option java_package = "com.google.firestore.v1";
24+
option objc_class_prefix = "GCFS";
25+
option php_namespace = "Google\\Cloud\\Firestore\\V1";
26+
option ruby_package = "Google::Cloud::Firestore::V1";
27+
28+
// A sequence of bits, encoded in a byte array.
29+
//
30+
// Each byte in the `bitmap` byte array stores 8 bits of the sequence. The only
31+
// exception is the last byte, which may store 8 _or fewer_ bits. The `padding`
32+
// defines the number of bits of the last byte to be ignored as "padding". The
33+
// values of these "padding" bits are unspecified and must be ignored.
34+
//
35+
// To retrieve the first bit, bit 0, calculate: `(bitmap[0] & 0x01) != 0`.
36+
// To retrieve the second bit, bit 1, calculate: `(bitmap[0] & 0x02) != 0`.
37+
// To retrieve the third bit, bit 2, calculate: `(bitmap[0] & 0x04) != 0`.
38+
// To retrieve the fourth bit, bit 3, calculate: `(bitmap[0] & 0x08) != 0`.
39+
// To retrieve bit n, calculate: `(bitmap[n / 8] & (0x01 << (n % 8))) != 0`.
40+
//
41+
// The "size" of a `BitSequence` (the number of bits it contains) is calculated
42+
// by this formula: `(bitmap.length * 8) - padding`.
43+
message BitSequence {
44+
// The bytes that encode the bit sequence.
45+
// May have a length of zero.
46+
bytes bitmap = 1;
47+
48+
// The number of bits of the last byte in `bitmap` to ignore as "padding".
49+
// If the length of `bitmap` is zero, then this value must be `0`.
50+
// Otherwise, this value must be between 0 and 7, inclusive.
51+
int32 padding = 2;
52+
}
53+
54+
// A bloom filter (https://en.wikipedia.org/wiki/Bloom_filter).
55+
//
56+
// The bloom filter hashes the entries with MD5 and treats the resulting 128-bit
57+
// hash as 2 distinct 64-bit hash values, interpreted as unsigned integers
58+
// using 2's complement encoding.
59+
//
60+
// These two hash values, named `h1` and `h2`, are then used to compute the
61+
// `hash_count` hash values using the formula, starting at `i=0`:
62+
//
63+
// h(i) = h1 + (i * h2)
64+
//
65+
// These resulting values are then taken modulo the number of bits in the bloom
66+
// filter to get the bits of the bloom filter to test for the given entry.
67+
message BloomFilter {
68+
// The bloom filter data.
69+
BitSequence bits = 1;
70+
71+
// The number of hashes used by the algorithm.
72+
int32 hash_count = 2;
73+
}

‎google/firestore/v1/firestore.proto‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import "google/firestore/v1/query.proto";
2626
import "google/firestore/v1/write.proto";
2727
import "google/protobuf/empty.proto";
2828
import "google/protobuf/timestamp.proto";
29+
import "google/protobuf/wrappers.proto";
2930
import "google/rpc/status.proto";
3031

3132
option csharp_namespace = "Google.Cloud.Firestore.V1";
@@ -932,6 +933,14 @@ message Target {
932933

933934
// If the target should be removed once it is current and consistent.
934935
bool once = 6;
936+
937+
// The number of documents that last matched the query at the resume token or
938+
// read time.
939+
//
940+
// This value is only relevant when a `resume_type` is provided. This value
941+
// being present and greater than zero signals that the client wants
942+
// `ExistenceFilter.unchanged_names` to be included in the response.
943+
google.protobuf.Int32Value expected_count = 12;
935944
}
936945

937946
// Targets being watched have changed.

‎google/firestore/v1/write.proto‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ syntax = "proto3";
1616

1717
package google.firestore.v1;
1818

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

0 commit comments

Comments
 (0)