Use the Data API to perform a sparse vector-based query - OpenSearch - Alibaba Cloud - OpenSearch

Submits a hybrid search request that combines dense and sparse vector scoring against an OpenSearch Vector Search Edition table.

Endpoint

POST /vector-service/query

Protocol: HTTP Format: JSON

Authentication

The request signature goes in the authorization header. Encode it as Base64 of username:password, then prefix with Basic.

Signature parameters

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

Generate the encoded 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);
    }
}

The encoded value looks like:

cm9vdDp******mdhbA==

Set the authorization header with the Basic prefix:

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

Request parameters

SearchRequest

Parameter	Type	Default	Required	Description
`tableName`	string	—	Yes	The name of the table to query.
`indexName`	string	—	Yes	The name of the dense vector index.
`vector`	list[float]	—	Yes	The dense vector data to query.
`sparseData`	SparseData	—	Yes	The sparse vector data to query. See SparseData.
`vectorCount`	int	1	No	The number of vectors in `vector`.
`namespace`	string	`""`	No	The namespace of the vector data.
`topK`	int	100	No	The maximum number of results to return.
`includeVector`	Boolean	`false`	No	Specifies whether to include vector data in the returned documents.
`outputFields`	list[string]	`[]`	No	The fields to include in the response.
`order`	string	`ASC`	No	The sort order of results. Valid values: `ASC` (ascending), `DESC` (descending).
`searchParams`	string	`""`	No	Additional query parameters. For HNSW indexes, see HnswSearcher.
`filter`	string	`""`	No	A filter expression to apply to results.
`scoreThreshold`	float	Not applied	No	The score threshold for filtering results. For Euclidean distance, only documents with a distance less than this value are returned. For inner product, only documents with an inner product greater than this value are returned.
`sort`	string	`""`	No	A sort expression.

SparseData

OpenSearch Vector Search Edition represents sparse vectors using two parallel multi-value fields: indices and values. The fields must have the same length, and each position corresponds one-to-one. The indices array must be sorted in ascending order; arrange values in the same order.

Example: Given the sparse vector (0, 0.5), (100, 0.9), (40, 0.3), (50, 0.7), (20, 0.6), sort the indices in ascending order:

{
  "indices": [0, 20, 40, 50, 100],
  "values": [0.5, 0.6, 0.3, 0.7, 0.9]
}

Parameter	Type	Default	Required	Description
`count`	list[int]	Number of indices (if one sparse vector)	No	The number of elements in each sparse vector.
`indices`	list[int]	—	Yes	The element indices, in ascending order.
`values`	list[float]	—	Yes	The element values, in the same order as `indices`.

Query weights

In a hybrid query, the final document score is the sum of the dense vector distance and the sparse vector distance. To apply different weights to each component, scale the values before submitting:

{
    "vector": [v * weight for v in dense_vector],
    "sparseData": {
        "indices": sparse_data["indices"],
        "values": [v * (1 - weight) for v in sparse_data["values"]]
    }
}

Sample request

{
    "tableName": "in0",
    "indexName": "vector",
    "vector": [
        0.1,
        0.2,
        0.3,
        0.4,
        0.5
    ],
    "sparseData": {
        "indices": [
            0,
            2
        ],
        "values": [
            1.2,
            2.4
        ]
    },
    "topK": 2,
    "order": "DESC"
}

Response parameters

Top-level fields

Parameter	Type	Description
`result`	list[Item]	The returned results.
`totalCount`	int	The total number of results.
`totalTime`	float	The response time, in milliseconds.
`errorCode`	int	The error code returned if the request failed.
`errorMsg`	string	The error message returned if the request failed.

Item

Parameter	Type	Description
`score`	float	The vector score.
`fields`	map\<string, FieldType\>	The document fields and their values.
`vector`	list[float]	The vector value.
`id`	FieldType	The primary key value. The data type matches the field definition.
`namespace`	string	The namespace of the vector. Returned only if the vector has a namespace configured.

Sample response

{
    "totalCount": 50,
    "result": [
        {
            "id": 99,
            "score": 0.18588095903396607,
            "__source__": 1,
            "fields": {
                "content": "Zhonghao Cat 6 Network Cable RJ45 Cat 6 Gigabit 8-Core Twisted Pair Jumper Broadband Monitoring Home Network Cable Finished Cable"
            }
        }
    ],
    "totalTime": 4.057
}