Django API docs

The S class

class elasticutils.contrib.django.S(mapping_type)

S that’s based on Django settings

This shows the Django-specific documentation. See elasticutils.S for more the rest.

__init__(mapping_type)

Create and return an S.

Parameters:mapping_type – class; the mapping type that this S is based on

Note

The elasticutils.S doesn’t require the mapping_type argument, but the elasticutils.contrib.django.S does.

get_doctypes(default_doctypes=None)

Returns the doctypes (or mapping type names) to use.

get_es(default_builder=<function get_es>)

Returns the elasticsearch Elasticsearch object to use.

This uses the django get_es builder by default which takes into account settings in settings.py.

get_indexes(default_indexes=None)

Returns the list of indexes to act on based on ES_INDEXES setting

The MappingType class

class elasticutils.contrib.django.MappingType

MappingType that ties to Django ORM models

You probably want to subclass this and override at least get_model().

This shows the Django-specific documentation. See elasticutils.MappingType for more the rest.

classmethod get_index()

Gets the index for this model.

The index for this model is specified in settings.ES_INDEXES which is a dict of mapping type -> index name.

By default, this uses .get_mapping_type() to determine the mapping and returns the value in settings.ES_INDEXES for that or settings.ES_INDEXES['default'].

Override this to compute it differently.

Returns:index name to use
classmethod get_mapping_type_name()

Returns the name of the mapping.

By default, this is:

cls.get_model()._meta.db_table

Override this if you want to compute the mapping type name differently.

Returns:mapping type string
classmethod get_model()

Return the model related to this DjangoMappingType.

This can be any class that has an instance related to this DjangoMappingtype by id.

Override this to return a model class.

Returns:model class
get_object()

Returns the database object for this result

By default, this is:

self.get_model().objects.get(pk=self._id)
classmethod search()

Returns a typed S for this class.

Returns:an S for this DjangoMappingType

The Indexable class

class elasticutils.contrib.django.Indexable

MappingType mixin that has indexing bits

Add this mixin to your MappingType subclass and it gives you super indexing power.

This shows the Django-specific documentation. See elasticutils.Indexable for more the rest.

classmethod get_es(**overrides)

Returns an ElasticSearch object using Django settings

Override this if you need special functionality.

Parameters:overrides – Allows you to override defaults to create the ElasticSearch object. You can override any of the arguments listed in elasticutils.get_es().
Returns:a elasticsearch Elasticsearch instance
classmethod get_indexable()

Returns the queryset of ids of all things to be indexed.

Defaults to:

cls.get_model().objects.order_by('id').values_list(
    'id', flat=True)
Returns:iterable of ids of objects to be indexed

View decorators

elasticutils.contrib.django.es_required(fun)

Wrap a callable and return None if ES_DISABLED is False.

This also adds an additional es argument to the callable giving you an ElasticSearch instance to use.

elasticutils.contrib.django.es_required_or_50x(*m_args, **m_kwargs)

The ESExceptionMiddleware class

class elasticutils.contrib.django.ESExceptionMiddleware(disabled_template=None, error_template=None)

Middleware to handle Elasticsearch errors.

HTTP 501
Returned when ES_DISABLED is True.
HTTP 503

Returned when any elasticsearch exception is thrown.

Template variables:

  • error: A string version of the exception thrown.
Parameters:
  • disabled_template –

    The template to use when ES_DISABLED is True.

    Defaults to elasticutils/501.html.

  • error_template –

    The template to use when Elasticsearch isn’t working properly, is missing an index, or something along those lines.

    Defaults to elasticutils/503.html.

Note

In order to use the included templates, you must add elasticutils.contrib.django to INSTALLED_APPS.

Tasks

elasticutils.contrib.django.tasks.index_objects(model, ids=[...])

Index documents of a specified mapping type.

This allows for asynchronous indexing.

If a mapping_type extends Indexable, you can add a post_save hook for the model that it’s based on like this:

@receiver(dbsignals.post_save, sender=MyModel)
def update_in_index(sender, instance, **kw):
    from elasticutils.contrib.django import tasks
    tasks.index_objects.delay(MyMappingType, [instance.id])
Parameters:
  • mapping_type – the mapping type for these ids
  • ids – the list of ids of things to index
  • chunk_size –

    the size of the chunk for bulk indexing

    Note

    The default chunk_size is 100. The number of documents you can bulk index at once depends on the size of the documents.

  • es – The Elasticsearch to use. If you don’t specify an Elasticsearch, it’ll use mapping_type.get_es().
  • index – The name of the index to use. If you don’t specify one it’ll use mapping_type.get_index().

The ESTestCase class

Subclass this and make it do what you need it to do. It’s definitely worth reading the code.

class elasticutils.contrib.django.estestcase.ESTestCase(methodName='runTest')

Test case scaffolding for ElasticUtils-using tests.

If ES_URLS is empty or missing or you can’t connect to Elasticsearch specified in ES_URLS, then this will skip each individual test. This works with py.test, nose, and unittest in Python 2.7. If you don’t have one of those, then this will print to stdout and just skip the test silently.

classmethod create_index(index, settings=None)

Creates index with given settings

Parameters:
  • index – the name of the index to create
  • settings – dict of settings to set in create_index call
classmethod get_es()

Returns an ES

Override this if you need different settings for your ES.

classmethod index_data(documents, index, doctype, id_field='id')

Bulk indexes given data.

This does a refresh after the data is indexed.

Parameters:
  • documents – list of python dicts each a document to index
  • index – name of the index
  • doctype – mapping type name
  • id_field – the field the document id is stored in in the document
classmethod refresh(index)

Refresh index after indexing.

Parameters:index – the name of the index to refresh. use _all to refresh all of them
setUp()

Skips the test if this class is skipping tests.

classmethod setUpClass()

Sets up the environment for ES tests

  • pings the ES server—if this fails, it marks all the tests for skipping
  • fixes settings
  • deletes the test index if there is one
classmethod tearDownClass()

Tears down environment

  • unfixes settings
  • deletes the test index