{"id":23070,"library":"django-opensearch-dsl","title":"django-opensearch-dsl","description":"Wrapper around opensearch-py for Django models, providing a high-level interface for indexing and searching Django models in OpenSearch. Current version is 0.8.0. Release cadence is irregular, with 10 releases since 2021.","status":"active","version":"0.8.0","language":"python","source_language":"en","source_url":"https://github.com/qcoumes/django-opensearch-dsl","tags":["django","opensearch","search","indexing"],"install":[{"cmd":"pip install django-opensearch-dsl","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for OpenSearch connection and document definition.","package":"opensearch-py","optional":false},{"reason":"Required for Django model integration.","package":"Django","optional":false},{"reason":"Optional for CelerySignalProcessor.","package":"celery","optional":true}],"imports":[{"note":"opensearch-dsl-py is deprecated; the correct package is django-opensearch-dsl.","wrong":"from opensearch_dsl import Document","symbol":"Document","correct":"from django_opensearch_dsl import Document"},{"note":"Field classes are part of django-opensearch-dsl, not opensearch-dsl-py.","wrong":"from opensearch_dsl import IntegerField","symbol":"IntegerField","correct":"from django_opensearch_dsl import IntegerField"},{"note":"Task classes for Celery integration.","wrong":"","symbol":"RegisteredTask","correct":"from django_opensearch_dsl.tasks import RegisteredTask"}],"quickstart":{"code":"import os\nfrom django_opensearch_dsl import Document\nfrom django_opensearch_dsl import fields\nfrom myapp.models import MyModel\n\nclass MyModelDocument(Document):\n    title = fields.TextField(attr='title')\n    class Index:\n        name = 'mymodel'\n\n# Register and create the index\nMyModelDocument().save()\n\n# Search\ndocuments = MyModelDocument.search().query('match', title='test')\nfor doc in documents:\n    print(doc.title)","lang":"python","description":"Define a Document class for a Django model, save it to create the index, and perform a search."},"warnings":[{"fix":"Update custom get_queryset/get_indexing_queryset methods to accept the optional alias parameter: def get_queryset(self, alias=None): ...","message":"In v0.8.0, Document.get_queryset() and Document.get_indexing_queryset() now take an optional 'alias' argument for database selection. Code that overrides these methods without the alias parameter will break.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"If you rely on default ordering, explicitly pass keep_order=False to restore previous behavior.","message":"In v0.5.0, keep_order argument of Search.to_queryset now defaults to True. This may change ordering behavior in existing code.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Change imports from opensearch_dsl to django_opensearch_dsl.","message":"The opensearch-dsl-py package is deprecated. Import from django-opensearch-dsl instead.","severity":"deprecated","affected_versions":"all"},{"fix":"In settings.py: OPENSEARCH_DSL_SIGNAL_PROCESSOR = 'django_opensearch_dsl.signals.CelerySignalProcessor'","message":"Signal processors (RealTimeSignalProcessor, CelerySignalProcessor) must be set via OPENSEARCH_DSL_SIGNAL_PROCESSOR setting, not by importing directly.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use from django_opensearch_dsl import ... instead of opensearch_dsl.","cause":"Installed django-opensearch-dsl but tried to import from opensearch_dsl.","error":"ModuleNotFoundError: No module named 'opensearch_dsl'"},{"fix":"Update the method signature to get_queryset(self, alias=None).","cause":"Custom Document subclass overrides get_queryset(self) without the alias parameter required since v0.8.0.","error":"TypeError: get_queryset() takes 1 positional argument but 2 were given"},{"fix":"Ensure you're calling save() on the Document class (e.g., MyModelDocument().save()) and upgrade to the latest version.","cause":"Using an older version where Document.save() was not a method; or trying to save an instance instead of the Document class.","error":"AttributeError: 'Document' object has no attribute 'save'"},{"fix":"Explicitly define a field in your Document class, e.g., myfield = fields.TextField()","cause":"The field type in your Django model is not automatically supported.","error":"django_opensearch_dsl.exceptions.ModelFieldNotMapped: The model field 'myapp.MyModel.myfield' cannot be mapped to a OpenSearch field"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}