Elasticsearch DSL¶

Manual¶

If you don’t wish to supply global configuration you can always pass in your own connection (instance of elasticsearch.Elasticsearch) as parameter using wherever it is accepted:

s = Search(using=Elasticsearch('localhost'))

You can even use this approach to override any connection the object might be already associated with:

s = s.using(Elasticsearch('otherhost:9200'))

Default connection¶

To define a default connection that will be used globally, use the connections module and the create_connection method:

from elasticsearch_dsl.connections import connections

connections.create_connection(hosts=['localhost'], timeout=20)

Any keyword arguments (hosts and timeout in our example) will be passed to the Elasticsearch class from elasticsearch-py. To see all the possible configuration options see the documentation.

Multiple clusters¶

You can define multiple connections to multiple clusters, either at the same time using the configure method:

from elasticsearch_dsl.connections import connections

connections.configure(
    default={'hosts': 'localhost'},
    dev={
        'hosts': ['esdev1.example.com:9200'],
        'sniff_on_start': True
    }
)

Such connections will be constructed lazily when requested for the first time.

Or just add them one by one:

# if you have configuration to be passed to Elasticsearch.__init__
connections.create_connection('qa', hosts=['esqa1.example.com'], sniff_on_start=True)

# if you already have an Elasticsearch instance ready
connections.add_connection('qa', my_client)

s = Search(using='qa')

The Search object¶

The Search object represents the entire search request:

• queries
• filters
• aggregations
• sort
• pagination
• additional parameters
• associated client

The API is designed to be chainable. With the exception of the aggregations functionality this means that the Search object is immutable - all changes to the object will result in a copy being created which contains the changes. This means you can safely pass the Search object to foreign code without fear of it modifying your objects.

You can pass an instance of the low-level elasticsearch client when instantiating the Search object:

from elasticsearch import Elasticsearch
from elasticsearch_dsl import Search

client = Elasticsearch()

s = Search(using=client)

You can also define the client at a later time (for more options see the ~:ref:connections chapter):

s = s.using(client)

The API is chainable, allowing you to combine multiple method calls in one statement:

s = Search().using(client).query("match", title="python")

To send the request to Elasticsearch:

response = s.execute()

If you just want to iterate over the hits returned by your search you can iterate over the Search object:

for hit in s:
    print(hit.title)

Search results will be cached. Subsequent calls to execute or trying to iterate over an already executed Search object will not trigger additional requests being sent to Elasticsearch. To force a request specify ignore_cache=True when calling execute.

For debugging purposes you can serialize the Search object to a dict explicitly:

print(s.to_dict())

from elasticsearch_dsl.query import MultiMatch, Match

# {"multi_match": {"query": "python django", "fields": ["title", "body"]}}
MultiMatch(query='python django', fields=['title', 'body'])

# {"match": {"title": {"query": "web framework", "type": "phrase"}}}
Match(title={"query": "web framework", "type": "phrase"})

Q("multi_match", query='python django', fields=['title', 'body'])
Q({"multi_match": {"query": "python django", "fields": ["title", "body"]}})

q = Q("multi_match", query='python django', fields=['title', 'body'])
s = s.query(q)

s = s.query("multi_match", query='python django', fields=['title', 'body'])

s.query = Q('bool', must=[Q('match', title='python'), Q('match', body='best')])

Q("match", title='python') | Q("match", title='django')
# {"bool": {"should": [...]}}

Q("match", title='python') & Q("match", title='django')
# {"bool": {"must": [...]}}

~Q("match", title="python")
# {"bool": {"must_not": [...]}}

s = s.query().query()
print(s.to_dict())
# {"query": {"bool": {...}}}

q = Q('bool',
    must=[Q('match', title='python')],
    should=[Q(...), Q(...)],
    minimum_should_match=1
)
s = Search().query(q)

s = Search()
s = s.filter('terms', tags=['search', 'python'])

s = Search()
s = s.query('bool', filter=[Q('terms', tags=['search', 'python'])])

A('terms', field='tags')
# {"terms": {"field": "tags"}}

a = A('terms', field='category')
# {'terms': {'field': 'category'}}

a.metric('clicks_per_category', 'sum', field='clicks')\
    .bucket('tags_per_category', 'terms', field='tags')
# {
#   'terms': {'field': 'category'},
#   'aggs': {
#     'clicks_per_category': {'sum': {'field': 'clicks'}},
#     'tags_per_category': {'terms': {'field': 'tags'}}
#   }
# }

s = Search()
a = A('terms', field='category')
s.aggs.bucket('category_terms', a)
# {
#   'aggs': {
#     'category_terms': {
#       'terms': {
#         'field': 'category'
#       }
#     }
#   }
# }

