django-opensearch-dsl

0.8.0 verified Fri May 01 auth: no python

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.

pip install django-opensearch-dsl

Common errors

error ModuleNotFoundError: No module named 'opensearch_dsl' ↓

cause Installed django-opensearch-dsl but tried to import from opensearch_dsl.

fix

Use from django_opensearch_dsl import ... instead of opensearch_dsl.

error TypeError: get_queryset() takes 1 positional argument but 2 were given ↓

cause Custom Document subclass overrides get_queryset(self) without the alias parameter required since v0.8.0.

fix

Update the method signature to get_queryset(self, alias=None).

error AttributeError: 'Document' object has no attribute 'save' ↓

cause Using an older version where Document.save() was not a method; or trying to save an instance instead of the Document class.

fix

Ensure you're calling save() on the Document class (e.g., MyModelDocument().save()) and upgrade to the latest version.

error django_opensearch_dsl.exceptions.ModelFieldNotMapped: The model field 'myapp.MyModel.myfield' cannot be mapped to a OpenSearch field ↓

cause The field type in your Django model is not automatically supported.

fix

Explicitly define a field in your Document class, e.g., myfield = fields.TextField()

Warnings

breaking 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. ↓

fix Update custom get_queryset/get_indexing_queryset methods to accept the optional alias parameter: def get_queryset(self, alias=None): ...

breaking In v0.5.0, keep_order argument of Search.to_queryset now defaults to True. This may change ordering behavior in existing code. ↓

fix If you rely on default ordering, explicitly pass keep_order=False to restore previous behavior.

deprecated The opensearch-dsl-py package is deprecated. Import from django-opensearch-dsl instead. ↓

fix Change imports from opensearch_dsl to django_opensearch_dsl.

gotcha Signal processors (RealTimeSignalProcessor, CelerySignalProcessor) must be set via OPENSEARCH_DSL_SIGNAL_PROCESSOR setting, not by importing directly. ↓

fix In settings.py: OPENSEARCH_DSL_SIGNAL_PROCESSOR = 'django_opensearch_dsl.signals.CelerySignalProcessor'

Imports

Document
wrong
```
from opensearch_dsl import Document
```
correct
```
from django_opensearch_dsl import Document
```
opensearch-dsl-py is deprecated; the correct package is django-opensearch-dsl.
IntegerField
wrong
```
from opensearch_dsl import IntegerField
```
correct
```
from django_opensearch_dsl import IntegerField
```
Field classes are part of django-opensearch-dsl, not opensearch-dsl-py.

RegisteredTask

from django_opensearch_dsl.tasks import RegisteredTask

Task classes for Celery integration.

Quickstart

Define a Document class for a Django model, save it to create the index, and perform a search.

import os
from django_opensearch_dsl import Document
from django_opensearch_dsl import fields
from myapp.models import MyModel

class MyModelDocument(Document):
    title = fields.TextField(attr='title')
    class Index:
        name = 'mymodel'

# Register and create the index
MyModelDocument().save()

# Search
documents = MyModelDocument.search().query('match', title='test')
for doc in documents:
    print(doc.title)