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-dslVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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.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.
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.
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.
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`.