feat: add VectorSearch API

Google APIs · copybara-github · commit 5e2ca445cd8f · 2024-03-21T15:33:12.000-07:00
PiperOrigin-RevId: 617982192
diff --git a/google/firestore/v1/query.proto b/google/firestore/v1/query.proto
@@ -263,6 +263,51 @@ message StructuredQuery {
     repeated FieldReference fields = 2;
   }
 
+  // Nearest Neighbors search config.
+  message FindNearest {
+    // The distance measure to use when comparing vectors.
+    enum DistanceMeasure {
+      // Should not be set.
+      DISTANCE_MEASURE_UNSPECIFIED = 0;
+
+      // Measures the EUCLIDEAN distance between the vectors. See
+      // [Euclidean](https://en.wikipedia.org/wiki/Euclidean_distance) to learn
+      // more
+      EUCLIDEAN = 1;
+
+      // Compares vectors based on the angle between them, which allows you to
+      // measure similarity that isn't based on the vectors magnitude.
+      // We recommend using DOT_PRODUCT with unit normalized vectors instead of
+      // COSINE distance, which is mathematically equivalent with better
+      // performance. See [Cosine
+      // Similarity](https://en.wikipedia.org/wiki/Cosine_similarity) to learn
+      // more.
+      COSINE = 2;
+
+      // Similar to cosine but is affected by the magnitude of the vectors. See
+      // [Dot Product](https://en.wikipedia.org/wiki/Dot_product) to learn more.
+      DOT_PRODUCT = 3;
+    }
+
+    // Required. An indexed vector field to search upon. Only documents which
+    // contain vectors whose dimensionality match the query_vector can be
+    // returned.
+    FieldReference vector_field = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The query vector that we are searching on. Must be a vector of
+    // no more than 2048 dimensions.
+    Value query_vector = 2 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The Distance Measure to use, required.
+    DistanceMeasure distance_measure = 3
+        [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The number of nearest neighbors to return. Must be a positive
+    // integer of no more than 1000.
+    google.protobuf.Int32Value limit = 4
+        [(google.api.field_behavior) = REQUIRED];
+  }
+
   // Optional sub-set of the fields to return.
   //
   // This acts as a [DocumentMask][google.firestore.v1.DocumentMask] over the
@@ -360,6 +405,13 @@ message StructuredQuery {
   //
   // * The value must be greater than or equal to zero if specified.
   google.protobuf.Int32Value limit = 5;
+
+  // Optional. A potential Nearest Neighbors Search.
+  //
+  // Applies after all other filters and ordering.
+  //
+  // Finds the closest vector embeddings to the given query vector.
+  FindNearest find_nearest = 9 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // Firestore query for running an aggregation over a
