Link Search Menu Expand Document Documentation Menu

k-NN (gRPC) API

Introduced 3.2

The gRPC k-NN API is generally available starting with OpenSearch 3.2. However, expect updates to the protobuf structure as the feature matures in upcoming versions.

The gRPC k-NN API provides an efficient, binary-encoded interface for performing k-nearest neighbor searches using protocol buffers over gRPC. The k-NN plugin offers a specific search query type for vector similarity searches. This API offers superior performance compared to the traditional HTTP-based approach, making it ideal for large-scale machine learning and vector database applications.

For information about HTTP-based k-NN queries, see k-NN query.

Prerequisite

To submit gRPC requests, you must have a set of protobufs on the client side. For ways to obtain the protobufs, see Using gRPC APIs.

gRPC service and method

gRPC k-NN APIs reside in the SearchService, the same service used for general search operations.

You can submit k-NN search requests by invoking the Search gRPC method within the SearchService, using a KnnQuery within the search request. The method takes a SearchRequest and returns a SearchResponse.

The gRPC implementation uses the same underlying k-NN functionality as the HTTP API while providing improved performance through protocol buffer serialization.

KnnQuery fields

The gRPC k-NN API uses the KnnQuery message within a QueryContainer for k-NN searches. The KnnQuery message accepts the following fields.

Field Protobuf type Description
field string The vector field against which to run the search query. Required.
vector repeated float A query vector. Must have the same number of dimensions as the vector field. Optional.
k int32 The number of nearest neighbors to return as top hits. Optional.
min_score float The minimum similarity score required for a neighbor to be considered a hit. Optional.
max_distance float The maximum physical distance in vector space required for a neighbor to be considered a hit. Optional.
filter QueryContainer Filters for the k-NN search query. See Filter limitations. Optional.
boost float A boost value used to increase or decrease relevance scores. Default is 1.0. Optional.
underscore_name string A query name for query tagging (JSON key: _name). Optional.
method_parameters ObjectMap Algorithm-specific parameters (for example, ef_search or nprobes). Optional.
rescore KnnQueryRescore A rescoring configuration for improved accuracy. Available in versions later than 2.17. Optional.
expand_nested_docs bool When true, retrieves scores for all nested field documents within each parent document. Used with nested queries. Optional.

Example request

The following example shows a gRPC search request with a k-NN query. It searches for the 10 most similar vectors to the query vector [0.1, 0.2, 0.3, 0.4] in the my_vector field of the vector_index index:

{
  "index": ["vector_index"],
  "request_body": {
    "query": {
      "knn": {
        "field": "my_vector",
        "vector": [0.1, 0.2, 0.3, 0.4],
        "k": 10
      }
    },
    "size": 10
  }
}

Java gRPC client example

The following is a basic example of using the gRPC k-NN API (the actual implementation depends on your gRPC client setup):

import org.opensearch.protobufs.*;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class KnnGrpcClient {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 9400)
                .usePlaintext()
                .build();

        // Create a gRPC stub for search operations
        SearchServiceGrpc.SearchServiceBlockingStub searchStub =
            SearchServiceGrpc.newBlockingStub(channel);

        // Build a k-NN query using protocol buffers
        QueryContainer knnQuery = QueryContainer.newBuilder()
            .setKnn(KnnQuery.newBuilder()
                .setField("my_vector")
                .addAllVector(Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f))
                .setK(10)
                .build())
            .build();

        // Create the search request
        SearchRequest request = SearchRequest.newBuilder()
            .addIndex("vector_index")
            .setRequestBody(SearchRequestBody.newBuilder()
                .setQuery(knnQuery)
                .setSize(10)
                .build())
            .build();

        // Execute the search
        SearchResponse response = searchStub.search(request);

        System.out.println("Found " + response.getResponseBody().getHits().getHitsCount() + " results");

        channel.shutdown();
    }
}

Response fields

k-NN search requests return the same SearchResponse structure as regular search operations. For information about response fields, see Search (gRPC) response fields.

The response includes the standard search metadata (took, timed_out, and shards) and a hits array containing the k-NN documents with their similarity scores.

Filter limitations

The gRPC k-NN API has limited support for the filter clause compared to the HTTP API. For the current list of supported query types in gRPC, see the Search API QueryContainer documentation and Supported queries.

For complex filtering requirements, consider using the HTTP k-NN API, simplifying your filter logic, or waiting for the next version of k-NN gRPC.

Next steps

350 characters left

Have a question? .

Want to contribute? or .