Elasticsearch DSL (Python)

8.12.0 verified Fri May 01 auth: no python

Elasticsearch DSL is a high-level Python library for Elasticsearch 8.x that provides a fluent, object-oriented way to construct queries, aggregations, and manage documents. It wraps the low-level elasticsearch-py client. The current version is 8.12.0 with a release cadence of several minor versions per year. Note: Starting from v8.18.0, development has moved to the official elasticsearch-py repo; this package (elasticsearch8-dsl) is a community fork.

pip install elasticsearch8-dsl

Common errors

error ImportError: cannot import name 'Search' from 'elasticsearch_dsl' ↓

cause Package not installed or wrong package name used (e.g., elasticsearch-dsl vs elasticsearch8-dsl).

fix

Install the correct package by running: pip install elasticsearch8-dsl

error AttributeError: 'Response' object has no attribute 'hits' ↓

cause The execute() method returns a Response object, not a plain dict. Trying to access .hits directly is incorrect; use iteration or response.hits.total for count.

fix

Iterate over the response object: for hit in response: print(hit.title). Or use response.hits.total.value to get total hits count.

error TypeError: __init__() got an unexpected keyword argument 'http_auth' ↓

cause The low-level client expects authentication parameters in a different format for older versions or when using the Elasticsearch client 8.x with a different constructor.

fix

Use the correct client initialization: Elasticsearch(['http://localhost:9200'], basic_auth=('user', 'pass')) or pass via http_auth tuple as shown in the quickstart. For Elasticsearch 8.x, use basic_auth parameter.

Warnings

deprecated This package is a community fork; official Elasticsearch DSL development has moved to the elasticsearch-py repo starting v8.18.0. New features and fixes will not land here. Consider migrating to the official package. ↓

fix Install elasticsearch-dsl from the official repo: pip install elasticsearch-dsl, and update your import statements. See migration docs at https://www.elastic.co/docs/reference/elasticsearch/clients/python/dsl_migrating

gotcha The 'elasticsearch8-dsl' package is versioned separately from the official DSL. The version listed here (8.12.0) corresponds to the compatibility with Elasticsearch 8.x clients, but the official package may have different version numbers. ↓

fix Always check the compatible versions in the package metadata. Use 'pip show elasticsearch8-dsl' to verify.

gotcha When using the 'Terms' query with a dictionary value, ensure the dictionary is passed as a list of dictionaries, not as a single dict. A regression existed in 8.15.0 and was fixed in 8.15.4. ↓

fix Upgrade to elasticsearch8-dsl>=8.15.4.

Imports

Search
```
from elasticsearch_dsl import Search
```
Document
```
from elasticsearch_dsl import Document
```
Index
```
from elasticsearch_dsl import Index
```

Quickstart

Create an Elasticsearch client, build a search query using the DSL, execute it, and print results.

from elasticsearch import Elasticsearch
from elasticsearch_dsl import Search, Q

# Create an Elasticsearch client (set auth via env vars for security)
client = Elasticsearch(
    hosts=[os.environ.get('ELASTICSEARCH_HOST', 'http://localhost:9200')],
    http_auth=(os.environ.get('ELASTICSEARCH_USER', 'elastic'), os.environ.get('ELASTICSEARCH_PASSWORD', 'changeme'))
)

# Build a search request
search = Search(using=client, index='my-index').query('match', title='python')

# Execute and iterate over hits
response = search.execute()
for hit in response:
    print(hit.title, hit.meta.score)

# Or use the Q shortcut:
s = Search(using=client).query(Q('bool', must=[Q('match', title='python'), Q('range', price={'gte': 100})]))
print(s.count())