diff --git a/Datastore/metadata/V1/Query.php b/Datastore/metadata/V1/Query.php index 04f68361a258..a42f6011f298 100644 Binary files a/Datastore/metadata/V1/Query.php and b/Datastore/metadata/V1/Query.php differ diff --git a/Datastore/src/V1/FindNearest.php b/Datastore/src/V1/FindNearest.php new file mode 100644 index 000000000000..cdad9dfa7c0f --- /dev/null +++ b/Datastore/src/V1/FindNearest.php @@ -0,0 +1,390 @@ +google.datastore.v1.FindNearest + */ +class FindNearest extends \Google\Protobuf\Internal\Message +{ + /** + * Required. An indexed vector property to search upon. Only documents which + * contain vectors whose dimensionality match the query_vector can be + * returned. + * + * Generated from protobuf field .google.datastore.v1.PropertyReference vector_property = 1 [(.google.api.field_behavior) = REQUIRED]; + */ + private $vector_property = null; + /** + * Required. The query vector that we are searching on. Must be a vector of no + * more than 2048 dimensions. + * + * Generated from protobuf field .google.datastore.v1.Value query_vector = 2 [(.google.api.field_behavior) = REQUIRED]; + */ + private $query_vector = null; + /** + * Required. The Distance Measure to use, required. + * + * Generated from protobuf field .google.datastore.v1.FindNearest.DistanceMeasure distance_measure = 3 [(.google.api.field_behavior) = REQUIRED]; + */ + private $distance_measure = 0; + /** + * Required. The number of nearest neighbors to return. Must be a positive + * integer of no more than 100. + * + * Generated from protobuf field .google.protobuf.Int32Value limit = 4 [(.google.api.field_behavior) = REQUIRED]; + */ + private $limit = null; + /** + * Optional. Optional name of the field to output the result of the vector + * distance calculation. Must conform to [entity + * property][google.datastore.v1.Entity.properties] limitations. + * + * Generated from protobuf field string distance_result_property = 5 [(.google.api.field_behavior) = OPTIONAL]; + */ + private $distance_result_property = ''; + /** + * 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 + * + * Generated from protobuf field .google.protobuf.DoubleValue distance_threshold = 6 [(.google.api.field_behavior) = OPTIONAL]; + */ + private $distance_threshold = null; + + /** + * Constructor. + * + * @param array $data { + * Optional. Data for populating the Message object. + * + * @type \Google\Cloud\Datastore\V1\PropertyReference $vector_property + * Required. An indexed vector property to search upon. Only documents which + * contain vectors whose dimensionality match the query_vector can be + * returned. + * @type \Google\Cloud\Datastore\V1\Value $query_vector + * 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. + * @type \Google\Protobuf\Int32Value $limit + * Required. The number of nearest neighbors to return. Must be a positive + * integer of no more than 100. + * @type string $distance_result_property + * Optional. Optional name of the field to output the result of the vector + * distance calculation. Must conform to [entity + * property][google.datastore.v1.Entity.properties] limitations. + * @type \Google\Protobuf\DoubleValue $distance_threshold + * 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 + * } + */ + public function __construct($data = NULL) { + \GPBMetadata\Google\Datastore\V1\Query::initOnce(); + parent::__construct($data); + } + + /** + * Required. An indexed vector property to search upon. Only documents which + * contain vectors whose dimensionality match the query_vector can be + * returned. + * + * Generated from protobuf field .google.datastore.v1.PropertyReference vector_property = 1 [(.google.api.field_behavior) = REQUIRED]; + * @return \Google\Cloud\Datastore\V1\PropertyReference|null + */ + public function getVectorProperty() + { + return $this->vector_property; + } + + public function hasVectorProperty() + { + return isset($this->vector_property); + } + + public function clearVectorProperty() + { + unset($this->vector_property); + } + + /** + * Required. An indexed vector property to search upon. Only documents which + * contain vectors whose dimensionality match the query_vector can be + * returned. + * + * Generated from protobuf field .google.datastore.v1.PropertyReference vector_property = 1 [(.google.api.field_behavior) = REQUIRED]; + * @param \Google\Cloud\Datastore\V1\PropertyReference $var + * @return $this + */ + public function setVectorProperty($var) + { + GPBUtil::checkMessage($var, \Google\Cloud\Datastore\V1\PropertyReference::class); + $this->vector_property = $var; + + return $this; + } + + /** + * Required. The query vector that we are searching on. Must be a vector of no + * more than 2048 dimensions. + * + * Generated from protobuf field .google.datastore.v1.Value query_vector = 2 [(.google.api.field_behavior) = REQUIRED]; + * @return \Google\Cloud\Datastore\V1\Value|null + */ + public function getQueryVector() + { + return $this->query_vector; + } + + public function hasQueryVector() + { + return isset($this->query_vector); + } + + public function clearQueryVector() + { + unset($this->query_vector); + } + + /** + * Required. The query vector that we are searching on. Must be a vector of no + * more than 2048 dimensions. + * + * Generated from protobuf field .google.datastore.v1.Value query_vector = 2 [(.google.api.field_behavior) = REQUIRED]; + * @param \Google\Cloud\Datastore\V1\Value $var + * @return $this + */ + public function setQueryVector($var) + { + GPBUtil::checkMessage($var, \Google\Cloud\Datastore\V1\Value::class); + $this->query_vector = $var; + + return $this; + } + + /** + * Required. The Distance Measure to use, required. + * + * Generated from protobuf field .google.datastore.v1.FindNearest.DistanceMeasure distance_measure = 3 [(.google.api.field_behavior) = REQUIRED]; + * @return int + */ + public function getDistanceMeasure() + { + return $this->distance_measure; + } + + /** + * Required. The Distance Measure to use, required. + * + * Generated from protobuf field .google.datastore.v1.FindNearest.DistanceMeasure distance_measure = 3 [(.google.api.field_behavior) = REQUIRED]; + * @param int $var + * @return $this + */ + public function setDistanceMeasure($var) + { + GPBUtil::checkEnum($var, \Google\Cloud\Datastore\V1\FindNearest\DistanceMeasure::class); + $this->distance_measure = $var; + + return $this; + } + + /** + * Required. The number of nearest neighbors to return. Must be a positive + * integer of no more than 100. + * + * Generated from protobuf field .google.protobuf.Int32Value limit = 4 [(.google.api.field_behavior) = REQUIRED]; + * @return \Google\Protobuf\Int32Value|null + */ + public function getLimit() + { + return $this->limit; + } + + public function hasLimit() + { + return isset($this->limit); + } + + public function clearLimit() + { + unset($this->limit); + } + + /** + * Returns the unboxed value from getLimit() + + * Required. The number of nearest neighbors to return. Must be a positive + * integer of no more than 100. + * + * Generated from protobuf field .google.protobuf.Int32Value limit = 4 [(.google.api.field_behavior) = REQUIRED]; + * @return int|null + */ + public function getLimitValue() + { + return $this->readWrapperValue("limit"); + } + + /** + * Required. The number of nearest neighbors to return. Must be a positive + * integer of no more than 100. + * + * Generated from protobuf field .google.protobuf.Int32Value limit = 4 [(.google.api.field_behavior) = REQUIRED]; + * @param \Google\Protobuf\Int32Value $var + * @return $this + */ + public function setLimit($var) + { + GPBUtil::checkMessage($var, \Google\Protobuf\Int32Value::class); + $this->limit = $var; + + return $this; + } + + /** + * Sets the field by wrapping a primitive type in a Google\Protobuf\Int32Value object. + + * Required. The number of nearest neighbors to return. Must be a positive + * integer of no more than 100. + * + * Generated from protobuf field .google.protobuf.Int32Value limit = 4 [(.google.api.field_behavior) = REQUIRED]; + * @param int|null $var + * @return $this + */ + public function setLimitValue($var) + { + $this->writeWrapperValue("limit", $var); + return $this;} + + /** + * Optional. Optional name of the field to output the result of the vector + * distance calculation. Must conform to [entity + * property][google.datastore.v1.Entity.properties] limitations. + * + * Generated from protobuf field string distance_result_property = 5 [(.google.api.field_behavior) = OPTIONAL]; + * @return string + */ + public function getDistanceResultProperty() + { + return $this->distance_result_property; + } + + /** + * Optional. Optional name of the field to output the result of the vector + * distance calculation. Must conform to [entity + * property][google.datastore.v1.Entity.properties] limitations. + * + * Generated from protobuf field string distance_result_property = 5 [(.google.api.field_behavior) = OPTIONAL]; + * @param string $var + * @return $this + */ + public function setDistanceResultProperty($var) + { + GPBUtil::checkString($var, True); + $this->distance_result_property = $var; + + return $this; + } + + /** + * 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 + * + * Generated from protobuf field .google.protobuf.DoubleValue distance_threshold = 6 [(.google.api.field_behavior) = OPTIONAL]; + * @return \Google\Protobuf\DoubleValue|null + */ + public function getDistanceThreshold() + { + return $this->distance_threshold; + } + + public function hasDistanceThreshold() + { + return isset($this->distance_threshold); + } + + public function clearDistanceThreshold() + { + unset($this->distance_threshold); + } + + /** + * Returns the unboxed value from getDistanceThreshold() + + * 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 + * + * Generated from protobuf field .google.protobuf.DoubleValue distance_threshold = 6 [(.google.api.field_behavior) = OPTIONAL]; + * @return float|null + */ + public function getDistanceThresholdValue() + { + return $this->readWrapperValue("distance_threshold"); + } + + /** + * 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 + * + * Generated from protobuf field .google.protobuf.DoubleValue distance_threshold = 6 [(.google.api.field_behavior) = OPTIONAL]; + * @param \Google\Protobuf\DoubleValue $var + * @return $this + */ + public function setDistanceThreshold($var) + { + GPBUtil::checkMessage($var, \Google\Protobuf\DoubleValue::class); + $this->distance_threshold = $var; + + return $this; + } + + /** + * Sets the field by wrapping a primitive type in a Google\Protobuf\DoubleValue object. + + * 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 + * + * Generated from protobuf field .google.protobuf.DoubleValue distance_threshold = 6 [(.google.api.field_behavior) = OPTIONAL]; + * @param float|null $var + * @return $this + */ + public function setDistanceThresholdValue($var) + { + $this->writeWrapperValue("distance_threshold", $var); + return $this;} + +} + diff --git a/Datastore/src/V1/FindNearest/DistanceMeasure.php b/Datastore/src/V1/FindNearest/DistanceMeasure.php new file mode 100644 index 000000000000..5eb0ccc00196 --- /dev/null +++ b/Datastore/src/V1/FindNearest/DistanceMeasure.php @@ -0,0 +1,82 @@ +google.datastore.v1.FindNearest.DistanceMeasure + */ +class DistanceMeasure +{ + /** + * Should not be set. + * + * Generated from protobuf enum DISTANCE_MEASURE_UNSPECIFIED = 0; + */ + const DISTANCE_MEASURE_UNSPECIFIED = 0; + /** + * Measures the EUCLIDEAN distance between the vectors. See + * [Euclidean](https://en.wikipedia.org/wiki/Euclidean_distance) to learn + * more. The resulting distance decreases the more similar two vectors are. + * + * Generated from protobuf enum EUCLIDEAN = 1; + */ + const EUCLIDEAN = 1; + /** + * 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 about COSINE similarity and COSINE distance. The resulting COSINE + * distance decreases the more similar two vectors are. + * + * Generated from protobuf enum COSINE = 2; + */ + const 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. + * + * Generated from protobuf enum DOT_PRODUCT = 3; + */ + const DOT_PRODUCT = 3; + + private static $valueToName = [ + self::DISTANCE_MEASURE_UNSPECIFIED => 'DISTANCE_MEASURE_UNSPECIFIED', + self::EUCLIDEAN => 'EUCLIDEAN', + self::COSINE => 'COSINE', + self::DOT_PRODUCT => 'DOT_PRODUCT', + ]; + + public static function name($value) + { + if (!isset(self::$valueToName[$value])) { + throw new UnexpectedValueException(sprintf( + 'Enum %s has no name defined for value %s', __CLASS__, $value)); + } + return self::$valueToName[$value]; + } + + + public static function value($name) + { + $const = __CLASS__ . '::' . strtoupper($name); + if (!defined($const)) { + throw new UnexpectedValueException(sprintf( + 'Enum %s has no value defined for name %s', __CLASS__, $name)); + } + return constant($const); + } +} + +// Adding a class alias for backwards compatibility with the previous class name. +class_alias(DistanceMeasure::class, \Google\Cloud\Datastore\V1\FindNearest_DistanceMeasure::class); + diff --git a/Datastore/src/V1/Query.php b/Datastore/src/V1/Query.php index 0c752662bf17..e89908155e7d 100644 --- a/Datastore/src/V1/Query.php +++ b/Datastore/src/V1/Query.php @@ -10,6 +10,14 @@ /** * A query for entities. + * The query stages are executed in the following order: + * 1. kind + * 2. filter + * 3. projection + * 4. order + start_cursor + end_cursor + * 5. offset + * 6. limit + * 7. find_nearest * * Generated from protobuf message google.datastore.v1.Query */ @@ -85,6 +93,14 @@ class Query extends \Google\Protobuf\Internal\Message * Generated from protobuf field .google.protobuf.Int32Value limit = 12; */ private $limit = null; + /** + * Optional. A potential Nearest Neighbors Search. + * Applies after all other filters and ordering. + * Finds the closest vector embeddings to the given query vector. + * + * Generated from protobuf field .google.datastore.v1.FindNearest find_nearest = 13 [(.google.api.field_behavior) = OPTIONAL]; + */ + private $find_nearest = null; /** * Constructor. @@ -126,6 +142,10 @@ class Query extends \Google\Protobuf\Internal\Message * constraints. Optional. * Unspecified is interpreted as no limit. * Must be >= 0 if specified. + * @type \Google\Cloud\Datastore\V1\FindNearest $find_nearest + * Optional. A potential Nearest Neighbors Search. + * Applies after all other filters and ordering. + * Finds the closest vector embeddings to the given query vector. * } */ public function __construct($data = NULL) { @@ -452,5 +472,45 @@ public function setLimitValue($var) $this->writeWrapperValue("limit", $var); return $this;} + /** + * Optional. A potential Nearest Neighbors Search. + * Applies after all other filters and ordering. + * Finds the closest vector embeddings to the given query vector. + * + * Generated from protobuf field .google.datastore.v1.FindNearest find_nearest = 13 [(.google.api.field_behavior) = OPTIONAL]; + * @return \Google\Cloud\Datastore\V1\FindNearest|null + */ + public function getFindNearest() + { + return $this->find_nearest; + } + + public function hasFindNearest() + { + return isset($this->find_nearest); + } + + public function clearFindNearest() + { + unset($this->find_nearest); + } + + /** + * Optional. A potential Nearest Neighbors Search. + * Applies after all other filters and ordering. + * Finds the closest vector embeddings to the given query vector. + * + * Generated from protobuf field .google.datastore.v1.FindNearest find_nearest = 13 [(.google.api.field_behavior) = OPTIONAL]; + * @param \Google\Cloud\Datastore\V1\FindNearest $var + * @return $this + */ + public function setFindNearest($var) + { + GPBUtil::checkMessage($var, \Google\Cloud\Datastore\V1\FindNearest::class); + $this->find_nearest = $var; + + return $this; + } + }