Stage Queries
When to Use
Use this skill when the user wants to find prims by a predicate rather than by an
explicit path list: select by prim type, path (exact or subtree), parent, child, applied
schema, or attribute presence — and inspect what a query matched (count, reported
attributes, reusable handle). For building an explicit path list to query a known set of
prims, use path-dictionary instead.
Inputs
Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.
- The selection criterion: which built-in metadata attribute + operator, or attribute-presence (
HAS).
- Whether the prims carry the metadata built-ins (these require population; a purely
client-written attribute column has
usd-path and HAS-able columns but not
usd-prim-type/usd-parent/usd-children/usd-schemas).
- Target API surface: C, Python, or both.
- Whether the caller needs just a count, the matched set to read from, or the reported attributes.
- The shipped headers and the referenced example/test snippets are the authoritative contract.
Prerequisites
- Use an ovstage checkout that contains the
include/ headers and the referenced snippets.
- Read the relevant
> **Source:** snippet before writing or explaining API usage.
- Understand the async submit/observe model (
cpu-ahead-gpu-async): query is an enqueue
returning a handle; drive it to completion (ovstage_wait_op / .wait()) before fetching.
- Queries resolve against the latest committed state — no write-floor advance is needed for a
query to see a populated/written prim (reads of matched columns still target sealed data).
Instructions
- Build the filter: a
Filter is a conjunction (AND) of Predicates; each predicate is an
attribute + FilterOp + string values. A None/empty filter matches all prims.
- Enqueue
ovstage_query (C) / Stage.query (Python) and drive it to completion.
- Fetch the result (
ovstage_fetch_query_result / Query.result()): read total_prim_count,
the reported attributes, and all_handle (the same query handle, echoed back).
- To read columns from the matched set, feed the query handle (or
all_handle) to
read_attributes.
- Release the query handle (and the result payload in C) before destroying the instance.
- For a known, explicit set of prims, prefer
query_from_path_list (see path-dictionary).
Output Format
- For explanations, cite the API names, the source snippet(s), the supported predicate matrix,
and the population caveat.
- For code changes, summarize the files touched, snippets affected, and validation run.
Scripts
This skill has no scripts.
Limitations
- The referenced snippets remain the source of truth; update or add tested snippets before
documenting new API usage.
- Narrow support matrix. The bindings/headers describe more operators than the current
implementation accepts; anything outside the table below is rejected at enqueue
(
NOT_SUPPORTED).
- Values are always strings, even for token/type attributes. Predicates in one
Filter AND
together.
- Metadata built-ins need population.
usd-prim-type/usd-parent/usd-children/usd-schemas
are auto-maintained by the population bridge; a scene built only with write_attribute exposes
usd-path and HAS-able user columns but not those relational built-ins.
- Instancing queries require populated content. C exposes the native
ovstage_instancing.h
path-list handles; Python exposes string-returning wrappers in ovstage.instancing.
- ⚠️ Draft — API in flux. Treat exact symbols/ordering as provisional against the headers.
Overview
query finds prims by predicate and reserves a query handle; fetch_query_result reports what it
matched. The supported predicate matrix:
| Attribute |
Operators |
Selects |
| any attribute |
HAS |
prims where the attribute exists (no value test) |
usd-path |
IN, PREFIX |
exact path(s) / subtree (byte-prefix; trailing / scopes) |
usd-parent |
IN |
direct children of the named parent(s) |
usd-children |
CONTAINS |
prims having the named child |
usd-prim-type |
IN |
prims of the named type(s) |
usd-schemas |
CONTAINS |
applied-schema membership |
usd-active is not supported. It appears in the header contract for
stability, but a live prim is always active, so the attribute carries no
information; any read or predicate naming it is rejected with
NOT_SUPPORTED. Subject to removal in a future release.
usd-active is not supported. It appears in the header contract for
stability, but a live prim is always active, so the attribute carries no
information; any read or predicate naming it is rejected with
NOT_SUPPORTED. Subject to removal in a future release.
C
Run one filter query per predicate (no path list — the stage finds the prims), then map the
scene-graph-instancing structure:
Source: examples/c/queries/main.cpp snippet filter-predicates
Followed by: examples/c/queries/main.cpp snippet query-introspection
Followed by: examples/c/queries/main.cpp snippet instancing-queries-c (scene-graph instancing)
The public C test asserts the documented match set for each predicate against the produced package:
Source: tests/c/test_queries.cpp snippet query-predicate-matrix-c
usd-path IN and attribute HAS also work on purely client-written prims (no population):
Source: tests/c/test_queries.cpp snippets query-by-usd-path-c, query-has-attribute-c
Introspection — match count, the scoped attribute list, and the reusable all_handle:
Source: tests/c/test_queries.cpp snippet query-result-introspection-c
Python
Stage.query(filter=Filter([...])) returns a Query handle; Query.result() reports the match:
Source: examples/python/queries/main.py snippet filter-predicates
Followed by: examples/python/queries/main.py snippet query-introspection
Followed by: examples/python/queries/main.py snippet instancing-queries
The public Python test asserts the documented match set for each predicate against the wheel:
Source: tests/python/test_queries.py snippet query-predicate-matrix
usd-path IN and attribute HAS also work on purely client-written prims (no population):
Source: tests/python/test_queries.py snippets query-by-usd-path, query-has-attribute
Introspection — match count, the scoped attribute list, and the reusable all_handle:
Source: tests/python/test_queries.py snippet query-result-introspection
Key Types / Functions
| Python |
C |
Stage.query(filter=, attrs=) → Query |
ovstage_query(instance, filter, attrs, attr_count, &handle) |
Query.result() → QueryResult |
ovstage_fetch_query_result(instance, handle, timeout, &result) |
QueryResult.total_prim_count / .attributes / .all_handle |
ovstage_query_result_t.total_prim_count / .attributes / .all_handle |
Filter([Predicate(attr, FilterOp.IN, [..])]) |
ovstage_filter_t / ovstage_predicate_t / ovstage_filter_op_t |
Stage.release_query(handle) |
ovstage_release_query (+ ovstage_release_query_result) |
Troubleshooting
- Enqueue rejected
OVSTAGE_ERROR_NOT_SUPPORTED — the attribute+operator pairing is outside
the matrix above. Use a supported pairing; the bindings advertise more than the engine accepts.
- Zero matches for a metadata predicate — the scene wasn't populated, so
usd-prim-type/usd-parent/usd-children/usd-schemas aren't authored. Populate first, or
filter on usd-path/HAS, which work on client-written prims.
PREFIX "/World" matches /Worldwide — usd-path PREFIX is byte-prefix matching on the
path string. Append a trailing / to scope to the subtree (PREFIX "/World/").
OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION reading a matched set — the selected columns weren't
sealed; advance the write floor to/above the write ordinal before reading (queries see latest
committed state, but reads target sealed data). See application-flow.
OVSTAGE_ERROR_OUT_OF_RANGE reading a fixed range — a selected (attribute, path) has a
retained successor after the range end, so latest-only storage cannot represent the window.
Widen/rebase the range or request latest state; advancing the floor alone does not fix it.
- Handle leak / teardown crash — release the query (and in C the query result) before
destroying the instance; read-group prim lists are borrows, never
destroy_path_list them.
References
- Use the
> **Source:** directives in this skill to locate tested snippets before reusing API patterns.
path-dictionary — building path lists and query_from_path_list for a known prim set.
loading-usd — population, which authors the metadata built-ins these filters match.
cpu-ahead-gpu-async — the async submit/observe model queries share with every op.
application-flow — where queries fit in the create → write → seal → read lifecycle.
- Keep related skills, docs, and snippets synchronized when changing the workflow.
1---2name: stage-queries-33description: Find prims with filter queries — predicates over reserved metadata built-ins (usd-path, usd-prim-type, usd-parent, usd-children, usd-schemas) and attribute presence — instead of explicit path lists, then introspect what a query matched. Use when the user asks to query, filter, select, or find prims by type, path, parent, child, applied schema, or attribute presence, or to read a query result's count / attributes / reusable handle.4license: LicenseRef-NvidiaProprietary5---67# Stage Queries89## When to Use1011Use this skill when the user wants to **find prims by a predicate** rather than by an12explicit path list: select by prim type, path (exact or subtree), parent, child, applied13schema, or attribute presence — and inspect what a query matched (count, reported14attributes, reusable handle). For building an explicit path list to query a *known* set of15prims, use `path-dictionary` instead.1617## Inputs1819Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.2021- The selection criterion: which built-in metadata attribute + operator, or attribute-presence (`HAS`).22- Whether the prims carry the metadata built-ins (these require **population**; a purely23 client-written attribute column has `usd-path` and `HAS`-able columns but not24 `usd-prim-type`/`usd-parent`/`usd-children`/`usd-schemas`).25- Target API surface: C, Python, or both.26- Whether the caller needs just a count, the matched set to read from, or the reported attributes.27- The shipped headers and the referenced example/test snippets are the authoritative contract.2829## Prerequisites3031- Use an ovstage checkout that contains the `include/` headers and the referenced snippets.32- Read the relevant `> **Source:**` snippet before writing or explaining API usage.33- Understand the async **submit/observe** model (`cpu-ahead-gpu-async`): `query` is an enqueue34 returning a handle; drive it to completion (`ovstage_wait_op` / `.wait()`) before fetching.35- Queries resolve against the **latest committed state** — no write-floor advance is needed for a36 query to see a populated/written prim (reads of matched columns still target sealed data).3738## Instructions39401. Build the filter: a `Filter` is a conjunction (AND) of `Predicate`s; each predicate is an41 attribute + `FilterOp` + string values. A `None`/empty filter matches all prims.422. Enqueue `ovstage_query` (C) / `Stage.query` (Python) and drive it to completion.433. Fetch the result (`ovstage_fetch_query_result` / `Query.result()`): read `total_prim_count`,44 the reported `attributes`, and `all_handle` (the same query handle, echoed back).454. To read columns from the matched set, feed the query handle (or `all_handle`) to46 `read_attributes`.475. Release the query handle (and the result payload in C) before destroying the instance.486. For a known, explicit set of prims, prefer `query_from_path_list` (see `path-dictionary`).4950## Output Format5152- For explanations, cite the API names, the source snippet(s), the supported predicate matrix,53 and the population caveat.54- For code changes, summarize the files touched, snippets affected, and validation run.5556## Scripts5758This skill has no scripts.5960## Limitations6162- The referenced snippets remain the source of truth; update or add tested snippets before63 documenting new API usage.64- **Narrow support matrix.** The bindings/headers describe more operators than the current65 implementation accepts; anything outside the table below is rejected at enqueue66 (`NOT_SUPPORTED`).67- **Values are always strings**, even for token/type attributes. Predicates in one `Filter` AND68 together.69- **Metadata built-ins need population.** `usd-prim-type`/`usd-parent`/`usd-children`/`usd-schemas`70 are auto-maintained by the population bridge; a scene built only with `write_attribute` exposes71 `usd-path` and `HAS`-able user columns but not those relational built-ins.72- **Instancing queries require populated content.** C exposes the native `ovstage_instancing.h`73 path-list handles; Python exposes string-returning wrappers in `ovstage.instancing`.74- **⚠️ Draft — API in flux.** Treat exact symbols/ordering as provisional against the headers.7576## Overview7778`query` finds prims by predicate and reserves a query handle; `fetch_query_result` reports what it79matched. The supported predicate matrix:8081| Attribute | Operators | Selects |82|-----------|-----------|---------|83| any attribute | `HAS` | prims where the attribute exists (no value test) |84| `usd-path` | `IN`, `PREFIX` | exact path(s) / subtree (byte-prefix; trailing `/` scopes) |85| `usd-parent` | `IN` | direct children of the named parent(s) |86| `usd-children` | `CONTAINS` | prims having the named child |87| `usd-prim-type` | `IN` | prims of the named type(s) |88| `usd-schemas` | `CONTAINS` | applied-schema membership |8990> **`usd-active` is not supported.** It appears in the header contract for91> stability, but a live prim is always active, so the attribute carries no92> information; any read or predicate naming it is rejected with93> `NOT_SUPPORTED`. Subject to removal in a future release.9495> **`usd-active` is not supported.** It appears in the header contract for96> stability, but a live prim is always active, so the attribute carries no97> information; any read or predicate naming it is rejected with98> `NOT_SUPPORTED`. Subject to removal in a future release.99100## C101102Run one filter query per predicate (no path list — the stage finds the prims), then map the103scene-graph-instancing structure:104105> **Source:** `examples/c/queries/main.cpp` snippet `filter-predicates`106>107> Followed by: `examples/c/queries/main.cpp` snippet `query-introspection`108>109> Followed by: `examples/c/queries/main.cpp` snippet `instancing-queries-c` (scene-graph instancing)110111The public C test asserts the documented match set for each predicate against the produced package:112113> **Source:** `tests/c/test_queries.cpp` snippet `query-predicate-matrix-c`114115usd-path `IN` and attribute `HAS` also work on purely client-written prims (no population):116117> **Source:** `tests/c/test_queries.cpp` snippets `query-by-usd-path-c`, `query-has-attribute-c`118119Introspection — match count, the scoped attribute list, and the reusable `all_handle`:120121> **Source:** `tests/c/test_queries.cpp` snippet `query-result-introspection-c`122123## Python124125`Stage.query(filter=Filter([...]))` returns a `Query` handle; `Query.result()` reports the match:126127> **Source:** `examples/python/queries/main.py` snippet `filter-predicates`128>129> Followed by: `examples/python/queries/main.py` snippet `query-introspection`130>131> Followed by: `examples/python/queries/main.py` snippet `instancing-queries`132133The public Python test asserts the documented match set for each predicate against the wheel:134135> **Source:** `tests/python/test_queries.py` snippet `query-predicate-matrix`136137usd-path `IN` and attribute `HAS` also work on purely client-written prims (no population):138139> **Source:** `tests/python/test_queries.py` snippets `query-by-usd-path`, `query-has-attribute`140141Introspection — match count, the scoped attribute list, and the reusable `all_handle`:142143> **Source:** `tests/python/test_queries.py` snippet `query-result-introspection`144145## Key Types / Functions146147| Python | C |148|--------|---|149| `Stage.query(filter=, attrs=)` → `Query` | `ovstage_query(instance, filter, attrs, attr_count, &handle)` |150| `Query.result()` → `QueryResult` | `ovstage_fetch_query_result(instance, handle, timeout, &result)` |151| `QueryResult.total_prim_count` / `.attributes` / `.all_handle` | `ovstage_query_result_t.total_prim_count` / `.attributes` / `.all_handle` |152| `Filter([Predicate(attr, FilterOp.IN, [..])])` | `ovstage_filter_t` / `ovstage_predicate_t` / `ovstage_filter_op_t` |153| `Stage.release_query(handle)` | `ovstage_release_query` (+ `ovstage_release_query_result`) |154155## Troubleshooting156157- **Enqueue rejected `OVSTAGE_ERROR_NOT_SUPPORTED`** — the attribute+operator pairing is outside158 the matrix above. Use a supported pairing; the bindings advertise more than the engine accepts.159- **Zero matches for a metadata predicate** — the scene wasn't populated, so160 `usd-prim-type`/`usd-parent`/`usd-children`/`usd-schemas` aren't authored. Populate first, or161 filter on `usd-path`/`HAS`, which work on client-written prims.162- **`PREFIX "/World"` matches `/Worldwide`** — `usd-path` PREFIX is byte-prefix matching on the163 path string. Append a trailing `/` to scope to the subtree (`PREFIX "/World/"`).164- **`OVSTAGE_ERROR_WRITE_FLOOR_VIOLATION` reading a matched set** — the selected columns weren't165 sealed; advance the write floor to/above the write ordinal before reading (queries see latest166 committed state, but reads target sealed data). See `application-flow`.167- **`OVSTAGE_ERROR_OUT_OF_RANGE` reading a fixed range** — a selected `(attribute, path)` has a168 retained successor after the range end, so latest-only storage cannot represent the window.169 Widen/rebase the range or request latest state; advancing the floor alone does not fix it.170- **Handle leak / teardown crash** — release the query (and in C the query result) before171 destroying the instance; read-group prim lists are borrows, never `destroy_path_list` them.172173## References174175- Use the `> **Source:**` directives in this skill to locate tested snippets before reusing API patterns.176- `path-dictionary` — building path lists and `query_from_path_list` for a known prim set.177- `loading-usd` — population, which authors the metadata built-ins these filters match.178- `cpu-ahead-gpu-async` — the async submit/observe model queries share with every op.179- `application-flow` — where queries fit in the create → write → seal → read lifecycle.180- Keep related skills, docs, and snippets synchronized when changing the workflow.