OpenSearch:Vector-based query

Description

You can import the vector data to an OpenSearch Vector Search Edition instance and use the instance to perform vector-based queries.

Note: If you do not have a vector model to convert the data into vectors, you can use the image vectorization and text vectorization features of OpenSearch Vector Search Edition and convert the data into vectors by using the built-in vector models. Then, you can perform prediction-based queries.

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 the OpenSearch application.

• 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

You can use the fields in the following table to calculate the request signature. The request signature is stored in the authorization header.

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

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 for data queries.

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

Item

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
}