From 9a373d5d130afd1548a3a1056179e51effbb5754 Mon Sep 17 00:00:00 2001 From: "gcf-owl-bot[bot]" <78513119+gcf-owl-bot[bot]@users.noreply.github.com> Date: Wed, 24 Jul 2024 13:26:10 -0700 Subject: [PATCH] chore: expose new experimental FindNearest distance params to the preview branch (#7547) docs: minor documentation clarifications on FindNearest DistanceMeasure options PiperOrigin-RevId: 655267922 Source-Link: https://github.com/googleapis/googleapis/commit/7858db457900d9dd8924ce88ce1a7dd3c66cfbe6 Source-Link: https://github.com/googleapis/googleapis-gen/commit/c0754282e8062565959b52391bb3addb870267b8 Copy-Tag: eyJwIjoiRmlyZXN0b3JlLy5Pd2xCb3QueWFtbCIsImgiOiJjMDc1NDI4MmU4MDYyNTY1OTU5YjUyMzkxYmIzYWRkYjg3MDI2N2I4In0= --- Firestore/metadata/V1/Document.php | Bin 1930 -> 2019 bytes Firestore/src/V1/StructuredQuery.php | 8 ++++---- .../src/V1/StructuredQuery/FindNearest.php | 13 ++++++++----- .../FindNearest/DistanceMeasure.php | 17 ++++++++++------- Firestore/src/V1/Value.php | 6 +++--- 5 files changed, 25 insertions(+), 19 deletions(-) diff --git a/Firestore/metadata/V1/Document.php b/Firestore/metadata/V1/Document.php index 0d2328d9b6142573315b7ae8e0cacf99427360f2..fdb899ded9b7106d59917d9eb948fea2c359104b 100644 GIT binary patch delta 78 zcmeC;f6TvO8>66OL1v6wW@=7~Q))(HS!RCGWJV^f$?q9CC+}z6!}xe|4U@I3OnQEP fdQPf-K~a85eo|?gesM`rX>y4kn7?@&(-jr~f)yR; delta 28 kcmaFN-^IUS8{_1Uj7M3Ha&jq6^j4aDhe>R+0P|%Q0HlcuT>t<8 diff --git a/Firestore/src/V1/StructuredQuery.php b/Firestore/src/V1/StructuredQuery.php index 47ed315b963e..10229cba1072 100644 --- a/Firestore/src/V1/StructuredQuery.php +++ b/Firestore/src/V1/StructuredQuery.php @@ -122,7 +122,7 @@ class StructuredQuery extends \Google\Protobuf\Internal\Message */ private $limit = null; /** - * 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. * @@ -204,7 +204,7 @@ class StructuredQuery extends \Google\Protobuf\Internal\Message * Requires: * * The value must be greater than or equal to zero if specified. * @type \Google\Cloud\Firestore\V1\StructuredQuery\FindNearest $find_nearest - * 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. * } @@ -608,7 +608,7 @@ public function setLimitValue($var) return $this;} /** - * 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. * @@ -631,7 +631,7 @@ public function clearFindNearest() } /** - * 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. * diff --git a/Firestore/src/V1/StructuredQuery/FindNearest.php b/Firestore/src/V1/StructuredQuery/FindNearest.php index 39d22376411a..2688ef227d10 100644 --- a/Firestore/src/V1/StructuredQuery/FindNearest.php +++ b/Firestore/src/V1/StructuredQuery/FindNearest.php @@ -9,7 +9,10 @@ use Google\Protobuf\Internal\GPBUtil; /** - * 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. * * Generated from protobuf message google.firestore.v1.StructuredQuery.FindNearest */ @@ -31,7 +34,7 @@ class FindNearest extends \Google\Protobuf\Internal\Message */ private $query_vector = null; /** - * Required. The Distance Measure to use, required. + * Required. The distance measure to use, required. * * Generated from protobuf field .google.firestore.v1.StructuredQuery.FindNearest.DistanceMeasure distance_measure = 3 [(.google.api.field_behavior) = REQUIRED]; */ @@ -58,7 +61,7 @@ class FindNearest extends \Google\Protobuf\Internal\Message * Required. The query vector that we are searching on. Must be a vector of * no more than 2048 dimensions. * @type int $distance_measure - * Required. The Distance Measure to use, required. + * Required. The distance measure to use, required. * @type \Google\Protobuf\Int32Value $limit * Required. The number of nearest neighbors to return. Must be a positive * integer of no more than 1000. @@ -148,7 +151,7 @@ public function setQueryVector($var) } /** - * Required. The Distance Measure to use, required. + * Required. The distance measure to use, required. * * Generated from protobuf field .google.firestore.v1.StructuredQuery.FindNearest.DistanceMeasure distance_measure = 3 [(.google.api.field_behavior) = REQUIRED]; * @return int @@ -159,7 +162,7 @@ public function getDistanceMeasure() } /** - * Required. The Distance Measure to use, required. + * Required. The distance measure to use, required. * * Generated from protobuf field .google.firestore.v1.StructuredQuery.FindNearest.DistanceMeasure distance_measure = 3 [(.google.api.field_behavior) = REQUIRED]; * @param int $var diff --git a/Firestore/src/V1/StructuredQuery/FindNearest/DistanceMeasure.php b/Firestore/src/V1/StructuredQuery/FindNearest/DistanceMeasure.php index bc3c1978f8f4..f50ed905abcd 100644 --- a/Firestore/src/V1/StructuredQuery/FindNearest/DistanceMeasure.php +++ b/Firestore/src/V1/StructuredQuery/FindNearest/DistanceMeasure.php @@ -22,19 +22,21 @@ class 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. * * Generated from protobuf enum EUCLIDEAN = 1; */ const 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. * * Generated from protobuf enum COSINE = 2; */ @@ -42,6 +44,7 @@ class DistanceMeasure /** * 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. * * Generated from protobuf enum DOT_PRODUCT = 3; */ diff --git a/Firestore/src/V1/Value.php b/Firestore/src/V1/Value.php index de439f4118f4..fbfb290bbe78 100644 --- a/Firestore/src/V1/Value.php +++ b/Firestore/src/V1/Value.php @@ -51,7 +51,7 @@ class Value extends \Google\Protobuf\Internal\Message * A geo point value representing a point on the surface of Earth. * @type \Google\Cloud\Firestore\V1\ArrayValue $array_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. * @type \Google\Cloud\Firestore\V1\MapValue $map_value * A map value. @@ -359,7 +359,7 @@ public function setGeoPointValue($var) /** * 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. * * Generated from protobuf field .google.firestore.v1.ArrayValue array_value = 9; @@ -377,7 +377,7 @@ public function hasArrayValue() /** * 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. * * Generated from protobuf field .google.firestore.v1.ArrayValue array_value = 9;