OpenSearch Python Client

Warnings

• breaking Package name is 'opensearch-py' but import is 'from opensearchpy import OpenSearch' (no hyphen). pip install opensearch-py; import opensearchpy.
  Fix: pip install opensearch-py; from opensearchpy import OpenSearch
• gotcha opensearch-py and elasticsearch-py have near-identical APIs but are NOT interchangeable. Different packages, different auth patterns, different SSL defaults. Cannot swap imports.
  Fix: Use opensearch-py for OpenSearch/Amazon OpenSearch Service. Use elasticsearch for Elasticsearch.
• gotcha Amazon OpenSearch Service (AWS managed) requires AWS SigV4 auth — not basic_auth. Use opensearch-py with requests-aws4auth or boto3 credentials.
  Fix: from requests_aws4auth import AWS4Auth; client = OpenSearch(http_auth=AWS4Auth(...))
• gotcha OpenSearch 1.x deprecated May 2025. Amazon OpenSearch Service still supports 1.x and 2.x but new projects should target 2.x+.
  Fix: Target OpenSearch 2.x or 3.x for new projects.
• gotcha Unlike elasticsearch-py v8+, opensearch-py still uses the body= parameter pattern (elasticsearch v7 style). Don't apply elasticsearch v8 named-param migration to opensearch-py.
  Fix: client.search(index='my-index', body={'query': {...}}) — body= is correct for opensearch-py.

Install

• pip install opensearch-py Python (sync + async)

Imports

• OpenSearch

  from opensearchpy import OpenSearch
  
  client = OpenSearch(
      hosts=[{'host': 'localhost', 'port': 9200}],
      http_auth=('admin', 'admin'),
      use_ssl=True,
      verify_certs=False,  # dev only
      ssl_show_warn=False
  )
  
  # Index — same pattern as elasticsearch-py v7
  client.index(
      index='my-index',
      body={'name': 'Alice', 'age': 30},
      id='1'
  )
  
  # Search
  resp = client.search(
      index='my-index',
      body={'query': {'match': {'name': 'Alice'}}}
  )

  Import is 'from opensearchpy import OpenSearch' — not 'from elasticsearch import Elasticsearch'. Despite near-identical APIs, they are different packages with different auth and SSL handling.
• AsyncOpenSearch

  from opensearchpy import AsyncOpenSearch
  import asyncio
  
  async def main():
      client = AsyncOpenSearch(
          hosts=[{'host': 'localhost', 'port': 9200}],
          http_auth=('admin', 'admin'),
          use_ssl=False
      )
      resp = await client.search(
          index='my-index',
          body={'query': {'match_all': {}}}
      )
      await client.close()
  
  asyncio.run(main())

  AsyncOpenSearch is the async counterpart — same API as sync but all methods are coroutines. Must call await client.close() to prevent connection leaks.

Quickstart

Minimal opensearch-py connection and CRUD.

# pip install opensearch-py
from opensearchpy import OpenSearch

client = OpenSearch(
    hosts=[{'host': 'localhost', 'port': 9200}],
    http_auth=('admin', 'admin'),
    use_ssl=False
)

# Create index
client.indices.create(
    index='products',
    body={
        'mappings': {
            'properties': {
                'name': {'type': 'text'},
                'price': {'type': 'float'}
            }
        }
    }
)

# Index document
client.index(index='products', id='1', body={'name': 'Widget', 'price': 9.99})

# Search
resp = client.search(
    index='products',
    body={'query': {'match': {'name': 'Widget'}}}
)
for hit in resp['hits']['hits']:
    print(hit['_source'])