API Documentation

Below please find the documentation for the public classes and functions of elasticsearch_dsl.

Document

class elasticsearch_dsl.Document(meta=None, **kwargs)

Model-like class for persisting documents in elasticsearch.

delete(using=None, index=None, **kwargs)

Delete the instance in elasticsearch.

Parameters:
  • index – elasticsearch index to use, if the Document is associated with an index this can be omitted.
  • using – connection alias to use, defaults to 'default'

Any additional keyword arguments will be passed to Elasticsearch.delete unchanged.

classmethod get(id, using=None, index=None, **kwargs)

Retrieve a single document from elasticsearch using its id.

Parameters:
  • id – id of the document to be retrieved
  • index – elasticsearch index to use, if the Document is associated with an index this can be omitted.
  • using – connection alias to use, defaults to 'default'

Any additional keyword arguments will be passed to Elasticsearch.get unchanged.

classmethod init(index=None, using=None)

Create the index and populate the mappings in elasticsearch.

classmethod mget(docs, using=None, index=None, raise_on_error=True, missing='none', **kwargs)

Retrieve multiple document by their ids. Returns a list of instances in the same order as requested.

Parameters:
  • docs – list of ids of the documents to be retrieved or a list of document specifications as per https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html
  • index – elasticsearch index to use, if the Document is associated with an index this can be omitted.
  • using – connection alias to use, defaults to 'default'
  • missing – what to do when one of the documents requested is not found. Valid options are 'none' (use None), 'raise' (raise NotFoundError) or 'skip' (ignore the missing document).

Any additional keyword arguments will be passed to Elasticsearch.mget unchanged.

save(using=None, index=None, validate=True, skip_empty=True, **kwargs)

Save the document into elasticsearch. If the document doesn’t exist it is created, it is overwritten otherwise. Returns True if this operations resulted in new document being created.

Parameters:
  • index – elasticsearch index to use, if the Document is associated with an index this can be omitted.
  • using – connection alias to use, defaults to 'default'
  • validate – set to False to skip validating the document
  • skip_empty – if set to False will cause empty values (None, [], {}) to be left on the document. Those values will be stripped out otherwise as they make no difference in elasticsearch.

Any additional keyword arguments will be passed to Elasticsearch.index unchanged.

:return operation result created/updated

classmethod search(using=None, index=None)

Create an Search instance that will search over this Document.

to_dict(include_meta=False, skip_empty=True)

Serialize the instance into a dictionary so that it can be saved in elasticsearch.

Parameters:
  • include_meta – if set to True will include all the metadata (_index, _id etc). Otherwise just the document’s data is serialized. This is useful when passing multiple instances into elasticsearch.helpers.bulk.
  • skip_empty – if set to False will cause empty values (None, [], {}) to be left on the document. Those values will be stripped out otherwise as they make no difference in elasticsearch.
update(using=None, index=None, detect_noop=True, doc_as_upsert=False, refresh=False, retry_on_conflict=None, script=None, script_id=None, scripted_upsert=False, upsert=None, **fields)

Partial update of the document, specify fields you wish to update and both the instance and the document in elasticsearch will be updated:

doc = MyDocument(title='Document Title!')
doc.save()
doc.update(title='New Document Title!')
Parameters:
  • index – elasticsearch index to use, if the Document is associated with an index this can be omitted.
  • using – connection alias to use, defaults to 'default'
  • detect_noop – Set to False to disable noop detection.
  • refresh – Control when the changes made by this request are visible to search. Set to True for immediate effect.
  • retry_on_conflict – In between the get and indexing phases of the update, it is possible that another process might have already updated the same document. By default, the update will fail with a version conflict exception. The retry_on_conflict parameter controls how many times to retry the update before finally throwing an exception.
  • doc_as_upsert – Instead of sending a partial doc plus an upsert doc, setting doc_as_upsert to true will use the contents of doc as the upsert value

:return operation result noop/updated

Index

class elasticsearch_dsl.Index(name, using='default')
Parameters:
  • name – name of the index
  • using – connection alias to use, defaults to 'default'
aliases(**kwargs)

Add aliases to the index definition:

i = Index('blog-v2')
i.aliases(blog={}, published={'filter': Q('term', published=True)})
analyze(using=None, **kwargs)

Perform the analysis process on a text and return the tokens breakdown of the text.

Any additional keyword arguments will be passed to Elasticsearch.indices.analyze unchanged.

analyzer(*args, **kwargs)

Explicitly add an analyzer to an index. Note that all custom analyzers defined in mappings will also be created. This is useful for search analyzers.

Example:

from elasticsearch_dsl import analyzer, tokenizer

my_analyzer = analyzer('my_analyzer',
    tokenizer=tokenizer('trigram', 'nGram', min_gram=3, max_gram=3),
    filter=['lowercase']
)

i = Index('blog')
i.analyzer(my_analyzer)
clear_cache(using=None, **kwargs)

