urna media
Reference for urna media, which lists the media blobs a .urna corpus references and exports the inlined ones to files after checking each SHA-256.
urna media lists the media blobs, such as the encoded images of an image corpus, that a .urna corpus references. With --export, it writes the blobs stored inside the file back out as standalone files, checking each one against its recorded SHA-256 before writing it.
Usage
urna media [OPTIONS] <FILE>Arguments
| Argument | Description |
|---|---|
<FILE> | Path to the .urna file |
Options
| Option | Default | Description |
|---|---|---|
--export <EXPORT> | Directory to write the inlined blobs to. Created if it does not exist | |
-h, --help | Print help |
Behavior
A media corpus records its blobs in blob_refs (0x14): one entry per blob with the SHA-256 of the original bytes, a uri, the byte length, and whether the bytes are inlined. Inlined bytes live in blob_data (0x17) inside the .urna. The others are sidecar files kept next to the corpus; the forge writes them to <name>.media/ unless [output] embed_media = true (see the output table of the spec).
- Opens the file with the full runtime check. The blob tables are read only when the manifest sets
capabilities_ext.blobs_present. - If there is no blob table, prints
no media: <file> declares no blob_refs (0x14)and exits 0, with or without--export. - Prints a summary line and one line per blob, in table order.
- With
--export: fails if the file has noblob_datasection. Otherwise, for each inlined blob in order, computes its SHA-256, refuses to continue if it differs fromblob_refs, and writes it to the export directory. Sidecar blobs are skipped.
Export names each file after the last path component of its uri, with any media:// prefix removed, so a uri can never write outside the export directory. A file that already exists with that name is overwritten. Each blob is checked right before it is written, so when one blob fails its hash, the inlined blobs before it are already on disk.
Output
To stdout:
media blobs: <n> (<inlined> inlined, <sidecar> sidecar), inlined bytes: <bytes>
[<i>] <uri> <byte_len> bytes inlined|sidecar
exported <n> blobs to <dir>The exported line appears only with --export. For a JSON view of the same table, use urna inspect --json (the blobs array).
Exit codes
| Code | Meaning |
|---|---|
0 | Listed (and exported, with --export), or the file declares no media |
1 | File missing or unreadable, a failed check, --export on a file with no blob_data, a blob that fails its SHA-256, a blob with no usable file name, or a write error. Printed to stderr as Error: <message> |
2 | Usage error: a missing argument |
The export errors read:
Error: <file> has no blob_data (0x17): its media lives in the sidecar files listed above
Error: blob <i> (<uri>) failed its content_hash check; refusing to exportExamples
List the media of a corpus and export the inlined blobs:
urna media corpus.urna
urna media corpus.urna --export ./media-outThe quickstart corpus is text only:
urna media examples/quickstart/out/quickstart.urnano media: examples/quickstart/out/quickstart.urna declares no blob_refs (0x14)How media gets into a corpus is covered in Images and PDFs and Media and named spaces.
urna stats
Reference for urna stats, which prints a .urna file's size, chunk count, dim, dtype, search contract, model, sections, named spaces and hashes.
urna benchmark
Reference for urna benchmark, which times exact search on random query vectors, and optionally HNSW with recall@k, a cold-cache pass, or a named space.