API Documentation¶

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

Search¶

class elasticsearch_dsl.Search(**kwargs)¶

Search 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).

count()¶: Return the number of hits matching the query and filters. Note that only the actual number is returned.

execute(ignore_cache=False)¶

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

Parameters:	response_class – optional subclass of `Response` to use instead.

execute_suggest()¶: Execute just the suggesters. Ignores all parts of the request that are not relevant, including query and doc_type.

classmethod from_dict(d)¶

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

Example:

s = Search.from_dict({
    "query": {
        "bool": {
            "must": [...]
        }
    },
    "aggs": {...}
})
s = s.filter('term', published=True)

highlight(*fields, **kwargs)¶

Request highlighting of some fields. All keyword arguments passed in will be used as parameters. Example:

Search().highlight('title', 'body', fragment_size=50)

will produce the equivalent of:

{
    "highlight": {
        "fields": {
            "body": {"fragment_size": 50},
            "title": {"fragment_size": 50}
        }
    }
}

highlight_options(**kwargs)¶

Update the global highlighting options used for this request. For example:

s = Search()
s = s.highlight_options(order='score')

response_class(cls)¶: Override the default wrapper used for the response.

scan()¶

Turn the search into a scan search and return a generator that will iterate over all the documents matching the query.

Use params method to specify any additional arguments you with to pass to the underlying scan helper from elasticsearch-py - https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan

script_fields(**kwargs)¶

Define script fields to be calculated on hits. See https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-script-fields.html for more details.

Example:

s = Search()
s = s.script_fields(times_two="doc['field'].value * 2")
s = s.script_fields(
    times_three={
        'script': "doc['field'].value * n",
        'params': {'n': 3}
    }
)

sort(*keys)¶

Add sorting information to the search request. If called without arguments it will remove all sort requirements. Otherwise it will replace them. Acceptable arguments are:

'some.field'
'-some.other.field'
{'different.field': {'any': 'dict'}}

so for example:

s = Search().sort(
    'category',
    '-title',
    {"price" : {"order" : "asc", "mode" : "avg"}}
)

will sort by category, title (in descending order) and price in ascending order using the avg mode.

The API returns a copy of the Search object and can thus be chained.

source(fields=None, **kwargs)¶

Selectively control how the _source field is returned.

Parameters:	source – wildcard string, array of wildcards, or dictionary of includes and excludes

If source is None, the entire document will be returned for each hit. If source is a dictionary with keys of ‘include’ and/or ‘exclude’ the fields will be either included or excluded appropriately.

Calling this multiple times with the same named parameter will override the previous values with the new ones.

Example:

s = Search()
s = s.source(include=['obj1.*'], exclude=["*.description"])

s = Search()
s = s.source(include=['obj1.*']).source(exclude=["*.description"])

suggest(name, text, **kwargs)¶

Add a suggestions request to the search.

Parameters:	name – name of the suggestion text – text to suggest on

All keyword arguments will be added to the suggestions body. For example:

s = Search()
s = s.suggest('suggestion-1', 'Elasticsearch', term={'field': 'body'})

to_dict(count=False, **kwargs)¶

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

Parameters:	count – a flag to specify we are interested in a body for count - no aggregations, no pagination bounds etc.

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.

class elasticsearch_dsl.MultiSearch(**kwargs)¶

Combine multiple Search objects into a single request.

add(search)¶

Adds a new Search object to the request:

ms = MultiSearch(index='my-index')
ms = ms.add(Search(doc_type=Category).filter('term', category='python'))
ms = ms.add(Search(doc_type=Blog))

execute(ignore_cache=False, raise_on_error=True)¶: Execute the multi search request and return a list of search results.

Document¶

class elasticsearch_dsl.DocType(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 `DocType` 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 from_es(hit)¶: Helper method to construct an instance from a dictionary returned by elasticsearch.

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

Retrieve a single document from elasticsearch using it’s id.

Parameters:	id – `id` of the document to be retireved index – elasticsearch index to use, if the `DocType` 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 retireved 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 DocType 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, **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 `DocType` 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

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

classmethod search(using=None, index=None)¶: Create an Search instance that will search over this DocType.

to_dict(include_meta=False)¶

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`, `_type`, `_id` etc). Otherwise just the document’s data is serialized. This is useful when passing multiple instances into `elasticsearch.helpers.bulk`.

update(using=None, index=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 `DocType` 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.update unchanged.

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)})

analyzer(analyzer)¶

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)

clone(name, 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(**kwargs)¶

Closes the index in elasticsearch.

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

create(**kwargs)¶

Creates the index in elasticsearch.

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

delete(**kwargs)¶

Deletes the index in elasticsearch.

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

doc_type(doc_type)¶

Associate a DocType subclass with an index. This means that, when this index is created, it will contain the mappings fo the DocType. If the DocType class doesn’t have a default index yet, name of the Index instance will be used. Can be used as a decorator:

i = Index('blog')

@i.doc_type
class Post(DocType):
    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(**kwargs)¶

Returns True if the index already exists in elasticsearch.

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

flush(**kwargs)¶

Preforms a flush operation on the index.

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

open(**kwargs)¶

Opens the index in elasticsearch.

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

refresh(**kwargs)¶

Preforms a refresh operation on the index.

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

search()¶: Rteurn a Search object searching over this index and its DocTypes.

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.

Faceted Search¶

class elasticsearch_dsl.FacetedSearch(query=None, filters={}, sort=None)¶

Abstraction for creating faceted navigation searches that takes care of composing the queries, aggregations and filters as needed as well as presenting the results in an easy-to-consume fashion:

class BlogSearch(FacetedSearch):
    index = 'blogs'
    doc_types = [Blog, Post]
    fields = ['title^5', 'category', 'description', 'body']

    facets = {
        'type': TermsFacet(field='_type'),
        'category': TermsFacet(field='category'),
        'weekly_posts': DateHistogramFacet(field='published_from', interval='week')
    }

    def search(self):
        ' Override search to add your own filters '
        s = super(BlogSearch, self).search()
        return s.filter('term', published=True)

# when using:
blog_search = BlogSearch("web framework", filters={"category": "python"})

# supports pagination
blog_search[10:20]

response = blog_search.execute()

# easy access to aggregation results:
for category, hit_count, is_selected in response.facets.category:
    print(
        "Category %s has %d hits%s." % (
            category,
            hit_count,
            ' and is chosen' if is_selected else ''
        )
    )

Parameters:	query – the text to search for filters – facet values to filter sort – sort information to be passed to `Search`

add_filter(name, filter_values)¶: Add a filter for a facet.

aggregate(search)¶: Add aggregations representing the facets selected, including potential filters.

build_search()¶: Construct the Search object.

execute()¶: Execute the search and return the response.

filter(search)¶: Add a post_filter to the search request narrowing the results based on the facet filters.

highlight(search)¶: Add highlighting for all the fields

query(search, query)¶

Add query part to search.

Override this if you wish to customize the query used.

search()¶: Construct the Search object.

sort(search)¶: Add sorting information to the request.