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

Runs up to five independent queries in parallel within a single request. The Multi-path Search API merges and sorts results from all paths into a single ranked list. For each path, set a retrieval quota and priority, and trace which path each result came from.

Key concepts

Path: A single independent query within a multi-path request. Each path runs against the DPI engine in parallel and returns its own candidate set.
Query group: A set of paths that share the same priority. Paths in the same group share a retrieval quota. For example, if paths A and B are in the same group and each has a quota of 100, and path A retrieves only 70 documents, path B can use the remaining 30 quota and retrieve up to 130 documents.
Derived vector search: When a text query path matches a text embedding rule configured in query analysis, the system automatically creates a vector query path derived from the text path. The derived path inherits the same priority as its parent and has a default quota of 0, meaning it shares the parent path's quota.

When to use multi-path search

Multi-path search is designed for scenarios where a single query strategy is not enough. Use it when you need to:

Combine text search and vector search in the same request
Query different indexes with different ranking strategies
Blend results from multiple query strategies and control which results take precedence

Do not use multi-path search for standard single-strategy retrieval. This feature is available only for dedicated applications and does not support aggregation, distinct, or highlighting.

Limitations

A single request supports a maximum of five paths. Derived vector search paths do not count toward this limit.
Available only for dedicated applications.
A maximum of 5,000 candidate documents can be retrieved from the DPI engine per path.
The aggregation, distinct, and highlighting features are not supported.

Request

Method: POST

URL:

/v3/openapi/apps/$app_name/multi-path-search

$app_name is the name of your application. Premium Edition and Standard Edition support multiple applications and require an application name for access. You can also specify the ID of an offline application.

The URL above omits request headers, encoding, and the host address for accessing the application.

Global parameters

These parameters apply to the entire request.

Parameter	Type	Required	Default	Description
`raw_query`	String	No	`""`	The original query from the end user. Used for query analysis or logging.
`start`	Integer	No	`0`	The starting position for pagination. Valid values: `[0, 5000]`.
`hit`	Integer	No	`10`	The maximum number of documents to return. Valid values: `[1, 500]`.
`format`	String	No	`fulljson`	The format of the result set.
`fetch_fields`	String	No	All fields	The document fields to return. Separate multiple fields with semicolons (`;`).
`unified_rank_size`	Integer	No	`2000`	The total number of documents for unified sorting. The system selects up to this number from all paths based on priority. Valid values: `[1, 10000]`.
`unified_rank_type`	String	No	`none`	The unified sorting strategy. See Choose a unified sorting strategy.
`unified_rank_name`	String	No	`""`	The name of the sorting script. Required when `unified_rank_type` is `cava_script`.
`vector_search`	Object	No	`{}`	Vector retrieval configuration. For parameter details, see Vector retrieval.
`user_id`	String	No	`""`	The unique identifier of the end user. Used for UV statistics or algorithm training.
`trace`	String	No	`""`	The log level for search. Used for troubleshooting.
`rank_trace`	String	No	`""`	The log level for sorting. Used for troubleshooting.

Choose a unified sorting strategy

The unified_rank_type parameter controls how results from multiple paths are merged and ranked before being returned.

Value	Description	When to use
`rrf`	Uses the Reciprocal Rank Fusion (RRF) algorithm to merge and rank results across paths. RRF ranks documents by their relative positions across result sets rather than absolute scores, making it robust when scores from different paths are not directly comparable.	Combining results from heterogeneous paths (for example, text and vector) without a custom scoring model.
`cava_script`	Uses a custom Cava script for sorting. Text relevance scoring is not available in the Cava script for unified sorting; use models such as click-through rate (CTR) for scoring. Requires `unified_rank_name` to specify the script name.	Custom business logic for merging results.
`none`	Skips unified sorting entirely. All candidate documents are returned as-is. The `start` and `hit` pagination parameters are ignored.	Implementing sorting logic outside of OpenSearch. This mode can return a large volume of data.

Path parameters (`queries` array)

Each object in the queries array defines one query path.

Parameter	Type	Required	Default	Description
`path`	String	Yes	—	The unique identifier for this query path. Appears in sorting logs and `tracerInfo` to identify the source of each result.
`query`	String	Yes	—	The query clause defining the retrieval conditions for this path. For syntax details, see Index retrieval - query clause.
`priority`	Integer	Yes	—	The retrieval priority; non-negative integers, where `0` is the highest priority. The system prioritizes documents from higher-priority paths when selecting candidates for unified sorting.
`quota`	Integer	Yes	—	The maximum number of documents to retrieve for this path. Non-negative integers.
`qp`	String	No	Default rules in the console	The names of the query analysis configurations. Separate multiple names with commas (`,`).
`first_rank_name`	String	No	Default configurations in the console	The name of the rough sort configuration.
`second_rank_name`	String	No	Default configurations in the console	The name of the fine sort configuration.
`total_rank_size`	Integer	No	DPI engine default	The total number of documents for rough sorting. Valid values: `[1, 5000000]`.
`total_rerank_size`	Integer	No	DPI engine default	The total number of documents for fine sorting. Valid values: `[1, 10000]`.
`sort`	String	No	`-RANK`	The sort clause. For syntax details, see Global sorting - sort clause.
`filter`	String	No	`""`	The filter clause. For syntax details, see Result filtering - filter clause.
`kvpairs`	Map	No	`{}`	Custom key-value pairs. For usage details, see Custom parameter passing - kvpairs clause.

Code examples

Request example

The following request defines two query paths:

main (priority 1): queries the title index using the sys_title query analysis rule.
sub (priority 2): queries the title index without a query analysis rule.

Because the main path uses a text embedding rule in query analysis, the system automatically creates a third derived vector search path (main/vector) with the same priority as main.

All three paths use RRF for unified sorting.

