Segmentation Result Sets

A result set is one immutable execution's segmentations, identified by its run_id. A video legitimately has several — every run of green_valley_validation is its own result — so reading segmentations starts by choosing result sets, and the choice is always explicit.

All grace segmentations commands are read-only.

Select result sets

grace segmentations runs --video <VIDEO_ID>

Every option is a selection dimension; combine as many as you need:

Option	Meaning
--video, -V	Video id; repeat or comma-separate (up to 100)
--step-key	Producing step, e.g. green_valley_validation
--output-kind	Result type, e.g. validation_span
--method-name, --method-version	Producing implementation (matched exactly, never ordered)
--source-system + --source-execution-id	The producing execution (a pair)
--created-after, --created-before	RFC3339 with an offset, half-open
--run, -r	Run ids to pin (only with --policy exact)

Policies

--policy decides which of the matching sets you get:

Policy	Result
all (default)	Every matching set, newest first
latest_per_video	Per video, the newest set among those matching every other option
exact	Exactly the --run ids, in the order given

# The newest validation of each video made by one method version
grace segmentations runs --policy latest_per_video \
  --video <A> --video <B> \
  --step-key green_valley_validation --method-version manual-20260923-081306

A video with no matching set is reported on stderr (and as unmatched_video_ids with -o json).

Reproducing a read

Pin the run ids you read to get the same result sets back later. With exact, --video, --step-key and --output-kind become expectations: a pinned run that does not satisfy one fails the command and every mismatch is printed, and an unknown run id is an error — a pinned run is never silently dropped.

grace segmentations runs --policy exact --run <RUN_1> --run <RUN_2> --step-key green_valley_validation

Reading many pages

--all reads every page on one stable snapshot: result sets published while it runs never appear, and latest_per_video never switches to a newer set halfway.

grace -o json segmentations runs --policy latest_per_video --video <A>,<B>,<C> --all

To page by hand, pass --snapshot on page 1 and the printed --snapshot-id with the same options on later pages. A snapshot lives 24 hours and holds at most 10,000 result sets; broader, fleet-wide exports belong in Discovery.

Query segmentations

grace segmentations query returns the segmentations of the selected result sets, filtered on the server — no joining or filtering on your side. It takes every selection option above, plus:

Option	Meaning
--frames START:END (--frames-within)	Frame range; overlapping by default, or fully inside
--timestamps START:END (--timestamps-within)	Timestamp range, same modes
--payload KEY=VALUE	Payload key equals the string VALUE
--payload KEY:=JSON	Payload key equals a typed JSON scalar (true, 12.5, "x")
--type, --env, --task, --status	Exact values; repeat for OR
--include-deleted	Include soft-deleted spans
--no-payload	Lightweight records: no payload
--runs	Show each result set's count, live_count and matched_count (its spans matching the query, across all pages) — a table in table mode

# Deliverable kitchen spans inside frames 0–900 of each video's newest v1 validation
grace segmentations query --policy latest_per_video --video <A>,<B> \
  --step-key green_valley_validation --method-version v1 \
  --frames 0:900 --frames-within --env kitchen --payload deliverable:=true --no-payload

String or JSON?

--payload deliverable=true matches the string "true", not the boolean. The CLI warns when a value looks like a JSON literal; use deliverable:=true for the boolean.

Every row names the result set it came from (producing_run_id). Frames are shown only when the payload holds a valid interval; malformed historical values never fail the query.

--all reads every page on one stable resolution (result sets published meanwhile never appear) and streams: each page is written before the next is fetched, so memory holds one page no matter how many spans the selection has. With -o json the output is NDJSON of typed records, ready for jq -c or a file: {"record": "segmentation", ...} per span and, with --runs, {"record": "run", ...} once per result set, just before the first page that includes it. In table mode --runs adds a result-set table for the runs first seen on each page. --all --cursor <CURSOR> resumes an interrupted read from that page.

grace -o json segmentations query --video <A>,<B> --no-payload --runs --all > spans.ndjson
jq -c 'select(.record == "run") | {run_id, method_version, matched_count}' spans.ndjson

To page by hand, pass the printed --cursor with the same options.