Search (gRPC)

Introduced 3.0

This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated GitHub issue.

The gRPC Search API provides a performant, binary interface for running queries using protocol buffers over gRPC. It mirrors the capabilities of the HTTP Search API while benefiting from protobuf-typed contracts and gRPC transport. The gRPC APIs are ideal for low-latency, high-throughput applications.

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 Document APIs reside in the SearchService.

You can submit search requests by invoking the Search gRPC method within the SearchService. The method takes in a SearchRequest and returns a SearchResponse.

Currently, only the following basic queries are supported: match_all, term, terms, and match_none. Additional query types will be supported in future versions.

Request fields

The gRPC Search API supports the following request fields.

SearchRequest fields

The SearchRequest message accepts the following fields. All fields are optional.

SearchRequestBody fields

The SearchRequestBody message accepts the following fields. All fields are optional.

QueryContainer fields

QueryContainer is the entry point for all supported query types.

Exactly one of the following fields must be provided in each QueryContainer message.

Note that some query types are currently unsupported. Currently, only match_all, term, terms, and match_none are supported.

Supported queries

The gRPC Search API supports the following queries.

All of the following examples show valid request payloads that can be sent to the SearchService/Search gRPC method.

Match all query

A match_all query returns all documents in the index. For example, the following request returns a maximum of 50 documents from the index:

{
  "request_body": {
    "query": {
      "match_all": {}
    },
    "size": 50
  }
}

Term query

A term query matches a single field with a specific term. For example, the following query searches for titles containing the word Rush:

{
  "index": "my_index",
  "request_body": {
    "query": {
      "term": {
        "title": {
          "value": {
            "string_value": "Rush"
          },
          "case_insensitive": true
        }
      }
    }
  }
}

Terms query

A terms query matches documents in which a specific field contains any value from a list. For example, the following query searches for lines with the IDs 61809 and 61810:

{
 "request_body": {
   "query": {
     "terms": {
       "terms_lookup_field_string_array_map": {
         "line_id": {
           "string_array": {
             "string_array": [
               "61809",
                    "61810"
             ]
           }
         }
       }
     }
   }
 }
}

Terms query with a terms lookup

A terms query with a terms lookup is a specialized form of the terms query that allows you to fetch the terms for filtering from another document in your cluster rather than specifying them directly in the query. For example, the following request matches documents in the students index with every student whose id matches one of the values in the enrolled array:

{
  "request_body": {
    "query": {
      "terms": {
        "boost": 1.0,
        "terms_lookup_field_string_array_map": {
          "student_id": {
            "terms_lookup_field": {
              "index": "classes",
              "id": "101",
              "path": "enrolled"
            }
          }
        }
      }
    }
  }
}

Match none query

A match_none query matches none of the documents:

{
  "request_body": {
    "query": {
      "match_none": {}
    }
  }
}

Response fields

The gRPC Search API provides the following response fields.

SearchResponse fields

The following table lists the supported fields for the SearchResponse message.

ResponseBody fields

The ResponseBody contains the following fields.

The source documents are returned as bytes. Use Base64 decoding to read the _source field in the gRPC response.

HitsMetadata fields

The HitsMetadata object contains information about the search results, including the total number of matching documents and an array of individual document matches. It includes the following fields.

Hit fields

Each Hit represents a single document matched by the query and contains the following fields.

source is Base64 encoded and must be decoded to obtain the JSON document.

Example response

{
  "responseBody": {
    "took": "64",
    "timedOut": false,
    "shards": {
      "successful": 1,
      "total": 1
    },
    "hits": {
      "total": {
        "totalHits": {
          "relation": "TOTAL_HITS_RELATION_EQ",
          "value": "1"
        }
      },
      "hits": [
        {
          "index": "my_index",
          "id": "3",
          "score": {
            "floatValue": 1
          },
          "source": "eyAidGl0bGUiOiAiUnVzaCIsICJ5ZWFyIjogMjAxM30=",
          "metaFields": {}
        }
      ],
      "maxScore": {
        "floatValue": 1
      }
    }
  }
}

Java gRPC client example

The following example shows a Java client-side program that submits a sample search term query gRPC request and then prints the number of hits returned in the search response:

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

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

        SearchServiceGrpc.SearchServiceBlockingStub stub = SearchServiceGrpc.newBlockingStub(channel);

        Query query = Query.newBuilder()
            .setTerm(TermQuery.newBuilder().setField("director").setValue("Nolan"))
            .build();

        SearchRequest request = SearchRequest.newBuilder()
            .addIndex("movies")
            .setQuery(query)
            .setSize(5)
            .build();

        SearchResponse response = stub.search(request);
        System.out.println("Found hits: " + response.getHits().getTotal());
        channel.shutdown();
    }
}