Vector-based query - OpenSearch - Alibaba Cloud Documentation Center

URL

/vector-service/query

The sample URL omits information such as the request headers and the encoding method.
The sample URL also omits the endpoint that is used to connect to an OpenSearch instance.
For more information about the definitions, usage, and example values of all the request parameters that are concatenated in the preceding URL, see the "Request parameters" section of this topic.

Protocol

HTTP

Request method

POST

Supported format

JSON

Request signature

Request signature in the authorization header

Parameter	Type	Description
accessUserName	string	The username. You can view the username in the API Endpoint section of the Instance Details page.
accessPassWord	string	The password. You can modify the password 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);
		}
}

Valid format for the value of the authorization header:

cm9vdDp******mdhbA==

You must add the Basic prefix when you specify the authorization header in an HTTP request.

Example:

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

Request parameters

Parameter	Description	Default value	Type	Required
tableName	The name of the table to be queried.	No default value	string	Yes
vector	The vector data to be queried.	No default value	list[float]	Yes
vectorCount	The number of vectors specified in the vector parameter.	1	int	No
namespace	The namespace of the vector data.	""	string	No
topK	The number of results to be returned.	100	int	No
includeVector	Specifies whether to return the vector information in documents.	false	bool	No
outputFields	The fields to be returned.	[]	list[string]	No
order	The order in which the results are sorted. A value of ASC specifies the ascending order. A value of DESC specifies the descending order.	ASC	string	No
searchParams	The parameters that are used to query data. QcSearcher HnswSearcher	""	string	No
filter	The filter expression.	""	string	No
scoreThreshold	The threshold score used to filter documents. If the score is the squared Euclidean distance, only the documents whose squared Euclidean distance is less than the value of the scoreThreshold parameter are returned. If the score is the inner product, only the documents whose inner product is greater than the value of the scoreThreshold parameters are returned.	By default, the results are not filtered.	float	No

Query by using a single vector

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

Namespace-based query

OpenSearch Vector Search Edition allows you to partition indexes by using namespaces. After you configure namespaces for vector indexes, you can specify a namespace to query data. This way, you can query different subsets of indexes by sending different query requests.

Note: If you configure a namespace for a vector index, you must specify the namespace when you query data.

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

Query by using multiple namespaces

If you configure namespaces for vector indexes, you can query data in multiple namespaces.

{
    "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 by using filter conditions

You can use filter expressions to specify filter conditions to query data.

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

Query by using multiple vectors

You can query multiple vectors at the same time. OpenSearch merges and sorts the results of all vectors, and returns the top K results. The following sample code provides an example on how to query two two-dimensional vectors at a time:

{
    "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	Description	Type
result	The returned results.	list[Item]
totalCount	The number of results.	int
totalTime	The response time. Unit: millisecond.	float
errorCode	The error code returned if the request failed.	int
errorMsg	The error message returned if the request failed.	string

Item

Parameter	Description	Type
score	The score of the vector.	float
fields	The fields and the corresponding values.	map<string, FieldType>
vector	The vector value.	list[float]
id	The primary key value. The value is of the defined data type.	FieldType
namespace	The namespace of the vector. This parameter is returned if a namespace is configured for the vector.	string

Example:

{
    "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
}