Description

Retrieve the top K vectors closest in distance to a target vector using KNN from the vector index.

Request syntax

The endpoint must use the Bucket Endpoint.

POST /QueryVectors HTTP/1.1​
Host: {VectorBucketName}-{AccountID}.tosvectors-cn-beijing.volces.com​
Authorization: authorization string​
Date: Mon, 10 Dec 2025 12:49:14 GMT​
​
{​
    "vectorBucketName": "test-vector-bucket",​
    "indexName":"test-index",​
    "queryVector": {​
        "float32": [​
            0.1,​
            0.1,​
            0.1,​
            0.1,​
            0.1​
        ]​
    },​
    "topK": 10,​
    "returnDistance": true,​
    "returnMetadata": true,​
    "filter": {"$and": [{"key_a": "va"}]}​
}​

Request parameters and headers

None.

Request body elements

Field name	Type	Required	Example value	Description
vectorBucketName	String	Yes	test-vector-bucket	Name of the vector bucket.
indexName	String	Yes	test-index	name of the vector index
filter	JSON value	No	{"$and": [{"key_a": "va"}]}	Metadata filters applied during the query.
queryVector	VectorData	Yes	{ "float32": [ 0.1, 0.1, 0.1, 0.1, 0.1] }	Query vector. Ensure the query vector's dimension matches the dimension of the indexed vectors.
returnDistance	boolean	No	true	Indicates whether to include the calculated distance in the response. Default: false.
returnMetadata	boolean	No	true	Indicates whether to include metadata in the response. Default: false.
topK	integer	Yes	10	The number of results returned for each query. Valid range: minimum 1, maximum 30.

The VectorData structure is a union type with only one active member (float32) currently, as shown in the table below.

Field name	Type	Example value	Description
float32	float32[]	[0.1, 0.1, 0.1, 0.1, 0.1]	Vector data. The vector dimension must match the vector index dimension defined in CreateIndex.

Response headers

For common response headers, see Common parameters.

Response body elements

If the operation succeeds, the service returns an HTTP 200 status code along with the following response elements.

If the operation fails, it returns the error code defined in the Response code.

Field	Condition operator type	Example value	Description
vectors	[]QueryOutputVector	see the table below	An array containing vector search results.

QueryOutputVector structure parameter description:

Name	Type	Example value	Description
data	VectorData	[0.1, 0.1, 0.1, 0.1, 0.1]	Vector data. Ensure the query vector's dimension matches the dimension of the vector index being queried.
distance	float	0.050000004	Distance between query vector and result vector.
key	String	key0	Unique identifier of the vector.
metadata	JSON value	{ "key_a": "va", "key_b": "vb", "key_c": "vc1", "key_d": "vd" }	Metadata associated with the vector

Sample request

Sample response

Torch Object Storage