chore: expose new experimental FindNearest distance params to the pre…

…view branch

docs: minor documentation clarifications on FindNearest DistanceMeasure options

PiperOrigin-RevId: 655267922

google/firestore/v1/document.proto

@@ -16,6 +16,7 @@ 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";
@@ -122,7 +123,7 @@ message Value {
 
     // An array value.
     //
-    // Cannot directly contain another array value, though can contain an
+    // Cannot directly contain another array value, though can contain a
     // map which contains another array.
     ArrayValue array_value = 9;
 

google/firestore/v1/query.proto

@@ -263,7 +263,10 @@ message StructuredQuery {
     repeated FieldReference fields = 2;
   }
 
-  // Nearest Neighbors search config.
+  // Nearest Neighbors search config. The ordering provided by FindNearest
+  // supersedes the order_by stage. If multiple documents have the same vector
+  // distance, the returned document order is not guaranteed to be stable
+  // between queries.
   message FindNearest {
     // The distance measure to use when comparing vectors.
     enum DistanceMeasure {
@@ -272,20 +275,23 @@ message StructuredQuery {
 
       // Measures the EUCLIDEAN distance between the vectors. See
       // [Euclidean](https://en.wikipedia.org/wiki/Euclidean_distance) to learn
-      // more
+      // more. The resulting distance decreases the more similar two vectors
+      // are.
       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
+      // COSINE distance 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.
+      // more about COSINE similarity and COSINE distance. The resulting
+      // COSINE distance decreases the more similar two vectors are.
       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.
+      // The resulting distance increases the more similar two vectors are.
       DOT_PRODUCT = 3;
     }
 
@@ -298,7 +304,7 @@ message StructuredQuery {
     // no more than 2048 dimensions.
     Value query_vector = 2 [(google.api.field_behavior) = REQUIRED];
 
-    // Required. The Distance Measure to use, required.
+    // Required. The distance measure to use, required.
     DistanceMeasure distance_measure = 3
         [(google.api.field_behavior) = REQUIRED];
 
@@ -406,7 +412,7 @@ 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.
+  // Optional. A potential nearest neighbors search.
   //
   // Applies after all other filters and ordering.
   //