Queries#

A query selects the set of prims that subsequent reads, writes, and maps operate over. The simplest query is built directly from an interned prim-path list; queries resolve against the latest committed state.

Query From a Path List#

Build an immutable prim-path list through the path dictionary, then open a query over it:

# Build an interned prim-path list and open a query over those prims.
# The query is a context manager: block exit releases its handle, and
# Stage teardown requires all handles released first -- the try/finally
# releases the path list even when an error interrupts the flow.
prim_paths = paths.create_path_list_from_strings(["/World/A", "/World/B", "/World/C"])
try:
    with stage.query_from_path_list(prim_paths) as query:

// Build an immutable prim-path list from strings and open a query over it.
const ovx_string_t paths[] = { literal_to_ovx_string("/World/A"), literal_to_ovx_string("/World/B"),
                               literal_to_ovx_string("/World/C") };
ovx_primpath_list_t pathList = OVX_INVALID_PRIMPATH_LIST;
ovxResult = path_dictionary_create_path_list_from_strings(dict, paths, 3, &pathList);
checkOvx(dict, ovxResult, "create-path-list");

ovstage_query_handle_t query = OVSTAGE_INVALID_QUERY_HANDLE;
status = ovstage_query_from_path_list(stage, pathList, &query);
check(stage, status, "query_from_path_list");

The resulting query handle is what you pass to Writing Attributes, Reading Attributes, and the map path.

Filtering by Predicate#

Queries can be narrowed with predicates. An ovstage_predicate_t names an attribute (as ovx_string_or_token_t), a comparison op (ovstage_filter_op_t), and one or more values; an ovstage_filter_t is a set of predicates. The built-in metadata attributes are filterable, so you can select, for example, all prims of a given usd-prim-type or under a given usd-parent. Refer to C API Reference for the predicate and filter type signatures.

Built-in Metadata Attributes#

The following reserved attributes are auto-maintained and usable both in reads and in filter predicates:

Attribute

Contents

usd-path

The prim’s path.

usd-prim-type

The prim’s type name.

usd-schemas

Applied API schemas.

usd-parent

The parent prim.

usd-children

The child prims.

usd-active

Whether the prim is active. Not supported — a live prim is always active, so predicates naming it return NOT_SUPPORTED; subject to removal in a future release.

usd-path PREFIX Convention#

PREFIX is byte-prefix matching on the path string. A value without a trailing / can match unrelated paths that share the same opening bytes — for example, PREFIX "/World" also matches /Worldwide. Append a trailing / to scope to the subtree under that path: PREFIX "/World/" matches only paths under /World/.

Where to Go Next#