query-vectors-Object Storage Service(OSS)-阿里云帮助中心

Permissions

By default, an Alibaba Cloud account has full permissions. In contrast, RAM users and RAM roles have no permissions and must be granted access by an account owner or administrator through a RAM policy or a bucket policy.

API	Action	Description
QueryVectors	`oss:QueryVectors`	Queries vector data.

Command format

ossutil vectors-api query-vectors --bucket value --index-name value --query-vector value --top-k value  [flags]

Parameters

Parameter	Type	Description
--bucket	string	The name of the vector bucket.
--index-name	string	The name of the vector index.
--query-vector	string	The query vector in JSON format. The dimension of the query vector must be the same as the dimension of the vector index.
--top-k	int	The number of most similar vectors to return. Valid values: 1–500.
--filter	string	Filters query data with metadata. Maximum length of a single filter: 20 KB Maximum number of filter instructions: 1,024
--return-distance	/	The similarity distance is returned if this parameter is left empty or set to `true`.
--return-metadata	/	Metadata is returned if this parameter is left empty or set to `true`.

Note

The query-vectors command corresponds to the QueryVectors API operation.
For more information about the supported global command-line options, see Global command-line options.

Filter operators

Operator	Type	Description
`$eq`	String, Number, Boolean	Exact match (for a single value). When used on array-type metadata, the operator returns `true` if the value matches any element in the array.
`$ne`	String, Number, Boolean	Matches values that are not equal to the specified value.
`$gt`	Number	Greater than.
`$gte`	Number	Greater than or equal to.
`$lt`	Number	Less than.
`$lte`	Number	Less than or equal to.
`$in`	Non-empty array of primitives	Matches any value in an array (similar to the SQL `IN` operation)
`$nin`	Non-empty array of primitives	Does not match any of the values in the array (similar to the SQL `NOT IN` operation).
`$exists`	Boolean	Checks whether a metadata key exists.
`$and`	Non-empty array of filters	Performs a logical AND operation on an array of filter conditions.
`$or`	Non-empty array of filters	Performs a logical OR operation on an array of filter conditions.
`$nor`	Non-empty array of filters	Performs a logical NOR operation on an array of filter conditions.

Filter examples

The following are common Filter expression examples. When the operator is omitted, $eq is used by default.

// Simple equality (uses $eq by default when the operator is omitted)
{"category": "finance"}

// Explicit equality / inequality
{"category": {"$eq": "finance"}}
{"category": {"$ne": "archived"}}

// Numeric comparison
{"created_year": {"$gt": 2023}}
{"created_year": {"$gte": 2024}}
{"created_year": {"$lt": 2026}}
{"created_year": {"$lte": 2025}}

// Array matching
{"language": {"$in": ["zh", "en"]}}
{"language": {"$nin": ["ja", "ko"]}}

// Existence check
{"author": {"$exists": true}}

// Logical combination
{"$and": [{"category": {"$eq": "finance"}}, {"created_year": {"$gte": 2024}}]}
{"$or": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}
{"$nor": [{"category": {"$eq": "finance"}}, {"category": {"$eq": "tech"}}]}

// Multiple conditions on the same field (range)
{"score": {"$gte": 0.6, "$lte": 0.95}}

Example

The following command finds the top 10 vectors in the 'index' vector index of the 'examplebucket' vector bucket that are most similar to a query vector and whose 'type' is 'comedy' or 'documentary'.

ossutil vectors-api query-vectors --bucket examplebucket --index-name index --filter "{\"$and\":[{\"type\":{\"$in\":[\"comedy\",\"documentary\"]}}]}" --query-vector "{\"float32\":[32]}" --top-k 10