OpenSearch Protobufs Python Client
raw JSON → 1.3.0 verified Tue May 12 auth: no python install: verified quickstart: stale
The `opensearch-protobufs` library provides Protocol Buffer definitions and generated Python code for interacting with OpenSearch's gRPC APIs. It serves as a downstream consumer of the `opensearch-api-specification`, packaging pre-generated code to simplify client-server communication for various OpenSearch projects. The library is actively maintained with frequent releases, offering a high-performance alternative to traditional REST APIs through binary serialization and gRPC.
pip install opensearch-protobufs Common errors
error ImportError: cannot import name 'SearchRequest' from 'opensearch.protobufs' ↓
cause The user is attempting to import a Protocol Buffer message directly from the top-level `opensearch.protobufs` package, but message definitions like `SearchRequest` are located in the `opensearch.protobufs.schemas` submodule.
fix
Change the import statement to explicitly import the message from the
schemas submodule: from opensearch.protobufs.schemas import SearchRequest. error grpc.aio.AioRpcError: <AioRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE details = "failed to connect to all addresses"> ↓
cause The gRPC client failed to establish a connection with the OpenSearch gRPC server. This commonly indicates the OpenSearch instance is not running, the gRPC plugin (`transport-grpc`) is not enabled or configured, or there's a network issue (e.g., incorrect host/port, firewall).
fix
Ensure the OpenSearch instance is running and accessible. Verify that the
transport-grpc plugin is installed and enabled in your opensearch.yml configuration (e.g., aux.transport.types: [experimental-transport-grpc]). Confirm the gRPC client is configured with the correct host and port for the OpenSearch gRPC endpoint. error AttributeError: 'SearchServiceStub' object has no attribute 'non_existent_method' ↓
cause The user is attempting to call a gRPC method on an instance of `SearchServiceStub` that is either misspelled, does not exist in the OpenSearch Search Service Protocol Buffer definition, or is not available in the specific version of the `opensearch-protobufs` library being used.
fix
Consult the
opensearch-protobufs library documentation or the source .proto files to verify the correct gRPC method names (e.g., SearchServiceStub.Search). Ensure the method name matches exactly, including case. Warnings
breaking The gRPC Search API is currently experimental, and its protobuf structure is subject to changes in future OpenSearch versions. This means that API structures and generated code might change in backward-incompatible ways between minor or major releases, requiring client-side code updates. ↓
fix Always consult the `opensearch-protobufs` GitHub repository and OpenSearch documentation's gRPC section, especially the compatibility matrix (`COMPATIBILITY.md`), when upgrading OpenSearch or `opensearch-protobufs` versions. Pin your `opensearch-protobufs` version carefully.
gotcha When sending document data (e.g., for Bulk API operations), documents must be provided as Base64 encoded bytes within the gRPC request. Directly providing plain JSON strings or Python dictionaries will result in errors. ↓
fix Ensure all document content intended for fields like `doc` or `source` is first serialized (e.g., to JSON string), then encoded to bytes, and finally Base64 encoded before being assigned to the protobuf field. For example: `base64.b64encode(json.dumps({'field': 'value'}).encode('utf-8'))`.
gotcha This library (`opensearch-protobufs`) only provides the *generated Python code* from `.proto` files. To actually make gRPC calls, you must explicitly install and use the `grpcio` library. If you need to generate protobuf code yourself from `.proto` definitions, `grpcio-tools` is also required. ↓
fix Install `grpcio` alongside `opensearch-protobufs`: `pip install opensearch-protobufs grpcio`. If generating code, also install `grpcio-tools`: `pip install opensearch-protobufs grpcio grpcio-tools`.
gotcha Compatibility between `opensearch-protobufs` client versions and OpenSearch server versions is crucial. Using an incompatible client-server pair can lead to unexpected behavior or gRPC errors. ↓
fix Refer to the `COMPATIBILITY.md` file in the `opensearch-protobufs` GitHub repository to determine the correct client version for your OpenSearch cluster version. Upgrade both components in sync as recommended.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.59s 40.4M
3.10 alpine (musl) - - 0.63s 40.3M
3.10 slim (glibc) wheel 3.4s 0.05s 38M
3.10 slim (glibc) - - 0.04s 38M
3.11 alpine (musl) wheel - 1.01s 43.0M
3.11 alpine (musl) - - 1.04s 42.9M
3.11 slim (glibc) wheel 2.8s 0.08s 41M
3.11 slim (glibc) - - 0.07s 41M
3.12 alpine (musl) wheel - 0.81s 34.8M
3.12 alpine (musl) - - 0.83s 34.7M
3.12 slim (glibc) wheel 2.3s 0.08s 33M
3.12 slim (glibc) - - 0.07s 33M
3.13 alpine (musl) wheel - 0.69s 34.5M
3.13 alpine (musl) - - 0.76s 34.3M
3.13 slim (glibc) wheel 2.5s 0.07s 32M
3.13 slim (glibc) - - 0.13s 32M
3.9 alpine (musl) wheel - - 17.3M
3.9 alpine (musl) - - - -
3.9 slim (glibc) wheel 1.8s - 18M
3.9 slim (glibc) - - - -
Imports
- SearchRequest
from opensearch.protobufs.schemas import SearchRequest - BulkRequest
from opensearch.protobufs.schemas import BulkRequest - SearchServiceStub
from opensearch.protobufs.services import SearchServiceStub - DocumentServiceStub
from opensearch.protobufs.services import DocumentServiceStub
Quickstart stale last tested: 2026-04-24
import grpc
import os
import base64
from opensearch.protobufs.schemas import SearchRequest, Query, MatchQuery
from opensearch.protobufs.services import SearchServiceStub
# Configure your OpenSearch gRPC endpoint
# In a real application, you'd replace this with your actual OpenSearch gRPC host and port
OPENSEARCH_GRPC_TARGET = os.environ.get('OPENSEARCH_GRPC_TARGET', 'localhost:9200') # Example
def run_search_query():
try:
# Establish an insecure gRPC channel (use secure channels for production!)
with grpc.insecure_channel(OPENSEARCH_GRPC_TARGET) as channel:
stub = SearchServiceStub(channel)
# Create a simple match query
match_query = MatchQuery(field='title', query='OpenSearch')
query = Query(match=match_query)
# Create the search request
search_request = SearchRequest(
query=query,
size=5
)
print(f"Sending SearchRequest to {OPENSEARCH_GRPC_TARGET}:")
print(search_request)
# Make the gRPC call
response = stub.Search(search_request)
print("\nSearch Response:")
for hit in response.hits.hits:
# _source is returned as bytes, decode if it's JSON-like
source_data = hit.source.value.decode('utf-8') if hit.source.value else '{}'
print(f" ID: {hit.id}, Score: {hit.score}, Source: {source_data}")
except grpc.RpcError as e:
print(f"gRPC Error: {e.code()} - {e.details()}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
if __name__ == '__main__':
print("Note: This quickstart requires a running OpenSearch instance with gRPC enabled.")
print(f"Attempting to connect to gRPC target: {OPENSEARCH_GRPC_TARGET}\n")
run_search_query()