urna stats

urna stats prints a one-screen summary of a .urna file: its size, chunk count, embedding dim and dtype, the search contract, the embedding model and its hash, the section sizes, any named spaces, and the two hashes. Use it to find out which model a corpus needs and which search path ask will take.

UsageCopy Anchor Link

urna stats <FILE>

ArgumentsCopy Anchor Link

OptionsCopy Anchor Link

BehaviorCopy Anchor Link

stats reads the file into memory and runs the reader's integrity check (checksums, manifest, footer hash, contract) before printing. It does not decode the indices or walk the embeddings for NaN; urna validate does the NaN walk.

OutputCopy Anchor Link

To stdout, one field per line:

Three details:

• The runtime opens the HNSW and BM25 indices when their sections are present; it does not read supports_ann or supports_bm25. Read the sections list to see what the file carries.
• index_type is what routes ask and retrieve (see how ask and retrieve choose a path). A file with a BM25 section and index_type: hnsw never uses BM25 from those verbs.
• Encoding names cover raw, zstd, float16, int8, int4 and intpack; the other text codecs print as unknown. Section names print as unknown for 0x09, 0x0A, 0x0B and reserved ids.

The Python wheel installs its own urna command, whose stats prints no size and no spaces block. See The wheel's urna command.

Exit codesCopy Anchor Link

ExamplesCopy Anchor Link

urna stats examples/quickstart/out/quickstart.urna

file:         examples/quickstart/out/quickstart.urna
size:         17942 bytes (0.02 MB)
chunks:       12
embeddings:   12
dim:          256
dtype:        float32
metric:       ip
score_type:   cosine
normalize:    l2
index_type:   hnsw
rerank:       exact
model:        minishlab/potion-base-8M/v1
model_hash:   sha256:8f2eb91a754b4da59cdd8223d0ba196185fed1bb6f092fd2be0ff02b893b1c98
chunker:      quickstart/1
supports_ann: true
supports_bm25:true
simd_backend: neon
sections:     9
  0x01 chunk_ids                encoding=intpack  389 bytes
  0x02 chunks_canonical         encoding=zstd     1484 bytes
  0x03 chunks_original_spans    encoding=zstd     154 bytes
  0x04 embeddings               encoding=raw      12288 bytes
  0x05 provenance               encoding=zstd     118 bytes
  0x06 search_contract          encoding=zstd     95 bytes
  0x07 hnsw_index               encoding=raw      182 bytes
  0x08 bm25_index               encoding=zstd     1695 bytes
  0x0c graph_adjacency          encoding=raw      174 bytes
file_hash:    sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832
content_hash: sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df

This corpus was embedded with minishlab/potion-base-8M/v1, so the potion embedder that ships with the installed binary can query it. A corpus built with a registry model (the clip-vit-b32, siglip2, jina-v5-omni or wemm presets) needs a repo checkout and that model's Python dependencies before ask or retrieve can query it with text. See Open a corpus you downloaded.

For every byte of the header and section table, use urna inspect.