{"id":739,"library":"opensearch-protobufs","title":"OpenSearch Protobufs Python Client","description":"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.","status":"active","version":"1.3.0","language":"python","source_language":"en","source_url":"https://github.com/opensearch-project/opensearch-protobufs","tags":["opensearch","protobuf","grpc","client","api","search","documents"],"install":[{"cmd":"pip install opensearch-protobufs","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required 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.","package":"grpcio","optional":false},{"reason":"Needed if you intend to generate your own Python protobuf code from .proto files, rather than using the pre-generated code provided by this package.","package":"grpcio-tools","optional":true}],"imports":[{"note":"Commonly used for creating search requests to the OpenSearch gRPC API.","symbol":"SearchRequest","correct":"from opensearch.protobufs.schemas import SearchRequest"},{"note":"Used for performing multiple document operations (index, update, delete) in a single gRPC call.","symbol":"BulkRequest","correct":"from opensearch.protobufs.schemas import BulkRequest"},{"note":"The gRPC service stub for interacting with the OpenSearch Search API.","symbol":"SearchServiceStub","correct":"from opensearch.protobufs.services import SearchServiceStub"},{"note":"The gRPC service stub for interacting with the OpenSearch Document (Bulk) API.","symbol":"DocumentServiceStub","correct":"from opensearch.protobufs.services import DocumentServiceStub"}],"quickstart":{"code":"import grpc\nimport os\nimport base64\nfrom opensearch.protobufs.schemas import SearchRequest, Query, MatchQuery\nfrom opensearch.protobufs.services import SearchServiceStub\n\n# Configure your OpenSearch gRPC endpoint\n# In a real application, you'd replace this with your actual OpenSearch gRPC host and port\nOPENSEARCH_GRPC_TARGET = os.environ.get('OPENSEARCH_GRPC_TARGET', 'localhost:9200') # Example\n\ndef run_search_query():\n    try:\n        # Establish an insecure gRPC channel (use secure channels for production!)\n        with grpc.insecure_channel(OPENSEARCH_GRPC_TARGET) as channel:\n            stub = SearchServiceStub(channel)\n\n            # Create a simple match query\n            match_query = MatchQuery(field='title', query='OpenSearch')\n            query = Query(match=match_query)\n\n            # Create the search request\n            search_request = SearchRequest(\n                query=query,\n                size=5\n            )\n\n            print(f\"Sending SearchRequest to {OPENSEARCH_GRPC_TARGET}:\")\n            print(search_request)\n\n            # Make the gRPC call\n            response = stub.Search(search_request)\n\n            print(\"\\nSearch Response:\")\n            for hit in response.hits.hits:\n                # _source is returned as bytes, decode if it's JSON-like\n                source_data = hit.source.value.decode('utf-8') if hit.source.value else '{}'\n                print(f\"  ID: {hit.id}, Score: {hit.score}, Source: {source_data}\")\n\n    except grpc.RpcError as e:\n        print(f\"gRPC Error: {e.code()} - {e.details()}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    print(\"Note: This quickstart requires a running OpenSearch instance with gRPC enabled.\")\n    print(f\"Attempting to connect to gRPC target: {OPENSEARCH_GRPC_TARGET}\\n\")\n    run_search_query()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"OpenSearch 3.2+"},{"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'))`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:27:54.214Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Change the import statement to explicitly import the message from the `schemas` submodule: `from opensearch.protobufs.schemas import SearchRequest`.","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.","error":"ImportError: cannot import name 'SearchRequest' from 'opensearch.protobufs'"},{"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.","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).","error":"grpc.aio.AioRpcError: <AioRpcError of RPC that terminated with: status = StatusCode.UNAVAILABLE details = \"failed to connect to all addresses\">"},{"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.","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.","error":"AttributeError: 'SearchServiceStub' object has no attribute 'non_existent_method'"}],"ecosystem":"pypi","meta_description":null,"install_score":90,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.4.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.59,"mem_mb":9.4,"disk_size":"40.4M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.63,"mem_mb":8.6,"disk_size":"40.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":3.4,"import_time_s":0.05,"mem_mb":3.1,"disk_size":"38M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":3,"disk_size":"38M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":1.01,"mem_mb":9.4,"disk_size":"43.0M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.04,"mem_mb":8.7,"disk_size":"42.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.8,"import_time_s":0.08,"mem_mb":3.6,"disk_size":"41M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.2,"disk_size":"41M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.81,"mem_mb":9.2,"disk_size":"34.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.83,"mem_mb":8.4,"disk_size":"34.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.3,"import_time_s":0.08,"mem_mb":3.7,"disk_size":"33M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.1,"disk_size":"33M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.69,"mem_mb":9.4,"disk_size":"34.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.76,"mem_mb":8.5,"disk_size":"34.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2.5,"import_time_s":0.07,"mem_mb":3.4,"disk_size":"32M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":2.9,"disk_size":"32M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}