Elasticsearch Python Client

Warnings

• breaking 'body' parameter removed in v8.0. es.search(body={...}) and es.index(body={...}) raise TypeError. The most common pattern in all pre-2022 tutorials and LLM-generated code.
  Fix: Replace body={'query': {...}} with query={...} directly as a keyword argument.
• breaking doc_type parameter removed in v8.0. Elasticsearch dropped mapping types — there is no more _doc or custom type. Raises TypeError.
  Fix: Remove doc_type entirely. es.index(index='my-index', document={...})
• breaking Client major version must match Elasticsearch server major version. v9 client against v8 server (or v8 client against v7 server) raises UnsupportedProductError.
  Fix: Pin client version to match server: pip install elasticsearch8 for ES 8.x server, elasticsearch for ES 9.x server.
• breaking Authentication changed in v8. Old: Elasticsearch(http_auth=('user', 'pass')). New: Elasticsearch(basic_auth=('user', 'pass')) or api_key='...'.
  Fix: Use basic_auth=('user', 'pass') or api_key='key' — not http_auth.
• gotcha Three packages on PyPI: elasticsearch (latest), elasticsearch8, elasticsearch7. 'pip install elasticsearch' always installs latest major. If your server is v8, 'pip install elasticsearch' will install v9 and break.
  Fix: Pin to server major: pip install 'elasticsearch>=8,<9' or pip install elasticsearch8
• gotcha Response is now ObjectApiResponse — dict-like but not a plain dict. Most code works but isinstance(resp, dict) is False.
  Fix: Access like a dict: resp['hits']['hits']. Or convert: dict(resp) for plain dict.
• gotcha Elastic Cloud connections use cloud_id + api_key — not a URL. Using a URL for Elastic Cloud works but is not recommended.
  Fix: es = Elasticsearch(cloud_id='...', api_key='...')

Install

• pip install elasticsearch Python (latest — v9.x)
• pip install elasticsearch8 Python (pinned to v8.x)
• pip install elasticsearch7 Python (pinned to v7.x — legacy)

Imports

• Elasticsearch index/search (v8+ style)

  from elasticsearch import Elasticsearch
  
  es = Elasticsearch(
      'https://localhost:9200',
      basic_auth=('user', 'password'),
      ca_certs='/path/to/ca.crt'
  )
  
  # Index — use 'document=' not 'body='
  es.index(
      index='my-index',
      id='1',
      document={'name': 'Alice', 'age': 30}
  )
  
  # Search — use 'query=' not 'body='
  resp = es.search(
      index='my-index',
      query={'match': {'name': 'Alice'}}
  )
  print(resp['hits']['hits'])

  'body' parameter removed in v8.0. Use named keyword arguments instead. doc_type removed — Elasticsearch dropped mapping types in v8. LLMs trained on pre-2022 docs generate body= and doc_type= patterns.
• AsyncElasticsearch

  from elasticsearch import AsyncElasticsearch
  import asyncio
  
  async def main():
      es = AsyncElasticsearch(
          'https://localhost:9200',
          basic_auth=('user', 'password')
      )
      resp = await es.search(
          index='my-index',
          query={'match_all': {}}
      )
      print(resp['hits']['hits'])
      await es.close()
  
  asyncio.run(main())

  Use AsyncElasticsearch for async/FastAPI contexts. Same API as sync but all methods are coroutines.

Quickstart

Elasticsearch v8/v9 Python client with named params (no body=).

# pip install elasticsearch
from elasticsearch import Elasticsearch

# Elastic Cloud
es = Elasticsearch(
    cloud_id='my-deployment:dXMtZ...',
    api_key='my-api-key'
)

# Self-hosted
es = Elasticsearch(
    'https://localhost:9200',
    basic_auth=('elastic', 'password'),
    verify_certs=False  # dev only
)

# Index a document — no body=, no doc_type
es.index(index='products', id='1', document={
    'name': 'Widget',
    'price': 9.99
})

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

es.close()