Queryable Fields

mosaicolabs.query.queryable_fields

Queryable Fields Module.

This module defines the concrete types that the .Q proxy of a Serializable class resolves each leaf field to. When you write IMU.Q.acceleration.x, the .x attribute you get back is a QueryableNumeric instance - one per leaf field, one class per underlying data type (QueryableNumeric, QueryableString, QueryableBool). Each class only exposes the comparison operators that make sense for its data type (e.g. numeric fields get .lt()/.gt()/.between(), string fields get .match(), boolean fields only get .eq()), so building an expression on the wrong operator is a type error, not a runtime surprise.

Because a Queryable* field only needs a fully-qualified, dot-notated path (f"{ontology_tag}.field.subfield") to build its _QueryCatalogExpression, the classes in this module double as a class-free escape hatch for Unmodeled ontology models: you can build the exact same expression a resolved class's .Q proxy would produce, without resolving (or even having) that class at all - as long as you know the field's path and its data type.

Example

from mosaicolabs import MosaicoClient, QueryOntologyCatalog
from mosaicolabs.query.queryable_fields import QueryableNumeric

with MosaicoClient.connect("localhost", 6726) as client:
    # Equivalent to `SomeResolvedClass.Q.temperature.celsius.lt(22.0)`,
    # but requires no resolved class - only the known tag and field path.
    qresponse = client.query(
        QueryOntologyCatalog().with_expression(
            QueryableNumeric("SomeResolvedClass.temperature.celsius").lt(22.0)
        )
    )

QueryableNumeric

QueryableNumeric(path)

Bases: _QueryableField, _QueryableNumeric

The queryable type of a numeric field.

IMU.Q.acceleration.x is a QueryableNumeric instance; this class is what you get, and what you can construct directly by path when no resolved class is available. It exposes the numeric operators .eq(), .lt(), ... Values passed to any operator must be int or float.

Use it directly when you know the exact server-side field path you want to filter on but don't have (or don't want to construct) a Serializable class to hang a .Q proxy off of - most commonly for Unmodeled ontology data.

Example

from mosaicolabs.query.queryable_fields import QueryableNumeric

# Equivalent to `IMU.Q.acceleration.x.gt(9.8)`, addressed by path alone.
expr = QueryableNumeric("IMU.acceleration.x").gt(9.8)

Parameters:

Name	Type	Description	Default
path	str	The fully-qualified, dot-notated field path, prefixed by the ontology tag (e.g. "IMU.acceleration.x", or f"{ontology_tag}.temperature.celsius" for an unmodeled ontology).	required

eq

eq(value)

Matches records where the field is exactly equal to value.

Parameters:

Name	Type	Description	Default
value	Any	The value to compare against. Must match one of the types in __mixin_supported_types__ for this field.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($eq).

Raises:

Type	Description
TypeError	If value isn't one of the supported types.

neq

neq(value)

Matches records where the field is not equal to value.

Parameters:

Name	Type	Description	Default
value	Any	The value to compare against. Must match one of the types in __mixin_supported_types__ for this field.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($neq).

Raises:

Type	Description
TypeError	If value isn't one of the supported types.

lt

lt(value)

Matches records where the field is strictly less than value.

Parameters:

Name	Type	Description	Default
value	Any	The exclusive upper bound. Must match one of the types in __mixin_supported_types__ for this field.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($lt).

Raises:

Type	Description
TypeError	If value isn't one of the supported types.

leq

leq(value)

Matches records where the field is less than or equal to value.

Parameters:

Name	Type	Description	Default
value	Any	The inclusive upper bound. Must match one of the types in __mixin_supported_types__ for this field.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($leq).

Raises:

Type	Description
TypeError	If value isn't one of the supported types.

gt

gt(value)

Matches records where the field is strictly greater than value.

Parameters:

Name	Type	Description	Default
value	Any	The exclusive lower bound. Must match one of the types in __mixin_supported_types__ for this field.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($gt).

Raises:

Type	Description
TypeError	If value isn't one of the supported types.

geq

geq(value)

Matches records where the field is greater than or equal to value.

Parameters:

Name	Type	Description	Default
value	Any	The inclusive lower bound. Must match one of the types in __mixin_supported_types__ for this field.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($geq).

Raises:

Type	Description
TypeError	If value isn't one of the supported types.

in_

in_(*values)

Matches records where the field's value is one of values.

Parameters:

Name	Type	Description	Default
*values	Any	The candidate values, passed either as separate positional arguments (in_(v1, v2)) or as a single list or tuple (in_([v1, v2])). All must be either float or int.	()

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($in).

Raises:

Type	Description
ValueError	If no values are provided.
TypeError	If the values don't all share the same, supported type.

between

between(*values)

Matches records where the field's value falls within an inclusive range, i.e. lower <= v <= upper.

Parameters:

Name	Type	Description	Default
*values	Any	Exactly two values (lower, upper), passed either as two positional arguments (between(lo, hi)) or as a single list or tuple (between([lo, hi])), with lower <= upper. Both must be either float or int.	()

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($between).

Raises:

Type	Description
ValueError	If not exactly two values are provided, or if the first value is greater than the second.
TypeError	If the values don't share the same, supported type.

outside

outside(*values)

Matches records where the field's value falls outside an exclusive range, i.e. v < lower || v > upper.

Parameters:

Name	Type	Description	Default
*values	Any	Exactly two values (lower, upper), passed either as two positional arguments (outside(lo, hi)) or as a single list or tuple (outside([lo, hi])), with lower <= upper. Both must be either float or int.	()

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($outside).

Raises:

Type	Description
ValueError	If not exactly two values are provided, or if the first value is greater than the second.
TypeError	If the values don't share the same, supported types.

