{"id":14790,"library":"opensearch-dsl","title":"OpenSearch DSL","description":"The `opensearch-dsl` library provides a high-level, declarative Python client for OpenSearch, enabling users to work with OpenSearch entities like documents and search queries as Python objects. It simplifies query construction and common OpenSearch operations, building on top of the lower-level `opensearch-py` client. The current version is 2.1.0. It has been announced that this library will be deprecated after version 2.1.0, with its functionality merged into `opensearch-py`.","status":"deprecated","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/opensearch-project/opensearch-dsl-py","tags":["opensearch","search","dsl","orm","client","deprecated"],"install":[{"cmd":"pip install opensearch-dsl","lang":"bash","label":"Install `opensearch-dsl`"}],"dependencies":[{"reason":"`opensearch-dsl` is built on top of `opensearch-py`, the low-level client.","package":"opensearch-py"},{"reason":"Minimum Python version requirement.","package":"Python >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"}],"imports":[{"symbol":"OpenSearch","correct":"from opensearchpy import OpenSearch"},{"symbol":"Search","correct":"from opensearch_dsl import Search"},{"symbol":"Document","correct":"from opensearch_dsl import Document"},{"symbol":"Text","correct":"from opensearch_dsl import Text"},{"symbol":"Keyword","correct":"from opensearch_dsl import Keyword"}],"quickstart":{"code":"import os\nfrom opensearchpy import OpenSearch\nfrom opensearch_dsl import Document, Text, Keyword, Search\n\n# Configuration from environment variables for security and flexibility\nOPENSEARCH_HOST = os.environ.get('OPENSEARCH_HOST', 'localhost')\nOPENSEARCH_PORT = int(os.environ.get('OPENSEARCH_PORT', 9200))\nOPENSEARCH_USER = os.environ.get('OPENSEARCH_USER', 'admin')\nOPENSEARCH_PASSWORD = os.environ.get('OPENSEARCH_PASSWORD', 'admin')\nOPENSEARCH_CA_CERTS = os.environ.get('OPENSEARCH_CA_CERTS', None) # e.g., '/full/path/to/root-ca.pem'\n\n# Create the OpenSearch client\nclient = OpenSearch(\n    hosts=[{'host': OPENSEARCH_HOST, 'port': OPENSEACH_PORT}],\n    http_compress=True, # enables gzip compression for request bodies\n    http_auth=(OPENSEARCH_USER, OPENSEARCH_PASSWORD),\n    use_ssl=True if OPENSEARCH_HOST != 'localhost' else False, # Use SSL for non-localhost\n    verify_certs=True,\n    ssl_assert_hostname=False, # Disable hostname verification for testing/local setups\n    ssl_show_warn=False,\n    ca_certs=OPENSEARCH_CA_CERTS\n)\n\nindex_name = 'my-dsl-index'\n\n# 1. Define a Document class\nclass MyDocument(Document):\n    title = Text(fields={'raw': Keyword()})\n    description = Text()\n    category = Keyword()\n\n    class Index:\n        name = index_name\n        settings = {\n            'number_of_shards': 1,\n            'number_of_replicas': 0\n        }\n\n# 2. Create the index (if it doesn't exist)\nif not client.indices.exists(index_name):\n    response = client.indices.create(index_name, body=MyDocument._index.to_dict())\n    print('Creating index:', response)\n\n# 3. Index a document\ndoc = MyDocument(meta={'id': '1'}, title='Python Basics', description='A guide to Python programming', category='programming')\ndoc.save(using=client)\nprint('Indexed document:', doc.to_dict())\n\n# 4. Refresh the index to make the document searchable\nclient.indices.refresh(index=index_name)\n\n# 5. Search for the document\ns = Search(using=client, index=index_name)\ns = s.filter('term', category='programming').query('match', title='python')\nresponse = s.execute()\n\nprint('\\nSearch results:')\nfor hit in response:\n    print(f\"Score: {hit.meta.score}, Title: {hit.title}, Category: {hit.category}\")\n\n# 6. Clean up: Delete the document and then the index (optional)\n# client.delete(index=index_name, id='1', refresh=True)\n# print('\\nDeleted document with id 1')\n# client.indices.delete(index=index_name)\n# print('Deleted index:', index_name)\n","lang":"python","description":"This quickstart demonstrates how to connect to an OpenSearch cluster, define a document schema using `opensearch-dsl.Document`, create an index, index a document, and perform a search query. It uses environment variables for OpenSearch connection details, which is recommended for production settings."},"warnings":[{"fix":"Migrate your code to use `opensearch-py` directly. The DSL-like capabilities are now available within `opensearch-py`.","message":"The `opensearch-dsl-py` library is being deprecated after version 2.1.0. All its functionality has been merged into the lower-level `opensearch-py` client. Users are strongly encouraged to migrate to `opensearch-py` directly.","severity":"deprecated","affected_versions":"2.1.0 and later"},{"fix":"Remove any explicit usage of `_type` in your document definitions and queries. Indexes are now categorized by document type implicitly, and mapping types are no longer supported by the OpenSearch server.","message":"OpenSearch 2.0 (and thus `opensearch-dsl` 2.0+) removed the `_type` mapping parameter. This means that documents no longer have an explicit `_type` field for mapping.","severity":"breaking","affected_versions":"2.0.0 and later"},{"fix":"Always align your `opensearch-dsl` (or `opensearch-py`) client version with your OpenSearch cluster version (e.g., `opensearch-dsl` 2.x with OpenSearch 2.x).","message":"Compatibility between `opensearch-dsl` and OpenSearch server versions is crucial. For OpenSearch 2.0 and later, only OpenSearch clients (like `opensearch-dsl` 2.x and `opensearch-py` 2.x) are fully compatible. Using older Elasticsearch clients or mixing client/server versions carries a high risk of errors.","severity":"gotcha","affected_versions":"2.0.0 and later"},{"fix":"This might require temporary `# type: ignore` comments for affected lines, or contributing to the `opensearch-py` project to improve its type hints.","message":"After migrating from `opensearch-dsl` to `opensearch-py` (which now includes DSL features), some users reported `mypy` type checking errors with ported resources like `Search` and `Response` objects due to incomplete type hints.","severity":"gotcha","affected_versions":"`opensearch-py` versions after `opensearch-dsl` merger (e.g., 2.2.0+)"},{"fix":"Refer to the archived `opensearch-dsl-py` documentation or GitHub samples for common DSL patterns, and consult `opensearch-py`'s general client documentation. This is an ongoing documentation issue.","message":"Post-deprecation, documentation for the DSL features within `opensearch-py` can be hard to find, leading to confusion for users transitioning from `opensearch-dsl-py`.","severity":"gotcha","affected_versions":"Current `opensearch-py` versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[],"ecosystem":"pypi"}