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

Runs multiple vector queries in a single request and merges the results into a unified ranked list. Supports searching across multiple namespaces, multiple indexes, and combinations of dense and sparse vectors.

Request

Method: POST

URL: /vector-service/multi-query

Format: JSON

Authentication

The request signature uses HTTP Basic Auth. Encode username:password as Base64 and pass the result in the authorization header.

Credentials

Parameter	Type	Description
`accessUserName`	string	The username. View it in the API Endpoint section of the Instance Details page.
`accessPassWord`	string	The password. Modify it in the API Endpoint section of the Instance Details page.

Generate the authorization value

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);
    }
}

Set the header with the Basic prefix:

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

Request parameters

SearchRequest

Parameter	Type	Required	Default	Description
`tableName`	string	Yes	—	The name of the table to query.
`indexName`	string	No	—	The index to use for all queries. Specify here or in each individual `Query` object.
`queries`	list[Query]	Yes	—	The list of vector queries to run.
`mode`	string	No	`sum`	The score aggregation method when multiple queries match the same primary key. Valid values: `sum`, `max`, `min`.
`topK`	int	No	`100`	The number of results to return.
`includeVector`	bool	No	`false`	Specifies whether to include vector values in the response.
`outputFields`	list[string]	No	`[]`	The fields to include in each result. Returns all fields if empty.
`order`	string	No	`ASC`	The sort order of results. Valid values: `ASC` (ascending), `DESC` (descending).
`filter`	string	No	`""`	A filter expression to apply to results.
`sort`	string	No	`""`	A sort expression to apply to results.

Query

Parameter	Type	Required	Default	Description
`indexName`	string	No	—	The index to use for this query. Overrides the `indexName` in `SearchRequest`. Either this field or `SearchRequest.indexName` must be set.
`vector`	list[float]	No	—	The dense vector to search. To include multiple vectors, tile them sequentially in this list and set `vectorCount` accordingly.
`vectorCount`	int	No	`1`	The number of vectors in the `vector` field.
`topK`	int	No	`100`	The number of results to return for this query.
`namespace`	string	No	`""`	The namespace of the vector data to search.
`sparseData`	SparseData	No	—	The sparse vector to search. Used for hybrid dense-sparse queries.
`weight`	float	No	`1.0`	The weight of this query when merging results.
`searchParams`	string	No	`""`	Additional query parameters.
`scoreThreshold`	float	No	—	Filters results by score. For squared Euclidean distance, only documents with a distance smaller than this value are returned. For inner product, only documents with an inner product greater than this value are returned.

SparseData

Parameter	Type	Required	Default	Description
`indices`	list[int]	Yes	—	The indexes of the non-zero elements, in ascending order.
`values`	list[float]	Yes	—	The values of the non-zero elements, in the same order as `indices`.
`count`	list[int]	No	Number of indexes (single sparse vector)	The number of elements in each sparse vector. Required when passing multiple sparse vectors.

Response parameters

Top-level response

Parameter	Type	Description
`result`	list[Item]	The matched documents.
`totalCount`	int	The number of results returned.
`totalTime`	float	The total query time, in milliseconds.
`errorCode`	int	The error code. Returned only when an error occurs.
`errorMsg`	string	The error message. Returned only when an error occurs.

Item

Parameter	Type	Description
`id`	Type	The primary key of the document.
`score`	float	The distance score for this result.
`fields`	map<string, FieldType>	The field names and their values.
`vector`	list[float]	The vector value. Returned when `includeVector` is `true`.
`namespace`	string	The namespace of the vector. Returned when a namespace is configured.

Examples

Query across multiple namespaces

Search two namespaces simultaneously and return the top 3 results using the minimum score across matches.

Request body

{
    "tableName": "gist",
    "indexName": "vec_index",
    "queries": [
        {
            "vector": [0.1, 0.2, 0.3],
            "namespace": "space_a"
        },
        {
            "vector": [0.4, 0.5, 0.6],
            "namespace": "space_b"
        }
    ],
    "mode": "min",
    "topK": 3,
    "includeVector": true
}

Response

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

Hybrid query across multiple indexes

Search two indexes simultaneously using dense and sparse vectors with different weights. Each query targets a separate index and namespace.

Request body

{
    "tableName": "gist",
    "queries": [
        {
            "indexName": "content_vec",
            "vector": [0.1, 0.2, 0.3],
            "sparseData": {
                "count": [3],
                "indices": [102, 405, 503],
                "values": [0.32, 0.94, 0.25]
            },
            "weight": 0.7,
            "namespace": "space_a"
        },
        {
            "indexName": "title_vec",
            "vector": [0.4, 0.5, 0.6],
            "sparseData": {
                "count": [2],
                "indices": [203, 709],
                "values": [0.98, 0.08]
            },
            "weight": 0.3,
            "namespace": "space_b"
        }
    ],
    "topK": 3,
    "includeVector": true
}