pyes.query

class pyes.query.BoolQuery(must=None, must_not=None, should=None, boost=None, minimum_number_should_match=1, disable_coord=None, **kwargs)

A boolean combination of other queries.

BoolQuery maps to Lucene BooleanQuery. It is built using one or more boolean clauses, each clause with a typed occurrence. The occurrence types are:

Occur Description
must The clause (query) must appear in matching documents.
should The clause (query) should appear in the matching document. A boolean query with no must clauses, one or more should clauses must match a document. The minimum number of should clauses to match can be set using minimum_number_should_match parameter.
must_not The clause (query) must not appear in the matching documents. Note that it is not possible to search on documents that only consists of a must_not clauses.

The bool query also supports disable_coord parameter (defaults to false).

add_must(queries)

Add a query to the “must” clause of the query.

The Query object will be returned, so calls to this can be chained.

add_must_not(queries)

Add a query to the “must_not” clause of the query.

The Query object will be returned, so calls to this can be chained.

add_should(queries)

Add a query to the “should” clause of the query.

The Query object will be returned, so calls to this can be chained.

is_empty()
class pyes.query.ConstantScoreQuery(filter=None, boost=1.0, **kwargs)

Returns a constant score for all documents matching a filter.

Multiple filters may be supplied by passing a sequence or iterator as the filter parameter. If multiple filters are supplied, documents must match all of them to be matched by this query.

add(filter_or_query)

Add a filter, or a list of filters, to the query.

If a sequence of filters is supplied, they are all added, and will be combined with an ANDFilter.

If a sequence of queries is supplied, they are all added, and will be combined with an BooleanQuery(must) .

is_empty()

Returns True if the query is empty.

class pyes.query.CustomScoreQuery(query=None, script=None, params=None, lang=None, **kwargs)
add_param(name, value)
class pyes.query.DisMaxQuery(query=None, tie_breaker=0.0, boost=1.0, queries=None, **kwargs)
add(query)
class pyes.query.FieldParameter(field, query, default_operator='OR', analyzer=None, allow_leading_wildcard=True, lowercase_expanded_terms=True, enable_position_increments=True, fuzzy_prefix_length=0, fuzzy_min_sim=0.5, phrase_slop=0, boost=1.0)
serialize()
class pyes.query.FilterQuery(filters=None, **kwargs)
add(filterquery)
class pyes.query.FilteredQuery(query, filter, **kwargs)

FilteredQuery allows for results to be filtered using the various filter classes.

Example:

t = TermFilter(‘name’, ‘john’) q = FilteredQuery(MatchAllQuery(), t) results = conn.search(q)

class pyes.query.FunctionScoreQuery(functions=None, query=None, filter=None, max_boost=None, boost=None, score_mode=None, boost_mode=None, params=None)

The functoin_score query exists since 0.90.4. It replaces CustomScoreQuery and some other.

class BoostFunction(boost_factor, filter=None)

Boost by a factor

serialize()
class FunctionScoreQuery.BoostModes

Some helper object to show the possibility of boost_mode

AVG = 'avg'
MAX = 'max'
MIN = 'min'
MULTIPLY = 'multiply'
REPLACE = 'replace'
SUM = 'sum'
class FunctionScoreQuery.DecayFunction(decay_function, field, origin, scale, decay=None, offset=None, filter=None)
class FunctionScoreQuery.FunctionScoreFunction
serialize()

Serialize the function to a structure using the query DSL.

class FunctionScoreQuery.RandomFunction(seed, filter=None)

Is a random boost based on a seed value

class FunctionScoreQuery.ScoreModes

Some helper object to show the possibility of score_mode

AVG = 'avg'
FIRST = 'first'
MAX = 'max'
MIN = 'min'
MULTIPLY = 'multiply'
SUM = 'sum'
class FunctionScoreQuery.ScriptScoreFunction(script=None, params=None, lang=None, filter=None)

Scripting function with params and a script. Also possible to switch the script language

class pyes.query.FuzzyLikeThisFieldQuery(field, like_text, ignore_tf=False, max_query_terms=25, boost=1.0, min_similarity=0.5, **kwargs)
class pyes.query.FuzzyLikeThisQuery(fields, like_text, ignore_tf=False, max_query_terms=25, min_similarity=0.5, prefix_length=0, boost=1.0, **kwargs)
class pyes.query.FuzzyQuery(field, value, boost=None, min_similarity=0.5, prefix_length=0, **kwargs)

A fuzzy based query that uses similarity based on Levenshtein (edit distance) algorithm.

