Registry / database / elasticsearch-dsl

elasticsearch-dsl

JSON →
library8.18.0pypypi✓ verified 23d ago

Elasticsearch DSL is a Python client that provides a high-level, declarative, and object-oriented way to write and execute queries against Elasticsearch. It allows users to define document mappings as Python classes and build complex search queries and aggregations using Python objects. As of version 8.18.0, the `elasticsearch-dsl` package's functionality has been integrated directly into the `elasticsearch-py` client library under the `elasticsearch.dsl` namespace. While the `elasticsearch-dsl` package still exists for compatibility, active development now continues within the main `elasticsearch-py` project. Releases are generally tied to Elasticsearch major/minor versions or feature additions.

pip install elasticsearch-dsl
INSTALL
IMPORT
SIG · ELASTICSEARCH-DSL
E
elasticsearch-dsl
databasepythonv8.18.0
Install
2.7s avg
Import
1190ms
Disk
57MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v8.18.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.910 runs
installs and imports cleanly · install 0.0s · import 1.224s · 83.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.7s · import 1.156s · 32MB
57MB installed
● package 57MB
Code
Verified usage

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

Search
from elasticsearch_dsl import Search
While functional in v8.18.0 via compatibility layer, future-proof approach is 'from elasticsearch.dsl import Search'
Document
from elasticsearch_dsl import Document
from elasticsearch_dsl import DocType
`DocType` was renamed to `Document` in v7.0.0. Using `DocType` is deprecated and will fail in v8.
connections
from elasticsearch_dsl import connections
Manages connections to Elasticsearch clusters.
Text, Keyword, Integer, Date
from elasticsearch_dsl import Text, Keyword, Integer, Date
Common field types for defining document mappings.

This quickstart demonstrates how to define an Elasticsearch document mapping using a Python class, establish a connection to Elasticsearch, index a few documents, and perform both simple and complex search queries using the DSL. It connects to a local Elasticsearch instance by default but can be configured for cloud or API key authentication.

