urna inspect
Reference for urna inspect, which prints a .urna file's header, section table with checksums, manifest and hashes, as text or as JSON with blobs and spaces.
urna inspect prints what a .urna file declares: the header, every entry of the section table with its encoding, offset, size and checksum, the manifest, and the two hashes. With --json it prints one JSON document for programs, which also lists media blobs and named spaces.
Usage
urna inspect [OPTIONS] <FILE>Arguments
| Argument | Description |
|---|---|
<FILE> | Path to the .urna file |
Options
| Option | Default | Description |
|---|---|---|
--json | off | Emit as JSON instead of the human-readable layout. Schema: {magic, version_major, version_minor, format_version, schema_version, embedding_dim, n_chunks, n_embeddings, file_size, manifest, sections[], blobs, spaces[], file_hash, content_hash, simd_backend} |
-h, --help | Print help |
Behavior
The two modes open the file differently:
- The text layout reads the file into memory and runs the reader's integrity check (checksums, manifest, footer hash, contract). It does not decode the indices.
--jsonopens the file the way a search does (MmapUrnaFile::open): the integrity check plus the NaN walk, and a decode of the HNSW, BM25, graph, blob and space sections. A file whose index payload is malformed prints in text mode and fails with--json.
Neither mode checks that the embeddings match any model. See urna validate for what integrity means here.
Output
Text
Magic: "URNA"
Version: 1.0
File size: <bytes> bytes
Sections: <n>
0x<id> <name> encoding=<encoding> offset=<offset> size=<size> checksum=<16 hex>
Manifest:
<the manifest, pretty-printed JSON>
File hash: sha256:<64 hex>
Content hash: sha256:<64 hex>checksumis the section's 8-byte payload checksum, as 16 hex digits.encodingnamesraw,zstd,float16,int8,int4andintpack. The other text codecs (ids 5, 9, 10) print asunknown;--jsongives the numeric id.- Sections without a public name (
0x09,0x0A,0x0Band reserved ids) print asunknown.
JSON
--json prints one pretty-printed object:
| Key | Type | Meaning |
|---|---|---|
magic | string | URNA (or NEST for files from 0.4.0 and earlier) |
version_major, version_minor | number | Header version, 1 and 0 |
format_version, schema_version | number | From the manifest |
embedding_dim, n_chunks, n_embeddings, file_size | number | From the header |
manifest | object | The manifest as stored |
sections | array | One object per section table entry, see below |
blobs | array or null | Media blobs from blob_refs (0x14), null when the file declares none |
spaces | array or null | Named spaces from space_table (0x15), null when the file declares none |
file_hash | string | SHA-256 of the whole file |
content_hash | string | SHA-256 of the canonical sections |
simd_backend | string | The kernel this machine uses: avx2, neon or scalar. It describes the machine, not the file |
Each sections entry:
| Key | Type | Meaning |
|---|---|---|
section_id | number | Decimal id (12 is 0x0C) |
name | string | Section name, or unknown |
encoding | number | Wire encoding id (see Encodings) |
offset, size | number | Payload position and length in bytes |
checksum | string | 16 hex digits |
Each blobs entry:
| Key | Type | Meaning |
|---|---|---|
content_hash | string | sha256: hash of the original media bytes |
original_uri | string | The blob's uri |
byte_len | number | Length of the original bytes |
inlined | boolean | true when the bytes are inside this file (blob_data), false when they live in a sidecar file |
Each spaces entry:
| Key | Type | Meaning |
|---|---|---|
name | string | The name to pass to search-space --space |
space_index | number | Band index, 1 to 15 |
dim | number | Vector length for queries on this space |
dtype | string | Stored precision of the band |
model_hash | string | The model fingerprint recorded for the space |
n_vectors | number | Always equal to n_chunks |
band_bytes | number | Size of the band section |
blobs is filled only when the manifest sets capabilities_ext.blobs_present, and spaces only when it sets capabilities_ext.supports_multimodal.
The Python UrnaFile.inspect() returns the same document as a dict, with None for null (see UrnaFile). The wheel also installs its own urna command, whose inspect always prints JSON; which urna runs depends on your PATH (see The wheel's urna command).
Exit codes
| Code | Meaning |
|---|---|
0 | Printed |
1 | File missing or unreadable, or a failed check. Printed to stderr as Error: <message> |
2 | Usage error: a missing argument |
Examples
urna inspect examples/quickstart/out/quickstart.urnaMagic: "URNA"
Version: 1.0
File size: 17942 bytes
Sections: 9
0x01 chunk_ids encoding=intpack offset=1088 size=389 checksum=767fcd18ff76f81a
0x02 chunks_canonical encoding=zstd offset=1536 size=1484 checksum=37c32466fed5b2aa
0x03 chunks_original_spans encoding=zstd offset=3072 size=154 checksum=f5ebb8153ac42505
0x04 embeddings encoding=raw offset=3264 size=12288 checksum=8c05dacc9166c95e
0x05 provenance encoding=zstd offset=15552 size=118 checksum=520a09b8b7960591
0x06 search_contract encoding=zstd offset=15680 size=95 checksum=3dfaffaf63da0cd0
0x07 hnsw_index encoding=raw offset=15808 size=182 checksum=f5d4bddd060c3f1d
0x08 bm25_index encoding=zstd offset=16000 size=1695 checksum=83963b53867225ae
0x0c graph_adjacency encoding=raw offset=17728 size=174 checksum=70dcc63d4a7b1092
Manifest:
{
"format_version": 1,
"schema_version": 1,
"embedding_model": "minishlab/potion-base-8M/v1",
"embedding_dim": 256,
"n_chunks": 12,
"dtype": "float32",
"metric": "ip",
"score_type": "cosine",
"normalize": "l2",
"index_type": "hnsw",
"rerank_policy": "exact",
"model_hash": "sha256:8f2eb91a754b4da59cdd8223d0ba196185fed1bb6f092fd2be0ff02b893b1c98",
"chunker_version": "quickstart/1",
"capabilities": {
"supports_exact": true,
"supports_ann": true,
"supports_bm25": true,
"supports_citations": true,
"supports_reproducible_build": true
},
"title": "quickstart",
"version": "0.1.0",
"created": "1970-01-01T00:00:00Z",
"capabilities_ext": {
"graph_present": true
}
}
File hash: sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832
Content hash: sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09dfRead one field with jq:
urna inspect --json examples/quickstart/out/quickstart.urna | jq -r '.manifest.model_hash'sha256:8f2eb91a754b4da59cdd8223d0ba196185fed1bb6f092fd2be0ff02b893b1c98The same file as JSON, abridged to the header keys, one section, and the keys after sections:
{
"magic": "URNA",
"version_major": 1,
"version_minor": 0,
"format_version": 1,
"schema_version": 1,
"embedding_dim": 256,
"n_chunks": 12,
"n_embeddings": 12,
"file_size": 17942,
"sections": [
{
"section_id": 1,
"name": "chunk_ids",
"encoding": 4,
"offset": 1088,
"size": 389,
"checksum": "767fcd18ff76f81a"
}
],
"blobs": null,
"spaces": null,
"file_hash": "sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832",
"content_hash": "sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df",
"simd_backend": "neon"
}The byte layout behind these fields is in File format.
urna validate
Reference for urna validate, which checks a .urna file's header, section checksums, manifest, footer hash, contract, embedding values and inlined blobs.
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.