{"id":23662,"library":"elasticsearch8-dsl","title":"Elasticsearch DSL (Python)","description":"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.","status":"active","version":"8.12.0","language":"python","source_language":"en","source_url":"https://github.com/elasticsearch/elasticsearch-dsl-py","tags":["elasticsearch","dsl","search","query-builder","python-client"],"install":[{"cmd":"pip install elasticsearch8-dsl","lang":"bash","label":"Install elasticsearch8-dsl"}],"dependencies":[{"reason":"The DSL depends on the low-level elasticsearch Python client for the specified version (8.x).","package":"elasticsearch8","optional":false}],"imports":[{"note":"","wrong":"","symbol":"Search","correct":"from elasticsearch_dsl import Search"},{"note":"","wrong":"","symbol":"Document","correct":"from elasticsearch_dsl import Document"},{"note":"","wrong":"","symbol":"Index","correct":"from elasticsearch_dsl import Index"}],"quickstart":{"code":"from elasticsearch import Elasticsearch\nfrom elasticsearch_dsl import Search, Q\n\n# Create an Elasticsearch client (set auth via env vars for security)\nclient = Elasticsearch(\n    hosts=[os.environ.get('ELASTICSEARCH_HOST', 'http://localhost:9200')],\n    http_auth=(os.environ.get('ELASTICSEARCH_USER', 'elastic'), os.environ.get('ELASTICSEARCH_PASSWORD', 'changeme'))\n)\n\n# Build a search request\nsearch = Search(using=client, index='my-index').query('match', title='python')\n\n# Execute and iterate over hits\nresponse = search.execute()\nfor hit in response:\n    print(hit.title, hit.meta.score)\n\n# Or use the Q shortcut:\ns = Search(using=client).query(Q('bool', must=[Q('match', title='python'), Q('range', price={'gte': 100})]))\nprint(s.count())","lang":"python","description":"Create an Elasticsearch client, build a search query using the DSL, execute it, and print results."},"warnings":[{"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","message":"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.","severity":"deprecated","affected_versions":"*"},{"fix":"Always check the compatible versions in the package metadata. Use 'pip show elasticsearch8-dsl' to verify.","message":"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.","severity":"gotcha","affected_versions":"8.x"},{"fix":"Upgrade to elasticsearch8-dsl>=8.15.4.","message":"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.","severity":"gotcha","affected_versions":"8.15.0 - 8.15.3"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install the correct package by running: pip install elasticsearch8-dsl","cause":"Package not installed or wrong package name used (e.g., elasticsearch-dsl vs elasticsearch8-dsl).","error":"ImportError: cannot import name 'Search' from 'elasticsearch_dsl'"},{"fix":"Iterate over the response object: for hit in response: print(hit.title). Or use response.hits.total.value to get total hits count.","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.","error":"AttributeError: 'Response' object has no attribute 'hits'"},{"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.","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.","error":"TypeError: __init__() got an unexpected keyword argument 'http_auth'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}