import os from elasticsearch_dsl import Document, Text, Keyword, connections, Search # Configure connection to Elasticsearch # Replace with your Elasticsearch host and credentials if necessary ES_HOST = os.environ.get('ES_HOST', 'http://localhost:9200') # For cloud deployments or API key auth, uncomment and set these: # ES_CLOUD_ID = os.environ.get('ES_CLOUD_ID') # ES_API_KEY = os.environ.get('ES_API_KEY') # ES_USERNAME = os.environ.get('ES_USERNAME', 'elastic') # ES_PASSWORD = os.environ.get('ES_PASSWORD', 'changeme') connections.create_connection(hosts=[ES_HOST]) # Example for local or basic auth # For cloud/API key: connections.create_connection(cloud_id=ES_CLOUD_ID, api_key=ES_API_KEY) # Define a Document (schema for your data) class Article(Document): title = Text(fields={'keyword': Keyword()}) author = Text(fields={'keyword': Keyword()}) published_date = Keyword() word_count = Keyword() class Index: name = 'my-articles' settings = { 'number_of_shards': 1, 'number_of_replicas': 0 } # Create the index (if it doesn't exist) based on the Document definition Article.init() # Index some data article1 = Article(meta={'id': '1'}, title='Python for AI', author='John Doe', published_date='2023-01-01', word_count='2000') article1.save() article2 = Article(meta={'id': '2'}, title='Elasticsearch DSL Basics', author='Jane Smith', published_date='2023-03-15', word_count='1500') article2.save() # Refresh the index to make documents searchable immediately connections.get_connection().indices.refresh(index='my-articles') # Perform a search s = Search(index='my-articles').query("match", title="python") response = s.execute() print(f"Found {response.hits.total.value} results for 'python':") for hit in response: print(f"ID: {hit.meta.id}, Title: {hit.title}, Author: {hit.author}") # Example of a more complex search with filtering s = Search(index='my-articles') \ .query("match_all") \ .filter("range", word_count={"gte": 1500}) \ .exclude("match", author="john") response = s.execute() print(f"\nFound {response.hits.total.value} results for complex query:") for hit in response: print(f"ID: {hit.meta.id}, Title: {hit.title}, Author: {hit.author}") # Cleanup (optional) # connections.get_connection().indices.delete(index='my-articles', ignore=[400, 404])
Debug
Known issues
breakingAs of v8.18.0, the `elasticsearch-dsl` package has been integrated into `elasticsearch-py` as the `elasticsearch.dsl` namespace. While `pip install elasticsearch-dsl` still works and provides a compatibility layer (re-exporting `elasticsearch.dsl`), the recommended long-term approach for new projects or migrations is to `pip install elasticsearch` and use `from elasticsearch.dsl import ...` directly. The `elasticsearch-dsl` GitHub repository is now largely archived, with development continuing in the `elasticsearch-py` repository.
fix
For new projects, `pip install elasticsearch` and change imports from `from elasticsearch_dsl import ...` to `from elasticsearch.dsl import ...`. For existing projects using `elasticsearch-dsl`, upgrading to 8.18.0 may not require immediate import changes due to compatibility layers, but be aware of the underlying change and plan for future migration.
affects: >=8.18.0
breakingMigrating from `elasticsearch-dsl` 7.x to 8.x involves significant breaking changes. Key changes include the removal of `Document.create()` (replaced by `Document.save(op_type='create')`), changes in how `connections` are configured (`connections.create_connection()` is now preferred over `connections.configure()`), and updates to default serializers for `datetime` objects.
fix
Consult the official migration guide for 7.x to 8.x: `https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/client-dsl-migrating.html#_migrating_from_7_x_to_8_x`. Update `Document.create()` calls to `Document.save(op_type='create')` and adjust `connections.create_connection()` parameters.
affects: >=8.0.0
gotchaNot properly initializing the `connections` object before interacting with Elasticsearch will lead to `ConnectionError` or `ImproperlyConfigured` exceptions. The `connections` object must be configured with at least host information.
fix
Ensure `elasticsearch_dsl.connections.create_connection(hosts=['your_host'])` (or similar for cloud/auth) is called at application startup before any `Document` operations or `Search` queries are made.
affects: all
gotchaWhen defining document fields, using `Keyword()` without `Text()` for a field you intend to analyze (e.g., for full-text search) will prevent that field from being tokenized. Similarly, defining a `Text()` field without an explicit `Keyword()` sub-field makes it harder to perform exact match queries or aggregations on the raw string.
fix
For fields that require both full-text search and exact matching/aggregation, define them as `Text(fields={'keyword': Keyword()})`. The `Text` part allows analysis, and the `keyword` sub-field provides an unanalyzed version.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'elasticsearch_dsl'
As of `elasticsearch-dsl` version 8.18.0, its functionality has been integrated directly into the `elasticsearch-py` client library under the `elasticsearch.dsl` namespace, making the separate `elasticsearch_dsl` package redundant and leading to import errors if the old import path is used.
fix
Replace `elasticsearch_dsl` with `elasticsearch.dsl` in your import statements (e.g., `from elasticsearch.dsl import Search, Document`) and ensure you have the `elasticsearch` package version 8.18.0 or newer installed. You may also uninstall the standalone `elasticsearch-dsl` package.
RequestError(400, 'mapper_parsing_exception', 'Root mapping definition has unsupported parameters: [doc : {properties=...}]') or ValueError: Empty value passed for a required argument 'index'
Elasticsearch versions 7.x deprecated mapping types, and Elasticsearch 8.x removed them entirely. Using `doc_type` in `Document` classes or `Search` objects in a way that implies mapping types (like implicitly relying on a default `_doc` type when an explicit index name is required) will cause errors with newer Elasticsearch clusters.
fix
Remove explicit `doc_type` parameters from `Document` definitions and `Search` calls. Ensure your `Document` classes explicitly define the `Index` metadata, including `name` (e.g., `class Index: name = 'my_index'`), or specify the index explicitly when calling methods like `Document.init()` or `Search(index='my_index')`. For Elasticsearch 7.x/8.x, each index typically represents a single document type.
AttributeError: 'Elasticsearch' object has no attribute 'options'
This often occurs when there's a version mismatch between the `elasticsearch` (low-level client) and `elasticsearch-dsl` (or `elasticsearch.dsl`) packages, or when `elasticsearch` itself is an older version that does not have the expected attributes or methods for newer `elasticsearch-dsl` functionality.
fix
Upgrade both the `elasticsearch` and `elasticsearch-dsl` packages to compatible, recent versions. If you are using `elasticsearch-dsl` 8.18.0+, ensure your `elasticsearch` package is also 8.18.0 or newer. A `pip install --upgrade elasticsearch elasticsearch-dsl` (or just `pip install --upgrade elasticsearch` if you have migrated to `elasticsearch.dsl`) can often resolve this.
AttributeError: 'Hit' object has no attribute 'field_name' (e.g., 'AttributeError: 'Hit' object has no attribute 'title')
When iterating over search results, `elasticsearch-dsl` wraps raw hits in a `Hit` object (or your custom `Document` class if properly defined). This error occurs when attempting to access a field directly on a `Hit` object, but the field either doesn't exist in the document's `_source`, or the `Hit` object's structure has changed across `elasticsearch-dsl` versions, or the `Document` class mapping is not correctly applied to the `Hit`.
fix
Ensure your `Document` class is correctly defined with all expected fields and that the search is properly associated with it (e.g., `MyDocument.search()`). If not using a `Document` class, or for older versions/specific use cases, you might need to access fields via `hit.to_dict()['field_name']` or explicitly check if the field exists before accessing it. For `elasticsearch-dsl` versions 6 and later, if a `Document` class is not explicitly used, `Hit` objects behave more like `AttrDict` (dictionaries) and fields can often be accessed directly if present in `_source`.
Upgrade
Version history
8.18.0latest on PyPI · released Apr 16, 2025
Audit
Dependencies
elasticsearchrequiredProvides the underlying client connection and the actual DSL implementation in v8.18.0+
Agent activity
22 hits · last 30 days
node
20
OpenAI (training)
1
Resources
elasticsearch-dsl — pip install elasticsearch-dsl · libregistry