# Stage Queries

> Discovering prims on the runtime stage and inspecting their attribute schemas. Use when user asks to find prims by type, filter by attribute, list all prims, or look up attribute types before reading or writing them.

- Skill: `nvidia-omniverse-ovrtx/stage-queries` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nvidia-omniverse-ovrtx/stage-queries`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia-omniverse-ovrtx/stage-queries/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: LicenseRef-NvidiaProprietary
- Author: nvidia-omniverse (https://skillmd.com/u/nvidia-omniverse-ovrtx)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/nvidia-omniverse-ovrtx/stage-queries

---


# Stage Queries

## When to Use

Use this skill when the user asks to find prims by type, filter by attribute, list all prims, or look up attribute types before reading or writing them.

## Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

- Target API surface: Python, C/C++, or both.
- Query goal: list all prims, filter by prim type, require/exclude attributes, or inspect attribute schemas before read/write.
- Filter predicates, requested attribute tokens, and whether names must be resolved through a path dictionary.
- Desired execution mode: Python ovstage query or C compatibility query.
- Repository source snippets referenced below. Treat these snippets as the API source of truth.

## Prerequisites

- Use an ovrtx checkout that contains the referenced examples and docs tests.
- Read the relevant `> **Source:**` snippet before writing or explaining API usage.
- Use this before attribute read/write skills when the target prim list or schema is unknown.

## Instructions

1. Identify whether the caller needs all prims, prims by type, prims with required attributes, or a filtered include/exclude query.
2. Read the matching Python or C query snippet before choosing filter fields or result traversal.
3. For async queries, preserve the two-phase wait/fetch lifecycle before reading result dictionaries or C result arrays.
4. In C, resolve path and attribute IDs through the path dictionary before presenting names to users.
5. When changing code, run the stage-query docs test that owns the snippet whenever practical.

## Output Format

- For explanations, cite the relevant API names, source snippets, and caveats.
- For code changes, summarize the files changed, 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.

## Overview

`stage.query` finds prims on ovstage that match a filter. A query handle can be reused by subsequent ovstage read, write, and map calls, so a typical workflow is:

1. Query to discover prims and/or their attribute schemas.
2. Decide what to read/write based on the result.
3. Reuse the query handle to read or write without re-resolving paths.

Build an `ovstage.Filter` from predicates such as `usd-prim-type` or `usd-path`. Pass interned attribute tokens through `attrs` when the query should report specific columns. The deprecated renderer query remains useful only for compatibility cases that require its OR/NOT filter shape.

## Python

### Discover every prim (no attribute descriptors)

> **Source:** `tests/docs/python/test_stage_query.py` snippet `doc-query-prims-basic`

### Filter by USD prim type

> **Source:** `tests/docs/python/test_stage_query.py` snippet `doc-query-prims-by-type`

### Request specific attribute descriptors

Intern requested names through `ovstage.PathDictionary`, then inspect the attribute token ids reported by the result.

> **Source:** `tests/docs/python/test_stage_query.py` snippet `doc-query-prims-with-attributes`

### Deprecated compatibility: combine OR and NOT filters

> **Source:** `tests/docs/python/test_stage_query.py` snippet `doc-query-require-any-exclude`

### Async query

An ovstage query can be waited explicitly before calling `.result()`. Release manually created queries when they are no longer needed, or use a context manager.

> **Source:** `tests/docs/python/test_stage_query.py` snippet `doc-query-prims-async`

## C

### Basic query

> **Source:** `tests/docs/c/test_stage_query.cpp` snippet `doc-query-prims-basic-c`

### Filter by prim type

> **Source:** `tests/docs/c/test_stage_query.cpp` snippet `doc-query-prims-by-type-c`

### Filter by attribute existence

> **Source:** `tests/docs/c/test_stage_query.cpp` snippet `doc-query-has-attribute-c`

### Combine OR and NOT filters

> **Source:** `tests/docs/c/test_stage_query.cpp` snippet `doc-query-require-any-exclude-c`

### Empty specific-attribute lists

> **Source:** `tests/docs/c/test_stage_query.cpp` snippet `doc-query-specific-empty-attributes-c`

### Path dictionary round-trip

The renderer's path dictionary resolves `ovx_primpath_t` / `ovx_token_t` handles to strings and back. It is valid for the lifetime of the renderer — no release call is required.

> **Source:** `tests/docs/c/test_stage_query.cpp` snippet `doc-path-dictionary-resolve-c`

Python ovstage code should use `ovstage.PathDictionary` to intern attribute tokens and create path lists.

## Key Types / Functions

| Python | C |
|--------|---|
| `stage.query(filter=..., attrs=...)` | `ovrtx_query_prims(renderer, &desc, &query_handle)` + `ovrtx_fetch_query_results(...)` |
| `ovstage.Filter` / `ovstage.Predicate` | `OVRTX_FILTER_*` compatibility filters |
| `ovstage.PathDictionary(stage)` | `ovrtx_get_path_dictionary(renderer, &pd)` |

C result shape:
- `ovrtx_query_result_t.groups` — one `ovrtx_query_prim_group_t` per attribute-schema bucket.
- Each group's `prim_list_handle` is a persistent `ovx_primpath_list_t` that plugs into `ovrtx_binding_desc_t::prims_list_handle`.
- Attribute names are returned as tokens — resolve via the path dictionary's `get_strings_from_tokens`.

## Troubleshooting

- In C, the pointers in `ovrtx_query_result_t` and `ovrtx_query_prim_group_t` become invalid after `ovrtx_release_query_results()`. Copy anything you want to keep.
- Deprecated renderer queries use `AttributeFilterMode`; `SPECIFIC` with an empty `attribute_names` list returns no descriptors, while `ALL` returns every descriptor and `NONE` performs lightweight discovery.
- Deprecated renderer query descriptors report relationship-valued attributes with `Semantic.PATH_ID`, not `PATH_STRING`.
- Ovstage query results return attribute-name token IDs. Resolve them with `ovstage.PathDictionary.token_to_string()`.
- An empty deprecated renderer filter matches every prim; pair it with `AttributeFilterMode.NONE` for the cheapest full-stage walk.

## Deprecated Standalone APIs

`query_prims*` is deprecated in 0.4 and retained for compatibility. New code should
query ovstage directly and use the ovstage-owned path dictionary for path lists and
token identities.

See `docs/core/ovstage_integration.rst`, `skills/update-0_3-0_4-c/SKILL.md` and `skills/update-0_3-0_4-python/SKILL.md`.

## References

- Use the `> **Source:**` directives in this skill to locate tested snippets before reusing API patterns.
- Keep related skills, docs, and snippets synchronized when changing the workflow.