{
    "queries": [
        {
            "query": "title:'OpenSearch'",
            "path": "main",
            "priority": 1,
            "quota": 100,
            "qp": "sys_title"
        },
        {
            "query": "title:'AI'",
            "path": "sub",
            "priority": 2,
            "quota": 100,
            "qp": ""
        }
    ],
    "raw_query": "OpenSearch",
    "start": 0,
    "hit": 10,
    "format": "fulljson",
    "trace": "debug",
    "rank_trace": "info",
    "unified_rank_type": "rrf",
    "unified_rank_size": 1000,
    "fetch_fields": "title",
    "user_id": "123",
    "vector_search": {
        "vector": {
            "top_n": 100,
            "namespaces": [],
            "threshold": 0.5,
            "search_params": {
                "qc_scan_ratio": 0.01
            }
        }
    }
}

Response example

{
    "errors": [
        {
            "code": 2112,
            "message": "Specified index not in query:text_relevance(title,default,true)"
        }
    ],
    "ops_request_misc": "%7B%22request%5Fid%22%3A%22176129335716862423300005%22%2C%22scm%22%3A%2220140713.120141928..%22%7D",
    "request_id": "176129335716862423300005",
    "result": {
        "compute_cost": [
            {
                "index_name": "test",
                "value": 13.73
            }
        ],
        "facet": [],
        "items": [
            {
                "attribute": {
                    "pk": [
                        "120142134_1"
                    ]
                },
                "fields": {
                    "title": "OpenSearch Industry Algorithm Edition"
                },
                "property": {},
                "sortExprValues": [
                    "0.0327869"
                ],
                "tracerInfo": "begin search path[main] rank trace:\nend search path[main] rank trace.\n\nbegin search path[main/vector] rank trace:\nend search path[main/vector] rank trace.\n",
                "variableValue": {}
            },
            {
                "attribute": {
                    "pk": [
                        "120142134_2"
                    ]
                },
                "fields": {
                    "title": "OpenSearch Retrieval Engine Edition"
                },
                "property": {},
                "sortExprValues": [
                    "0.0322581"
                ],
                "tracerInfo": "begin search path[main] rank trace:\nend search path[main] rank trace.\n\nbegin search path[main/vector] rank trace:\nend search path[main/vector] rank trace.\n",
                "variableValue": {}
            },
            {
                "attribute": {
                    "pk": [
                        "120142134_3"
                    ]
                },
                "fields": {
                    "title": "AI Search Open Platform"
                },
                "property": {},
                "sortExprValues": [
                    "0.0163934"
                ],
                "tracerInfo": "begin search path[sub] rank trace:\nend search path[sub] rank trace.\n",
                "variableValue": {}
            }
        ],
        "num": 3,
        "searchtime": 0.085292,
        "total": 3,
        "viewtotal": 3
    },
    "status": "OK",
    "tracer": ""
}

Trace result sources

Each item in result.items includes a tracerInfo field that shows which path retrieved the document. Enable path tracing by setting rank_trace to info or debug in the request.

In the response example above:

The first two items show path[main] and path[main/vector] in tracerInfo, meaning they were retrieved by the main text path and its derived vector path.
The third item shows path[sub], meaning it was retrieved by the sub path.

Use tracerInfo to diagnose ranking behavior — for example, to confirm that a higher-priority path is surfacing the expected documents, or to verify that derived vector search is contributing results.

Response parameters

Parameter	Type	Description
`status`	String	The result of the search request. `OK` means the search succeeded. `FAIL` means the search failed — check the `errors` field for details.
`request_id`	String	The request ID.
`result`	Object	The search results, including `searchtime`, `total`, `num`, `viewtotal`, `items`, `facet`, and `scroll_id`.
`errors`	Array	Error details. Each error includes a `code` and a `message`. For a full list of error codes, see Error codes.

Result fields

`searchtime`: The time the engine took to complete the search, in seconds.
`total`, `viewtotal`, and `num`:
- total: The total number of documents matching the query conditions in the engine. For large result sets, this value may be an estimate.
- viewtotal: The number of results the engine actually returns. For pagination, the sum of start + hit must be less than viewtotal.
- num: The number of documents returned in this response. Limited by start and hit, and never exceeds hit.
`compute_cost`: An array with one element. index_name is the application ID. value is the logical computing units (LCUs) consumed by this request.
`items`: The search results. Each item contains:
- fields: The document fields returned based on fetch_fields.
- sortExprValues: The sort score for this document.
- tracerInfo: The path trace log for this document. See Trace result sources.
- variableValue: Custom parameter values (for example, distance). Populated only when format is xml or fulljson. Not returned when format is json.
`facet`: Statistics from the aggregate clause.
Array-type fields: In JSON or fullJSON format, values are separated by tab characters (\t). In XML format, values are separated by spaces.

How it works

Each multi-path request goes through four stages:

Parallel retrieval: All paths run in parallel against the DPI engine. Each path retrieves up to its quota value of candidate documents, with a maximum of 5,000 per path.
Candidate selection: The system selects documents from each path based on priority, up to the specified quota. Selection stops when the total number of selected documents reaches unified_rank_size.
Unified sorting:
- cava_script: All candidate document IDs are sent to the DPI engine for sorting using a custom Cava script.
- rrf: The system sorts candidates directly using the Reciprocal Rank Fusion algorithm.
- none: This stage is skipped entirely.
Result return:
- If sorting ran, the system returns documents in the range defined by start and hit.
- If unified_rank_type is none, the entire candidate set is returned and start and hit are ignored.

Important

When unified_rank_type is none, the system skips unified sorting, ignores the start and hit pagination parameters, and returns the complete candidate set. This mode can return a large volume of data. Use it only if you intend to implement sorting logic outside of OpenSearch.