OpenSearch:Vector query

Feature description

A vector query is a query method in which you import pre-generated vector data into an OpenSearch Vector Search Edition instance and then perform vector retrieval.

Note: If you do not have a vector model to generate vectors for your data, you can use the image vectorization and text vectorization features of OpenSearch Vector Search Edition to generate vectors for your data with the built-in vector models, and then perform retrieval by using Prediction query.

URL

/vector-service/query

• The preceding URL omits factors such as request header parameters and encoding.

• The preceding URL omits the host address used to access the application.

• For the definitions, usage, and examples of all query parameters appended to the preceding URL, see "Query parameters" below.

Request protocol

HTTP

Request method

POST

Supported format

JSON

Signature mechanism

You can use the following method to calculate the signature (authorization)

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

Correct format of the returned authorization value:

cm9vdDp******mdhbA==

When you set the authorization parameter in an HTTP request, you must add the Basic prefix.

Example (added to the header):

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

Request body syntax

Single-vector query

{
    "tableName": "gist",
    "vector": [
        0.1,
        0.2,
        0.3
    ],
    "topK": 3,
    "sorts": [
      {
      "order": "DESC",
      "expression": "float(cate_id) + 1.0"
      },
      {
      "order": "ASC",
      "expression": "__vs_vector_score__ + 0.5"
      }
     ]
    "searchParams":"{\"qc.searcher.scan_ratio\":0.01}",
    "includeVector": true
}

Query with a namespace

OpenSearch Vector Search Edition allows you to partition an index by namespace. After you configure namespaces for a vector index, you can query within a specified namespace, so different query requests can search different subsets of the index.

Important: After you configure a namespace, you must specify the namespace in queries.

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

Multi-namespace query

After you configure namespaces for a vector index, you can query across 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 with filters

You can use Filter expressions to specify filter conditions for 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"
    ]
}

Multi-vector query

You can query multiple vectors at the same time. The results of these vectors are merged and sorted, and the final topK results are returned. For example, if the vector dimension is 2, query two vectors at the same 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

Definition of 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
}