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:

TypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

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:

NameTypeDescription

query

string

The query string

params

dictionary

Optional – Additional parameters as defined by the Elasticsearch documentation.