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

…view branch (#26517)

google-cloud-firestore-v1/proto_docs/google/firestore/v1/document.rb

@@ -125,7 +125,7 @@ class FieldsEntry
  # @return [::Google::Cloud::Firestore::V1::ArrayValue]
  # 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.
  # @!attribute [rw] map_value
  # @return [::Google::Cloud::Firestore::V1::MapValue]

google-cloud-firestore-v1/proto_docs/google/firestore/v1/query.rb

@@ -130,7 +130,7 @@ module V1
  # * The value must be greater than or equal to zero if specified.
  # @!attribute [rw] find_nearest
  # @return [::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest]
- # Optional. A potential Nearest Neighbors Search.
+ # Optional. A potential nearest neighbors search.
  #
  # Applies after all other filters and ordering.
  #
@@ -369,7 +369,10 @@ class Projection
  extend ::Google::Protobuf::MessageExts::ClassMethods
  end
 
- # 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.
  # @!attribute [rw] vector_field
  # @return [::Google::Cloud::Firestore::V1::StructuredQuery::FieldReference]
  # Required. An indexed vector field to search upon. Only documents which
@@ -381,7 +384,7 @@ class Projection
  # no more than 2048 dimensions.
  # @!attribute [rw] distance_measure
  # @return [::Google::Cloud::Firestore::V1::StructuredQuery::FindNearest::DistanceMeasure]
- # Required. The Distance Measure to use, required.
+ # Required. The distance measure to use, required.
  # @!attribute [rw] limit
  # @return [::Google::Protobuf::Int32Value]
  # Required. The number of nearest neighbors to return. Must be a positive
@@ -397,20 +400,23 @@ module DistanceMeasure
 
  # 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
  end
  end