All Products
Search

This Product

    Object Storage Service:query-vectors

    Document Center

    Object Storage Service:query-vectors

    Last Updated:Mar 25, 2026

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

    Permissions

    By default, an Alibaba Cloud account has all permissions, whereas RAM users and RAM roles have none. The account owner or an administrator must grant permissions by using 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 index name.

    --query-vector

    string

    The query vector, in JSON format. The dimension 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–100.

    --filter

    string

    Filters query results based on metadata.

    • Maximum length: 64 KB per request.

    • Maximum of 1,024 filter instructions per request.

    --return-distance

    /

    The similarity distance is returned if you leave this parameter empty or set it to true.

    --return-metadata

    /

    Specifies whether to return metadata. If you do not specify this parameter or set it to true, metadata is returned.

    Note

    Filter operators

    Operator

    Supported type

    Description

    $eq

    String

    Performs an 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 a metadata key exists.

    $and

    Non-empty array of filters

    Performs a logical AND operation on multiple conditions.

    $or

    Non-empty array of filters

    Performs a logical OR operation on multiple conditions.

    Examples

    This example finds the top 10 vectors most similar to a query vector. The search targets the 'index' vector index in the 'examplebucket' vector bucket and filters for vectors of the "comedy" and "documentary" types.

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