Entity Queries

Many space views are made up of visualizations that include more than one entity.

Rather that requiring you to specify each entity individually, Rerun supports this through "entity queries" that allow you to use "query expressions" to include or exclude entire subtrees.

Query expression syntax

An entity query is made up of a set of "query expressions." Each query expression is either an "inclusion," which starts with an optional + or an "exclusion," which always starts with a -.

Query expressions are also allowed to end with an optional /**. The/** suffix matches the whole subtree, i.e. self and any child, recursively. For example, /world/**matches both/worldand/world/car/driver. Other uses of * are not yet supported.

When combining multiple query expressions, the rules are sorted by entity-path, from least to most specific:

• If there are multiple matching rules, the most specific rule wins.
• If there are multiple rules of the same specificity, the last one wins.
• If no rules match, the path is excluded.

Consider the following example:

+ /world/**
- /world
- /world/car/**
+ /world/car/driver

• The last rule matching /world/car/driver is + /world/car/driver, so it is included.
• The last rule matching /world/car/hood is - /world/car/**, so it is excluded.
• The last rule matching /world is - /world, so it is excluded.
• The last rule matching /world/house is + /world/**, so it is included.

In the viewer

In the viewer, an entity query is typically displayed as a multi-line edit box, with each query expression shown on its own line. You can find the query editor in the right-hand selection panel when selecting a space view.

In the SDK

In the SDK, query expressions are represented as a list or iterable, with each expression written as a separate string. The query expression from above would be written as:

rrb.Spatial3DView(
    contents=[
        "+ helix/**,
        "- helix/structure/scaffolding",
    ],
),

origin substitution

Query expressions also allow you to use the variable $origin to refer to the origin of the space-view that the query belongs to.

For example, the above query could be rewritten as:

rrb.Spatial3DView(
    origin="helix",
    contents=[
        "+ $origin/**,
        "- $origin/structure/scaffolding",
    ],
),