All Products
Search

This Product

    Object Storage Service:query-vectors

    Document Center

    Object Storage Service:query-vectors

    Last Updated:Jun 27, 2026

    Use the query-vectors command to perform a vector similarity search.

    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

    Filter operators

    Operator

    Supported type

    Description

    $eq

    String

    Exact match for a single value. When compared with metadata of the array type, this operator returns true if the input value matches any element in the array.

    $ne

    String

    Not equal to

    $in

    String array

    Matches any value in an array. This is similar to the IN operation in SQL.

    $nin

    String array

    Does not match any value in an array. This is similar to the NOT IN operation in SQL.

    $exists

    Boolean

    Checks whether the metadata key exists.

    $and

    Non-empty array of filters

    Logical AND for multiple conditions.

    $or

    Non-empty array of filters

    Logical OR for multiple conditions.

    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