Query Builders

The third way of writing InsightMaker queries is by using the query builder helper objects available as part of the library, using these the Elastic DSL query in the previous section can be achieved by:

from insight_maker.api.query_builders import *

query = RangeQuery("size", 1000, 2000) & ~RegexQuery("name", ".*\.txt")

results = im.search(query, dataset = "documents", size = 10)

print(results.df)

All query builder objects support the python and (&), or (|) and not (~) logical operators allowing for plenty of flexibility.

The available helper objects are as follows:

SubQuery

SubQuery(method, content)

All helpers inherit from the base class, SubQuery, it has two key properties, method and content, corresponding to a key, value pair, i.e. {method: content}. It implements the following functions:

• SubQuery.query_json() The most important method of SubQuery, this returns the query wrapped in a Bool Query, suitable for use with the DS API.

• SubQuery.json() The query without a bool wrapper.

• SubQuery.content_json() The query json for the content element of this SubQuery only.

• SubQuery.append(other) Append another SubQuery of equivalent method to the content of this SubQuery. (This exists primarily to assist the logical operator overload functions)

• SubQuery.merge(new_content) Append additional content to the content of this SubQuery. (This exists primarily to assist the logical operator overload functions)

• SubQuery.is_bool_occurence() Is this SubQuery of method “must”, “filter”, “should” or “must_not”, all of which must exist within a Bool Query. (This exists primarily to assist the logical operator overload functions)

BoolQuery

BoolQuery(occurrences, minimum_should_match=1)

A way to logically combine other SubQuery objects – typically you should not need to create these, rather using the logical operators and (&), or (|) and not (~) on SubQuery objects will automatically create them for you. Elastic Query DSL reference.

Parameters:

	Type	Description
occurrences	list	A list of SubQuery objects of method: “must”, “filter”, “should” or “must_not”
minimum_should_match	numeric	The number or percentage of should clauses returned documents must match. Default: 1

FieldQuery

FieldQuery(field, values)

An Elastic Query DSL Terms Query, returns documents where a given field matches certain values.

Parameters:

Name	Type	Description
field	string	The name of the field to match on
values	list	A list of values (of appropriate type) to match the field on

ExistsQuery

ExistsQuery(field)

Filters to documents where a non-null/empty value exists for the given field. Reference.

Parameters:

Name	Type	Description
field	string	The name of the field to check

RegexQuery

RegexQuery(field, expression, flags=None, max_determined_states=None)

An Elastic Query DSL Regular Expression Query.

Parameters:

Name	Type	Description
field	string	The name of the field to check
expression	string	The regular expression string
flags	string	Optional - | separated flags of ALL (default), ANYSTRING, COMPLEMENT, EMPTY, INTERSECTION, INTERVAL, or NONE. As defined by Lucene.
max_determined_states	integer	Optional – A way of limiting the number of execution states for regex matches, useful for more complex regular expressions. Elasticsearch default: 10,000.

WildcardQuery

WildcardQuery(field, wildcard)

An Elastic Query DSL Wildcard Query. Slightly simpler than a full blown regular expression query, just using * to match zero or more characters.

Parameters:

Name	Type	Description
field	string	The name of the field to check
wildcard	string	The wildcard string to use

PrefixQuery

PrefixQuery(field, prefix)

An Elastic Query DSL Prefix Query. Used to match documents where a field starts with a given string.

Parameters:

Name	Type	Description
field	string	The name of the field to check
prefix	string	The prefix string to use

RangeQuery

RangeQuery(field, min_value, max_value, lower_inclusive=True, upper_inclusive=False)

An Elastic Query DSL Range Query.

Parameters:

Name	Type	Description
field	string	The name of the field to check
min_value	numeric	The lower bound to match above
max_value	numeric	The upper bound to match below
lower_inclusive	boolean	Include exact matches on the lower bound. Default: True
upper_inclusive	boolean	Include exact matches on the upper bound. Default: False

FuzzyQuery

FuzzyQuery(field, search_t, fuzziness=None, prefix_length=None, max_expansions=None, transpositions=None)

An Elastic Query DSL Fuzzy Query.

Parameters:

Name	Type	Description
field	string	The name of the field to check
search_t	string	The fuzzy search string
fuzziness	integer	The edit distance to match from. See documentation. Defaults to automatic.
prefix_length	integer	The number of initial characters to not consider part of the fuzzy match. Default: 0
max_expansions	integer	The maximum number of terms that the fuzzy query will expand to. Defaults to 50.
transpositions	boolean	If character transpositions are supported in the match (i.e. ab->ba would have a distance of 1 rather than 2). Default: False

QueryString

QueryString(query, params=None)

An Elasticsearch default string query. Supports Lucene syntax.

Parameters:

Name	Type	Description
query	string	The query string
params	dictionary	Optional – Additional parameters as defined by the Elasticsearch documentation.