Registry / serialization / opensearch-protobufs

opensearch-protobufs

JSON →
library1.7.0pypypi✓ verified 24d ago

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
INSTALL
IMPORT
SIG · OPENSEARCH-PROTOBU
O
opensearch-protobufs
serializationpythonv1.7.0
Install
2.6s avg
Import
458ms
Disk
34MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.676s · 40.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.6s · import 0.056s · 39MB
34MB installed
● package 34MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SearchRequest
from opensearch.protobufs.schemas import SearchRequest
Commonly used for creating search requests to the OpenSearch gRPC API.
BulkRequest
from opensearch.protobufs.schemas import BulkRequest
Used for performing multiple document operations (index, update, delete) in a single gRPC call.
SearchServiceStub
from opensearch.protobufs.services import SearchServiceStub
The gRPC service stub for interacting with the OpenSearch Search API.
DocumentServiceStub
from opensearch.protobufs.services import DocumentServiceStub
The gRPC service stub for interacting with the OpenSearch Document (Bulk) API.

This quickstart demonstrates how to create a simple `SearchRequest` using the generated protobuf classes, establish an insecure gRPC channel, and send the request to an OpenSearch gRPC endpoint. It then processes the `SearchResponse`. Remember to configure your `OPENSEARCH_GRPC_TARGET` and use secure channels in production environments. An OpenSearch instance with gRPC transport enabled (e.g., in `opensearch.yml` with `aux.transport.types: [transport-grpc]`) is required for this code to function against a live service.

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()
Debug
Known issues
breakingThe 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.
affects: OpenSearch 3.2+
gotchaWhen 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'))`.
affects: All versions
gotchaThis 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`.
affects: All versions
gotchaCompatibility 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.
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name 'SearchRequest' from 'opensearch.protobufs'
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`.
grpc.aio.AioRpcError: <AioRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE details = "failed to connect to all addresses">
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.
AttributeError: 'SearchServiceStub' object has no attribute 'non_existent_method'
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.
Upgrade
Version history
1.7.0latest on PyPI · released Aug 14, 2026
Audit
Dependencies
grpciorequiredRequired for establishing gRPC client connections and making RPC calls using the generated protobufs. This is not a direct dependency of opensearch-protobufs itself, but essential for its functional usage.
grpcio-toolsoptionalNeeded if you intend to generate your own Python protobuf code from .proto files, rather than using the pre-generated code provided by this package.
Agent activity
7 hits · last 30 days
node
6
Resources