Skip to main content

Query Sequences

As the number of recording sessions in your platform grows, browsing them manually becomes impractical. Mosaico's query system solves this with server-side filtering: instead of loading sessions and inspecting them locally, you describe what you are looking for and the daemon finds it for you. The client only receives the sessions that actually match. This keeps network traffic low and makes it feasible to search across thousands of recordings.

Sequence-level queries are the right tool when the criteria you care about live at the session level: the name of the mission, environment conditions logged at recording time, project identifiers, or any other metadata you attached to the Sequence when you created it. You are not yet asking questions about what sensor data is inside; you are asking questions about the recording session itself.

Learn

Doc: The Query Workflow

API Reference: Query Builders

API Reference: Query Response

Querying Sequences by Name and Metadata​

The QuerySequence builder constructs a filter by method chaining. Every .with_*() call you add becomes an additional AND condition: the daemon only returns sessions that satisfy every constraint you have specified. This makes it natural to start broad and progressively narrow; you can add conditions one at a time and the semantics are always "all of the above must be true."

with_name_match() matches the Sequence name against a glob-style pattern rather than a plain substring: passing "test_drive" looks for an exact match, while "test_drive*" matches any name that starts with that prefix. See the wildcard table below for the full set of supported wildcards.

with_user_metadata() works differently: it performs an exact, comparison-based, or pattern-based match against a specific metadata field, depending on the operator you pass as a keyword argument (eq, lt, gt, match, and so on). The first argument is the field key, and when you stored metadata as a nested dictionary during ingestion, you can reach any level of nesting using dot notation. For example, "project.name" queries the name field inside the project sub-object. The key itself can also use a glob pattern (see below) to match several nested fields at once without knowing the exact structure in advance.

Pattern Matching: Wildcards and Glob Keys​

Both with_name_match() and the match= keyword of with_user_metadata() accept a lightweight glob-style pattern instead of an exact value:

WildcardDescriptionExampleMatches
*Zero or more characters, including spacestest_drive*test_drive_01, test_drive_winter
?Exactly one character, including spaces?ublicpublic (not private)
[]A character set or range[rl]*raw, labeled
#Any single digit (0-9); shorthand for [0-9]test-sequence-#test-sequence-1

These wildcards apply to values you are matching against like the Sequence name, or the value passed to with_user_metadata(key, match=...). Glob patterns apply to metadata keys only: * matches exactly one key segment, and ** matches one or more segments at any depth. For example, "*.name" matches project.name or campaign.name, while "**.name" also matches mission.crew.name.

The example below finds every Sequence whose name starts with test_drive, whose metadata has some key ending in .name (one level deep) with a value starting with Apollo, and whose recorded visibility was below 50.

Query by name and metadata
from mosaicolabs import MosaicoClient, QuerySequence

with MosaicoClient.connect("localhost", 6726) as client:
    results = client.query(
        QuerySequence()
        .with_name_match("test_drive*")
        .with_user_metadata("*.name", match="Apollo*")
        .with_user_metadata("environment.visibility", lt=50)
    )

    if results:
        for item in results:
            print(f"Matched Sequence: {item.sequence.name}")
            print(f"  Topics: {[topic.name for topic in item.topics]}")

client.query() returns None on error, or a QueryResponse, a list of QueryResponseItem objects, one per matched Sequence. Each item carries two things: item.sequence, which holds the metadata of the matched session (its name, time boundary, and any stored metadata), and item.topics, which is the list of Topics that belong to that session. Because this is a Sequence-level query with no Topic filter applied, item.topics contains every Topic recorded under that Sequence, giving you a complete picture of what sensor streams are available before you decide which ones to open.

Result Normalization

topic.name returns the relative path (e.g. /front/camera/image), directly usable with other SDK methods like topic_handler() and streamers.

Key Concepts​

Generic methods using with_expression() and the .Q proxy give you access to the full operator set (.gt(), .lt(), .between(), and others) when the convenience methods above do not cover your use case. See The .Q Proxy for how it builds type-safe field paths from Ontology models.