Search Query API

class elasticmagic.search.SearchQuery(q=None, cluster=None, index=None, doc_cls=None, doc_type=None, routing=None, preference=None, timeout=None, search_type=None, query_cache=None, terminate_after=None, scroll=None, stats=None, track_total_hits=None, **kwargs)

Elasticsearch search query construction object.

SearchQuery object is usually instantiated by calling Index.search_query() method.

See Index.search_query() for more details.

to_dict(compiler=None)

Compiles the query and returns python dictionary that can be serialized to json.

get_result()

Executes current query and returns processed SearchResult object. Caches result so subsequent calls with the same search query will return cached value.

count()

Executes current query and returns number of documents matched the query. Uses count api.

exists()

Executes current query optimized for checking that there are at least 1 matching document. This method is an analogue of the old exists search api For Elasticsearch 5.x and more it emulates the exists API using size=0 and terminate_after=1.

explain(doc_or_id, doc_cls=None, routing=None, **kwargs)

Computes a score explanation for the current search query and the document.

Returns:result.ExplainResult

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-explain.html

delete(conflicts=None, refresh=None, timeout=None, scroll=None, scroll_size=None, wait_for_completion=None, requests_per_second=None, **kwargs)

Deletes all documents that match the query.

Note

As it uses delete by query api the documents that were changed between the time when a snapshot was taken and when the delete request was processed won’t be deleted.

aggregations(*args, **kwargs)

Adds aggregations to the search query.

Parameters:*aggs – dictionaries with aggregations. Can be None that cleans up previous aggregations.

After executing the query you can get aggregation result by its name calling SearchResult.get_aggregation() method.

from elasticmagic import agg

search_query = SearchQuery().aggregations({
    'stars': agg.Terms(PostDocument.stars, size=50, aggs={
        'profit': agg.Sum(PostDocument.profit)})})

assert search_query.to_dict(Compiler_5_0) == {
    'aggregations': {
        'stars': {'terms': {'field': 'stars', 'size': 50},
            'aggregations': {
                'profit': {'sum': {'field': 'profit'}}}}}}

aggs(*args, **kwargs)

A shortcut for the aggregations() method

boost_score(*args, **kwargs)

Adds one more level of the function_score query with default sum modes. It is especially useful for complex ordering scenarios.

Parameters:*functions – See function_score()

from elasticmagic import Factor, ScriptScore, Script

search_query = (
    SearchQuery(PostDocument.title.match('test'))
    .function_score(
        # Slightly boost hits on post popularity
        Factor(PostDocument.popularity, modifier='sqrt'))
    .boost_score(
        # Display advertized posts higher than any others
        ScriptScore(
            Script(inline='log10(10.0 + doc[cpc_field].value)',
                   params={'cpc_field': PostDocument.adv_cpc}),
            weight=1000,
            filter=PostDocument.adv_cpc > 0))
)

assert search_query.to_dict(Compiler_5_0) == {
    'query': {
        'function_score': {
            'query': {
                'function_score': {
                    'query': {'match': {'title': 'test'}},
                    'functions': [
                        {'field_value_factor': {
                            'field': 'popularity',
                            'modifier': 'sqrt'}}]}},
            'functions': [
                {'script_score': {'script': {
                     'inline': 'log10(10.0 + doc[cpc_field].value)',
                     'params': {'cpc_field': 'adv_cpc'}}},
                 'filter': {'range': {'adv_cpc': {'gt': 0}}},
                 'weight': 1000}],
            'boost_mode': 'sum',
            'score_mode': 'sum'}}}

clone()

Clones this query so you can modify both queries independently.

docvalue_fields(*fields)

Allows to load doc values fields. Marked in mapping as doc_values: true (turned on by default).

Example:

search_query = SearchQuery().docvalue_fields(PostDocument.rank)

assert search_query.to_dict(Compiler_7_0) == {'docvalue_fields': ['rank']}

See stored fields and stored fields filtering for more information.

filter(*filters, **kwargs)

Adds a filters into elasticsearch filter context.

Returns new SearchQuery object with applied filters.

search_query = SearchQuery().filter(
    PostDocument.status == 'published',
    PostDocument.publish_date >= datetime.date(2015, 1, 1),
)

assert search_query.to_dict(Compiler_5_0) == {
    'query': {'bool': {'filter': [
        {'term': {'status': 'published'}},
        {'range': {
            'publish_date': {
                'gte': datetime.date(2015, 1, 1)}}}]}}}

Filter expression can be a python dictionary object:

search_query = SearchQuery().filter({'term': {'status': 'published'}})

from_(offset)

Sets the offset - the number of hits to skip. Used for pagination.

See from / size

function_score(*args, **kwargs)

Adds function scores to the search query.

Parameters:*functions – list of function scores.

from elasticmagic import Weight, FieldValueFactor

search_query = (
    SearchQuery(PostDocument.title.match('test'))
    .function_score(
        Weight(2, filter=PostDocument.created_date == 'now/d'),
        FieldValueFactor(
            PostDocument.popularity, factor=1.2, modifier='sqrt'
        )
    )
)

