Choose Efficient Loading and Writes

Keep queries and writes efficient as the number of resources and runs grows.

RECAP provides explicit controls for relationship hydration and known-record updates. Use them to avoid loading more of the provenance graph than a task requires.

Keep query payloads small

Use references for identity-only results, explicit relationship paths for targeted hydration, and pagination for large result sets. See Choose query shape and loading, Query Resources, and Query Process Runs.

Use descendants() or under_parent() for targeted resource subtree queries instead of eager-loading an entire large hierarchy. See Trace Provenance for traversal patterns.

Test suites

Run default tests with pixi run test. This excludes SQL statement-budget regressions. Run those regressions with pixi run test-performance; run all tests with pixi run test-all before release or when changing query loading.

Update known records by ID

Builders accept resource_id= and process_run_id= for existing records. These paths avoid probing by name and avoid an insert-conflict-rollback-select cycle. See Use revisions and idempotency for known-ID update procedures.

with namespace.build_resource(resource_id=resource_id) as builder:
    resource = builder.get_model()
    resource.properties.status.used = True
    builder.set_model(resource)

Group work by namespace

Namespace context controls visibility and authorization. Reuse one namespace client for a batch of related operations rather than repeatedly switching contexts.