s = Search()
s.aggs.bucket('articles_per_day', 'date_histogram', field='publish_date', interval='day')\
    .metric('clicks_per_day', 'sum', field='clicks')\
    .pipeline('moving_click_average', 'moving_avg', buckets_path='clicks_per_day')\
    .bucket('tags_per_day', 'terms', field='tags')

s.to_dict()
# {
#   "aggs": {
#     "articles_per_day": {
#       "date_histogram": { "interval": "day", "field": "publish_date" },
#       "aggs": {
#         "clicks_per_day": { "sum": { "field": "clicks" } },
#         "moving_click_average": { "moving_avg": { "buckets_path": "clicks_per_day" } },
#         "tags_per_day": { "terms": { "field": "tags" } }
#       }
#     }
#   }
# }

s = Search()

s.aggs.bucket('per_category', 'terms', field='category')
s.aggs['per_category'].metric('clicks_per_category', 'sum', field='clicks')
s.aggs['per_category'].bucket('tags_per_category', 'terms', field='tags')

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

s = s.sort()

s = s[10:20]
# {"from": 10, "size": 10}

for hit in s.scan():
    print(hit.title)

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

s = s.highlight('title')
# or, including parameters:
s = s.highlight('title', fragment_size=50)

response = s.execute()
for hit in response:
    for fragment in hit.meta.highlight.title:
        print(fragment)

s = s.suggest('my_suggestion', 'pyhton', term={'field': 'title'})

s = s.suggest('my_suggestion', 'pyhton', term={'field': 'title'})
suggestions = s.execute_suggest()

print(suggestions.my_suggestion)

s = s.extra(explain=True)

s = s.params(search_type="count")

# only return the selected fields
s = s.source(['title', 'body'])
# don't return any fields, just the metadata
s = s.source(False)
# explicitly include/exclude fields
s = s.source(include=["title"], exclude=["user.*"])
# reset the field selection
s = s.source(None)

s = Search.from_dict({"query": {"match": {"title": "python"}}})

s = Search(index='i')
s.update_from_dict({"query": {"match": {"title": "python"}}, "size": 42})

Response¶

You can execute your search by calling the .execute() method that will return a Response object. The Response object allows you access to any key from the response dictionary via attribute access. It also provides some convenient helpers:

response = s.execute()

print(response.success())
# True

print(response.took)
# 12

print(response.hits.total)

print(response.suggest.my_suggestions)

If you want to inspect the contents of the response objects, just use its to_dict method to get access to the raw data for pretty printing.

response = s.execute()
print('Total %d hits found.' % response.hits.total)
for h in response:
    print(h.title, h.body)

response = s.execute()
h = response.hits[0]
print('/%s/%s/%s returned with score %f' % (
    h.meta.index, h.meta.doc_type, h.meta.id, h.meta.score))

for tag in response.aggregations.per_tag.buckets:
    print(tag.key, tag.max_lines.value)

MultiSearch¶

If you need to execute multiple searches at the same time you can use the MultiSearch class which will use the _msearch API:

from elasticsearch_dsl import MultiSearch, Search

ms = MultiSearch(index='blogs')

ms = ms.add(Search().filter('term', tags='python'))
ms = ms.add(Search().filter('term', tags='elasticsearch'))

responses = ms.execute()

for response in responses:
    print("Results for query %r." % response.search.query)
    for hit in response:
        print(hit.title)

Mappings¶

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()
comment.field('author', Text())
comment.field('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')

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.

Analysis¶

To specify analyzer values for Text fields you can just use the name of the analyzer (as a string) and either rely on the analyzer being defined (like built-in analyzers) or define the analyzer yourself manually.

Alternatively you can create your own analyzer and have the persistence layer handle its creation:

from elasticsearch_dsl import analyzer, tokenizer

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

Each analysis object needs to have a name (my_analyzer and trigram in our example) and tokenizers, token filters and char filters also need to specify type (nGram in our example).

DocType¶

If you want to create a model-like wrapper around your documents, use the DocType class:

from datetime import datetime
from elasticsearch_dsl import DocType, Date, Nested, Boolean, \
    analyzer, InnerObjectWrapper, Completion, Keyword, Text

html_strip = analyzer('html_strip',
    tokenizer="standard",
    filter=["standard", "lowercase", "stop", "snowball"],
    char_filter=["html_strip"]
)

class Comment(InnerObjectWrapper):
    def age(self):
        return datetime.now() - self.created_at