Note
Warning: this query is not very scalable with its default prefix length of 0 - in this case, every term will be enumerated and cause an edit score calculation. Here is a simple example:
class pyes.query.HasChildQuery(type, query, _scope=None, **kwargs)
class pyes.query.HasParentQuery(type, query, _scope=None, **kwargs)
class pyes.query.HasQuery(type, query, _scope=None, **kwargs)
class pyes.query.IdsQuery(values, type=None, **kwargs)
class pyes.query.MatchAllQuery(boost=None, **kwargs)

Query used to match all

Example:

q = MatchAllQuery() results = conn.search(q)

class pyes.query.MatchQuery(field, text, type='boolean', slop=0, fuzziness=None, prefix_length=0, max_expansions=2147483647, operator='or', analyzer=None, boost=1.0, minimum_should_match=None, cutoff_frequency=None, **kwargs)

Replaces TextQuery

class pyes.query.MoreLikeThisFieldQuery(field, like_text, percent_terms_to_match=0.3, min_term_freq=2, max_query_terms=25, stop_words=None, min_doc_freq=5, max_doc_freq=None, min_word_len=0, max_word_len=0, boost_terms=1, boost=1.0, **kwargs)
class pyes.query.MoreLikeThisQuery(fields, like_text, percent_terms_to_match=0.3, min_term_freq=2, max_query_terms=25, stop_words=None, min_doc_freq=5, max_doc_freq=None, min_word_len=0, max_word_len=0, boost_terms=1, boost=1.0, **kwargs)
class pyes.query.MultiMatchQuery(fields, text, type='boolean', slop=0, fuzziness=None, prefix_length=0, max_expansions=2147483647, rewrite=None, operator='or', analyzer=None, use_dis_max=True, minimum_should_match=None, **kwargs)

A family of match queries that accept text/numerics/dates, analyzes it, and constructs a query out of it. Replaces TextQuery.

Examples:

q = MatchQuery(‘book_title’, ‘elasticsearch’) results = conn.search(q)

q = MatchQuery(‘book_title’, ‘elasticsearch python’, type=’phrase’) results = conn.search(q)

class pyes.query.NestedQuery(path, query, _scope=None, score_mode='avg', **kwargs)

Nested query allows to query nested objects / docs (see nested mapping). The query is executed against the nested objects / docs as if they were indexed as separate docs (they are, internally) and resulting in the root parent doc (or parent nested mapping).

The query path points to the nested object path, and the query (or filter) includes the query that will run on the nested docs matching the direct path, and joining with the root parent docs.

The score_mode allows to set how inner children matching affects scoring of parent. It defaults to avg, but can be total, max and none.

Multi level nesting is automatically supported, and detected, resulting in an inner nested query to automatically match the relevant nesting level (and not root) if it exists within another nested query.

class pyes.query.PercolatorQuery(doc, query=None, **kwargs)

A percolator query is used to determine which registered PercolatorDoc’s match the document supplied.

search(**kwargs)

Disable this as it is not allowed in percolator queries.

serialize()

Serialize the query to a structure using the query DSL.

class pyes.query.PrefixQuery(field=None, prefix=None, boost=None, **kwargs)
add(field, prefix, boost=None)
class pyes.query.Query(*args, **kwargs)

Base class for all queries.

search(**kwargs)

Return this query wrapped in a Search object.

Any keyword arguments supplied to this call will be passed to the Search object.

serialize()

Serialize the query to a structure using the query DSL.

class pyes.query.QueryStringQuery(query, default_field=None, search_fields=None, default_operator='OR', analyzer=None, allow_leading_wildcard=True, lowercase_expanded_terms=True, enable_position_increments=True, fuzzy_prefix_length=0, fuzzy_min_sim=0.5, phrase_slop=0, boost=1.0, analyze_wildcard=False, use_dis_max=True, tie_breaker=0, clean_text=False, minimum_should_match=None, **kwargs)

Query to match values on all fields for a given string

Example:

q = QueryStringQuery(‘elasticsearch’) results = conn.search(q)

class pyes.query.RangeQuery(qrange=None, **kwargs)
add(qrange)
class pyes.query.RegexTermQuery(field=None, value=None, boost=None, **kwargs)
class pyes.query.RescoreQuery(query, window_size=None, query_weight=None, rescore_query_weight=None, **kwargs)

A rescore query is used to rescore top results from another query.

serialize()

Serialize the query to a structure using the query DSL.

class pyes.query.Search(query=None, filter=None, fields=None, start=None, size=None, highlight=None, sort=None, explain=False, facet=None, agg=None, rescore=None, window_size=None, version=None, track_scores=None, script_fields=None, index_boost=None, min_score=None, stats=None, bulk_read=None, partial_fields=None, _source=None, timeout=None)

A search to be performed.

This contains a query, and has additional parameters which are used to control how the search works, what it should return, etc.

The rescore parameter takes a Search object created from a RescoreQuery.

Example:

q = QueryStringQuery(‘elasticsearch’) s = Search(q, fields=[‘title’, ‘author’], start=100, size=50) results = conn.search(s)

