You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: _api-reference/grpc-apis/index.md
+81-38Lines changed: 81 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,67 +12,110 @@ redirect_from:
12
12
**Introduced 3.0**
13
13
{: .label .label-purple }
14
14
15
-
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](https://github.com/opensearch-project/OpenSearch/issues/16787).
16
-
{: .warning}
15
+
**Bulk and k-NN search generally available 3.2**
16
+
{: .label .label-green }
17
17
18
-
The OpenSearch gRPC plugin provides an alternative, high-performance transport layer using [gRPC](https://grpc.io/) for communication with OpenSearch. It uses protocol buffers over gRPC for lower overhead and faster serialization. This reduces overhead, speeds up serialization, and improves request-side latency, based on initial benchmarking results.
18
+
Starting with OpenSearch version 3.2, the gRPC [Bulk API]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/bulk/) and [k-NN search queries]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/knn/) are generally available. These use [protobuf version 0.6.0](https://github.com/opensearch-project/opensearch-protobufs/releases/tag/0.6.0). However, expect updates to the protobuf structure as the feature matures in upcoming versions. Other gRPC search functionality remains experimental and not recommended for production use. For updates on the progress of these features or to leave feedback, see the associated [GitHub issue](https://github.com/opensearch-project/OpenSearch/issues/16787).
19
+
{: .note}
19
20
20
-
The primary goal of the gRPC plugin is to:
21
+
The OpenSearch gRPC functionality provides an alternative, high-performance transport layer using [gRPC](https://grpc.io/) for communication with OpenSearch. It uses protocol buffers over gRPC for lower overhead and faster serialization. This reduces overhead, speeds up serialization, and improves request-side latency, based on initial benchmarking results.
21
22
22
-
* Offer a **binary-encoded** alternative to HTTP/REST-based communication.
23
-
***Improve performance** for bulk workloads and large-scale ingestion scenarios.
23
+
The primary goal of gRPC support is to:
24
+
25
+
* Offer a **binary-encoded** alternative to HTTP/REST-based communication.
26
+
***Improve performance** for bulk workloads and large-scale ingestion scenarios.
24
27
***Enable more efficient client integrations** across languages, like Java, Go, and Python, using native gRPC stubs.
25
28
26
-
## Enabling the plugin
29
+
## Performance benefits
27
30
28
-
To enable the gRPC plugin (`transport-grpc`) in OpenSearch:
29
-
1. Install the `transport-grpc` plugin. For more information, see [Installing plugins]({{site.url}}{{site.baseurl}}/install-and-configure/plugins/).
31
+
Using gRPC APIs provides several advantages over HTTP APIs:
30
32
31
-
1. Add the following settings to `opensearch.yml`:
- `grpc.host` (Static, list): Sets the address of an OpenSearch node for gRPC communication. The `grpc.host` setting is a combination of `grpc.bind_host` and `grpc.publish_host` if they are the same value. An alternative to `grpc.host` is to configure `grpc.bind_host` and `grpc.publish_host` separately, as needed.
57
+
Configure additional settings if needed (see [Advanced gRPC settings](#advanced-grpc-settings)):
59
58
60
-
- `grpc.bind_host` (Static, list): Specifies an address or addresses to which an OpenSearch node binds to listen for incoming gRPC connections.
59
+
```yaml
60
+
grpc.host: localhost
61
+
grpc.publish_host: 10.74.124.163
62
+
grpc.bind_host: 0.0.0.0
63
+
```
64
+
{% include copy.html %}
61
65
62
-
- `grpc.publish_host` (Static, list): Specifies an address or addresses that an OpenSearch node publishes to other nodes for gRPC communication.
66
+
## Advanced gRPC settings
63
67
64
-
These settings are similar to the [HTTP Network settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/network-settings/#advanced-http-settings).
68
+
OpenSearch supports the following advanced settings for gRPC communication. These settings can be configured in `opensearch.yml`.
69
+
70
+
| Setting name | Description | Example value | Default value |
71
+
| :---- | :---- | :---- | :---- |
72
+
| `grpc.publish_port` | The external port number that this node uses to publish itself to peers for gRPC transport. | `9400` | `-1` (disabled) |
73
+
| `grpc.host` | A list of addresses the gRPC server will bind to. | `["0.0.0.0"]` | `[]` |
74
+
| `grpc.bind_host` | A list of addresses to bind the gRPC server to. Can be distinct from publish hosts. | `["0.0.0.0", "::"]` | Value of `grpc.host` |
75
+
| `grpc.publish_host` | A list of hostnames or IPs published to peers for client connections. | `["thisnode.example.com"]` | Value of `grpc.host` |
76
+
| `grpc.netty.worker_count` | The number of Netty worker threads for the gRPC server. Controls concurrency and parallelism. | `2` | Number of processors |
77
+
| `grpc.netty.max_concurrent_connection_calls` | The maximum number of simultaneous in-flight requests allowed per client connection. | `200` | `100` |
78
+
| `grpc.netty.max_connection_age` | The maximum age a connection can reach before being gracefully closed. Supports time units like `ms`, `s`, or `m`. See [Time units]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | `500ms` | Not set (no limit) |
79
+
| `grpc.netty.max_connection_idle` | The maximum duration for which a connection can be idle before being closed. Supports time units like `ms`, `s`, or `m`. See [Time units]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | `2m` | Not set (no limit) |
80
+
| `grpc.netty.keepalive_timeout` | The amount of time to wait for `keepalive` ping acknowledgment before closing the connection. Supports [time units]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#time-units). | `1s` | Not set |
81
+
| `grpc.netty.max_msg_size` | The maximum inbound message size for gRPC requests. Supports units like `b`, `kb`, `mb`, or `gb`. See [Supported units]({{site.url}}{{site.baseurl}}/api-reference/units/). | `10mb` or `10485760` | `10mb` |
82
+
83
+
### Example configuration
84
+
85
+
The following is an example of a complete gRPC configuration in `opensearch.yml`:
86
+
87
+
```yaml
88
+
# Basic gRPC transport configuration
89
+
aux.transport.types: [transport-grpc]
90
+
aux.transport.transport-grpc.port: '9400-9500'
91
+
92
+
# Advanced gRPC settings
93
+
grpc.host: ["0.0.0.0"]
94
+
grpc.bind_host: ["0.0.0.0", "::"]
95
+
grpc.publish_host: ["thisnode.example.com"]
96
+
grpc.publish_port: 9400
97
+
grpc.netty.worker_count: 4
98
+
grpc.netty.max_concurrent_connection_calls: 200
99
+
grpc.netty.max_connection_age: 500ms
100
+
grpc.netty.max_connection_idle: 2m
101
+
grpc.netty.keepalive_timeout: 1s
102
+
grpc.netty.max_msg_size: 10mb
103
+
```
104
+
{% include copy.html %}
105
+
106
+
These settings are similar to the [HTTP Network settings]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/network-settings/#advanced-http-settings) but specifically apply to gRPC communication.
65
107
66
108
## Using gRPC APIs
67
109
68
110
To submit gRPC requests, you must have a set of protobufs on the client side. You can obtain the protobufs in the following ways:
69
111
70
-
- **Raw protobufs**: Download the raw protobuf schema from the [OpenSearch Protobufs GitHub repository (v0.3.0)](https://github.com/opensearch-project/opensearch-protobufs). You can then generate client-side code using the protocol buffer compilers for the [supported languages](https://grpc.io/docs/languages/).
71
-
- **Java client-side programs only**: Download the `opensearch-protobufs` jar from the [Maven Central repository](https://repo1.maven.org/maven2/org/opensearch/protobufs/0.3.0).
112
+
- **Raw protobufs**: Download the raw protobuf schema from the [OpenSearch Protobufs GitHub repository (v0.6.0)](https://github.com/opensearch-project/opensearch-protobufs/releases/tag/0.6.0). You can then generate client-side code using the protocol buffer compilers for the [supported languages](https://grpc.io/docs/languages/).
113
+
- **Java client-side programs only**: Download the `opensearch-protobufs` jar from the [Maven Central repository](https://repo1.maven.org/maven2/org/opensearch/protobufs/0.6.0).
72
114
73
115
## Supported APIs
74
116
75
-
This feature is currently under development and supports the following APIs:
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.
14
+
15
+
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.
16
+
17
+
For information about HTTP-based k-NN queries, see [k-NN query]({{site.url}}{{site.baseurl}}/query-dsl/specialized/k-nn/).
18
+
19
+
## Prerequisite
20
+
21
+
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]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/index/#using-grpc-apis).
22
+
23
+
## gRPC service and method
24
+
25
+
gRPC k-NN APIs reside in the [`SearchService`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/services/search_service.proto#L22), the same service used for general search operations.
26
+
27
+
You can submit k-NN search requests by invoking the [`Search`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/services/search_service.proto#L23) gRPC method within the `SearchService`, using a [`KnnQuery`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/common.proto#L1058) within the search request. The method takes a [`SearchRequest`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/search.proto#L18) and returns a [`SearchResponse`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/search.proto#L317).
28
+
29
+
The gRPC implementation uses the same underlying k-NN functionality as the HTTP API while providing improved performance through protocol buffer serialization.
30
+
31
+
## KnnQuery fields
32
+
33
+
The gRPC k-NN API uses the [`KnnQuery`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/common.proto#L1058) message within a [`QueryContainer`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/common.proto#L341) for k-NN searches. The `KnnQuery` message accepts the following fields.
34
+
35
+
| Field | Protobuf type | Description |
36
+
| :---- | :---- | :---- |
37
+
|`field`|`string`| The vector field against which to run the search query. Required. |
38
+
|`vector`|`repeated float`| A query vector. Must have the same number of dimensions as the vector field. Optional. |
39
+
|`k`|`int32`| The number of nearest neighbors to return as top hits. Optional. |
40
+
|`min_score`|`float`| The minimum similarity score required for a neighbor to be considered a hit. Optional. |
41
+
|`max_distance`|`float`| The maximum physical distance in vector space required for a neighbor to be considered a hit. Optional. |
42
+
|`filter`|[`QueryContainer`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/common.proto#L341)| Filters for the k-NN search query. See [Filter limitations](#filter-limitations). Optional. |
43
+
|`boost`|`float`| A boost value used to increase or decrease relevance scores. Default is 1.0. Optional. |
44
+
|`underscore_name`|`string`| A query name for query tagging (JSON key: `_name`). Optional. |
45
+
|`method_parameters`|[`ObjectMap`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/common.proto#L76)| Algorithm-specific parameters (for example, `ef_search` or `nprobes`). Optional. |
46
+
|`rescore`|[`KnnQueryRescore`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/common.proto#L1107)| A rescoring configuration for improved accuracy. Available in versions later than 2.17. Optional. |
47
+
|`expand_nested_docs`|`bool`| When `true`, retrieves scores for all nested field documents within each parent document. Used with nested queries. Optional. |
48
+
49
+
## Example request
50
+
51
+
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:
52
+
53
+
```json
54
+
{
55
+
"index": ["vector_index"],
56
+
"request_body": {
57
+
"query": {
58
+
"knn": {
59
+
"field": "my_vector",
60
+
"vector": [0.1, 0.2, 0.3, 0.4],
61
+
"k": 10
62
+
}
63
+
},
64
+
"size": 10
65
+
}
66
+
}
67
+
```
68
+
{% include copy.html %}
69
+
70
+
## Java gRPC client example
71
+
72
+
The following is a basic example of using the gRPC k-NN API (the actual implementation depends on your gRPC client setup):
k-NN search requests return the same [`SearchResponse`](https://github.com/opensearch-project/opensearch-protobufs/blob/0.6.0/protos/schemas/search.proto#L317) structure as regular search operations. For information about response fields, see [Search (gRPC) response fields]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/search/#response-fields).
121
+
122
+
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.
123
+
124
+
## Filter limitations
125
+
126
+
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]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/search/#querycontainer-fields) and [Supported queries]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/search/#supported-queries).
127
+
128
+
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.
129
+
130
+
131
+
132
+
## Related APIs
133
+
134
+
-[Search (gRPC)]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/search/) - General gRPC search functionality
135
+
-[Bulk (gRPC)]({{site.url}}{{site.baseurl}}/api-reference/grpc-apis/bulk/) - Bulk operations using gRPC
0 commit comments