django-elasticsearch-dsl-drf¶
Integrate Elasticsearch DSL with Django REST framework in the shortest way possible, with least efforts possible.
Package provides views, serializers, filter backends, pagination and other handy add-ons.
You are expected to use django-elasticsearch-dsl for defining your Elasticsearch documents.
Prerequisites¶
- Django 1.8, 1.9, 1.10, 1.11 and 2.0.
- Python 2.7, 3.4, 3.5, 3.6
- Elasticsearch 2.x, 5.x
Documentation¶
Documentation is available on Read the Docs.
Main features and highlights¶
- Dynamic serializer for Documents.
- Search filter backend.
- Ordering filter backend.
- Filtering filter backend (big variety of
native- and functional- query lookups, such as
gt,gte,lt,lte,endswith,contains,wildcard,exists,exclude,isnull,range,in,prefix(same asstartswith),termandtermsis implemented. - Geo-spatial filtering filter backend (the
following filters implemented:
geo_distance,geo_polygonandgeo_bounding_box). - Geo-spatial ordering filter backend (the
following filters implemented:
geo_distance). - Faceted search filter backend.
- Highlight backend.
- Suggester filter backend.
- Pagination (Page number and limit/offset pagination).
- Ids filter backend.
Installation¶
Install latest stable version from PyPI:
pip install django-elasticsearch-dsl-drf
or latest stable version from GitHub:
pip install https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/archive/stable.tar.gz
or latest stable version from BitBucket:
pip install https://bitbucket.org/barseghyanartur/django-elasticsearch-dsl-drf/get/stable.tar.gz
Add
rest_framework,django_elasticsearch_dslanddjango_elasticsearch_dsl_drftoINSTALLED_APPS:INSTALLED_APPS = ( # ... # REST framework 'rest_framework', # Django Elasticsearch integration 'django_elasticsearch_dsl', # Django REST framework Elasticsearch integration (this package) 'django_elasticsearch_dsl_drf', # ... )
Quick start¶
Perhaps the easiest way to get acquainted with django-elasticsearch-dsl-drf
is to read the quick start tutorial.
See it as a guide of diving into integration of Elasticsearch with Django with very low knowledge entry level.
Testing¶
Project is covered with tests.
To test with all supported Python/Django versions type:
tox
To test against specific environment, type:
tox -e py36-django110
To test just your working environment type:
./runtests.py
To run a single test in your working environment type:
./runtests.py src/django_elasticsearch_dsl_drf/tests/test_filtering.py
Or:
./manage.py test django_elasticsearch_dsl_drf.tests.test_ordering
It’s assumed that you have all the requirements installed. If not, first install the test requirements:
pip install -r examples/requirements/test.txt
Writing documentation¶
Keep the following hierarchy.
=====
title
=====
header
======
sub-header
----------
sub-sub-header
~~~~~~~~~~~~~~
sub-sub-sub-header
^^^^^^^^^^^^^^^^^^
sub-sub-sub-sub-header
++++++++++++++++++++++
sub-sub-sub-sub-sub-header
**************************
Author¶
Artur Barseghyan <artur.barseghyan@gmail.com>
Project documentation¶
Contents:
Table of Contents
Quick start¶
The best way to get acquainted with django-elasticsearch-dsl-drf.
See it as a guide of diving into integration of Elasticsearch with Django with very low knowledge entry level.
Contents:
Table of Contents
Installation¶
Install latest stable version from PyPI:
pip install django-elasticsearch-dsl-drf
Add
rest_framework,django_elasticsearch_dslanddjango_elasticsearch_dsl_drftoINSTALLED_APPS:INSTALLED_APPS = ( # ... # REST framework 'rest_framework', # Django Elasticsearch integration 'django_elasticsearch_dsl', # Django REST framework Elasticsearch integration (this package) 'django_elasticsearch_dsl_drf', # ... )
Basic Django REST framework and
django-elasticsearch-dslconfiguration:REST_FRAMEWORK = { 'DEFAULT_AUTHENTICATION_CLASSES': ( 'rest_framework.authentication.BasicAuthentication', 'rest_framework.authentication.SessionAuthentication', ), 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination', 'PAGE_SIZE': 100, 'ORDERING_PARAM': 'ordering', } # Elasticsearch configuration ELASTICSEARCH_DSL = { 'default': { 'hosts': 'localhost:9200' }, }
Example app¶
To get started, let’s imagine we have a simple book register with a couple of models.
- Publisher model: The book publisher model. Each book might have only one
publisher (
ForeignKeyrelation). - Author model: The book author model. Each book might have unlimited number
of authors (
ManyToManyrelation). - Tag model: The tag model. Each book might have unlimited number of
tags (
ManyToManyrelation). - Book model: The book model.
To keep things separate, our Django models will reside in the books app.
Elasticsearch documents and Django REST framework views will be defined in a
search_indexes app. Both of the apps should be added to the
INSTALLED_APPS.
INSTALLED_APPS = (
# ...
'books', # Books application
'search_indexes', # Elasticsearch integration with the Django
# REST framework
# ...
)
Sample models¶
Content of the books/models.py file. Additionally, see the code comments.
Required imports¶
Imports required for model definition.
books/models/book.py
import json
from django.conf import settings
from django.db import models
from django.utils.translation import ugettext, ugettext_lazy as _
from six import python_2_unicode_compatible
Book statuses¶
books/models/book.py
# States indicate the publishing status of the book. Publishing might
# be in-progress, not yet published, published, rejected, etc.
BOOK_PUBLISHING_STATUS_PUBLISHED = 'published'
BOOK_PUBLISHING_STATUS_NOT_PUBLISHED = 'not_published'
BOOK_PUBLISHING_STATUS_IN_PROGRESS = 'in_progress'
BOOK_PUBLISHING_STATUS_CANCELLED = 'cancelled'
BOOK_PUBLISHING_STATUS_REJECTED = 'rejected'
BOOK_PUBLISHING_STATUS_CHOICES = (
(BOOK_PUBLISHING_STATUS_PUBLISHED, "Published"),
(BOOK_PUBLISHING_STATUS_NOT_PUBLISHED, "Not published"),
(BOOK_PUBLISHING_STATUS_IN_PROGRESS, "In progress"),
(BOOK_PUBLISHING_STATUS_CANCELLED, "Cancelled"),
(BOOK_PUBLISHING_STATUS_REJECTED, "Rejected"),
)
BOOK_PUBLISHING_STATUS_DEFAULT = BOOK_PUBLISHING_STATUS_PUBLISHED
Publisher model¶
books/models/book.py
@python_2_unicode_compatible
class Publisher(models.Model):
"""Publisher."""
name = models.CharField(max_length=30)
address = models.CharField(max_length=50)
city = models.CharField(max_length=60)
state_province = models.CharField(max_length=30)
country = models.CharField(max_length=50)
website = models.URLField()
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
@property
def location_field_indexing(self):
"""Location for indexing.
Used in Elasticsearch indexing/tests of `geo_distance` native filter.
"""
return {
'lat': self.latitude,
'lon': self.longitude,
}
Author model¶
books/models/author.py
@python_2_unicode_compatible
class Author(models.Model):
"""Author."""
salutation = models.CharField(max_length=10)
name = models.CharField(max_length=200)
email = models.EmailField()
headshot = models.ImageField(upload_to='authors', null=True, blank=True)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
Tag model¶
books/models/tag.py
class Tag(models.Model):
"""Simple tag model."""
title = models.CharField(max_length=255, unique=True)
class Meta(object):
"""Meta options."""
verbose_name = _("Tag")
verbose_name_plural = _("Tags")
def __str__(self):
return self.title
Book model¶
books/models/book.py
@python_2_unicode_compatible
class Book(models.Model):
"""Book."""
title = models.CharField(max_length=100)
description = models.TextField(null=True, blank=True)
summary = models.TextField(null=True, blank=True)
authors = models.ManyToManyField('books.Author', related_name='books')
publisher = models.ForeignKey(Publisher, related_name='books')
publication_date = models.DateField()
state = models.CharField(max_length=100,
choices=BOOK_PUBLISHING_STATUS_CHOICES,
default=BOOK_PUBLISHING_STATUS_DEFAULT)
isbn = models.CharField(max_length=100, unique=True)
price = models.DecimalField(max_digits=10, decimal_places=2)
pages = models.PositiveIntegerField(default=200)
stock_count = models.PositiveIntegerField(default=30)
tags = models.ManyToManyField('books.Tag',
related_name='books',
blank=True)
class Meta(object):
"""Meta options."""
ordering = ["isbn"]
def __str__(self):
return self.title
# The only publisher information we're going to need in our document
# is the publisher name. Since publisher isn't a required field,
# we define a properly on a model level to avoid indexing errors on
# non-existing relation.
@property
def publisher_indexing(self):
"""Publisher for indexing.
Used in Elasticsearch indexing.
"""
if self.publisher is not None:
return self.publisher.name
# As of tags, again, we only need a flat list of tag names, on which
# we can filter. Therefore, we define a properly on a model level,
# which will return a JSON dumped list of tags relevant to the
# current book model object.
@property
def tags_indexing(self):
"""Tags for indexing.
Used in Elasticsearch indexing.
"""
return [tag.title for tag in self.tags.all()]
Admin classes¶
This is just trivial. A couple of correspondent admin classes in order to ba able to fill some data.
books/admin.py
from django.contrib import admin
from .models import *
@admin.register(Book)
class BookAdmin(admin.ModelAdmin):
"""Book admin."""
list_display = ('title', 'isbn', 'price', 'publication_date')
search_fields = ('title',)
filter_horizontal = ('authors', 'tags',)
@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
"""Author admin."""
list_display = ('name', 'email',)
search_fields = ('name',)
@admin.register(Publisher)
class PublisherAdmin(admin.ModelAdmin):
"""Publisher admin."""
list_display = ('name',)
search_fields = ('name',)
@admin.register(Tag)
class TagAdmin(admin.ModelAdmin):
"""Tag admin."""
list_display = ('title',)
search_fields = ('title',)
Create database tables¶
For now, just run the migrations to create the database tables.
./manage.py makemigrations books
./manage.py migrate books
Fill in some data¶
If you have followed the instructions, you should now be able to log into the Django admin and create a dozen of Book/Author/Publisher/Tag records in admin.
http://localhost:8000/admin/books/publisher/
http://localhost:8000/admin/books/author/
http://localhost:8000/admin/books/tag/
http://localhost:8000/admin/books/book/
Once you’ve done that, proceed to the next step.
Sample document¶
In Elasticsearch, a document is a basic unit of information that can be indexed. For example, you can have a document for a single customer, another document for a single product, and yet another for a single order. This document is expressed in JSON (JavaScript Object Notation) which is an ubiquitous internet data interchange format.
Within an index/type, you can store as many documents as you want. Note that although a document physically resides in an index, a document actually must be indexed/assigned to a type inside an index.
Simply said, you could see an Elasticsearch index as a database and a document as a database table (which makes a Document definition in Elasticsearch DSL similar to a Django Model definition).
Often, complex SQL model structures are flatterned in Elasticsearch indexes/documents. Nested relations are denormalized.
In our example, all 4 models (Author, Publisher, Tag, Book)
would be flatterned into a single BookDocument, which would hold all
the required information.
Content of the search_indexes/documents/book.py file. Additionally, see
the code comments.
Required imports¶
search_indexes/documents/book.py
from django.conf import settings
from django_elasticsearch_dsl import DocType, Index, fields
from elasticsearch_dsl import analyzer
from books.models import Book
Index definition¶
To separate dev/test/staging/production indexes, the following approach is recommended.
settings/base.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.book': 'book',
'search_indexes.documents.publisher': 'publisher',
}
settings/testing.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.book': 'test_book',
'search_indexes.documents.publisher': 'test_publisher',
}
settings/production.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.book': 'prod_book',
'search_indexes.documents.publisher': 'prod_publisher',
}
search_indexes/documents/books.py
# Name of the Elasticsearch index
INDEX = Index(settings.ELASTICSEARCH_INDEX_NAMES[__name__])
# See Elasticsearch Indices API reference for available settings
INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
Custom analyzers¶
html_strip = analyzer(
'html_strip',
tokenizer="standard",
filter=["standard", "lowercase", "stop", "snowball"],
char_filter=["html_strip"]
)
Document definition¶
search_indexes/documents/book.py
@INDEX.doc_type
class BookDocument(DocType):
"""Book Elasticsearch document."""
id = fields.IntegerField(attr='id')
title = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
description = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
summary = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
publisher = fields.StringField(
attr='publisher_indexing',
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
publication_date = fields.DateField()
state = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
isbn = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
price = fields.FloatField()
pages = fields.IntegerField()
stock_count = fields.IntegerField()
tags = fields.StringField(
attr='tags_indexing',
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword', multi=True),
'suggest': fields.CompletionField(multi=True),
},
multi=True
)
class Meta(object):
"""Meta options."""
model = Book # The model associate with this DocType
Syncing Django’s database with Elasticsearch indexes¶
So far, we have a couple of Django models and a single (decentralized) Elasticsearch index/document (Book).
Full database sync¶
The excellent django-elasticsearch-dsl library makes a good job of keeping
the Book index fresh. It makes use of signals, so whenever the Book model
is changed, the correspondent BookDocument indexes would be updated.
To simply run the full sync between Django’s database and Elasticsearch, do as follows:
Create Elasticsearch indexes:
./manage.py search_index --create -f
Sync the data:
./manage.py search_index --populate -f
However, in case if a Tag, Publisher or Author models change, the Book index would not be automatically updated.
Sample partial sync (using custom signals)¶
In order to keep indexes fresh, you will have to write a couple of simple lines of code (using Django’s signals). Whenever a change is made to any of the Tag, Publisher or Author models, we’re going to update the correspondent BookDocument index.
search_indexes/signals.py
from django.db.models.signals import post_save, post_delete
from django.dispatch import receiver
from django_elasticsearch_dsl.registries import registry
Sample serializer¶
At this step we’re going to define a serializer to be used in the Django REST framework ViewSet.
Content of the search_indexes/serializers.py file. Additionally, see
the code comments.
Required imports¶
search_indexes/serializers/book.py
import json
from rest_framework import serializers
from django_elasticsearch_dsl_drf.serializers import DocumentSerializer
from .documents import BookDocument
Serializer definition¶
Simplest way to create a serializer, is to just specify which fields are needed to be serialized and leave it further to the dynamic serializer.
search_indexes/serializers/book.py
class BookDocumentSerializer(DocumentSerializer):
"""Serializer for the Book document."""
class Meta(object):
"""Meta options."""
# Specify the correspondent document class
document = BookDocument
# List the serializer fields. Note, that the order of the fields
# is preserved in the ViewSet.
fields = (
'id',
'title',
'description',
'summary',
'publisher',
'publication_date',
'state',
'isbn',
'price',
'pages',
'stock_count',
'tags',
)
However, if dynamic serializer doesn’t work for your or you want to customize
too many things, you are free to use standard Serializer class of the
Django REST framework.
search_indexes/serializers/book.py
class BookDocumentSerializer(serializers.Serializer):
"""Serializer for the Book document."""
id = serializers.IntegerField(read_only=True)
title = serializers.CharField(read_only=True)
description = serializers.CharField(read_only=True)
summary = serializers.CharField(read_only=True)
publisher = serializers.CharField(read_only=True)
publication_date = serializers.DateField(read_only=True)
state = serializers.CharField(read_only=True)
isbn = serializers.CharField(read_only=True)
price = serializers.FloatField(read_only=True)
pages = serializers.IntegerField(read_only=True)
stock_count = serializers.IntegerField(read_only=True)
tags = serializers.SerializerMethodField()
class Meta(object):
"""Meta options."""
# List the serializer fields. Note, that the order of the fields
# is preserved in the ViewSet.
fields = (
'id',
'title',
'description',
'summary',
'publisher',
'publication_date',
'state',
'isbn',
'price',
'pages',
'stock_count',
'tags',
)
def get_tags(self, obj):
"""Get tags."""
if obj.tags:
return list(obj.tags)
else:
return []
ViewSet definition¶
At this step, we’re going to define Django REST framework ViewSets.
Content of the search_indexes/viewsets.py file. Additionally, see
the code comments.
Required imports¶
search_indexes/viewsets/book.py
from django_elasticsearch_dsl_drf.constants import (
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_RANGE,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
LOOKUP_QUERY_EXCLUDE,
)
from django_elasticsearch_dsl_drf.filter_backends import (
FilteringFilterBackend,
IdsFilterBackend,
OrderingFilterBackend,
DefaultOrderingFilterBackend,
SearchFilterBackend,
)
from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
from .documents import BookDocument, PublisherDocument
from .serializers import BookDocumentSerializer
ViewSet definition¶
search_indexes/viewsets/book.py
class BookDocumentView(BaseDocumentViewSet):
"""The BookDocument view."""
document = BookDocument
serializer_class = BookDocumentSerializer
lookup_field = 'id'
filter_backends = [
FilteringFilterBackend,
IdsFilterBackend,
OrderingFilterBackend,
DefaultOrderingFilterBackend,
SearchFilterBackend,
]
# Define search fields
search_fields = (
'title',
'description',
'summary',
)
# Define filter fields
filter_fields = {
'id': {
'field': 'id',
# Note, that we limit the lookups of id field in this example,
# to `range`, `in`, `gt`, `gte`, `lt` and `lte` filters.
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
],
},
'title': 'title.raw',
'publisher': 'publisher.raw',
'publication_date': 'publication_date',
'state': 'state.raw',
'isbn': 'isbn.raw',
'price': {
'field': 'price.raw',
# Note, that we limit the lookups of `price` field in this
# example, to `range`, `gt`, `gte`, `lt` and `lte` filters.
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
],
},
'pages': {
'field': 'pages',
# Note, that we limit the lookups of `pages` field in this
# example, to `range`, `gt`, `gte`, `lt` and `lte` filters.
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
],
},
'stock_count': {
'field': 'stock_count',
# Note, that we limit the lookups of `stock_count` field in
# this example, to `range`, `gt`, `gte`, `lt` and `lte`
# filters.
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
],
},
'tags': {
'field': 'tags',
# Note, that we limit the lookups of `tags` field in
# this example, to `terms, `prefix`, `wildcard`, `in` and
# `exclude` filters.
'lookups': [
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
],
},
'tags.raw': {
'field': 'tags.raw',
# Note, that we limit the lookups of `tags.raw` field in
# this example, to `terms, `prefix`, `wildcard`, `in` and
# `exclude` filters.
'lookups': [
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
],
},
}
# Define ordering fields
ordering_fields = {
'id': 'id',
'title': 'title.raw',
'price': 'price.raw',
'state': 'state.raw',
'publication_date': 'publication_date',
}
# Specify default ordering
ordering = ('id', 'title', 'price',)
URLs¶
At this step, we’re going to define url patterns.
Content of the search_indexes/urls.py file. Additionally, see
the code comments.
Required imports¶
search_indexes/urls.py
from django.conf.urls import url, include
from rest_framework_extensions.routers import ExtendedDefaultRouter
from .views import BookDocumentView
Router definition¶
search_indexes/urls.py
router = ExtendedDefaultRouter()
books = router.register(r'books',
BookDocumentView,
base_name='bookdocument')
Check what you’ve done so far¶
At this point, you are one step away from a working example of integrating Elasticsearch DSL with Django.
URLs¶
If you didn’t add the urls of the search_indexes example application to
your project’s global url patterns, make sure to do it now.
from django.conf.urls import include, url
from search_indexes import urls as search_index_urls
urlpatterns = [
# ...
# Search URLs
url(r'^search/', include(search_index_urls)),
# ...
]
Test in browser¶
Open the following URL in your browser.
http://localhost:8000/search/books/
Perform a number of lookups:
http://localhost:8001/search/books/?ids=54|55|56
http://localhost:8001/search/books/?summary__contains=photography
http://localhost:8001/search/books/?tags__contains=ython
http://localhost:8001/search/books/?state=published
http://localhost:8001/search/books/?pages__gt=10&pages__lt=30
Development and debugging¶
Profiling tools¶
Looking for profiling tools for Elasticsearch?
Try django-elasticsearch-debug-toolbar package. It’s implemented as a panel for the well known Django Debug Toolbar and gives you full insights on what’s happening on the side of Elasticsearch.
Installation¶
pip install django-debug-toolbar
pip install django-elasticsearch-debug-toolbar
Configuration¶
Change your development settings in the following way:
settings/dev.py
MIDDLEWARE_CLASSES += (
'debug_toolbar.middleware.DebugToolbarMiddleware',
'debug_toolbar_force.middleware.ForceDebugToolbarMiddleware',
)
INSTALLED_APPS += (
'debug_toolbar',
'elastic_panel',
)
DEBUG_TOOLBAR_CONFIG = {
'INTERCEPT_REDIRECTS': False,
}
DEBUG_TOOLBAR_PANELS = (
# Defaults
'debug_toolbar.panels.versions.VersionsPanel',
'debug_toolbar.panels.timer.TimerPanel',
'debug_toolbar.panels.settings.SettingsPanel',
'debug_toolbar.panels.headers.HeadersPanel',
'debug_toolbar.panels.request.RequestPanel',
'debug_toolbar.panels.sql.SQLPanel',
'debug_toolbar.panels.staticfiles.StaticFilesPanel',
'debug_toolbar.panels.templates.TemplatesPanel',
'debug_toolbar.panels.cache.CachePanel',
'debug_toolbar.panels.signals.SignalsPanel',
'debug_toolbar.panels.logging.LoggingPanel',
'debug_toolbar.panels.redirects.RedirectsPanel',
# Additional
'elastic_panel.panel.ElasticDebugPanel',
)
Debugging¶
Although (the unbeatable) Kibana is strongly recommended for data analyses, there are other good tools worth mentioning. One of them is elasticsearch-head Elasticsearch 2.x plugin or a correspondent Chrome extension of the same plugin. You may find it very useful for quick data preview or testing Elasticsearch queries.
Filter usage examples¶
Example usage of filtering backends.
Contents:
Table of Contents
Search¶
Query param name reserved for search is search. Make sure your models and
documents do not have it as a field or attribute.
Multiple search terms are joined with OR.
Let’s assume we have a number of Book items with fields title,
description and summary.
Search in all fields¶
Search in all fields (name, address, city, state_province and
country) for word “reilly”.
http://127.0.0.1:8080/search/publisher/?search=reilly
Search a single term on specific field¶
In order to search in specific field (name) for term “reilly”, add
the field name separated with | to the search term.
http://127.0.0.1:8080/search/publisher/?search=name|reilly
Search for multiple terms¶
In order to search for multiple terms “reilly”, “bloomsbury” add
multiple search query params.
http://127.0.0.1:8080/search/publisher/?search=reilly&search=bloomsbury
Search for multiple terms in specific fields¶
In order to search for multiple terms “reilly”, “bloomsbury” in specific
fields add multiple search query params and field names separated with
| to each of the search terms.
http://127.0.0.1:8080/search/publisher/?search=name|reilly&search=city|london
Filtering¶
Supported lookups¶
Native¶
The following native (to Elasticsearch) filters/lookups are implemented:
Find documents which contain the exact term specified in the field specified.
http://127.0.0.1:8080/search/books/?tags__term=education&tags__term=economy
Find documents where the field specified contains values (dates, numbers, or strings) in the range specified.
Find documents where the field specified contains terms which begin with the exact prefix specified.
Functional¶
The following functional (non-native to Elasticsearch, but common in Django) filters/lookups are implemented:
Case-sensitive starts-with.
Basic usage examples¶
Basic Django REST framework integration example
See the example project for sample models/views/serializers.
Contents:
Table of Contents
Example app¶
Sample models¶
books/models/publisher.py
class Publisher(models.Model):
"""Publisher."""
name = models.CharField(max_length=30)
address = models.CharField(max_length=50)
city = models.CharField(max_length=60)
state_province = models.CharField(max_length=30)
country = models.CharField(max_length=50)
website = models.URLField()
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
@property
def location_field_indexing(self):
"""Location for indexing.
Used in Elasticsearch indexing/tests of `geo_distance` native filter.
"""
return {
'lat': self.latitude,
'lon': self.longitude,
}
Sample document¶
search_indexes/documents/publisher.py
from django_elasticsearch_dsl import DocType, Index, fields
from elasticsearch_dsl import analyzer
from books.models import Publisher
# Name of the Elasticsearch index
PUBLISHER_INDEX = Index('publisher')
# See Elasticsearch Indices API reference for available settings
PUBLISHER_INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
@PUBLISHER_INDEX.doc_type
class PublisherDocument(DocType):
"""Publisher Elasticsearch document."""
id = fields.IntegerField(attr='id')
name = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
info = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
address = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
city = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
state_province = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
country = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
website = fields.StringField()
# Location
location = fields.GeoPointField(attr='location_field_indexing')
class Meta(object):
"""Meta options."""
model = Publisher # The model associate with this DocType
Sample serializer¶
search_indexes/serializers/book.py
import json
from django_elasticsearch_dsl_drf.serializers import DocumentSerializer
class PublisherDocumentSerializer(DocumentSerializer):
"""Serializer for Publisher document."""
location = serializers.SerializerMethodField()
class Meta(object):
"""Meta options."""
# Note, that since we're using a dynamic serializer,
# we only have to declare fields that we want to be shown. If
# somehow, dynamic serializer doesn't work for you, either extend
# or declare your serializer explicitly.
fields = (
'id',
'name',
'info',
'address',
'city',
'state_province',
'country',
'website',
)
def get_location(self, obj):
"""Represent location value."""
try:
return obj.location.to_dict()
except:
return {}
Sample view¶
search_indexes/views/publisher.py
from django_elasticsearch_dsl_drf.constants import (
LOOKUP_FILTER_GEO_DISTANCE,
)
from django_elasticsearch_dsl_drf.filter_backends import (
FilteringFilterBackend,
OrderingFilterBackend,
SearchFilterBackend,
)
from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
# Example app models
from search_indexes.documents.publisher import PublisherDocument
from search_indxes.serializers import PublisherDocumentSerializer
class PublisherDocumentView(BaseDocumentViewSet):
"""The PublisherDocument view."""
document = PublisherDocument
serializer_class = PublisherDocumentSerializer
lookup_field = 'id'
filter_backends = [
FilteringFilterBackend,
OrderingFilterBackend,
DefaultOrderingFilterBackend,
SearchFilterBackend,
]
# Define search fields
search_fields = (
'name',
'info',
'address',
'city',
'state_province',
'country',
)
# Define filtering fields
filter_fields = {
'id': None,
'name': 'name.raw',
'city': 'city.raw',
'state_province': 'state_province.raw',
'country': 'country.raw',
}
# Define ordering fields
ordering_fields = {
'id': None,
'name': None,
'city': None,
'country': None,
}
# Specify default ordering
ordering = ('id', 'name',)
# Define geo-spatial filtering fields
geo_spatial_filter_fields = {
'location': {
'lookups': [
LOOKUP_FILTER_GEO_DISTANCE,
],
},
}
Usage example¶
Considering samples above, you should be able to perform the search, sorting and filtering actions described below.
Sample queries¶
Query param name reserved for search is search. Make sure your models and
documents do not have it as a field or attribute.
Multiple search terms are joined with OR.
Let’s assume we have a number of Book items with fields title,
description and summary.
Search in all fields
Search in all fields (name, address, city, state_province and
country) for word “reilly”.
http://127.0.0.1:8080/search/publisher/?search=reilly
Search a single term on specific field
In order to search in specific field (name) for term “reilly”, add
the field name separated with | to the search term.
http://127.0.0.1:8080/search/publisher/?search=name|reilly
Search for multiple terms
In order to search for multiple terms “reilly”, “bloomsbury” add
multiple search query params.
http://127.0.0.1:8080/search/publisher/?search=reilly&search=bloomsbury
Search for multiple terms in specific fields
In order to search for multiple terms “reilly”, “bloomsbury” in specific
fields add multiple search query params and field names separated with
| to each of the search terms.
http://127.0.0.1:8080/search/publisher/?search=name|reilly&search=city|london
Let’s assume we have a number of Publisher documents with in cities (Yerevan, Groningen, Amsterdam, London).
Multiple filter terms are joined with AND.
Filter documents by single field
Filter documents by field (city) “yerevan”.
http://127.0.0.1:8080/search/publisher/?city=yerevan
Filter documents by multiple fields
Filter documents by city “Yerevan” and “Groningen”.
http://127.0.0.1:8080/search/publisher/?city__in=yerevan|groningen
Filter document by a single field
Filter documents by (field country) “Armenia”.
http://127.0.0.1:8080/search/publisher/?country=armenia
Filter documents by multiple fields
Filter documents by multiple fields (field city) “Yerevan” and “Amsterdam”
with use of functional in query filter.
http://127.0.0.1:8080/search/publisher/?city__in=yerevan|amsterdam
You can achieve the same effect by specifying multiple filters (city)
“Yerevan” and “Amsterdam”. Note, that in this case multiple filter terms are
joined with OR.
http://127.0.0.1:8080/search/publisher/?city=yerevan&city=amsterdam
If you want the same as above, but joined with AND, add __term to each
lookup.
http://127.0.0.1:8080/search/publisher/?city__term=education&city__term=economy
Filter documents by a word part of a single field
Filter documents by a part word part in single field (city) “ondon”.
http://127.0.0.1:8080/search/publisher/?city__wildcard=*ondon
Geo-distance filtering
Filter documents by radius of 100000km from the given location.
http://127.0.0.1:8000/search/publishers/?location__geo_distance=100000km|12.04|-63.93
The - prefix means ordering should be descending.
Order documents by field (ascending)
Filter documents by field city (ascending).
http://127.0.0.1:8080/search/publisher/?search=country|armenia&ordering=city
Order documents by field (descending)
Filter documents by field country (descending).
http://127.0.0.1:8080/search/publisher/?ordering=-country
Order documents by multiple fields
If you want to order by multiple fields, use multiple ordering query params. In
the example below, documents would be ordered first by field country
(descending), then by field city (ascending).
http://127.0.0.1:8080/search/publisher/?ordering=-country&ordering=city
Advanced usage examples¶
Advanced Django REST framework integration examples.
See the example project for sample models/views/serializers.
Contents:
Table of Contents
Example app¶
Sample models¶
books/models/publisher.py
import json
from django.conf import settings
from django.db import models
from django.utils.translation import ugettext, ugettext_lazy as _
from six import python_2_unicode_compatible
BOOK_PUBLISHING_STATUS_PUBLISHED = 'published'
BOOK_PUBLISHING_STATUS_NOT_PUBLISHED = 'not_published'
BOOK_PUBLISHING_STATUS_IN_PROGRESS = 'in_progress'
BOOK_PUBLISHING_STATUS_CANCELLED = 'cancelled'
BOOK_PUBLISHING_STATUS_REJECTED = 'rejected'
BOOK_PUBLISHING_STATUS_CHOICES = (
(BOOK_PUBLISHING_STATUS_PUBLISHED, "Published"),
(BOOK_PUBLISHING_STATUS_NOT_PUBLISHED, "Not published"),
(BOOK_PUBLISHING_STATUS_IN_PROGRESS, "In progress"),
(BOOK_PUBLISHING_STATUS_CANCELLED, "Cancelled"),
(BOOK_PUBLISHING_STATUS_REJECTED, "Rejected"),
)
BOOK_PUBLISHING_STATUS_DEFAULT = BOOK_PUBLISHING_STATUS_PUBLISHED
@python_2_unicode_compatible
class Publisher(models.Model):
"""Publisher."""
name = models.CharField(max_length=30)
info = models.TextField(null=True, blank=True)
address = models.CharField(max_length=50)
city = models.CharField(max_length=60)
state_province = models.CharField(max_length=30)
country = models.CharField(max_length=50)
website = models.URLField()
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
@property
def location_field_indexing(self):
"""Location for indexing.
Used in Elasticsearch indexing/tests of `geo_distance` native filter.
"""
return {
'lat': self.latitude,
'lon': self.longitude,
}
books/models/author.py
@python_2_unicode_compatible
class Author(models.Model):
"""Author."""
salutation = models.CharField(max_length=10)
name = models.CharField(max_length=200)
email = models.EmailField()
headshot = models.ImageField(upload_to='authors', null=True, blank=True)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
books/models/tag.py
class Tag(models.Model):
"""Simple tag model."""
title = models.CharField(max_length=255, unique=True)
class Meta(object):
"""Meta options."""
verbose_name = _("Tag")
verbose_name_plural = _("Tags")
def __str__(self):
return self.title
books/models/book.py
@python_2_unicode_compatible
class Book(models.Model):
"""Book."""
title = models.CharField(max_length=100)
description = models.TextField(null=True, blank=True)
summary = models.TextField(null=True, blank=True)
authors = models.ManyToManyField('books.Author', related_name='books')
publisher = models.ForeignKey(Publisher, related_name='books')
publication_date = models.DateField()
state = models.CharField(max_length=100,
choices=BOOK_PUBLISHING_STATUS_CHOICES,
default=BOOK_PUBLISHING_STATUS_DEFAULT)
isbn = models.CharField(max_length=100, unique=True)
price = models.DecimalField(max_digits=10, decimal_places=2)
pages = models.PositiveIntegerField(default=200)
stock_count = models.PositiveIntegerField(default=30)
tags = models.ManyToManyField('books.Tag',
related_name='books',
blank=True)
class Meta(object):
"""Meta options."""
ordering = ["isbn"]
def __str__(self):
return self.title
@property
def publisher_indexing(self):
"""Publisher for indexing.
Used in Elasticsearch indexing.
"""
if self.publisher is not None:
return self.publisher.name
@property
def tags_indexing(self):
"""Tags for indexing.
Used in Elasticsearch indexing.
"""
return [tag.title for tag in self.tags.all()]
Sample document¶
Index definition¶
To separate dev/test/staging/production indexes, the following approach is recommended.
settings/base.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.book': 'book',
'search_indexes.documents.publisher': 'publisher',
}
settings/testing.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.book': 'test_book',
'search_indexes.documents.publisher': 'test_publisher',
}
settings/production.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.book': 'prod_book',
'search_indexes.documents.publisher': 'prod_publisher',
}
search_indexes/documents/book.py
from django.conf import settings
from django_elasticsearch_dsl import DocType, Index, fields
from elasticsearch_dsl import analyzer
from books.models import Book
# Name of the Elasticsearch index
INDEX = Index(settings.ELASTICSEARCH_INDEX_NAMES[__name__])
# See Elasticsearch Indices API reference for available settings
INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
html_strip = analyzer(
'html_strip',
tokenizer="standard",
filter=["standard", "lowercase", "stop", "snowball"],
char_filter=["html_strip"]
)
@INDEX.doc_type
class BookDocument(DocType):
"""Book Elasticsearch document."""
id = fields.IntegerField(attr='id')
title = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
description = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
summary = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
publisher = fields.StringField(
attr='publisher_indexing',
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
publication_date = fields.DateField()
state = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
isbn = fields.StringField(
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword'),
}
)
price = fields.FloatField()
pages = fields.IntegerField()
stock_count = fields.IntegerField()
tags = fields.StringField(
attr='tags_indexing',
analyzer=html_strip,
fields={
'raw': fields.StringField(analyzer='keyword', multi=True),
'suggest': fields.CompletionField(multi=True),
},
multi=True
)
class Meta(object):
"""Meta options."""
model = Book # The model associate with this DocType
Sample serializer¶
search_indexes/serializers/tag.py
import json
from rest_framework import serializers
class TagSerializer(serializers.Serializer):
"""Helper serializer for the Tag field of the Book document."""
title = serializers.CharField()
class Meta(object):
"""Meta options."""
fields = ('title',)
read_only_fields = ('title',)
search_indexes/serializers/book.py
class BookDocumentSerializer(serializers.Serializer):
"""Serializer for the Book document."""
id = serializers.SerializerMethodField()
title = serializers.CharField(read_only=True)
description = serializers.CharField(read_only=True)
summary = serializers.CharField(read_only=True)
publisher = serializers.CharField(read_only=True)
publication_date = serializers.DateField(read_only=True)
state = serializers.CharField(read_only=True)
isbn = serializers.CharField(read_only=True)
price = serializers.FloatField(read_only=True)
pages = serializers.IntegerField(read_only=True)
stock_count = serializers.IntegerField(read_only=True)
tags = serializers.SerializerMethodField()
class Meta(object):
"""Meta options."""
fields = (
'id',
'title',
'description',
'summary',
'publisher',
'publication_date',
'state',
'isbn',
'price',
'pages',
'stock_count',
'tags',
)
read_only_fields = fields
def get_tags(self, obj):
"""Get tags."""
if obj.tags:
return list(obj.tags)
else:
return []
Sample view¶
search_indexes/viewsets/book.py
from django_elasticsearch_dsl_drf.constants import (
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_RANGE,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
)
from django_elasticsearch_dsl_drf.filter_backends import (
FilteringFilterBackend,
OrderingFilterBackend,
DefaultOrderingFilterBackend,
SearchFilterBackend,
)
from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
# Example app models
from search_indexes.documents.book import BookDocument
from search_indxes.serializers import BookDocumentSerializer
class BookDocumentView(BaseDocumentViewSet):
"""The BookDocument view."""
document = BookDocument
serializer_class = BookDocumentSerializer
lookup_field = 'id'
filter_backends = [
FilteringFilterBackend,
OrderingFilterBackend,
DefaultOrderingFilterBackend,
SearchFilterBackend,
]
# Define search fields
search_fields = (
'title',
'description',
'summary',
)
# Define filtering fields
filter_fields = {
'id': {
'field': '_id',
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_IN,
],
},
'publisher': 'publisher.raw',
'publication_date': 'publication_date',
'isbn': 'isbn.raw',
'tags': {
'field': 'tags',
'lookups': [
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
],
},
'tags.raw': {
'field': 'tags.raw',
'lookups': [
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
],
},
}
# Define ordering fields
ordering_fields = {
'id': 'id',
'title': 'title.raw',
'price': 'price.raw',
'state': 'state.raw',
'publication_date': 'publication_date',
}
# Specify default ordering
ordering = ('id', 'title',)
Usage example¶
Considering samples above, you should be able to perform the search, sorting and filtering actions described below.
Search¶
Query param name reserved for search is search. Make sure your models and
documents do not have it as a field or attribute.
Multiple search terms are joined with OR.
Let’s assume we have a number of Book items with fields title,
description and summary.
Search in all fields
Search in all fields (title, description and summary) for word
“education”.
http://127.0.0.1:8080/search/books/?search=education
Search a single term on specific field
In order to search in specific field (title) for term “education”, add
the field name separated with | to the search term.
http://127.0.0.1:8080/search/books/?search=title|education
Search for multiple terms
In order to search for multiple terms “education”, “technology” add
multiple search query params.
http://127.0.0.1:8080/search/books/?search=education&search=technology
Search for multiple terms on specific fields
In order to search for multiple terms “education”, “technology” in specific
fields add multiple search query params and field names separated with
| to each of the search terms.
http://127.0.0.1:8080/search/books/?search=title|education&search=summary|technology
Filtering¶
Let’s assume we have a number of Book documents with the tags (education, politics, economy, biology, climate, environment, internet, technology).
Multiple filter terms are joined with AND.
Filter documents by field
Filter documents by field (state) “published”.
http://127.0.0.1:8080/search/books/?state=published
Filter documents by multiple fields
Filter documents by field (states) “published” and “in_progress”.
http://127.0.0.1:8080/search/books/?state__in=published|in_progress
Filter document by a single field
Filter documents by (field tag) “education”.
http://127.0.0.1:8080/search/books/?tag=education
Filter documents by multiple fields
Filter documents by multiple fields (field tags) “education” and “economy”
with use of functional in query filter.
http://127.0.0.1:8080/search/books/?tags__in=education|economy
You can achieve the same effect by specifying multiple fields (tags)
“education” and “economy”. Note, that in this case multiple filter terms are
joined with OR.
http://127.0.0.1:8080/search/books/?tags=education&tags=economy
If you want the same as above, but joined with AND, add __term to each
lookup.
http://127.0.0.1:8080/search/books/?tags__term=education&tags__term=economy
Filter documents by a word part of a single field
Filter documents by a part word part in single field (tags). Word part
should match both “technology” and “biology”.
http://127.0.0.1:8080/search/books/?tags__wildcard=*logy
Ordering¶
The - prefix means ordering should be descending.
Order documents by field (ascending)
Order documents by field price (ascending).
http://127.0.0.1:8080/search/books/?search=title|lorem&ordering=price
Order documents by field (descending)
Order documents by field price (descending).
http://127.0.0.1:8080/search/books/?search=title|lorem&ordering=-price
Order documents by multiple fields
If you want to order by multiple fields, use multiple ordering query params. In
the example below, documents would be ordered first by field
publication_date (descending), then by field price (ascending).
http://127.0.0.1:8080/search/books/?search=title|lorem&ordering=-publication_date&ordering=price
Ids filter¶
Filters documents that only have the provided ids.
http://127.0.0.1:8000/api/articles/?ids=68|64|58
Or, alternatively:
http://127.0.0.1:8000/api/articles/?ids=68&ids=64&ids=58
Faceted search¶
In order to add faceted search support, we would have to extend our view set in the following way:
search_indexes/viewsets/book.py
# ...
from django_elasticsearch_dsl_drf.filter_backends import (
# ...
FacetedSearchFilterBackend,
)
# ...
from elasticsearch_dsl import (
DateHistogramFacet,
RangeFacet,
TermsFacet,
)
# ...
class BookDocumentView(BaseDocumentViewSet):
"""The BookDocument view."""
# ...
filter_backends = [
# ...
FacetedSearchFilterBackend,
]
# ...
faceted_search_fields = {
'state': 'state.raw', # By default, TermsFacet is used
'publisher': {
'field': 'publisher.raw',
'facet': TermsFacet, # But we can define it explicitly
'enabled': True,
},
'publication_date': {
'field': 'publication_date',
'facet': DateHistogramFacet,
'options': {
'interval': 'year',
}
},
'pages_count': {
'field': 'pages',
'facet': RangeFacet,
'options': {
'ranges': [
("<10", (None, 10)),
("11-20", (11, 20)),
("20-50", (20, 50)),
(">50", (50, None)),
]
}
},
}
# ...
Note, that none of the facets is enabled by default, unless you explicitly specify it to be enabled. That means, that you will have to add a query string facet={facet_field_name} for each of the facets you want to see in results.
In the example below, we show results with faceted state and
pages_count facets.
http://127.0.0.1:8000/search/books/?facet=state&facet=pages_count
Geo-spatial features¶
For testing the boundaries the following online services might be helpful:
Filtering¶
Geo-distance filtering
Filter documents by radius of 100000km from the given location.
http://localhost:8000/search/publishers/?location__geo_distance=100000km|12.04|-63.93
Geo-polygon filtering
Filter documents that are located in the given polygon.
http://localhost:8000/search/publishers/?location__geo_polygon=40,-70|30,-80|20,-90
Geo-bounding-box filtering
Filter documents that are located in the given bounding box.
http://localhost:8000/search/publishers/?location__geo_bounding_box=44.87,40.07|43.87,41.11
Suggestions¶
The suggest feature suggests similar looking terms based on a provided text by using a suggester.
Note
The SuggesterFilterBackend filter backend can be used in the
suggest custom view action/route only. Usages outside of the are
suggest action/route are restricted.
There are three options available here: term, phrase and
completion.
Note
Suggestion functionality is exclusive. Once you have queried the
SuggesterFilterBackend, the latter will transform your current
search query into suggestion search query (which is very different).
Therefore, always add it as the very last filter backend.
Completion suggesters¶
To make use of suggestions, you should properly index relevant fields of your
documents using fields.CompletionField.
search_indexes/documents/publisher.py
from django.conf import settings
from django_elasticsearch_dsl import DocType, Index, fields
from books.models import Publisher
# Name of the Elasticsearch index
INDEX = Index(settings.ELASTICSEARCH_INDEX_NAMES[__name__])
# See Elasticsearch Indices API reference for available settings
INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
@INDEX.doc_type
class PublisherDocument(DocType):
"""Publisher Elasticsearch document."""
id = fields.IntegerField(attr='id')
name = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
'suggest': fields.CompletionField(),
}
)
info = fields.StringField()
address = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword')
}
)
city = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
'suggest': fields.CompletionField(),
}
)
state_province = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
'suggest': fields.CompletionField(),
}
)
country = fields.StringField(
fields={
'raw': fields.StringField(analyzer='keyword'),
'suggest': fields.CompletionField(),
}
)
website = fields.StringField()
# Location
location = fields.GeoPointField(attr='location_field_indexing')
class Meta(object):
"""Meta options."""
model = Publisher # The model associate with this DocType
After that the name.suggest, city.suggest, state_province.suggest
and country.suggest fields would be available for suggestions feature.
This is how publisher serializer would look like.
search_indexes/serializers/publisher.py
import json
from django_elasticsearch_dsl_drf.serializers import DocumentSerializer
class PublisherDocumentSerializer(DocumentSerializer):
"""Serializer for Publisher document."""
class Meta(object):
"""Meta options."""
# Note, that since we're using a dynamic serializer,
# we only have to declare fields that we want to be shown. If
# somehow, dynamic serializer doesn't work for you, either extend
# or declare your serializer explicitly.
fields = (
'id',
'name',
'info',
'address',
'city',
'state_province',
'country',
'website',
)
In order to add suggestions support, we would have to extend our view set in the following way:
search_indexes/viewsets/publisher.py
# ...
from django_elasticsearch_dsl_drf.constants import SUGGESTER_COMPLETION
from django_elasticsearch_dsl_drf.filter_backends import (
# ...
SuggesterFilterBackend,
)
# ...
class PublisherDocumentViewSet(BaseDocumentViewSet):
"""The PublisherDocument view."""
document = PublisherDocument
# ...
filter_backends = [
# ...
SuggesterFilterBackend,
]
# ...
# Suggester fields
suggester_fields = {
'name_suggest': {
'field': 'name.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
'city_suggest': {
'field': 'city.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
'state_province_suggest': {
'field': 'state_province.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
'country_suggest': {
'field': 'country.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
}
# Geo-spatial filtering fields
geo_spatial_filter_fields = {
'location': {
'lookups': [
LOOKUP_FILTER_GEO_DISTANCE,
],
},
}
In the example below, we show suggestion results (auto-completion) for
country field.
Once you have extended your view set with SuggesterFilterBackend
functionality, you can make use of the suggest custom action of your
view set.
Request
GET http://127.0.0.1:8000/search/publishers/suggest/?country_suggest__completion=Ar
Response
{
"_shards": {
"failed": 0,
"successful": 1,
"total": 1
},
"country_suggest__completion": [
{
"options": [
{
"score": 1.0,
"text": "Armenia"
},
{
"score": 1.0,
"text": "Argentina"
}
],
"offset": 0,
"length": 2,
"text": "Ar"
}
]
}
You can also have multiple suggesters per request.
Request
GET http://127.0.0.1:8000/search/publishers/suggest/?name_suggest__completion=B&country_suggest__completion=Ar
Response
{
"_shards": {
"successful": 1,
"total": 1,
"failed": 0
},
"country_suggest__completion": [
{
"text": "Ar",
"options": [
{
"score": 1.0,
"text": "Armenia"
},
{
"score": 1.0,
"text": "Argentina"
}
],
"offset": 0,
"length": 2
}
],
"name_suggest__completion": [
{
"text": "B",
"options": [
{
"score": 1.0,
"text": "Book Works"
},
{
"score": 1.0,
"text": "Brumleve LLC"
},
{
"score": 1.0,
"text": "Booktrope"
},
{
"score": 1.0,
"text": "Borman, Post and Wendt"
},
{
"score": 1.0,
"text": "Book League of America"
}
],
"offset": 0,
"length": 1
}
]
}
Suggestions on Array/List fields (typical use case - tags, where Tag model would be a many-to-many relation to a Book model) work almost the same.
Before checking the Sample requests/responses, do have in mind the following:
Book(see the Sample models)BookSerializer(see the Sample serializer)BookDocumentView(see the Sample view)
Once you have extended your view set with SuggesterFilterBackend
functionality, you can make use of the suggest custom action of your
view set.
Request
GET http://127.0.0.1:8000/search/books/suggest/?tag_suggest__completion=bio
Response
{
"_shards": {
"failed": 0,
"successful": 1,
"total": 1
},
"country_suggest__completion": [
{
"options": [
{
"score": 1.0,
"text": "Biography"
},
{
"score": 1.0,
"text": "Biology"
}
],
"offset": 0,
"length": 2,
"text": "bio"
}
]
}
Term and Phrase suggestions¶
While for the completion suggesters to work the CompletionField shall
be used, the term and phrase suggesters work on common text fields.
search_indexes/documents/book.py
from django.conf import settings
from django_elasticsearch_dsl import DocType, Index, fields
from books.models import Book
# Name of the Elasticsearch index
INDEX = Index(settings.ELASTICSEARCH_INDEX_NAMES[__name__])
# See Elasticsearch Indices API reference for available settings
INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
@INDEX.doc_type
class BookDocument(DocType):
"""Book Elasticsearch document."""
# ID
id = fields.IntegerField(attr='id')
title = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
)
description = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
}
)
summary = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField()
}
)
# Publisher
publisher = StringField(
attr='publisher_indexing',
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
)
# Publication date
publication_date = fields.DateField()
# State
state = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
}
)
# ISBN
isbn = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
}
)
# Price
price = fields.FloatField()
# Pages
pages = fields.IntegerField()
# Stock count
stock_count = fields.IntegerField()
# Tags
tags = StringField(
attr='tags_indexing',
analyzer=html_strip,
fields={
'raw': KeywordField(multi=True),
'suggest': fields.CompletionField(multi=True),
},
multi=True
)
null_field = fields.StringField(attr='null_field_indexing')
class Meta(object):
"""Meta options."""
model = Book # The model associate with this DocType
search_indexes/viewsets/book.py
from django_elasticsearch_dsl_drf.constants import (
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_RANGE,
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_EXCLUDE,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_ISNULL,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
SUGGESTER_PHRASE,
SUGGESTER_TERM,
)
from django_elasticsearch_dsl_drf.filter_backends import (
# ...
SuggesterFilterBackend,
)
class BookDocumentViewSet(BaseDocumentViewSet):
"""The BookDocument view."""
document = BookDocument
# serializer_class = BookDocumentSerializer
serializer_class = BookDocumentSimpleSerializer
lookup_field = 'id'
filter_backends = [
FilteringFilterBackend,
OrderingFilterBackend,
DefaultOrderingFilterBackend,
SearchFilterBackend,
SuggesterFilterBackend,
]
# Define search fields
search_fields = (
'title',
'description',
'summary',
)
# Define filter fields
filter_fields = {
'id': {
'field': 'id',
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
LOOKUP_FILTER_TERMS,
],
},
'title': 'title.raw',
'publisher': 'publisher.raw',
'publication_date': 'publication_date',
'state': 'state.raw',
'isbn': 'isbn.raw',
'price': {
'field': 'price.raw',
'lookups': [
LOOKUP_FILTER_RANGE,
],
},
'pages': {
'field': 'pages',
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
],
},
'stock_count': {
# 'field': 'stock_count',
'lookups': [
LOOKUP_FILTER_RANGE,
LOOKUP_QUERY_GT,
LOOKUP_QUERY_GTE,
LOOKUP_QUERY_LT,
LOOKUP_QUERY_LTE,
],
},
'tags': {
'field': 'tags',
'lookups': [
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
LOOKUP_QUERY_ISNULL,
],
},
'tags.raw': {
'field': 'tags.raw',
'lookups': [
LOOKUP_FILTER_TERMS,
LOOKUP_FILTER_PREFIX,
LOOKUP_FILTER_WILDCARD,
LOOKUP_QUERY_IN,
LOOKUP_QUERY_EXCLUDE,
],
},
# This has been added to test `exists` filter.
'non_existent_field': 'non_existent_field',
# This has been added to test `isnull` filter.
'null_field': 'null_field',
}
# Define ordering fields
ordering_fields = {
'id': 'id',
'title': 'title.raw',
'price': 'price.raw',
'state': 'state.raw',
'publication_date': 'publication_date',
}
# Specify default ordering
ordering = ('id', 'title', 'price',)
# Suggester fields
suggester_fields = {
'title_suggest': 'title.suggest',
'publisher_suggest': 'publisher.suggest',
'tag_suggest': 'tags.suggest',
'summary_suggest': 'summary',
}
Once you have extended your view set with SuggesterFilterBackend
functionality, you can make use of the suggest custom action of your
view set.
Let’s considering, that one of our books has the following text in the summary:
Twas brillig, and the slithy toves
Did gyre and gimble in the wabe.
All mimsy were the borogoves
And the mome raths outgrabe.
"Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!
Beware the Jubjub bird, and shun
The frumious Bandersnatch!"
He took his vorpal sword in his hand,
Long time the manxome foe he sought --
So rested he by the Tumtum tree,
And stood awhile in thought.
Request
GET http://127.0.0.1:8000/search/books/suggest/?summary_suggest__term=tovse
Response
{
"_shards": {
"failed": 0,
"total": 1,
"successful": 1
},
"summary_suggest__term": [
{
"text": "tovs",
"offset": 0,
"options": [
{
"text": "tove",
"score": 0.75,
"freq": 1
},
{
"text": "took",
"score": 0.5,
"freq": 1
},
{
"text": "twas",
"score": 0.5,
"freq": 1
}
],
"length": 5
}
]
}
Request
GET http://127.0.0.1:8000/search/books/suggest/?summary_suggest__phrase=slith%20tovs
Response
{
"summary_suggest__phrase": [
{
"text": "slith tovs",
"offset": 0,
"options": [
{
"text": "slithi tov",
"score": 0.00083028956
}
],
"length": 10
}
],
"_shards": {
"failed": 0,
"total": 1,
"successful": 1
}
}
Highlighting¶
Highlighters enable you to get highlighted snippets from one or more fields in your search results so you can show users where the query matches are.
ViewSet definition
from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
from django_elasticsearch_dsl_drf.filter_backends import (
# ...
HighlightBackend,
)
from ..documents import BookDocument
from ..serializers import BookDocumentSimpleSerializer
class BookDocumentViewSet(BaseDocumentViewSet):
"""The BookDocument view."""
document = BookDocument
# serializer_class = BookDocumentSerializer
serializer_class = BookDocumentSimpleSerializer
lookup_field = 'id'
filter_backends = [
# ...
HighlightBackend,
]
# ...
# Define highlight fields
highlight_fields = {
'title': {
'enabled': True,
'options': {
'pre_tags': ["<b>"],
'post_tags': ["</b>"],
}
},
'summary': {
'options': {
'fragment_size': 50,
'number_of_fragments': 3
}
},
'description': {},
}
# ...
Request
GET http://127.0.0.1:8000/search/books/?search=optimisation&highlight=title&highlight=summary
Response
{
"count": 1,
"next": null,
"previous": null,
"facets": {
"_filter_publisher": {
"publisher": {
"buckets": [
{
"key": "Self published",
"doc_count": 1
}
],
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0
},
"doc_count": 1
}
},
"results": [
{
"id": 999999,
"title": "Performance optimisation",
"description": null,
"summary": "Ad animi adipisci libero facilis iure totam
impedit. Facilis maiores quae qui magnam dolores.
Veritatis quia amet porro voluptates iure quod
impedit. Dolor voluptatibus maiores at libero
magnam.",
"authors": [
"Artur Barseghyan"
],
"publisher": "Self published",
"publication_date": "1981-04-29",
"state": "cancelled",
"isbn": "978-1-7372176-0-2",
"price": 40.51,
"pages": 162,
"stock_count": 30,
"tags": [
"Guide",
"Poetry",
"Fantasy"
],
"highlight": {
"title": [
"Performance <b>optimisation</b>"
]
},
"null_field": null
}
]
}
Pagination¶
Page number pagination¶
By default, the PageNumberPagination class is used on all view sets
which inherit from BaseDocumentViewSet.
Example:
http://127.0.0.1:8000/search/books/?page=4
http://127.0.0.1:8000/search/books/?page=4&page_size=100
Limit/offset pagination¶
In order to use a different pagination_class, for instance the
LimitOffsetPagination, specify it explicitly in the view.
search_indexes/viewsets/book.py
# ...
from django_elasticsearch_dsl_drf.pagination import LimitOffsetPagination
# ...
class BookDocumentView(BaseDocumentViewSet):
"""The BookDocument view."""
# ...
pagination_class = LimitOffsetPagination
# ...
Example:
http://127.0.0.1:8000/search/books/?limit=100
http://127.0.0.1:8000/search/books/?offset=400&limit=100
Customisations¶
If you want to add additional data to the paginated response, for instance,
the page size, subclass the correspondent pagination class and add your
modifications in the get_paginated_response_context method as follows:
from django_elasticsearch_dsl_drf.pagination import PageNumberPagination
class CustomPageNumberPagination(PageNumberPagination):
"""Custom page number pagination."""
def get_paginated_response_context(self, data):
__data = super(
CustomPageNumberPagination,
self
).get_paginated_response_context(data)
__data.append(
('current_page', int(self.request.query_params.get('page', 1)))
)
__data.append(
('page_size', self.get_page_size(self.request))
)
return sorted(__data)
Same applies to the customisations of the LimitOffsetPagination.
Nested fields usage examples¶
Advanced Django REST framework integration examples with object/nested fields.
See the example project for sample models/views/serializers.
Contents:
Table of Contents
Example app¶
Sample models¶
books/models/country.py
from django.db import models
from six import python_2_unicode_compatible
@python_2_unicode_compatible
class Country(models.Model):
"""Country."""
name = models.CharField(max_length=255)
info = models.TextField(null=True, blank=True)
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
@property
def location_field_indexing(self):
"""Location for indexing.
Used in Elasticsearch indexing/tests of `geo_distance` native
filter.
"""
return {
'lat': self.latitude,
'lon': self.longitude,
}
books/models/city.py
@python_2_unicode_compatible
class City(models.Model):
"""City."""
name = models.CharField(max_length=255)
info = models.TextField(null=True, blank=True)
country = models.ForeignKey('books.Country')
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return self.name
@property
def location_field_indexing(self):
"""Location for indexing.
Used in Elasticsearch indexing/tests of `geo_distance` native filter.
"""
return {
'lat': self.latitude,
'lon': self.longitude,
}
books/models/address.py
@python_2_unicode_compatible
class Address(models.Model):
"""Address."""
street = models.CharField(max_length=255)
house_number = models.CharField(max_length=60)
appendix = models.CharField(max_length=30, null=True, blank=True)
zip_code = models.CharField(max_length=60)
city = models.ForeignKey('books.City')
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
class Meta(object):
"""Meta options."""
ordering = ["id"]
def __str__(self):
return "{} {} {} {}".format(
self.street,
self.house_number,
self.appendix,
self.zip_code
)
@property
def location_field_indexing(self):
"""Location for indexing.
Used in Elasticsearch indexing/tests of `geo_distance` native filter.
"""
return {
'lat': self.latitude,
'lon': self.longitude,
}
Sample document¶
Index definition¶
To separate dev/test/staging/production indexes, the following approach is recommended.
settings/base.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.address': 'address',
}
settings/testing.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.address': 'test_address',
}
settings/production.py
# Name of the Elasticsearch index
ELASTICSEARCH_INDEX_NAMES = {
'search_indexes.documents.address': 'prod_address',
}
search_indexes/documents/address.py
from django.conf import settings
from django_elasticsearch_dsl import DocType, Index, fields
from django_elasticsearch_dsl_drf.compat import KeywordField, StringField
from books.models import Address
from .analyzers import html_strip
INDEX = Index(settings.ELASTICSEARCH_INDEX_NAMES[__name__])
# See Elasticsearch Indices API reference for available settings
INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
@INDEX.doc_type
class AddressDocument(DocType):
"""Address Elasticsearch document."""
# ID
id = fields.IntegerField(attr='id')
# ********************************************************************
# *********************** Main data fields for search ****************
# ********************************************************************
street = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
)
house_number = StringField(analyzer=html_strip)
appendix = StringField(analyzer=html_strip)
zip_code = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
)
# ********************************************************************
# ********** Additional fields for search and filtering **************
# ********************************************************************
# City object
city = fields.ObjectField(
properties={
'name': StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
),
'info': StringField(analyzer=html_strip),
'location': fields.GeoPointField(attr='location_field_indexing'),
'country': fields.ObjectField(
properties={
'name': StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
),
'info': StringField(analyzer=html_strip),
'location': fields.GeoPointField(
attr='location_field_indexing'
)
}
)
}
)
location = fields.GeoPointField(attr='location_field_indexing')
class Meta(object):
"""Meta options."""
model = Address # The model associate with this DocType
Sample serializer¶
search_indexes/serializers/address.py
from django_elasticsearch_dsl_drf.serializers import DocumentSerializer
from ..documents import AddressDocument
class AddressDocumentSerializer(DocumentSerializer):
"""Serializer for address document."""
class Meta(object):
"""Meta options."""
document = AddressDocument
fields = (
'id',
'name',
'info',
'city',
'location',
)
Sample view¶
search_indexes/viewsets/address.py
from django_elasticsearch_dsl_drf.constants import (
LOOKUP_FILTER_GEO_DISTANCE,
LOOKUP_FILTER_GEO_POLYGON,
LOOKUP_FILTER_GEO_BOUNDING_BOX,
# SUGGESTER_TERM,
# SUGGESTER_PHRASE,
SUGGESTER_COMPLETION,
)
from django_elasticsearch_dsl_drf.filter_backends import (
FilteringFilterBackend,
DefaultOrderingFilterBackend,
OrderingFilterBackend,
SearchFilterBackend,
SuggesterFilterBackend,
GeoSpatialFilteringFilterBackend,
GeoSpatialOrderingFilterBackend,
)
from django_elasticsearch_dsl_drf.pagination import LimitOffsetPagination
from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
from ..documents import AddressDocument
from ..serializers import AddressDocumentSerializer
class AddressDocumentViewSet(BaseDocumentViewSet):
"""The AddressDocument view."""
document = AddressDocument
serializer_class = AddressDocumentSerializer
lookup_field = 'id'
filter_backends = [
FilteringFilterBackend,
OrderingFilterBackend,
SearchFilterBackend,
GeoSpatialFilteringFilterBackend,
GeoSpatialOrderingFilterBackend,
DefaultOrderingFilterBackend,
SuggesterFilterBackend,
]
pagination_class = LimitOffsetPagination
# Define search fields
search_fields = (
'street',
'zip_code',
'city.name',
'city.country.name',
)
# Define filtering fields
filter_fields = {
'id': None,
'city': 'city.name.raw',
'country': 'city.country.name.raw',
}
# Define geo-spatial filtering fields
geo_spatial_filter_fields = {
'location': {
'lookups': [
LOOKUP_FILTER_GEO_BOUNDING_BOX,
LOOKUP_FILTER_GEO_DISTANCE,
LOOKUP_FILTER_GEO_POLYGON,
],
},
}
# Define ordering fields
ordering_fields = {
'id': None,
'street': None,
'city': 'city.name.raw',
'country': 'city.country.name.raw',
'zip_code': None,
}
# Define ordering fields
geo_spatial_ordering_fields = {
'location': None,
}
# Specify default ordering
ordering = (
'id',
'street.raw',
'city.name.raw',
)
# Suggester fields
suggester_fields = {
'street_suggest': {
'field': 'street.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
'city_suggest': {
'field': 'city.name.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
'country_suggest': {
'field': 'city.country.name.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
}
}
Usage example¶
Considering samples above, you should be able to perform the search, sorting and filtering actions described below.
Sample queries¶
Just a couple of examples, because searching in nested fields doesn’t differ from searching in simple fields.
Search in all fields
Search in all fields (street, zip_code and city, country) for
word “Picadilly”.
http://127.0.0.1:8000/search/addresses/?search=Piccadilly
Search a single term on specific field
In order to search in specific field (country) for term “Armenia”, add
the field name separated with | to the search term.
http://127.0.0.1:8000/search/addresses/?search=city.country.name|Armenia
For nested search, let’s have another example.
books/models/city.py
from django.db import models
from six import python_2_unicode_compatible
@python_2_unicode_compatible
class City(models.Model):
"""City."""
name = models.CharField(max_length=255)
info = models.TextField(null=True, blank=True)
country = models.ForeignKey('books.Country')
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
books/models/country.py
from django.db import models
from six import python_2_unicode_compatible
@python_2_unicode_compatible
class Country(models.Model):
"""Country."""
name = models.CharField(max_length=255)
info = models.TextField(null=True, blank=True)
latitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
longitude = models.DecimalField(null=True,
blank=True,
decimal_places=15,
max_digits=19,
default=0)
documents/city.py
from django.conf import settings
from django_elasticsearch_dsl import DocType, Index, fields
from django_elasticsearch_dsl_drf.compat import KeywordField, StringField
from books.models import City
from .analyzers import html_strip
INDEX = Index(settings.ELASTICSEARCH_INDEX_NAMES[__name__])
# See Elasticsearch Indices API reference for available settings
INDEX.settings(
number_of_shards=1,
number_of_replicas=1
)
@INDEX.doc_type
class CityDocument(DocType):
"""City Elasticsearch document.
This document has been created purely for testing out complex fields.
"""
# ID
id = fields.IntegerField(attr='id')
# ********************************************************************
# ********************** Main data fields for search *****************
# ********************************************************************
name = StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
)
info = StringField(analyzer=html_strip)
# ********************************************************************
# ************** Nested fields for search and filtering **************
# ********************************************************************
# City object
country = fields.NestedField(
properties={
'name': StringField(
analyzer=html_strip,
fields={
'raw': KeywordField(),
'suggest': fields.CompletionField(),
}
),
'info': StringField(analyzer=html_strip),
'location': fields.GeoPointField(attr='location_field_indexing'),
}
)
location = fields.GeoPointField(attr='location_field_indexing')
# ********************************************************************
# ********** Other complex fields for search and filtering ***********
# ********************************************************************
boolean_list = fields.ListField(
StringField(attr='boolean_list_indexing')
)
datetime_list = fields.ListField(
StringField(attr='datetime_list_indexing')
)
float_list = fields.ListField(
StringField(attr='float_list_indexing')
)
integer_list = fields.ListField(
StringField(attr='integer_list_indexing')
)
class Meta(object):
"""Meta options."""
model = City # The model associate with this DocType
viewsets/city.py
from django_elasticsearch_dsl_drf.constants import (
LOOKUP_FILTER_GEO_DISTANCE,
LOOKUP_FILTER_GEO_POLYGON,
LOOKUP_FILTER_GEO_BOUNDING_BOX,
SUGGESTER_COMPLETION,
)
from django_elasticsearch_dsl_drf.filter_backends import (
FilteringFilterBackend,
DefaultOrderingFilterBackend,
OrderingFilterBackend,
SearchFilterBackend,
SuggesterFilterBackend,
GeoSpatialFilteringFilterBackend,
GeoSpatialOrderingFilterBackend,
)
from django_elasticsearch_dsl_drf.pagination import LimitOffsetPagination
from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet
from ..documents import CityDocument
from ..serializers import CityDocumentSerializer
class CityDocumentViewSet(BaseDocumentViewSet):
"""The CityDocument view."""
document = CityDocument
serializer_class = CityDocumentSerializer
lookup_field = 'id'
filter_backends = [
FilteringFilterBackend,
OrderingFilterBackend,
SearchFilterBackend,
GeoSpatialFilteringFilterBackend,
GeoSpatialOrderingFilterBackend,
DefaultOrderingFilterBackend,
SuggesterFilterBackend,
]
pagination_class = LimitOffsetPagination
# Define search fields
search_fields = (
'name',
'info',
)
search_nested_fields = {
'country': ['name'],
}
# Define filtering fields
filter_fields = {
'id': None,
'name': 'name.raw',
'country': 'country.name.raw',
}
# Define geo-spatial filtering fields
geo_spatial_filter_fields = {
'location': {
'lookups': [
LOOKUP_FILTER_GEO_BOUNDING_BOX,
LOOKUP_FILTER_GEO_DISTANCE,
LOOKUP_FILTER_GEO_POLYGON,
],
},
}
# Define ordering fields
ordering_fields = {
'id': None,
'name': None,
'country': 'country.name.raw',
}
# Define ordering fields
geo_spatial_ordering_fields = {
'location': None,
}
# Specify default ordering
ordering = (
'id',
'name.raw',
'country.name.raw',
)
# Suggester fields
suggester_fields = {
'name_suggest': {
'field': 'name.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
},
'country_suggest': {
'field': 'country.name.suggest',
'suggesters': [
SUGGESTER_COMPLETION,
],
}
}
Suggestions¶
The suggest feature suggests similar looking terms based on a provided text by using a suggester.
Note
The SuggesterFilterBackend filter backend can be used in the
suggest custom view action/route only. Usages outside of the are
suggest action/route are restricted.
There are three options available here: term, phrase and
completion.
Note
Suggestion functionality is exclusive. Once you have queried the
SuggesterFilterBackend, the latter will transform your current
search query into suggestion search query (which is very different).
Therefore, always add it as the very last filter backend.
Suggest completion for field country.
http://127.0.0.1:8000/search/addresses/suggest/?country_suggest__completion=Ar
Suggest completion for field city.
http://127.0.0.1:8000/search/addresses/suggest/?city_suggest__completion=Ye
Various handy helpers¶
Contents:
Table of Contents
More like this¶
To get more-like-this results on a random registered model, do as follows:
from django_elasticsearch_dsl_drf.helpers import more_like_this
from books.models import Book
book = Book.objects.first()
similar_books = more_like_this(
book,
['title', 'description', 'summary']
)
Customize results as follows:
from django_elasticsearch_dsl_drf.helpers import more_like_this
from elasticsearch_dsl.query import Q
from books.models import Book
book = Book.objects.first()
query = Q('bool', must_not=Q('term', **{'state.raw': 'cancelled'}))
similar_books = more_like_this(
book,
query=query,
fields=['title', 'description', 'summary'],
min_term_freq=2,
min_doc_freq=1,
)
Release history and notes¶
Sequence based identifiers are used for versioning (schema follows below):
major.minor[.revision]
- It’s always safe to upgrade within the same minor version (for example, from 0.3 to 0.3.4).
- Minor version changes might be backwards incompatible. Read the release notes carefully before upgrading (for example, when upgrading from 0.3.4 to 0.4).
- All backwards incompatible changes are mentioned in this document.
0.6.2¶
2017-12-29
- Update example project (and the tests that are dependant on the example project) to work with Django 2.0.
- Set minimal requirement for
django-elasticsearch-dslto 3.0.
0.5.1¶
2017-10-18
- Fixed serialization of complex nested structures (lists of nested objects).
- Documentation fixes.
0.5¶
2017-10-05
Note
This release contains changes that might be backwards incompatible
for your project. If you have used dynamic document serializer
django_elasticsearch_dsl_drf.serializers.DocumentSerializer
with customisations (with use of serializers.SerializerMethodField,
having the value parsed to JSON), just remove the custom parts.
- Support for
ObjectField,NestedField,GeoPointField,ListField,GeoShapeField(and in general, nesting fields either as a dictionary or list should not be a problem at all). - Dynamic serializer has been made less strict.
- Added
get_paginated_response_contextmethods to bothPageNumberPaginationandLimitOffsetPaginationpagination classes to simplify customisations.
0.4.4¶
2017-10-02
- Documentation improvements (Elasticsearch suggestions).
- More tests (term and phrase suggestions).
- Code style fixes.
0.4¶
2017-09-26
Note
This release contains changes that might be backwards incompatible
for your project. Make sure to add the DefaultOrderingFilterBackend
everywhere you have used the OrderingFilterBackend, right after the
latter.
GeoSpatialFilteringFilterBackendfiltering backend, supportinggeo_distanceandgeo_polygongeo-spatial queries.GeoSpatialOrderingFilterBackendordering backend, supporting ordering of results forgeo_distancefilter.OrderingFilterBackendno longer provides defaults when no ordering is given. In order to take care of the defaults include theDefaultOrderingFilterBackendin the list offilter_backends(after all other ordering backends).
0.3.12¶
2017-09-21
- Added
geo_distancefilter. Note, that although functionally the filter would not change its’ behaviour, it is likely to be moved to a separate backend (geo_spatial). For now use as is. - Minor fixes.
0.3.6¶
2017-09-07
- Fixed suggestions test for Elasticsearch 5.x.
- Added compat module for painless testing of Elastic 2.x to Elastic 5.x transition.
0.1.6¶
2017-06-23
- Implemented
gt`, ``gte,ltandltefunctional query lookups. - Implemented
idsnative filter lookup.
0.1.5¶
2017-06-22
- Implemented
endswithandcontainsfunctional filters. - Added tests for
wildcard,exists,excludeandisnullfilters. Improvedrangefilter tests. - Improve
more_like_thishelper test. - Improve ordering tests.
- Two additional arguments added to the
more_like_thishelper:min_doc_freqandmax_doc_freq. - Minor documentation improvements.
0.1.3¶
2017-06-21
- Added tests for
more_like_thishelper,rangeandprefixfilters. - Minor documentation improvements.
django_elasticsearch_dsl_drf package¶
Subpackages¶
django_elasticsearch_dsl_drf.fields package¶
Submodules¶
django_elasticsearch_dsl_drf.fields.nested_fields module¶
Nested fields.
-
class
django_elasticsearch_dsl_drf.fields.nested_fields.GeoPointField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectFieldGeo point field.
-
class
django_elasticsearch_dsl_drf.fields.nested_fields.GeoShapeField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectFieldGeo shape field.
-
class
django_elasticsearch_dsl_drf.fields.nested_fields.NestedField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectFieldNested field.
-
class
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
rest_framework.fields.FieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.nested_fields.ListField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
rest_framework.fields.FieldList field.
Module contents¶
Fields.
-
class
django_elasticsearch_dsl_drf.fields.BooleanField(**kwargs)[source]¶ Bases:
rest_framework.fields.BooleanFieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.CharField(**kwargs)[source]¶ Bases:
rest_framework.fields.CharFieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.DateField(format=<class 'rest_framework.fields.empty'>, input_formats=None, *args, **kwargs)[source]¶ Bases:
rest_framework.fields.DateFieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.FloatField(**kwargs)[source]¶ Bases:
rest_framework.fields.FloatFieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.GeoPointField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectFieldGeo point field.
-
class
django_elasticsearch_dsl_drf.fields.GeoShapeField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectFieldGeo shape field.
-
class
django_elasticsearch_dsl_drf.fields.IntegerField(**kwargs)[source]¶ Bases:
rest_framework.fields.IntegerFieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.IPAddressField(protocol='both', **kwargs)[source]¶ Bases:
rest_framework.fields.IPAddressFieldObject field.
-
class
django_elasticsearch_dsl_drf.fields.ListField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
rest_framework.fields.FieldList field.
-
class
django_elasticsearch_dsl_drf.fields.NestedField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
django_elasticsearch_dsl_drf.fields.nested_fields.ObjectFieldNested field.
-
class
django_elasticsearch_dsl_drf.fields.ObjectField(read_only=False, write_only=False, required=None, default=<class 'rest_framework.fields.empty'>, initial=<class 'rest_framework.fields.empty'>, source=None, label=None, help_text=None, style=None, error_messages=None, validators=None, allow_null=False)[source]¶ Bases:
rest_framework.fields.FieldObject field.
django_elasticsearch_dsl_drf.filter_backends package¶
Subpackages¶
Common filtering backend.
-
class
django_elasticsearch_dsl_drf.filter_backends.filtering.common.FilteringFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinFiltering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.constants import ( >>> LOOKUP_FILTER_PREFIX, >>> LOOKUP_FILTER_WILDCARD, >>> LOOKUP_QUERY_EXCLUDE, >>> LOOKUP_QUERY_ISNULL, >>> ) >>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> FilteringFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [FilteringFilterBackend,] >>> filter_fields = { >>> 'title': 'title.raw', >>> 'state': { >>> 'field': 'state.raw', >>> 'lookups': [ >>> LOOKUP_FILTER_PREFIX, >>> LOOKUP_FILTER_WILDCARD, >>> LOOKUP_QUERY_EXCLUDE, >>> LOOKUP_QUERY_ISNULL, >>> ], >>> } >>> }
-
classmethod
apply_filter_prefix(queryset, options, value)[source]¶ Apply prefix filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_filter_range(queryset, options, value)[source]¶ Apply range filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_filter_term(queryset, options, value)[source]¶ Apply term filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_filter_terms(queryset, options, value)[source]¶ Apply terms filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (mixed: either str or iterable (list, tuple)) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_contains(queryset, options, value)[source]¶ Apply contains filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_endswith(queryset, options, value)[source]¶ Apply endswith filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_exclude(queryset, options, value)[source]¶ Apply exclude functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_exists(queryset, options, value)[source]¶ Apply exists filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_gt(queryset, options, value)[source]¶ Apply gt functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_gte(queryset, options, value)[source]¶ Apply gte functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_in(queryset, options, value)[source]¶ Apply in functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_isnull(queryset, options, value)[source]¶ Apply isnull functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_lt(queryset, options, value)[source]¶ Apply lt functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_lte(queryset, options, value)[source]¶ Apply lte functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_wildcard(queryset, options, value)[source]¶ Apply wildcard filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_filter_query_params(request, view)[source]¶ Get query params to be filtered on.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Request query params to filter on.
Return type: dict
-
classmethod
get_gte_lte_params(value, lookup)[source]¶ Get params for gte, gt, lte and lt query.
Parameters: - value (str) –
- lookup (str) –
Returns: Params to be used in range query.
Return type: dict
-
classmethod
Geo spatial filtering backend.
Elasticsearch supports two types of geo data:
- geo_point fields which support lat/lon pairs
- geo_shape fields, which support points, lines, circles, polygons, multi-polygons etc.
The queries in this group are:
- geo_shape query: Find document with geo-shapes which either intersect, are contained by, or do not intersect with the specified geo-shape.
- geo_bounding_box query: Finds documents with geo-points that fall into the specified rectangle.
- geo_distance query: Finds document with geo-points within the specified distance of a central point.
- geo_distance_range query: Like the geo_distance query, but the range starts at a specified distance from the central point. Note, that this one is deprecated and this isn’t implemented.
- geo_polygon query: Find documents with geo-points within the specified polygon.
-
class
django_elasticsearch_dsl_drf.filter_backends.filtering.geo_spatial.GeoSpatialFilteringFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinGeo-spatial filtering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.constants import ( >>> LOOKUP_FILTER_GEO_DISTANCE, >>> ) >>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> GeoSpatialFilteringFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [GeoSpatialFilteringFilterBackend,] >>> geo_spatial_filter_fields = { >>> 'loc': 'location', >>> 'location': { >>> 'field': 'location', >>> 'lookups': [ >>> LOOKUP_FILTER_GEO_DISTANCE, >>> ], >>> } >>> }
-
classmethod
apply_query_geo_bounding_box(queryset, options, value)[source]¶ Apply geo_bounding_box query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_geo_distance(queryset, options, value)[source]¶ Apply geo_distance query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_geo_polygon(queryset, options, value)[source]¶ Apply geo_polygon query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_filter_query_params(request, view)[source]¶ Get query params to be filtered on.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Request query params to filter on.
Return type: dict
-
classmethod
get_geo_bounding_box_params(value, field)[source]¶ Get params for geo_bounding_box query.
Example:
/api/articles/?location__geo_bounding_box=40.73,-74.1|40.01,-71.12Example:
- /api/articles/?location__geo_polygon=40.73,-74.1|40.01,-71.12
- |_name:myname|validation_method:IGNORE_MALFORMED|type:indexed
Elasticsearch:
- {
- “query”: {
- “bool” : {
- “must” : {
- “match_all” : {}
}, “filter” : {
- “geo_bounding_box” : {
- “person.location” : {
- “top_left” : {
- “lat” : 40.73, “lon” : -74.1
}, “bottom_right” : {
“lat” : 40.01, “lon” : -71.12}
}
}
}
}
}
}
Parameters: - value (str) –
- field –
Returns: Params to be used in geo_bounding_box query.
Return type: dict
-
classmethod
get_geo_distance_params(value, field)[source]¶ Get params for geo_distance query.
Example:
/api/articles/?location__geo_distance=2km|43.53|-12.23Parameters: - value (str) –
- field –
Returns: Params to be used in geo_distance query.
Return type: dict
-
classmethod
get_geo_polygon_params(value, field)[source]¶ Get params for geo_polygon query.
Example:
/api/articles/?location__geo_polygon=40,-70|30,-80|20,-90Example:
- /api/articles/?location__geo_polygon=40,-70|30,-80|20,-90
- |_name:myname|validation_method:IGNORE_MALFORMED
Elasticsearch:
- {
- “query”: {
- “bool” : {
- “must” : {
- “match_all” : {}
}, “filter” : {
- “geo_polygon” : {
- “person.location” : {
- “points” : [
- {“lat” : 40, “lon” : -70}, {“lat” : 30, “lon” : -80}, {“lat” : 20, “lon” : -90}
]
}
}
}
}
}
}
Parameters: - value (str) –
- field –
Returns: Params to be used in geo_distance query.
Return type: dict
-
classmethod
Ids filtering backend.
Filters documents that only have the provided ids. Note, this query uses the _uid field.
Elastic query:
- {
- “query”: {
- “ids”: {
- “type”: “book_document”, “values”: [“68”, “64”, “58”]
}
}
}
REST framework request equivalent:
- http://localhost:8000/api/articles/?ids=68|64|58
- http://localhost:8000/api/articles/?ids=68&ids=64&ids=58
Official Elastic docs:
- https://www.elastic.co/guide/en/elasticsearch/reference/current/ query-dsl-ids-query.html
-
class
django_elasticsearch_dsl_drf.filter_backends.filtering.ids.IdsFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinIds filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> IdsFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [IdsFilterBackend]
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_ids_query_params(request)[source]¶ Get search query params.
Parameters: request (rest_framework.request.Request) – Django REST framework request. Returns: List of search query params. Return type: list
-
get_ids_values(request, view)[source]¶ Get ids values for query.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
ids_query_param= 'ids'¶
-
Term level filtering backends.
-
class
django_elasticsearch_dsl_drf.filter_backends.filtering.FilteringFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinFiltering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.constants import ( >>> LOOKUP_FILTER_PREFIX, >>> LOOKUP_FILTER_WILDCARD, >>> LOOKUP_QUERY_EXCLUDE, >>> LOOKUP_QUERY_ISNULL, >>> ) >>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> FilteringFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [FilteringFilterBackend,] >>> filter_fields = { >>> 'title': 'title.raw', >>> 'state': { >>> 'field': 'state.raw', >>> 'lookups': [ >>> LOOKUP_FILTER_PREFIX, >>> LOOKUP_FILTER_WILDCARD, >>> LOOKUP_QUERY_EXCLUDE, >>> LOOKUP_QUERY_ISNULL, >>> ], >>> } >>> }
-
classmethod
apply_filter_prefix(queryset, options, value)[source]¶ Apply prefix filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_filter_range(queryset, options, value)[source]¶ Apply range filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_filter_term(queryset, options, value)[source]¶ Apply term filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_filter_terms(queryset, options, value)[source]¶ Apply terms filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (mixed: either str or iterable (list, tuple)) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_contains(queryset, options, value)[source]¶ Apply contains filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_endswith(queryset, options, value)[source]¶ Apply endswith filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_exclude(queryset, options, value)[source]¶ Apply exclude functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_exists(queryset, options, value)[source]¶ Apply exists filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_gt(queryset, options, value)[source]¶ Apply gt functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_gte(queryset, options, value)[source]¶ Apply gte functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_in(queryset, options, value)[source]¶ Apply in functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_isnull(queryset, options, value)[source]¶ Apply isnull functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_lt(queryset, options, value)[source]¶ Apply lt functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_lte(queryset, options, value)[source]¶ Apply lte functional query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_wildcard(queryset, options, value)[source]¶ Apply wildcard filter.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_filter_query_params(request, view)[source]¶ Get query params to be filtered on.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Request query params to filter on.
Return type: dict
-
classmethod
get_gte_lte_params(value, lookup)[source]¶ Get params for gte, gt, lte and lt query.
Parameters: - value (str) –
- lookup (str) –
Returns: Params to be used in range query.
Return type: dict
-
classmethod
-
class
django_elasticsearch_dsl_drf.filter_backends.filtering.GeoSpatialFilteringFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinGeo-spatial filtering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.constants import ( >>> LOOKUP_FILTER_GEO_DISTANCE, >>> ) >>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> GeoSpatialFilteringFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [GeoSpatialFilteringFilterBackend,] >>> geo_spatial_filter_fields = { >>> 'loc': 'location', >>> 'location': { >>> 'field': 'location', >>> 'lookups': [ >>> LOOKUP_FILTER_GEO_DISTANCE, >>> ], >>> } >>> }
-
classmethod
apply_query_geo_bounding_box(queryset, options, value)[source]¶ Apply geo_bounding_box query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_geo_distance(queryset, options, value)[source]¶ Apply geo_distance query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_query_geo_polygon(queryset, options, value)[source]¶ Apply geo_polygon query.
Parameters: - queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_filter_query_params(request, view)[source]¶ Get query params to be filtered on.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Request query params to filter on.
Return type: dict
-
classmethod
get_geo_bounding_box_params(value, field)[source]¶ Get params for geo_bounding_box query.
Example:
/api/articles/?location__geo_bounding_box=40.73,-74.1|40.01,-71.12Example:
- /api/articles/?location__geo_polygon=40.73,-74.1|40.01,-71.12
- |_name:myname|validation_method:IGNORE_MALFORMED|type:indexed
Elasticsearch:
- {
- “query”: {
- “bool” : {
- “must” : {
- “match_all” : {}
}, “filter” : {
- “geo_bounding_box” : {
- “person.location” : {
- “top_left” : {
- “lat” : 40.73, “lon” : -74.1
}, “bottom_right” : {
“lat” : 40.01, “lon” : -71.12}
}
}
}
}
}
}
Parameters: - value (str) –
- field –
Returns: Params to be used in geo_bounding_box query.
Return type: dict
-
classmethod
get_geo_distance_params(value, field)[source]¶ Get params for geo_distance query.
Example:
/api/articles/?location__geo_distance=2km|43.53|-12.23Parameters: - value (str) –
- field –
Returns: Params to be used in geo_distance query.
Return type: dict
-
classmethod
get_geo_polygon_params(value, field)[source]¶ Get params for geo_polygon query.
Example:
/api/articles/?location__geo_polygon=40,-70|30,-80|20,-90Example:
- /api/articles/?location__geo_polygon=40,-70|30,-80|20,-90
- |_name:myname|validation_method:IGNORE_MALFORMED
Elasticsearch:
- {
- “query”: {
- “bool” : {
- “must” : {
- “match_all” : {}
}, “filter” : {
- “geo_polygon” : {
- “person.location” : {
- “points” : [
- {“lat” : 40, “lon” : -70}, {“lat” : 30, “lon” : -80}, {“lat” : 20, “lon” : -90}
]
}
}
}
}
}
}
Parameters: - value (str) –
- field –
Returns: Params to be used in geo_distance query.
Return type: dict
-
classmethod
-
class
django_elasticsearch_dsl_drf.filter_backends.filtering.IdsFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinIds filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> IdsFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [IdsFilterBackend]
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_ids_query_params(request)[source]¶ Get search query params.
Parameters: request (rest_framework.request.Request) – Django REST framework request. Returns: List of search query params. Return type: list
-
get_ids_values(request, view)[source]¶ Get ids values for query.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
ids_query_param= 'ids'¶
-
Ordering backend.
-
class
django_elasticsearch_dsl_drf.filter_backends.ordering.common.DefaultOrderingFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackendDefault ordering filter backend for Elasticsearch.
Make sure this is your last ordering backend.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> DefaultOrderingFilterBackend, >>> OrderingFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [ >>> DefaultOrderingFilterBackend, >>> OrderingFilterBackend, >>> ] >>> ordering_fields = { >>> 'id': 'id', >>> 'title': 'title.raw', >>> 'date_submitted': 'date_submitted', >>> 'state': { >>> 'field': 'state.raw', >>> } >>> } >>> ordering = 'name'
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
get_default_ordering_params(view)[source]¶ Get the default ordering params for the view.
Parameters: view (rest_framework.viewsets.ReadOnlyModelViewSet) – View. Returns: Ordering params to be used for ordering. Return type: list
-
get_ordering_query_params(request, view)[source]¶ Get ordering query params.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Ordering params to be used for ordering.
Return type: list
-
ordering_param= 'ordering'¶
-
-
class
django_elasticsearch_dsl_drf.filter_backends.ordering.common.OrderingFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackendOrdering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> OrderingFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [OrderingFilterBackend,] >>> ordering_fields = { >>> 'id': 'id', >>> 'title': 'title.raw', >>> 'date_submitted': 'date_submitted', >>> 'state': { >>> 'field': 'state.raw', >>> } >>> } >>> ordering = ('id', 'name',)
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_ordering_query_params(request, view)[source]¶ Get ordering query params.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Ordering params to be used for ordering.
Return type: list
-
ordering_param= 'ordering'¶
-
Geo-spatial ordering backend.
-
class
django_elasticsearch_dsl_drf.filter_backends.ordering.geo_spatial.GeoSpatialOrderingFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinGeo-spatial ordering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> GeoSpatialOrderingFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [GeoSpatialOrderingFilterBackend,] >>> geo_spatial_ordering_fields = { >>> 'location': { >>> 'field': 'location', >>> } >>> }
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
get_geo_distance_params(value, field)[source]¶ Get params for geo_distance ordering.
Example:
/api/articles/?ordering=-location|45.3214|-34.3421|km|planesParameters: - value (str) –
- field –
Returns: Params to be used in geo_distance query.
Return type: dict
-
get_ordering_query_params(request, view)[source]¶ Get ordering query params.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Ordering params to be used for ordering.
Return type: list
-
ordering_param= 'ordering'¶
-
Ordering backends.
-
class
django_elasticsearch_dsl_drf.filter_backends.ordering.DefaultOrderingFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackendDefault ordering filter backend for Elasticsearch.
Make sure this is your last ordering backend.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> DefaultOrderingFilterBackend, >>> OrderingFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [ >>> DefaultOrderingFilterBackend, >>> OrderingFilterBackend, >>> ] >>> ordering_fields = { >>> 'id': 'id', >>> 'title': 'title.raw', >>> 'date_submitted': 'date_submitted', >>> 'state': { >>> 'field': 'state.raw', >>> } >>> } >>> ordering = 'name'
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
get_default_ordering_params(view)[source]¶ Get the default ordering params for the view.
Parameters: view (rest_framework.viewsets.ReadOnlyModelViewSet) – View. Returns: Ordering params to be used for ordering. Return type: list
-
get_ordering_query_params(request, view)[source]¶ Get ordering query params.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Ordering params to be used for ordering.
Return type: list
-
ordering_param= 'ordering'¶
-
-
class
django_elasticsearch_dsl_drf.filter_backends.ordering.GeoSpatialOrderingFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinGeo-spatial ordering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> GeoSpatialOrderingFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [GeoSpatialOrderingFilterBackend,] >>> geo_spatial_ordering_fields = { >>> 'location': { >>> 'field': 'location', >>> } >>> }
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
get_geo_distance_params(value, field)[source]¶ Get params for geo_distance ordering.
Example:
/api/articles/?ordering=-location|45.3214|-34.3421|km|planesParameters: - value (str) –
- field –
Returns: Params to be used in geo_distance query.
Return type: dict
-
get_ordering_query_params(request, view)[source]¶ Get ordering query params.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Ordering params to be used for ordering.
Return type: list
-
ordering_param= 'ordering'¶
-
-
class
django_elasticsearch_dsl_drf.filter_backends.ordering.OrderingFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackendOrdering filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> OrderingFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [OrderingFilterBackend,] >>> ordering_fields = { >>> 'id': 'id', >>> 'title': 'title.raw', >>> 'date_submitted': 'date_submitted', >>> 'state': { >>> 'field': 'state.raw', >>> } >>> } >>> ordering = ('id', 'name',)
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_ordering_query_params(request, view)[source]¶ Get ordering query params.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Ordering params to be used for ordering.
Return type: list
-
ordering_param= 'ordering'¶
-
Submodules¶
django_elasticsearch_dsl_drf.filter_backends.faceted_search module¶
Faceted search backend.
-
class
django_elasticsearch_dsl_drf.filter_backends.faceted_search.FacetedSearchFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackendFaceted search backend.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> FacetedSearchFilterBackend >>> ) >>> from elasticsearch_dsl import TermsFacet, DateHistogramFacet >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [FacetedSearchFilterBackend,] >>> faceted_search_fields = { >>> 'title': 'title.raw', # Uses `TermsFacet` by default >>> 'state': { >>> 'field': 'state.raw', >>> 'facet': TermsFacet, >>> }, >>> 'publisher': { >>> 'field': 'publisher.raw', >>> 'facet': TermsFacet, >>> 'enabled': False, >>> }, >>> 'date_published': { >>> 'field': 'date_published.raw', >>> 'facet': DateHistogramFacet, >>> 'options': { >>> 'interval': 'month', >>> }, >>> 'enabled': True, >>> }, >>> >>> }
Facets make queries to be more heavy. That’s why by default all facets are disabled and enabled only explicitly either in the filter options (enabled set to True) or via query params ?facet=state&facet=date_published.
-
aggregate(request, queryset, view)[source]¶ Aggregate.
Parameters: - request –
- queryset –
- view –
Returns:
-
construct_facets(request, view)[source]¶ Construct facets.
Turns the following structure:
>>> { >>> 'publisher': { >>> 'field': 'publisher.raw', >>> 'facet': TermsFacet, >>> 'enabled': False, >>> } >>> 'date_published': { >>> 'field': 'date_published', >>> 'facet': DateHistogramFacet, >>> 'options': { >>> 'interval': 'month', >>> }, >>> 'enabled': True, >>> }, >>> }
Into the following structure:
>>> { >>> 'publisher': TermsFacet(field='publisher.raw'), >>> 'publishing_frequency': DateHistogramFacet( >>> field='date_published.raw', >>> interval='month' >>> ), >>> }
-
faceted_search_param= 'facet'¶
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_faceted_search_query_params(request)[source]¶ Get faceted search query params.
Parameters: request (rest_framework.request.Request) – Django REST framework request. Returns: List of search query params. Return type: list
-
classmethod
prepare_faceted_search_fields(view)[source]¶ Prepare faceted search fields.
Prepares the following structure:
>>> { >>> 'publisher': { >>> 'field': 'publisher.raw', >>> 'facet': TermsFacet, >>> 'enabled': False, >>> } >>> 'date_published': { >>> 'field': 'date_published.raw', >>> 'facet': DateHistogramFacet, >>> 'options': { >>> 'interval': 'month', >>> }, >>> 'enabled': True, >>> }, >>> }
Parameters: view (rest_framework.viewsets.ReadOnlyModelViewSet) – Returns: Faceted search fields options. Return type: dict
-
django_elasticsearch_dsl_drf.filter_backends.mixins module¶
Mixins.
-
class
django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixin[source]¶ Bases:
objectFilter backend mixin.
-
classmethod
split_lookup_complex_value(value, maxsplit=-1)[source]¶ Split lookup complex value.
Parameters: - value (str) – Value to split.
- maxsplit (int) – The maxsplit option of string.split.
Returns: Lookup filter split into a list.
Return type: list
-
classmethod
django_elasticsearch_dsl_drf.filter_backends.search module¶
Search backend.
-
class
django_elasticsearch_dsl_drf.filter_backends.search.SearchFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinSearch filter backend for Elasticsearch.
Example:
>>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> SearchFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local article document definition >>> from .documents import ArticleDocument >>> >>> # Local article document serializer >>> from .serializers import ArticleDocumentSerializer >>> >>> class ArticleDocumentView(BaseDocumentViewSet): >>> >>> document = ArticleDocument >>> serializer_class = ArticleDocumentSerializer >>> filter_backends = [SearchFilterBackend,] >>> search_fields = ( >>> 'title', >>> 'content', >>> ) >>> search_nested_fields = { >>> 'state': ['name'], >>> 'documents.author': ['title', 'description'], >>> }
-
construct_nested_search(request, view)[source]¶ Construct nested search.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
construct_search(request, view)[source]¶ Construct search.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
get_search_query_params(request)[source]¶ Get search query params.
Parameters: request (rest_framework.request.Request) – Django REST framework request. Returns: List of search query params. Return type: list
-
search_param= 'search'¶
-
django_elasticsearch_dsl_drf.filter_backends.suggester module¶
Suggesters backend.
It’s assumed, that fields you’re planning to query suggestions for have been
properly indexed using fields.CompletionField.
Example:
>>> from django_elasticsearch_dsl import DocType, Index, fields
>>>
>>> from books.models import Publisher
>>>
>>> # Name of the Elasticsearch index
>>> PUBLISHER_INDEX = Index(PUBLISHER_INDEX_NAME)
>>> # See Elasticsearch Indices API reference for available settings
>>> PUBLISHER_INDEX.settings(
>>> number_of_shards=1,
>>> number_of_replicas=1
>>> )
>>>
>>> @PUBLISHER_INDEX.doc_type
>>> class PublisherDocument(DocType):
>>> "Publisher Elasticsearch document."
>>>
>>> id = fields.IntegerField(attr='id')
>>>
>>> name = fields.StringField(
>>> fields={
>>> 'raw': fields.StringField(analyzer='keyword'),
>>> 'suggest': fields.CompletionField(),
>>> }
>>> )
>>>
>>> info = fields.StringField()
>>>
>>> address = fields.StringField(
>>> fields={
>>> 'raw': fields.StringField(analyzer='keyword')
>>> }
>>> )
>>>
>>> city = fields.StringField(
>>> fields={
>>> 'raw': fields.StringField(analyzer='keyword'),
>>> 'suggest': fields.CompletionField(),
>>> }
>>> )
>>>
>>> state_province = fields.StringField(
>>> fields={
>>> 'raw': fields.StringField(analyzer='keyword'),
>>> 'suggest': fields.CompletionField(),
>>> }
>>> )
>>>
>>> country = fields.StringField(
>>> fields={
>>> 'raw': fields.StringField(analyzer='keyword'),
>>> 'suggest': fields.CompletionField(),
>>> }
>>> )
>>>
>>> website = fields.StringField()
>>>
>>> class Meta(object):
>>> "Meta options."
>>>
>>> model = Publisher # The model associate with this DocType
-
class
django_elasticsearch_dsl_drf.filter_backends.suggester.SuggesterFilterBackend[source]¶ Bases:
rest_framework.filters.BaseFilterBackend,django_elasticsearch_dsl_drf.filter_backends.mixins.FilterBackendMixinSuggester filter backend for Elasticsearch.
Suggestion functionality is exclusive. Once you have queried the
SuggesterFilterBackend, the latter will transform your current search query into suggestion search query (which is very different). Therefore, always add it as the very last filter backend.Example:
>>> from django_elasticsearch_dsl_drf.constants import ( >>> SUGGESTER_TERM, >>> SUGGESTER_PHRASE, >>> SUGGESTER_COMPLETION, >>> ) >>> from django_elasticsearch_dsl_drf.filter_backends import ( >>> SuggesterFilterBackend >>> ) >>> from django_elasticsearch_dsl_drf.views import BaseDocumentViewSet >>> >>> # Local PublisherDocument definition >>> from .documents import PublisherDocument >>> >>> # Local PublisherDocument serializer >>> from .serializers import PublisherDocumentSerializer >>> >>> class PublisherDocumentView(BaseDocumentViewSet): >>> >>> document = PublisherDocument >>> serializer_class = PublisherDocumentSerializer >>> filter_backends = [ >>> # ... >>> SuggesterFilterBackend, >>> ] >>> # Suggester fields >>> suggester_fields = { >>> 'name_suggest': { >>> 'field': 'name.suggest', >>> 'suggesters': [ >>> SUGGESTER_TERM, >>> SUGGESTER_PHRASE, >>> SUGGESTER_COMPLETION, >>> ], >>> }, >>> 'city_suggest': { >>> 'field': 'city.suggest', >>> 'suggesters': [ >>> SUGGESTER_COMPLETION, >>> ], >>> }, >>> 'state_province_suggest': { >>> 'field': 'state_province.suggest', >>> 'suggesters': [ >>> SUGGESTER_COMPLETION, >>> ], >>> }, >>> 'country_suggest': { >>> 'field': 'country.suggest', >>> 'suggesters': [ >>> SUGGESTER_COMPLETION, >>> ], >>> }, >>> }
-
classmethod
apply_suggester_completion(suggester_name, queryset, options, value)[source]¶ Apply completion suggester.
Parameters: - suggester_name (str) –
- queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_suggester_phrase(suggester_name, queryset, options, value)[source]¶ Apply phrase suggester.
Parameters: - suggester_name (str) –
- queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
apply_suggester_term(suggester_name, queryset, options, value)[source]¶ Apply term suggester.
Parameters: - suggester_name (str) –
- queryset (elasticsearch_dsl.search.Search) – Original queryset.
- options (dict) – Filter options.
- value (str) – value to filter on.
Returns: Modified queryset.
Return type: elasticsearch_dsl.search.Search
-
filter_queryset(request, queryset, view)[source]¶ Filter the queryset.
Parameters: - request (rest_framework.request.Request) – Django REST framework request.
- queryset (elasticsearch_dsl.search.Search) – Base queryset.
- view (rest_framework.viewsets.ReadOnlyModelViewSet) – View.
Returns: Updated queryset.
Return type: elasticsearch_dsl.search.Search
-
classmethod
Module contents¶
All filter backends.
django_elasticsearch_dsl_drf.tests package¶
Submodules¶
django_elasticsearch_dsl_drf.tests.base module¶
Base tests.
-
class
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCase(methodName='runTest')[source]¶ Bases:
django.test.testcases.TransactionTestCaseBase REST framework test case.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
django_elasticsearch_dsl_drf.tests.data_mixins module¶
Data mixins.
django_elasticsearch_dsl_drf.tests.test_faceted_search module¶
Test faceted search backend.
-
class
django_elasticsearch_dsl_drf.tests.test_faceted_search.TestFacetedSearch(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest faceted search.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
django_elasticsearch_dsl_drf.tests.test_filtering_common module¶
Test filtering backend.
-
class
django_elasticsearch_dsl_drf.tests.test_filtering_common.TestFilteringCommon(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCase,django_elasticsearch_dsl_drf.tests.data_mixins.AddressesMixin,django_elasticsearch_dsl_drf.tests.data_mixins.BooksMixinTest filtering common.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
test_field_filter_gt_with_boost()[source]¶ Field filter gt with boost.
Example:
http://localhost:8000/api/users/?id__gt=10|2.0Returns:
-
test_field_filter_in()[source]¶ Test filter in.
Example:
http://localhost:8000/api/articles/?id__in=1|2|3
-
test_field_filter_lt_with_boost()[source]¶ Field filter lt with boost.
Example:
http://localhost:8000/api/users/?id__lt=10|2.0Returns:
-
test_field_filter_range()[source]¶ Field filter range.
Example:
http://localhost:8000/api/users/?age__range=16|67
-
test_field_filter_range_with_boost()[source]¶ Field filter range.
Example:
http://localhost:8000/api/users/?age__range=16|67|2.0
-
test_field_filter_terms_string()[source]¶ Test filter terms.
Example:
http://localhost:8000/api/articles/?id__terms=1|2|3
-
django_elasticsearch_dsl_drf.tests.test_filtering_geo_spatial module¶
Test geo-spatial filtering backend.
-
class
django_elasticsearch_dsl_drf.tests.test_filtering_geo_spatial.TestFilteringGeoSpatial(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest filtering geo-spatial.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
test_field_filter_geo_bounding_box_fail_test()[source]¶ Test field filter geo-bounding-box (fail test).
Returns:
-
test_field_filter_geo_distance()[source]¶ Field filter geo-distance.
Example:
http://localhost:8000 /api/publisher/?location__geo_distance=1km|48.8549|2.3000
-
django_elasticsearch_dsl_drf.tests.test_helpers module¶
Test helpers.
-
class
django_elasticsearch_dsl_drf.tests.test_helpers.TestHelpers(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseTestCaseTest helpers.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
django_elasticsearch_dsl_drf.tests.test_ordering_common module¶
Test ordering backend.
-
class
django_elasticsearch_dsl_drf.tests.test_ordering_common.TestOrdering(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest ordering.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
Author order by default.
Order by field name ascending.
Order by field id descending.
Order by field name ascending.
Order by field name descending.
-
django_elasticsearch_dsl_drf.tests.test_ordering_geo_spatial module¶
Test geo-spatial ordering filter backend.
-
class
django_elasticsearch_dsl_drf.tests.test_ordering_geo_spatial.TestOrderingGeoSpatial(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest ordering geo-spatial.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
test_field_filter_geo_distance()[source]¶ Field filter geo_distance.
Example:
http://localhost:8000 /api/publisher/?ordering=location|48.85|2.30|km|plane
-
django_elasticsearch_dsl_drf.tests.test_pagination module¶
Test pagination.
-
class
django_elasticsearch_dsl_drf.tests.test_pagination.TestPagination(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest pagination.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
django_elasticsearch_dsl_drf.tests.test_search module¶
Test search backend.
-
class
django_elasticsearch_dsl_drf.tests.test_search.TestSearch(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest search.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
django_elasticsearch_dsl_drf.tests.test_suggesters module¶
Test suggestions backend.
-
class
django_elasticsearch_dsl_drf.tests.test_suggesters.TestSuggesters(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCase,django_elasticsearch_dsl_drf.tests.data_mixins.AddressesMixinTest suggesters.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
django_elasticsearch_dsl_drf.tests.test_views module¶
Test views.
-
class
django_elasticsearch_dsl_drf.tests.test_views.TestViews(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest views.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
Module contents¶
Tests.
-
class
django_elasticsearch_dsl_drf.tests.TestFacetedSearch(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest faceted search.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
-
class
django_elasticsearch_dsl_drf.tests.TestFilteringCommon(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCase,django_elasticsearch_dsl_drf.tests.data_mixins.AddressesMixin,django_elasticsearch_dsl_drf.tests.data_mixins.BooksMixinTest filtering common.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
test_field_filter_gt_with_boost()[source]¶ Field filter gt with boost.
Example:
http://localhost:8000/api/users/?id__gt=10|2.0Returns:
-
test_field_filter_in()[source]¶ Test filter in.
Example:
http://localhost:8000/api/articles/?id__in=1|2|3
-
test_field_filter_lt_with_boost()[source]¶ Field filter lt with boost.
Example:
http://localhost:8000/api/users/?id__lt=10|2.0Returns:
-
test_field_filter_range()[source]¶ Field filter range.
Example:
http://localhost:8000/api/users/?age__range=16|67
-
test_field_filter_range_with_boost()[source]¶ Field filter range.
Example:
http://localhost:8000/api/users/?age__range=16|67|2.0
-
test_field_filter_terms_string()[source]¶ Test filter terms.
Example:
http://localhost:8000/api/articles/?id__terms=1|2|3
-
-
class
django_elasticsearch_dsl_drf.tests.TestFilteringGeoSpatial(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest filtering geo-spatial.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
test_field_filter_geo_bounding_box_fail_test()[source]¶ Test field filter geo-bounding-box (fail test).
Returns:
-
test_field_filter_geo_distance()[source]¶ Field filter geo-distance.
Example:
http://localhost:8000 /api/publisher/?location__geo_distance=1km|48.8549|2.3000
-
-
class
django_elasticsearch_dsl_drf.tests.TestHelpers(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseTestCaseTest helpers.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
-
class
django_elasticsearch_dsl_drf.tests.TestOrdering(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest ordering.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
Author order by default.
Order by field name ascending.
Order by field id descending.
Order by field name ascending.
Order by field name descending.
-
-
class
django_elasticsearch_dsl_drf.tests.TestOrderingGeoSpatial(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest ordering geo-spatial.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
test_field_filter_geo_distance()[source]¶ Field filter geo_distance.
Example:
http://localhost:8000 /api/publisher/?ordering=location|48.85|2.30|km|plane
-
-
class
django_elasticsearch_dsl_drf.tests.TestPagination(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest pagination.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
-
class
django_elasticsearch_dsl_drf.tests.TestSearch(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest search.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
-
class
django_elasticsearch_dsl_drf.tests.TestSerializers(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest serializers.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
-
class
django_elasticsearch_dsl_drf.tests.TestViews(methodName='runTest')[source]¶ Bases:
django_elasticsearch_dsl_drf.tests.base.BaseRestFrameworkTestCaseTest views.
-
pytestmark= [<MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>, <MarkDecorator 'django_db' {'kwargs': {}, 'args': ()}>]¶
-
Submodules¶
django_elasticsearch_dsl_drf.apps module¶
Apps.
django_elasticsearch_dsl_drf.compat module¶
Transitional compatibility module. Contains various field wrappers and helpers for painless (testing of) Elastic 2.x to Elastic 5.x transition. This module is not supposed to solve all transition issues for you. Better move to Elastic 5.x as soon as possible.
-
django_elasticsearch_dsl_drf.compat.get_elasticsearch_version(default=(2, 0, 0))[source]¶ Get Elasticsearch version.
Parameters: default (tuple) – Default value. Mainly added for building the docs when Elasticsearch is not running. Returns: Return type: list
-
django_elasticsearch_dsl_drf.compat.KeywordField(**kwargs)¶ Keyword field.
Parameters: kwargs – Returns:
-
django_elasticsearch_dsl_drf.compat.StringField(**kwargs)¶ String field.
Parameters: kwargs – Returns:
django_elasticsearch_dsl_drf.constants module¶
Constants module. Contains Elasticsearch constants, lookup constants, functional constants, suggesters, etc.
django_elasticsearch_dsl_drf.helpers module¶
Helpers.
-
django_elasticsearch_dsl_drf.helpers.get_document_for_model(model)[source]¶ Get document for model given.
Parameters: model (Subclass of django.db.models.Model.) – Model to get document index for. Returns: Document index for the given model. Return type: Subclass of django_elasticsearch_dsl.DocType.
-
django_elasticsearch_dsl_drf.helpers.get_index_and_mapping_for_model(model)[source]¶ Get index and mapping for model.
Parameters: model (Subclass of django.db.models.Model.) – Django model for which to get index and mapping for. Returns: Index and mapping values. Return type: tuple.
-
django_elasticsearch_dsl_drf.helpers.more_like_this(obj, fields, max_query_terms=25, min_term_freq=2, min_doc_freq=5, max_doc_freq=0, query=None)[source]¶ More like this.
https://www.elastic.co/guide/en/elasticsearch/reference/current/ query-dsl-mlt-query.html
Parameters: - obj (Instance of django.db.models.Model (sub-classed) model.) – Django model instance for which similar objects shall be found.
- fields (list) – Fields to search in.
- max_query_terms (int) –
- min_term_freq (int) –
- min_doc_freq (int) –
- max_doc_freq (int) –
- query (elasticsearch_dsl.query.Q) – Q query
Returns: List of objects.
Return type: elasticsearch_dsl.search.Search
Example:
>>> from django_elasticsearch_dsl_drf.helpers import more_like_this >>> from books.models import Book >>> book = Book.objects.first() >>> similar_books = more_like_this( >>> book, >>> ['title', 'description', 'summary'] >>> )
-
django_elasticsearch_dsl_drf.helpers.sort_by_list(unsorted_dict, sorted_keys)[source]¶ Sort an OrderedDict by list of sorted keys.
Parameters: - unsorted_dict (collections.OrderedDict) – Source dictionary.
- sorted_keys (list) – Keys to sort on.
Returns: Sorted dictionary.
Return type: collections.OrderedDict
django_elasticsearch_dsl_drf.pagination module¶
Pagination.
-
class
django_elasticsearch_dsl_drf.pagination.LimitOffsetPagination(*args, **kwargs)[source]¶ Bases:
rest_framework.pagination.LimitOffsetPaginationA limit/offset pagination.
Example:
-
class
django_elasticsearch_dsl_drf.pagination.Page(object_list, number, paginator, facets)[source]¶ Bases:
django.core.paginator.PagePage for Elasticsearch.
-
class
django_elasticsearch_dsl_drf.pagination.PageNumberPagination(*args, **kwargs)[source]¶ Bases:
rest_framework.pagination.PageNumberPaginationPage number pagination.
A simple page number based style that supports page numbers as query parameters.
Example:
django_elasticsearch_dsl_drf.serializers module¶
Serializers.
-
class
django_elasticsearch_dsl_drf.serializers.DocumentSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)[source]¶ Bases:
rest_framework.serializers.SerializerA dynamic DocumentSerializer class.
django_elasticsearch_dsl_drf.utils module¶
Utils.
django_elasticsearch_dsl_drf.views module¶
django_elasticsearch_dsl_drf.viewsets module¶
Base ViewSets.
Module contents¶
Integrate Elasticsearch DSL with Django REST framework.