class Post(DocType):
    title = Text()
    title_suggest = Completion(payloads=True)
    created_at = Date()
    published = Boolean()
    category = Text(
        analyzer=html_strip,
        fields={'raw': Keyword()}
    )

    comments = Nested(
        doc_class=Comment,
        properties={
            'author': Text(fields={'raw': Keyword()}),
            'content': Text(analyzer='snowball'),
            'created_at': Date()
        }
    )

    class Meta:
        index = 'blog'

    def add_comment(self, author, content):
        self.comments.append(
          {'author': author, 'content': content})

    def save(self, ** kwargs):
        self.created_at = datetime.now()
        return super().save(** kwargs)

# create the mappings in Elasticsearch
Post.init()

# instantiate the document
first = Post(title='My First Blog Post, yay!', published=True)
# assign some field values, can be values or lists of values
first.category = ['everything', 'nothing']
# every document has an id in meta
first.meta.id = 47


# save the document into the cluster
first.save()

post = Post(meta={'id': 42})

# prints 42, same as post._id
print(post.meta.id)

# override default index, same as post._index
post.meta.index = 'my-blog'

# retrieve the document
first = Post.get(id=42)
# now we can call methods, change fields, ...
first.add_comment('me', 'This is nice!')
# and save the changes into the cluster again
first.save()

# you can also update just individual fields which will call the update API
# and also update the document in place
first.update(published=True, published_by='me')

p = Post.get(id='not-in-es', ignore=404)
p is None

posts = Post.mget([42, 47, 256])

# name of the type and index in elasticsearch
Post._doc_type.name
Post._doc_type.index

# the raw Mapping object
Post._doc_type.mapping

# the optional name of the parent type (if defined)
Post._doc_type.parent

Post._doc_type.refresh()

first = Post.get(id=42)
first.delete()

# by calling .search we get back a standard Search object
s = Post.search()
# the search is already limited to the index and doc_type of our document
s = s.filter('term', published=True).query('match', title='first')


results = s.execute()

# when you execute the search the results are wrapped in your document class (Post)
for post in results:
    print(post.meta.score, post.title)

s = Search()
s = s.doc_type(Post)

s = Post.search()
s = s.suggest('title_suggestions', 'pyth', completion={'field': 'title_suggest'})

# you can even execute just the suggestions via the _suggest API
suggestions = s.execute_suggest()

for result in suggestions.title_suggestions:
    print('Suggestions for %s:' % result.text)
    for option in result.options:
        print('  %s (%r)' % (option.text, option.payload))

class Post(DocType):
    title = Text()

    class Meta:
        all = MetaField(enabled=False)
        parent = MetaField(type='blog')
        dynamic = MetaField('strict')

Index¶

Index is a class responsible for holding all the metadata related to an index in elasticsearch - mappings and settings. It is most useful when defining your mappings since it allows for easy creation of multiple mappings at the same time. This is especially useful when setting up your elasticsearch objects in a migration:

from elasticsearch_dsl import Index, DocType, Text, analyzer

blogs = Index('blogs')

# define custom settings
blogs.settings(
    number_of_shards=1,
    number_of_replicas=0
)

# define aliases
blogs.aliases(
    old_blogs={}
)

# register a doc_type with the index
blogs.doc_type(Post)

# can also be used as class decorator when defining the DocType
@blogs.doc_type
class Post(DocType):
    title = Text()

# You can attach custom analyzers to the index

html_strip = analyzer('html_strip',
    tokenizer="standard",
    filter=["standard", "lowercase", "stop", "snowball"],
    char_filter=["html_strip"]
)

blog.analyzer(html_strip)

# delete the index, ignore if it doesn't exist
blogs.delete(ignore=404)

# create the index in elasticsearch
blogs.create()

You can also set up a template for your indices and use the clone method to create specific copies:

blogs = Index('blogs', using='production')
blogs.settings(number_of_shards=2)
blogs.doc_type(Post)

# create a copy of the index with different name
company_blogs = blogs.clone('company-blogs')

# create a different copy on different cluster
dev_blogs = blogs.clone('blogs', using='dev')
# and change its settings
dev_blogs.setting(number_of_shards=1)

Configuration¶

You can provide several configuration options (as class attributes) when declaring a FacetedSearch subclass:

index

the name of the index (as string) to search through, defaults to '_all'.

doc_types

list of DocType subclasses or strings to be used, defaults to ['_all'].

fields

list of fields on the document type to search through. The list will be passes to MultiMatch query so can contain boost values ('title^5'), defaults to ['*'].

facets

dictionary of facets to display/filter on. The key is the name displayed and values should be instances of any Facet subclass, for example: {'tags': TermsFacet(field='tags')}

Usage¶

The custom subclass can be instantiated empty to provide an empty search (matching everything) or with query and filters.

query

is used to pass in the text of the query to be performed. If None is passed in (default) a MatchAll query will be used. For example 'python web'

