Vector-based query-OpenSearch(Open Search)-阿里云帮助中心

Send a vector to OpenSearch Vector Search Edition and retrieve the most similar documents from your index. If you don't have a vector model, use the image vectorization or text vectorization features to generate vectors with built-in models, then run prediction-based queries.

Endpoint

POST /vector-service/query

Protocol: HTTP Format: JSON

Note: The endpoint path omits the base URL of your OpenSearch application and any request headers. See Request signature for authentication details.

Request signature

The authorization header carries a Base64-encoded username:password string. Find your credentials in the API Endpoint section of the Instance Details page.

import com.aliyun.darabonba.encode.Encoder;
import com.aliyun.darabonbastring.Client;

public class GenerateAuthorization {

    public static void main(String[] args) throws Exception {
        String accessUserName = "username";
        String accessPassWord = "password";
        String realmStr = "" + accessUserName + ":" + accessPassWord + "";
        String authorization = Encoder.base64EncodeToString(Client.toBytes(realmStr, "UTF-8"));
        System.out.println(authorization);
    }
}

The encoded value looks like:

cm9vdDp******mdhbA==

Set the header in every request:

authorization: Basic cm9vdDp******mdhbA==

Request parameters

By default, the response includes only id and score — no field values and no vector data. Set outputFields and includeVector to include additional data.

Parameter	Type	Required	Default	Description
`tableName`	STRING	Yes	—	Name of the table to query.
`vector`	LIST[FLOAT]	Yes	—	Query vector. For multiple vectors, concatenate them in a single array and set `vectorCount`.
`vectorCount`	INT	No	`1`	Number of vectors in the `vector` array.
`namespace`	STRING	No	`""`	Namespace of the vector data. If a namespace is configured on the vector index, this field is required.
`topK`	INT	No	`100`	Maximum number of results to return.
`includeVector`	BOOLEAN	No	`false`	Specifies whether to return the raw vector in each result. Set to `true` only when you need the vector values; omitting it reduces response size and latency.
`outputFields`	LIST[STRING]	No	`[]`	Field names to include in each result. Omit to return only `id` and `score`.
`order`	STRING	No	`ASC`	Sort direction for the primary sort. Valid values: `ASC`, `DESC`.
`searchParams`	STRING	No	`""`	JSON-encoded searcher configuration. Supports QcSearcher and HnswSearcher parameters.
`filter`	STRING	No	`""`	Filter expression to narrow results before ranking.
`scoreThreshold`	FLOAT	No	—	Score cutoff for filtering results. For squared Euclidean distance, only documents with a score lower than the threshold are returned. For inner product, only documents with a score higher than the threshold are returned.
`sort`	STRING	No	`""`	Sort expression for combining vector similarity with other fields. Use `_vs_vector_score` to include the vector score, for example: `-create_gmt;+_vs_vector_score`.
`sorts`	LIST[Sort]	No	`[]`	Multi-dimensional sort. When set, the `score` in results reflects the configured sort dimensions.

Sort object

Parameter	Type	Required	Default	Description
`order`	STRING	No	`""`	Sort direction. Valid values: `ASC` (ascending), `DESC` (descending).
`expression`	STRING	No	`""`	Expression to sort by.

Examples

Single vector query

Request:

{
    "tableName": "gist",
    "vector": [0.1, 0.2, 0.3],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Response:

{
    "result": [
        {"id": 1, "score": 1.0508723258972169, "vector": [0.1, 0.2, 0.3]},
        {"id": 2, "score": 1.0329746007919312, "vector": [0.2, 0.2, 0.3]},
        {"id": 3, "score": 0.980593204498291,  "vector": [0.3, 0.2, 0.3]}
    ],
    "totalCount": 3,
    "totalTime": 2.943
}

Namespace-based query

Namespaces partition a vector index into isolated subsets. If a namespace is configured on the index, you must include it in every query.

{
    "tableName": "gist",
    "namespace": "space_b",
    "vector": [0.1, 0.2],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Query across multiple namespaces

Use the queries array to search across multiple namespaces in a single request. OpenSearch merges and ranks the results, then returns the top K.

{
    "tableName": "gist",
    "queries": [
        {"vector": [0.1, 0.2, 0.3], "namespace": "space_a"},
        {"vector": [0.4, 0.5, 0.6], "namespace": "space_b"}
    ],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Query with filter conditions

Use a filter expression to restrict candidates before ranking. Combine with outputFields to control which fields are returned.

{
    "tableName": "gist",
    "vector": [0.1, 0.2],
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "filter": "a > 10",
    "includeVector": true,
    "outputFields": ["a", "b"]
}

Multi-vector query

Concatenate all vectors into the vector array and set vectorCount to the number of vectors. OpenSearch merges and ranks the results from all vectors, then returns the top K. The example below queries two 2D vectors:

{
    "tableName": "gist",
    "vector": [0.1, 0.2, 0.3, 0.4],
    "vectorCount": 2,
    "topK": 3,
    "searchParams": "{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true,
    "outputFields": ["a", "b"]
}

Response parameters

Parameter	Type	Description
`result`	LIST[Item]	Ranked list of matching documents.
`totalCount`	INT	Number of results returned.
`totalTime`	FLOAT	Query latency in milliseconds.
`errorCode`	INT	Error code. Present only when the request fails.
`errorMsg`	STRING	Error message. Present only when the request fails.

Item

Parameter	Type	Description
`id`	FieldType	Primary key of the document.
`score`	FLOAT	Similarity score. The direction depends on the distance metric: for squared Euclidean distance, a lower score means higher similarity; for inner product, a higher score means higher similarity.
`fields`	MAP<STRING, FieldType>	The fields and the corresponding values.
`vector`	LIST[FLOAT]	The vector value.
`namespace`	STRING	Namespace of the document. Returned only when a namespace is configured.