Internal Types¶

mosaicolabs.models.query.protocols.QueryableProtocol ¶

Bases: Protocol

Structural protocol for classes that integrate into a multi-domain Query.

A class implicitly satisfies this protocol if it provides a unique identification tag via name() and a serialization method via to_dict(). This protocol ensures that the root Query or the can orchestrate complex requests without knowing the specific internal logic of each sub-query.

Reference Implementations¶

The following classes are standard examples of this protocol:

QueryTopic: Filters Topic-level metadata.
QuerySequence: Filters Sequence-level metadata.
QueryOntologyCatalog: Filters fine-grained sensor field data.

with_expression ¶

with_expression(expr)

Appends a new filter expression using a fluent interface.

Parameters:

Name	Type	Description	Default
`expr`	`_QueryExpression`	A valid `_QueryExpression`	required

name ¶

name()

Returns the unique key identifying this sub-query within the root request.

Examples include "topic", "sequence", or "ontology".

to_dict ¶

to_dict()

Serializes the internal expressions into a platform-compatible dictionary.

mosaicolabs.models.query.expressions._QueryExpression ¶

_QueryExpression(full_path, op, value)

Base class for all atomic comparison operations in the Mosaico Query DSL.

A _QueryExpression represents the smallest indivisible unit of a query. It is typically not instantiated directly by the user, but is instead the result of a terminal method call on a queryable field (e.g., .gt(), .eq(), .between()) via the .Q query proxy.

The class manages the expression lifecycle in a Query:

Generation: A user calls IMU.Q.acceleration.x.gt(9.8), which generates a _QueryCatalogExpression (a subclass of this class).
Validation: A Builder receives the expression and validates its type, operator format, and key uniqueness.
Serialization: The builder calls .to_dict() on the expression to transform it into the specific JSON format expected by the platform.

Attributes:

Name	Type	Description
`full_path`		The complete, dot-separated path to the target field on the platform.
`op`		The Mosaico-compliant operator string (e.g., `"$eq"`, `"$gt"`, `"$between"`).
`value`		The comparison value or data structure (e.g., a constant, a list for `$in`, or a range for `$between`).

Initializes an atomic comparison.

Parameters:

Name	Type	Description	Default
`full_path`	`str`	The dot-separated field path used in the final query dictionary.	required
`op`	`str`	The short-string operation identifier (must start with `$`).	required
`value`	`Any`	The constant value for the comparison.	required

to_dict ¶

to_dict()

Converts the expression into its final dictionary format.

Example

{"gps.status.service": {"$eq": 0}}

mosaicolabs.models.query.expressions._QueryTopicExpression ¶

_QueryTopicExpression(full_path, op, value)

Bases: _QueryExpression

An atomic comparison unit specialized for the Topic Catalog context.

This class is utilized exclusively by the QueryTopic builder to filter topics based on system attributes (like name or ontology_tag) and nested user metadata.

The QueryTopic class enforces that all provided expressions are instances of this type to prevent cross-domain query contamination.

Internal Translation Example:

User Call	Internal Translation
`Topic.Q.user_metadata["calibrated"].eq(True)`	`_QueryTopicExpression("user_metadata.calibrated", "$eq", True)`
`QueryTopic().with_name("camera_front")`	`_QueryTopicExpression("name", "$eq", "camera_front")`
`QueryTopic().with_ontology_tag("imu")`	`_QueryTopicExpression("ontology_tag", "$eq", "imu")`

Initializes an atomic comparison.

Parameters:

Name	Type	Description	Default
`full_path`	`str`	The dot-separated field path used in the final query dictionary.	required
`op`	`str`	The short-string operation identifier (must start with `$`).	required
`value`	`Any`	The constant value for the comparison.	required

to_dict ¶

to_dict()

Converts the expression into its final dictionary format.

Example

{"gps.status.service": {"$eq": 0}}

mosaicolabs.models.query.expressions._QuerySequenceExpression ¶

_QuerySequenceExpression(full_path, op, value)

Bases: _QueryExpression

An atomic comparison unit specialized for the Sequence Catalog context.

This class represents filters targeting high-level sequence containers. It is the only expression type accepted by the QuerySequence builder.

It handles fields such as the sequence name, created_timestamp, or custom entries within the sequence's user_metadata.

Internal Translation Example:

User Call	Internal Translation
`Sequence.Q.user_metadata["project"].eq("Apollo")`	`_QuerySequenceExpression("user_metadata.project", "$eq", "Apollo")`
`QuerySequence().with_name("Apollo")`	`_QuerySequenceExpression("name", "$eq", "Apollo")`
`QuerySequence().with_created_timestamp(Time.from_float(1704067200.0))`	`_QuerySequenceExpression("created_timestamp", "$between", [1704067200.0, None])`

Initializes an atomic comparison.

Parameters:

Name	Type	Description	Default
`full_path`	`str`	The dot-separated field path used in the final query dictionary.	required
`op`	`str`	The short-string operation identifier (must start with `$`).	required
`value`	`Any`	The constant value for the comparison.	required

to_dict ¶

to_dict()

Converts the expression into its final dictionary format.

Example

{"gps.status.service": {"$eq": 0}}

mosaicolabs.models.query.expressions._QueryCatalogExpression ¶

_QueryCatalogExpression(full_path, op, value)

Bases: _QueryExpression

An atomic comparison unit specialized for Data Ontology (Sensor Payload) filtering.

This expression type is used by the QueryOntologyCatalog builder to filter actual sensor data values across the entire platform.

Because ontology queries target specific fields within a sensor payload (e.g., accelerometer readings), these expressions use fully qualified dot-notated paths prefixed by the ontology tag.

Internal Translation Example:

User Call	Internal Translation
`IMU.Q.acceleration.x.gt(9.8)`	`_QueryCatalogExpression("imu.acceleration.x", "$gt", 9.8)`
`IMU.Q.acceleration.y.gt(9.8)`	`_QueryCatalogExpression("imu.acceleration.y", "$gt", 9.8)`
`IMU.Q.acceleration.z.gt(9.8)`	`_QueryCatalogExpression("imu.acceleration.z", "$gt", 9.8)`
`IMU.Q.acceleration.x.gt(9.8)`	`_QueryCatalogExpression("imu.acceleration.x", "$gt", 9.8)`

Initializes an atomic comparison.

Parameters:

Name	Type	Description	Default
`full_path`	`str`	The dot-separated field path used in the final query dictionary.	required
`op`	`str`	The short-string operation identifier (must start with `$`).	required
`value`	`Any`	The constant value for the comparison.	required

to_dict ¶

to_dict()

Converts the expression into its final dictionary format.

Example

{"gps.status.service": {"$eq": 0}}