filters

is a dictionary containing all the facet filters that you wish to apply. Use the name of the facet (from .facets attribute) as the key and one of the possible values as value. For example {'tags': 'python'}.

Example¶

from datetime import date

from elasticsearch_dsl import FacetedSearch, TermsFacet, DateHistogramFacet

class BlogSearch(FacetedSearch):
    doc_types = [Article, ]
    # fields that should be searched
    fields = ['tags', 'title', 'body']

    facets = {
        # use bucket aggregations to define facets
        'tags': TermsFacet(field='tags'),
        'publishing_frequency': DateHistogramFacet(field='published_from', interval='month')
    }

    def search(self):
        # override methods to add custom pieces
        s = super().search()
        return s.filter('range', publish_from={'lte': 'now/h'})

bs = BlogSearch('python web', {'publishing_frequency': date(2015, 6)})
response = bs.execute()

# access hits and other attributes as usual
print(response.hits.total, 'hits total')
for hit in response:
    print(hit.meta.score, hit.title)

for (tag, count, selected) in response.facets.tags:
    print(tag, ' (SELECTED):' if selected else ':', count)

for (month, count, selected) in response.facets.publishing_frequency:
    print(month.strftime('%B %Y'), ' (SELECTED):' if selected else ':', count)

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.

5.1.0 (2017-01-08)¶

• Renamed Result and ResultMeta to Hit and HitMeta respectively
• Response now stores Search which it gets as first arg to __init__
• aggregation results are now wrapped in classes and properly deserialized
• Date fields now allow for numerical timestamps in the java format (in millis)
• Added API documentation
• replaced generated classes with manually created

5.0.0 (2016-11-04)¶

Version compatible with elasticsearch 5.0.

Breaking changes:

• String field type has been deprecated in favor of Text and Keyword
• fields method has been removed in favor of source filtering

2.2.0 (2016-11-04)¶

• accessing missing string fields no longer returnd '' but returns None instead.
• fix issues with bool’s | and & operators and minimum_should_match

2.1.0 (2016-06-29)¶

• inner_hits are now also wrapped in Response
• + operator is deprecated, .query() now uses & to combine queries
• added mget method to DocType
• fixed validation for “empty” values like '' and []

2.0.0 (2016-02-18)¶

Compatibility with Elasticsearch 2.x:

• Filters have been removed and additional queries have been added. Instead of F objects you can now use Q.
• Search.filter is now just a shortcut to add queries in filter context
• support for pipeline aggregations added

Backwards incompatible changes:

• list of analysis objects and classes was removed, any string used as tokenizer, char or token filter or analyzer will be treated as a builtin
• internal method Field.to_python has been renamed to deserialize and an optional serialization mechanic for fields has been added.
• Custom response class is now set by response_class method instead of a kwarg to Search.execute

Other changes:

• FacetedSearch now supports pagination via slicing

0.0.10 (2016-01-24)¶

• Search can now be iterated over to get back hits
• Search now caches responses from Elasticsearch
• DateHistogramFacet now defaults to returning empty intervals
• Search no longer accepts positional parameters
• Experimental MultiSearch API
• added option to talk to _suggest endpoint (execute_suggest)

0.0.9 (2015-10-26)¶

• FacetedSearch now uses its own Facet class instead of built in aggregations

0.0.8 (2015-08-28)¶

• 0.0.5 and 0.0.6 was released with broken .tar.gz on pypi, just a build fix

0.0.5 (2015-08-27)¶

• added support for (index/search)_analyzer via #143, thanks @wkiser!
• even keys accessed via ['field'] on AttrDict will be wrapped in Attr[Dict|List] for consistency
• Added a convenient option to specify a custom doc_class to wrap inner/Nested documents
• blank option has been removed
• AttributeError is no longer raised when accessing an empty field.
• added required flag to fields and validation hooks to fields and (sub)documents
• removed get method from AttrDict. Use getattr(d, key, default) instead.
• added FacetedSearch for easy declarative faceted navigation

0.0.4 (2015-04-24)¶

• Metadata fields (such as id, parent, index, version etc) must be stored (and retrieved) using the meta attribute (#58) on both Result and DocType objects or using their underscored variants (_id, _parent etc)
• query on Search can now be directly assigned
• suggest method added to Search
• Search.doc_type now accepts DocType subclasses directly
• Properties.property method renamed to field for consistency
• Date field now raises ValidationException on incorrect data

0.0.3 (2015-01-23)¶

Added persistence layer (Mapping and DocType), various fixes and improvements.

0.0.2 (2014-08-27)¶

Fix for python 2

0.0.1 (2014-08-27)¶

Initial release.