Clear all caches or specific cached associated with the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.clear_cache unchanged.

clone(name=None, using=None)

Create a copy of the instance with another name or connection alias. Useful for creating multiple indices with shared configuration:

i = Index('base-index')
i.settings(number_of_shards=1)
i.create()

i2 = i.clone('other-index')
i2.create()
Parameters:
  • name – name of the index
  • using – connection alias to use, defaults to 'default'
close(using=None, **kwargs)

Closes the index in elasticsearch.

Any additional keyword arguments will be passed to Elasticsearch.indices.close unchanged.

create(using=None, **kwargs)

Creates the index in elasticsearch.

Any additional keyword arguments will be passed to Elasticsearch.indices.create unchanged.

delete(using=None, **kwargs)

Deletes the index in elasticsearch.

Any additional keyword arguments will be passed to Elasticsearch.indices.delete unchanged.

delete_alias(using=None, **kwargs)

Delete specific alias.

Any additional keyword arguments will be passed to Elasticsearch.indices.delete_alias unchanged.

document(document)

Associate a Document subclass with an index. This means that, when this index is created, it will contain the mappings for the Document. If the Document class doesn’t have a default index yet (by defining class Index), this instance will be used. Can be used as a decorator:

i = Index('blog')

@i.document
class Post(Document):
    title = Text()

# create the index, including Post mappings
i.create()

# .search() will now return a Search object that will return
# properly deserialized Post instances
s = i.search()
exists(using=None, **kwargs)

Returns True if the index already exists in elasticsearch.

Any additional keyword arguments will be passed to Elasticsearch.indices.exists unchanged.

exists_alias(using=None, **kwargs)

Return a boolean indicating whether given alias exists for this index.

Any additional keyword arguments will be passed to Elasticsearch.indices.exists_alias unchanged.

exists_type(using=None, **kwargs)

Check if a type/types exists in the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.exists_type unchanged.

flush(using=None, **kwargs)

Performs a flush operation on the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.flush unchanged.

flush_synced(using=None, **kwargs)

Perform a normal flush, then add a generated unique marker (sync_id) to all shards.

Any additional keyword arguments will be passed to Elasticsearch.indices.flush_synced unchanged.

forcemerge(using=None, **kwargs)

The force merge API allows to force merging of the index through an API. The merge relates to the number of segments a Lucene index holds within each shard. The force merge operation allows to reduce the number of segments by merging them.

This call will block until the merge is complete. If the http connection is lost, the request will continue in the background, and any new requests will block until the previous force merge is complete.

Any additional keyword arguments will be passed to Elasticsearch.indices.forcemerge unchanged.

get(using=None, **kwargs)

The get index API allows to retrieve information about the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.get unchanged.

get_alias(using=None, **kwargs)

Retrieve a specified alias.

Any additional keyword arguments will be passed to Elasticsearch.indices.get_alias unchanged.

get_field_mapping(using=None, **kwargs)

Retrieve mapping definition of a specific field.

Any additional keyword arguments will be passed to Elasticsearch.indices.get_field_mapping unchanged.

get_mapping(using=None, **kwargs)

Retrieve specific mapping definition for a specific type.

Any additional keyword arguments will be passed to Elasticsearch.indices.get_mapping unchanged.

get_settings(using=None, **kwargs)

Retrieve settings for the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.get_settings unchanged.

get_upgrade(using=None, **kwargs)

Monitor how much of the index is upgraded.

Any additional keyword arguments will be passed to Elasticsearch.indices.get_upgrade unchanged.

mapping(mapping)

Associate a mapping (an instance of Mapping) with this index. This means that, when this index is created, it will contain the mappings for the document type defined by those mappings.

open(using=None, **kwargs)

Opens the index in elasticsearch.

Any additional keyword arguments will be passed to Elasticsearch.indices.open unchanged.

put_alias(using=None, **kwargs)

Create an alias for the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.put_alias unchanged.

put_mapping(using=None, **kwargs)

Register specific mapping definition for a specific type.

Any additional keyword arguments will be passed to Elasticsearch.indices.put_mapping unchanged.

put_settings(using=None, **kwargs)

Change specific index level settings in real time.

Any additional keyword arguments will be passed to Elasticsearch.indices.put_settings unchanged.

recovery(using=None, **kwargs)

The indices recovery API provides insight into on-going shard recoveries for the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.recovery unchanged.

refresh(using=None, **kwargs)

Performs a refresh operation on the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.refresh unchanged.

save(using=None)

Sync the index definition with elasticsearch, creating the index if it doesn’t exist and updating its settings and mappings if it does.

Note some settings and mapping changes cannot be done on an open index (or at all on an existing index) and for those this method will fail with the underlying exception.

search(using=None)

Return a Search object searching over the index (or all the indices belonging to this template) and its Documents.

segments(using=None, **kwargs)

Provide low level segments information that a Lucene index (shard level) is built with.

