Queries#

A query selects the prims that are affected by a read, write, or map operation.

First create a query by supplying explicit paths or finding prims that match conditions. Pass that query to stage.read_attributes(), stage.write_attribute(), or stage.map_attribute() to operate on those prims.

You can call query.result() after a query.wait() to inspect the selection, such as its prim count.

Release the query when it is no longer needed. Python’s with statement handles this for you.

Creating a Query From a List of Paths#

Use this when you already know the paths of the prims you want to read or write. Store those paths in a list through the path dictionary, then pass the list to stage.query_from_path_list(). This creates a query containing the supplied paths without checking whether the prims exist.

These snippets create a path list and a query for use in later operations:

Python

# 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:

C

// 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");

Creating a Query by Filtering Prims#

Use a filter when you want ovstage to find prims that meet conditions, such as having an attribute or belonging to a particular prim type. Pass a ovstage.Filter to ovstage.Stage.query(). ovstage checks prims in the runtime stage and includes those that match in the resulting query. Omitting the filter selects all prims.

Each ovstage.Predicate describes one condition: an attribute to check, a ovstage.FilterOp operation, and any values needed by that operation. All predicates in a filter must match. Built-in metadata attributes let you check a prim’s type (usd-prim-type), path (usd-path), or parent (usd-parent).

Filtered queries find prims in the current scene state. They do not reconstruct an earlier scene state from an ordinal.

Example: Find Mesh Prims in a Subtree#

Combine a type match with a path prefix. These snippets select Mesh prims below /World/Group. The trailing slash excludes the group itself and avoids matching names such as /World/GroupExtra:

Python

from ovstage import Filter, FilterOp, Predicate

# Separate predicates must all match.
mesh_filter = Filter([
    Predicate("usd-prim-type", FilterOp.IN, ["Mesh"]),
    Predicate("usd-path", FilterOp.PREFIX, ["/World/Group/"]),
])
with stage.query(filter=mesh_filter) as query:
    query.wait()
    mesh_count = query.result().total_prim_count
print("Meshes below /World/Group:", mesh_count)
# Meshes below /World/Group: 2

C

The waitOp() helper waits, checks errors, and releases operation tracking; check() checks synchronous status codes.

// Match Mesh prims below /World/Group; the trailing slash excludes the root.
const ovx_string_t type = literal_to_ovx_string("Mesh");
const ovx_string_t prefix = literal_to_ovx_string("/World/Group/");
ovstage_predicate_t predicates[2]{};
predicates[0].attribute.string = literal_to_ovx_string("usd-prim-type");
predicates[0].op = OVSTAGE_FILTER_OP_IN;
predicates[0].values = &type;
predicates[0].value_count = 1;
predicates[1].attribute.string = literal_to_ovx_string("usd-path");
predicates[1].op = OVSTAGE_FILTER_OP_PREFIX;
predicates[1].values = &prefix;
predicates[1].value_count = 1;
ovstage_filter_t filter{};
filter.predicates = predicates;
filter.count = 2;

// Wait, inspect the match count, and release the result and query.
ovstage_query_handle_t query = OVSTAGE_INVALID_QUERY_HANDLE;
waitOp(stage, ovstage_query(stage, &filter, nullptr, 0, &query), "query");
ovstage_query_result_t result{};
check(stage, ovstage_fetch_query_result(stage, query, OVSTAGE_TIMEOUT_INFINITE, &result),
      "fetch_query_result");
std::printf("Meshes below /World/Group: %llu\n", static_cast<unsigned long long>(result.total_prim_count));
// Meshes below /World/Group: 2
check(stage, ovstage_release_query_result(stage, &result), "release_query_result");
waitOp(stage, ovstage_release_query(stage, query), "release_query");

Supported Predicates#

The current implementation supports these combinations. The operator names are members of FilterOp in Python.

Attribute	Operator	Matches
Any supported attribute	`HAS`	Prims where the attribute is present; no value comparison.
`usd-path`	`IN`	Any of the exact paths listed. Use several values to check a set of candidate paths.
`usd-path`	`PREFIX`	Paths starting with a listed byte prefix; see the trailing-slash rule below.
`usd-parent`	`IN`	Direct children of any listed parent.
`usd-children`	`CONTAINS`	Prims with any listed child path.
`usd-prim-type`	`IN`	Prims with any listed type, such as `Mesh` or `Cube`.
`usd-schemas`	`CONTAINS`	Prims with any listed applied API schema, such as `PhysicsRigidBodyAPI`.
`usd-ancestor-types`	`CONTAINS`	Prims with any listed ancestor schema type, such as `Gprim` or `Boundable`.

Any versus all: values within one IN predicate match any listed value. Separate predicates must all match. For example, one usd-prim-type predicate with ["Mesh", "Cube"] matches either type. Two separate type predicates requiring Mesh and Cube cannot both match a prim. For applied schemas and ancestor types, one CONTAINS predicate with several names matches any; use separate predicates to require all of them.

Other combinations fail with ErrorCode.NOT_SUPPORTED. In particular, the current query implementation cannot compare an ordinary attribute’s value, such as mass > 10. Read the values and filter them in your application. usd-active is unsupported even with HAS.

query.result().attributes lists discovered attribute tokens. Resolve them with the path dictionary. The attrs= argument to Stage.query() limits that discovery; it does not require the attributes to exist. Use HAS for that requirement.

Built-in Metadata Attributes#

These reserved attributes describe the current scene. All except usd-active can be read and used in filters:

Attribute	Contents
`usd-path`	The prim’s path.
`usd-prim-type`	The prim’s type name.
`usd-schemas`	Applied API schemas.
`usd-ancestor-types`	The types the prim’s type derives from, such as `Gprim` and `Boundable` for a `Mesh`. Use `CONTAINS` to select prims by a base type.
`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 `ErrorCode.NOT_SUPPORTED`; subject to removal in a future release.

A query that names no path restriction spans every prim on the stage. With the RENDERING domain populated, that currently includes a few prims the runtime maintains for its own bookkeeping (see Runtime-Owned Prims, a temporary limitation of that domain). A HAS predicate on usd-prim-type matches those too, so total_prim_count on such a query is not the number of prims in the loaded scene. Scope to the scene with a usd-path PREFIX, or match usd-prim-type IN the types you expect, when the count matters.

`usd-path` PREFIX Convention#

FilterOp.PREFIX compares the opening bytes of 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 descendants of /World; it does not match /World itself.

Queries#

Creating a Query From a List of Paths#

Creating a Query by Filtering Prims#

Example: Find Mesh Prims in a Subtree#

Common Patterns#

Checking Whether a Prim Exists#

Checking Whether an Attribute Exists on a Prim#

Selecting Children#

Requiring Several Attributes#

Listing the Matched Paths#

Selecting Prims With an Applied API Schema#

Listing the Applied API Schemas on a Prim#

Supported Predicates#

Built-in Metadata Attributes#

`usd-path` PREFIX Convention#

Further Reading#

Queries#

Creating a Query From a List of Paths#

Creating a Query by Filtering Prims#

Example: Find Mesh Prims in a Subtree#

Common Patterns#

Checking Whether a Prim Exists#

Checking Whether an Attribute Exists on a Prim#

Selecting Children#

Requiring Several Attributes#

Listing the Matched Paths#

Selecting Prims With an Applied API Schema#

Listing the Applied API Schemas on a Prim#

Supported Predicates#

Built-in Metadata Attributes#

usd-path PREFIX Convention#

Further Reading#

`usd-path` PREFIX Convention#