query.rb in google-cloud-firestore-v1-1.1.0

- old
+ new

@@ -128,11 +128,11 @@
         #     Requires:
         #
         #     * 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.
         #
         #     Finds the closest vector embeddings to the given query vector.
         class StructuredQuery
@@ -367,11 +367,14 @@
           class Projection
             include ::Google::Protobuf::MessageExts
             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
           #     contain vectors whose dimensionality match the query_vector can be
           #     returned.
@@ -379,15 +382,30 @@
           #   @return [::Google::Cloud::Firestore::V1::Value]
           #     Required. The query vector that we are searching on. Must be a vector of
           #     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
           #     integer of no more than 1000.
+          # @!attribute [rw] distance_result_field
+          #   @return [::String]
+          #     Optional. Optional name of the field to output the result of the vector
+          #     distance calculation. Must conform to [document field
+          #     name][google.firestore.v1.Document.fields] limitations.
+          # @!attribute [rw] distance_threshold
+          #   @return [::Google::Protobuf::DoubleValue]
+          #     Optional. Option to specify a threshold for which no less similar
+          #     documents will be returned. The behavior of the specified
+          #     `distance_measure` will affect the meaning of the distance threshold.
+          #     Since DOT_PRODUCT distances increase when the vectors are more similar,
+          #     the comparison is inverted.
+          #
+          #     For EUCLIDEAN, COSINE: WHERE distance <= distance_threshold
+          #     For DOT_PRODUCT:       WHERE distance >= distance_threshold
           class FindNearest
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods
 
             # The distance measure to use when comparing vectors.
@@ -395,23 +413,26 @@
               # 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
+              # 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
 
           # A sort direction.