assert search_query.to_dict(Compiler_5_0) == {
    'query': {
        'function_score': {
            'query': {'match': {'title': 'test'}},
            'functions': [
                {'weight': 2,
                 'filter': {'term': {'created_date': 'now/d'}}},
                {'field_value_factor': {
                     'field': 'popularity',
                     'factor': 1.2,
                      'modifier': 'sqrt'}}]}}}

function_score_settings(*function_score_settings)

Adds or updates function score level. Levels will be inserted before existing.

highlight(fields=None, type=None, pre_tags=None, post_tags=None, fragment_size=None, number_of_fragments=None, order=None, encoder=None, require_field_match=None, boundary_max_scan=None, highlight_query=None, matched_fields=None, fragment_offset=None, no_match_size=None, phrase_limit=None, **kwargs)

Highlights search results.

from elasticmagic import MultiMatch

search_query = (
    SearchQuery(
        MultiMatch('The quick brown fox',
                   [PostDocument.title, PostDocument.content])
    )
    .highlight([PostDocument.title, PostDocument.content])
)

When processing search result you can get hit highlight by calling Document.get_highlight().

See highlighting for details.

limit(limit)

Sets size of the maximum amount of hits. Used for pagination.

See from / size

min_score(min_score)

Excludes hits with a _score less then min_score. See min score

offset(offset)

Sets the offset - the number of hits to skip. Used for pagination.

See from / size

order_by(*orders)

Apply sorting criterion to the search query. Corresponds elasticsearch’s sort.

search_query = SearchQuery().order_by(
    PostDocument.publish_date.desc(),
    PostDocument._score,
)
assert search_query.to_dict(Compiler_5_0) == {
    'sort': [
        {'publish_date': 'desc'},
        '_score'
    ]
}

When called with single None argument clears any sorting criterion applied before:

search_query = SearchQuery().order_by(None)
assert search_query.to_dict(Compiler_5_0) == {}

post_filter(*filters, **kwargs)

Adds a filters into elasticsearch post filter context.

All parameters have the same meaning as for filter() method.

query(q)

Replaces query clause. Elasticsearch’s query clause will calculate _score for every matching document.

Parameters:q – query expression. Existing query can be cancelled by passing None.

search_query = SearchQuery().query(
    PostDocument.title.match('test', minimum_should_match='100%'))

assert search_query.to_dict(Compiler_5_0) == {
    'query': {'match': {'title': {
        'query': 'test',
        'minimum_should_match': '100%'}}}}

rescore(rescorer, window_size=None)

Adds a rescorer for the query. See rescoring

script_fields(*args, **kwargs)

Allows to evaluate fields based on scripts.

from elasticmagic import Script

search_query = SearchQuery().script_fields(
    rating=Script(
        inline='doc[params.positive_opinions_field].value / '
               'doc[params.total_opinions_field].value * 5',
        params={
            'total_opinions_field': PostDocument.total_opinions,
            'positive_opinions_field': PostDocument.positive_opinions,
        }
    )
)

expected = {
    'script_fields': {
        'rating': {
            'script': {
                'inline': 'doc[params.positive_opinions_field].value / '
                          'doc[params.total_opinions_field].value * 5',
                'params': {
                    'total_opinions_field': 'total_opinions',
                    'positive_opinions_field': 'positive_opinions'
                }
            }
        }
    }
}

assert search_query.to_dict(Compiler_5_0) == {
    'script_fields': {
        'rating': {
            'script': {
                'inline': 'doc[params.positive_opinions_field].value / '
                          'doc[params.total_opinions_field].value * 5',
                'params': {
                    'total_opinions_field': 'total_opinions',
                    'positive_opinions_field': 'positive_opinions'
                }
            }
        }
    }
}

See script fields

size(limit)

Sets size of the maximum amount of hits. Used for pagination.

See from / size

slice(offset, limit)

Applies offset and limit to the query.

source(*fields, **kwargs)

Controls which fields of the document’s _source field to retrieve.

Parameters:

• *fields –

  list of fields which should be returned by elasticsearch. Can be one of the following types:

  • field expression, for example: PostDocument.title
  • str means field name or glob pattern. For example: "title", "user.*"
  • False disables retrieving source
  • True enables retrieving all source document
  • None cancels source filtering applied before
• include – list of fields to include
• exclude – list of fields to exclude

Example:

search_query = SearchQuery().source(PostDocument.title, 'user.*')

assert search_query.to_dict(Compiler_5_0) == {'_source': ['title', 'user.*']}

See source filtering for more information.

stored_fields(*fields)

Allows to load fields that marked as store: true.

Example:

search_query = SearchQuery().stored_fields(PostDocument.rank)

assert search_query.to_dict(Compiler_5_0) == {'stored_fields': ['rank']}

See stored fields and stored fields filtering for more information.

suggest(*args, **kwargs)

Adds suggesters to the query

class elasticmagic.ext.asyncio.search.AsyncSearchQuery(q=None, cluster=None, index=None, doc_cls=None, doc_type=None, routing=None, preference=None, timeout=None, search_type=None, query_cache=None, terminate_after=None, scroll=None, stats=None, track_total_hits=None, **kwargs)

Asynchronous version of the SearchQuery