Any additional keyword arguments will be passed to Elasticsearch.indices.segments unchanged.

settings(**kwargs)

Add settings to the index:

i = Index('i')
i.settings(number_of_shards=1, number_of_replicas=0)

Multiple calls to settings will merge the keys, later overriding the earlier.

shard_stores(using=None, **kwargs)

Provides store information for shard copies of the index. Store information reports on which nodes shard copies exist, the shard copy version, indicating how recent they are, and any exceptions encountered while opening the shard index or from earlier engine failure.

Any additional keyword arguments will be passed to Elasticsearch.indices.shard_stores unchanged.

shrink(using=None, **kwargs)

The shrink index API allows you to shrink an existing index into a new index with fewer primary shards. The number of primary shards in the target index must be a factor of the shards in the source index. For example an index with 8 primary shards can be shrunk into 4, 2 or 1 primary shards or an index with 15 primary shards can be shrunk into 5, 3 or 1. If the number of shards in the index is a prime number it can only be shrunk into a single primary shard. Before shrinking, a (primary or replica) copy of every shard in the index must be present on the same node.

Any additional keyword arguments will be passed to Elasticsearch.indices.shrink unchanged.

stats(using=None, **kwargs)

Retrieve statistics on different operations happening on the index.

Any additional keyword arguments will be passed to Elasticsearch.indices.stats unchanged.

updateByQuery(using=None)

Return a UpdateByQuery object searching over the index (or all the indices belonging to this template) and updating Documents that match the search criteria.

For more information, see here: https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html

upgrade(using=None, **kwargs)

Upgrade the index to the latest format.

Any additional keyword arguments will be passed to Elasticsearch.indices.upgrade unchanged.

validate_query(using=None, **kwargs)

Validate a potentially expensive query without executing it.

Any additional keyword arguments will be passed to Elasticsearch.indices.validate_query unchanged.

Update By Query

class elasticsearch_dsl.UpdateByQuery(**kwargs)

Update by query request to elasticsearch.

Parameters:
  • using – Elasticsearch instance to use
  • index – limit the search to index
  • doc_type – only query this type.

All the parameters supplied (or omitted) at creation type can be later overriden by methods (using, index and doc_type respectively).

execute()

Execute the search and return an instance of Response wrapping all the data.

classmethod from_dict(d)

Construct a new UpdateByQuery instance from a raw dict containing the search body. Useful when migrating from raw dictionaries.

Example:

ubq = UpdateByQuery.from_dict({
    "query": {
        "bool": {
            "must": [...]
        }
    },
    "script": {...}
})
ubq = ubq.filter('term', published=True)
response_class(cls)

Override the default wrapper used for the response.

script(**kwargs)

Define update action to take: https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-using.html for more details.

Note: the API only accepts a single script, so calling the script multiple times will overwrite.

Example:

ubq = Search()
ubq = ubq.script(source="ctx._source.likes++"")
ubq = ubq.script(source="ctx._source.likes += params.f"",
             lang="expression",
             params={'f': 3})
to_dict(**kwargs)

Serialize the search into the dictionary that will be sent over as the request’ubq body.

All additional keyword arguments will be included into the dictionary.

update_from_dict(d)

Apply options from a serialized body to the current instance. Modifies the object in-place. Used mostly by from_dict.

Mappings

If you wish to create mappings manually you can use the Mapping class, for more advanced use cases, however, we recommend you use the Document abstraction in combination with Index (or IndexTemplate) to define index-level settings and properties. The mapping definition follows a similar pattern to the query dsl:

from elasticsearch_dsl import Keyword, Mapping, Nested, Text

# name your type
m = Mapping('my-type')

# add fields
m.field('title', 'text')

# you can use multi-fields easily
m.field('category', 'text', fields={'raw': Keyword()})

# you can also create a field manually
comment = Nested(
                 properties={
                    'author': Text(),
                    'created_at': Date()
                 })

# and attach it to the mapping
m.field('comments', comment)

# you can also define mappings for the meta fields
m.meta('_all', enabled=False)

# save the mapping into index 'my-index'
m.save('my-index')

Note

By default all fields (with the exception of Nested) will expect single values. You can always override this expectation during the field creation/definition by passing in multi=True into the constructor (m.field('tags', Keyword(multi=True))). Then the value of the field, even if the field hasn’t been set, will be an empty list enabling you to write doc.tags.append('search').

Especially if you are using dynamic mappings it might be useful to update the mapping based on an existing type in Elasticsearch, or create the mapping directly from an existing type:

# get the mapping from our production cluster
m = Mapping.from_es('my-index', 'my-type', using='prod')

# update based on data in QA cluster
m.update_from_es('my-index', using='qa')

# update the mapping on production
m.save('my-index', using='prod')

Common field options:

multi
If set to True the field’s value will be set to [] at first access.
required
Indicates if a field requires a value for the document to be valid.