add_highlight(field, fragment_size=None, number_of_fragments=None, fragment_offset=None, type=None)

Add a highlight field.

The Search object will be returned, so calls to this can be chained.

add_index_boost(index, boost)

Add a boost on an index.

The Search object will be returned, so calls to this can be chained.

get_agg_factory()

Returns the agg factory

get_facet_factory()

Returns the facet factory

highlight
script_fields
serialize()

Serialize the search to a structure as passed for a search body.

class pyes.query.SimpleQueryStringQuery(query, default_field=None, search_fields=None, default_operator='OR', analyzer=None, allow_leading_wildcard=True, lowercase_expanded_terms=True, enable_position_increments=True, fuzzy_prefix_length=0, fuzzy_min_sim=0.5, phrase_slop=0, boost=1.0, analyze_wildcard=False, use_dis_max=True, tie_breaker=0, clean_text=False, minimum_should_match=None, **kwargs)

A query that uses the SimpleQueryParser to parse its context. Unlike the regular query_string query, the simple_query_string query will never throw an exception, and discards invalid parts of the query.

Example:

q = SimpleQueryStringQuery(‘elasticsearch’) results = conn.search(q)

class pyes.query.SpanFirstQuery(field=None, value=None, end=3, **kwargs)
class pyes.query.SpanMultiQuery(query, **kwargs)

This query allows you to wrap multi term queries (fuzzy, prefix, wildcard, range).

The query element is either of type WildcardQuery, FuzzyQuery, PrefixQuery or RangeQuery. A boost can also be associated with the element query

class pyes.query.SpanNearQuery(clauses=None, slop=1, in_order=None, collect_payloads=None, **kwargs)

Matches spans which are near one another. One can specify _slop_, the maximum number of intervening unmatched positions, as well as whether matches are required to be in-order.

The clauses element is a list of one or more other span type queries and the slop controls the maximum number of intervening unmatched positions permitted.

class pyes.query.SpanNotQuery(include, exclude, **kwargs)

Removes matches which overlap with another span query.

The include and exclude clauses can be any span type query. The include clause is the span query whose matches are filtered, and the exclude clause is the span query whose matches must not overlap those returned.

class pyes.query.SpanOrQuery(clauses=None, **kwargs)

Matches the union of its span clauses.

The clauses element is a list of one or more other span type queries.

class pyes.query.SpanTermQuery(field=None, value=None, boost=None, **kwargs)
class pyes.query.Suggest(fields=None)
add(text, name, field, type='term', size=None, params=None)

Set the suggester of given type.

Parameters:
  • text – text
  • name – name of suggest
  • field – field to be used
  • type – type of suggester to add, available types are: completion, phrase, term
  • size – number of phrases
  • params – dict of additional parameters to pass to the suggester
Returns:

None

add_completion(text, name, field, size=None, params=None)

Add completion-type suggestion:

http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-suggesters-completion.html

Parameters:
  • text – text for searching using autocompletion
  • name – name for the suggester
  • field – document’s field to be autocompleted
  • size – (optional) size of the autocomplete list
Returns:

add_phrase(text, name, field, size=None, params=None)
add_term(text, name, field, size=None, params=None)
is_valid()
serialize()
class pyes.query.TermQuery(field=None, value=None, boost=None, **kwargs)

Match documents that have fields that contain a term (not analyzed).

A boost may be supplied.

Example:

q = TermQuery(‘name’, ‘john’) results = conn.search(q)

With boost:

q = TermQuery(‘name’, ‘john’, boost=0.75) results = conn.search(q)

add(field, value, boost=None)
class pyes.query.TermsQuery(*args, **kwargs)
add(field, value, minimum_match=1, boost=None)
class pyes.query.TextQuery(field, text, type='boolean', slop=0, fuzziness=None, prefix_length=0, max_expansions=2147483647, operator='or', analyzer=None, boost=1.0, minimum_should_match=None, cutoff_frequency=None, **kwargs)

A new family of text queries that accept text, analyzes it, and constructs a query out of it.

Examples:

q = TextQuery(‘book_title’, ‘elasticsearch’) results = conn.search(q)

q = TextQuery(‘book_title’, ‘elasticsearch python’, operator=’and’) results = conn.search(q)

add_query(field, text, type='boolean', slop=0, fuzziness=None, prefix_length=0, max_expansions=2147483647, operator='or', analyzer=None, boost=1.0, minimum_should_match=None, cutoff_frequency=None)
class pyes.query.TopChildrenQuery(type, score='max', factor=5, incremental_factor=2, **kwargs)
class pyes.query.WildcardQuery(field=None, value=None, boost=None, **kwargs)
pyes.query.is_a_spanquery(obj)

Returns if the object is a span query