QueryableString

QueryableString(path)

Bases: _QueryableField, _QueryableString

The queryable type of a string field.

IMU.Q.frame_id is a QueryableString instance; this class is what you get, and what you can construct directly by path when no resolved class is available. It exposes the string operators .eq(), .match(), ... Values passed to any operator must be str.

Use it directly when you know the exact server-side field path you want to filter on but don't have (or don't want to construct) a Serializable class to hang a .Q proxy off of - most commonly for Unmodeled ontology data.

Example

from mosaicolabs.query.queryable_fields import QueryableString

# Equivalent to `IMU.Q.frame_id.eq("imu_link")`, addressed by path alone.
expr = QueryableString("IMU.frame_id").eq("imu_link")

Parameters:

Name	Type	Description	Default
path	str	The fully-qualified, dot-notated field path, prefixed by the ontology tag (e.g. "IMU.frame_id", or f"{ontology_tag}.status.label" for an unmodeled ontology).	required

eq

eq(value)

Matches records where the field is exactly equal to value.

Parameters:

Name	Type	Description	Default
value	Any	The string to compare against.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($eq).

Raises:

Type	Description
TypeError	If value isn't a str.

match

match(value)

Matches records where the field satisfies a glob-style pattern.

value is a lightweight glob pattern that must match the entire field value. It supports the following wildcards:

Wildcard	Description	Example	Matches
*	Zero or more characters, including spaces	*imu	front_imu, camera_imu
?	Exactly one character, including spaces	?.2.0	1.2.0, 3.2.0 (not 10.2.0)
[]	A character set or range	[gs]* / [a-z]*	gyrolytics, satnavics
#	Any single digit (0-9); shorthand for [0-9]	test-query-sequence-#	test-query-sequence-1

Note

If value contains none of the wildcards above, the operator is equivalent to .eq(), i.e. an exact match will be performed.

Parameters:

Name	Type	Description	Default
value	Any	The glob pattern to match against.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($match).

Raises:

Type	Description
TypeError	If value isn't a str.

lt

lt(value)

Matches records where the field sorts strictly before value, lexicographically.

Parameters:

Name	Type	Description	Default
value	Any	The exclusive upper bound.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($lt).

Raises:

Type	Description
TypeError	If value isn't a str.

leq

leq(value)

Matches records where the field sorts at or before value, lexicographically.

Parameters:

Name	Type	Description	Default
value	Any	The inclusive upper bound.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($leq).

Raises:

Type	Description
TypeError	If value isn't a str.

gt

gt(value)

Matches records where the field sorts strictly after value, lexicographically.

Parameters:

Name	Type	Description	Default
value	Any	The exclusive lower bound.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($gt).

Raises:

Type	Description
TypeError	If value isn't a str.

geq

geq(value)

Matches records where the field sorts at or after value, lexicographically.

Parameters:

Name	Type	Description	Default
value	Any	The inclusive lower bound.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($geq).

Raises:

Type	Description
TypeError	If value isn't a str.

in_

in_(*values)

Matches records where the field's value is one of values.

Parameters:

Name	Type	Description	Default
*values	str	The candidate strings, passed either as separate positional arguments (in_(v1, v2)) or as a single list or tuple (in_([v1, v2])).	()

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($in).

Raises:

Type	Description
ValueError	If no values are provided.
TypeError	If any value isn't a str.

between

between(*values)

Matches records where the field's value falls within an inclusive range, i.e. lower <= v <= upper. Since the field is a str, the comparison is lexicographic.

Parameters:

Name	Type	Description	Default
*values	Any	Exactly two values (lower, upper), passed either as two positional arguments (between(lo, hi)) or as a single list or tuple (between([lo, hi])), with lower <= upper. Both must be of type str.	()

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($between).

Raises:

Type	Description
ValueError	If not exactly two values are provided, or if the first value is greater than the second.
TypeError	If any value isn't a str.

outside

outside(*values)

Matches records where the field's value falls outside an exclusive range, i.e. v < lower || v > upper. Since the field is a str, the comparison is lexicographic.

Parameters:

Name	Type	Description	Default
*values	Any	Exactly two values (lower, upper), passed either as two positional arguments (outside(lo, hi)) or as a single list or tuple (outside([lo, hi])), with lower <= upper. Both must be of type str.	()

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($outside).

Raises:

Type	Description
ValueError	If not exactly two values are provided, or if the first value is greater than the second.
TypeError	If any value isn't a str.

QueryableBool

QueryableBool(path)

Bases: _QueryableField, _QueryableBool

The queryable type of a boolean field.

ROI.Q.do_rectify is a QueryableBool instance; this class is what you get, and what you can construct directly by path when no resolved class is available. Booleans only support equality, so it exposes just .eq(). Values passed to the operator must be bool.

Use it directly when you know the exact server-side field path you want to filter on but don't have (or don't want to construct) a Serializable class to hang a .Q proxy off of - most commonly for Unmodeled ontology data.

Example

from mosaicolabs.query.queryable_fields import QueryableBool

# Equivalent to `ROI.Q.do_rectify.eq(True)`, addressed by path alone.
expr = QueryableBool("ROI.do_rectify").eq(True)

Parameters:

Name	Type	Description	Default
path	str	The fully-qualified, dot-notated field path, prefixed by the ontology tag (e.g. "ROI.do_rectify", or f"{ontology_tag}.status.is_online" for an unmodeled ontology).	required

eq

eq(value)

Matches records where the field equals value.

Parameters:

Name	Type	Description	Default
value	Any	True or False.	required

Returns:

Name	Type	Description
_QueryExpression	_QueryExpression	The atomic comparison expression ($eq).

Raises:

Type	Description
TypeError	If value isn't a bool.