Queries

Built in query types

These can be used in searches, as in

c.search(FullText("hello"))

Follow the links in the table below for examples specific to each query.

tiled.queries.Comparison(operator, key, value)	Query binary comparison between given key's value to the specified value.
tiled.queries.Contains(key, value)	Query where a given key's value contains the specified value.
tiled.queries.Eq(key, value)	Query equality of a given key's value to the specified value.
tiled.queries.NotEq(key, value)	Query inequality of a given key's value to the specified value.
tiled.queries.FullText(text)	Search the full text of all metadata values for word matches.
tiled.queries.In(key, value)	Query if a given key's value is present in the specified sequence of values.
tiled.queries.NotIn(key, value)	Query if a given key's value is not present in the specified sequence of values.
tiled.queries.Regex(key, pattern[, ...])	Match a key's value to a regular expression.
tiled.queries.SpecQuery(spec)	Convenience function for querying if specs list contains a given spec
tiled.queries.SpecsQuery(include[, exclude])	Query if specs list matches all elements in include list and does not match any element in exclude list
tiled.queries.StructureFamilyQuery(value)	Query if structure_families match value

(Some have the word Query at the end of their name to avoid confusion with other objects in the Tiled codebase.)

Query expressions

The Key object can be used to construct queries in a readable way using standard Python comparison operators, as in

Key("color") == "red"
Key("shape") != "circle"
Key("temperature") > 300

used in searches like

c.search(Key("color") == "red").search(Key("shape") != "circle").search(Key("temperature") > 300)

Notice that, to progressively narrow results, you may use repeated calls to .search() as in

c.search(...).search(...).search(...)

The above achieves logical AND. To achieve logical OR, you must perform separate queries and combine them yourself. It may be convenient to combine them as shown in a dict, as long as the results are not too numerous to fit in memory.

a = c.search(...)
b = c.search(...)
c = c.search(...)
combined_results = {**a, **b, **c}  # to handle repeats, must use {...} syntax not dict(...)

Warning

You cannot use queries with the Python keywords not, in, and, or or.

In Python, and and or have a particular behavior:

>>> 3 or 5
3

>>> 3 and 5
5

which would result in the first or last query being used, respectively, ignoring all others. This is an unavoidable consequence of Python semantics. Likewise, in X and ``not Xmust returnTrueorFalse`; they cannot return a query.

To avoid confusion, Tiled raises a TypeError if you attempt to use a query with not, in, and, or or.

tiled.queries.Key(key)

Compare a key in the metadata to a value using standard Python operators.

Convenience Functions

We recommend building convenience functions to provide for succinct usage for common searches. For example:

def Sample(sample_name):
    return Key("sample_name") == sample_name

This reduces

c.search(Key("sample_name") == "stuff")

to

c.search(Sample("stuff"))

Custom queries

Not all queries can be expressed as combinations of the built in ones. External libraries (like databroker) may register custom query types in addition to those built in to Tiled.