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
anddoc_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 underlyingscan
helper fromelasticsearch-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) andprice
in ascending order using theavg
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.- index – elasticsearch index to use, if the
-
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.- id –
-
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
id
s. Returns a list of instances in the same order as requested.Parameters: - docs – list of
id
s 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'
(useNone
),'raise'
(raiseNotFoundError
) or'skip'
(ignore the missing document).
Any additional keyword arguments will be passed to
Elasticsearch.mget
unchanged.- docs – list of
-
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.- index – elasticsearch index to use, if the
-
classmethod
search
(using=None, index=None)¶ Create an
Search
instance that will search over thisDocType
.
-
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 intoelasticsearch.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 – elasticsearch index to use, if the
-
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 theDocType
. If theDocType
class doesn’t have a default index yet, name of theIndex
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.
-
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.