urna search-space
Reference for urna search-space, the exact search over one named embedding space of a multimodal .urna file, with an optional model_hash assertion.
urna search-space runs an exact search over one named embedding space of a .urna file, such as an image tower stored next to the text embeddings. You pass the space name and a query vector embedded with that space's model. Hits map back to chunks, so they carry the same chunk_id and citation as any other hit on that chunk.
Usage
urna search-space [OPTIONS] --space <SPACE> <FILE> <QUERY>Arguments
| Argument | Description |
|---|---|
<FILE> | Path to the .urna file |
<QUERY> | JSON array of f32 at the space's dim |
Options
| Option | Default | Description |
|---|---|---|
--space <SPACE> | required | Space name as listed by stats / inspect --json (e.g. "wemm-2b@256") |
-k, --k <K> | 10 | Number of hits to return. Must be greater than 0 |
--expect-model-hash <EXPECT_MODEL_HASH> | Also assert the space's model_hash equals this value | |
-h, --help | Print help |
Behavior
- Parses
<QUERY>as JSON, before opening the file. - Opens the file with the full runtime check. Named spaces are opened when the manifest sets
capabilities_ext.supports_multimodal; each band is checked for NaN and Inf. - Looks up the space by name. An unknown name fails with
embedding space not found. - When
--expect-model-hashis given, compares it with the space's recordedmodel_hashand fails on a mismatch. - Validates the query against the space's dim (not the file's
embedding_dim):kabove 0, not empty, right length, no NaN or Inf, norm not zero. Then L2-normalizes it. - Scores every vector in the space's band by cosine and returns the top
k.
The verb never falls back to the text embeddings: a wrong name, a wrong dim or a wrong hash is an error. The text paths (search, ask, retrieve) never read a space band either.
Without --expect-model-hash there is no model check. Pass the hash from urna stats or inspect --json when you want the run to refuse a query built for a different space.
Space names
Find the names with urna stats (a spaces: block, present only when the file has a space table) or urna inspect --json (the spaces array, null when there is none). The forge names them after the model preset and dim: <preset> or <preset>@<dim> for an image tower, <preset>-text or <preset>-text@<dim> for a text tower. A file holds at most 15 named spaces. See Media and named spaces.
Output
A space: line with the name, then the same block as urna search. The result reports index_type: space and recall: 1, and hits have reranked=false, because the space path is an exact scan. The model field of each hit shows the file's text embedding_model, not the space's model.
Exit codes
| Code | Meaning |
|---|---|
0 | Search ran and printed its result |
1 | Any error: <QUERY> is not a JSON array of numbers, file missing or unreadable, a failed integrity check, unknown space, model_hash mismatch, wrong dimension, NaN or Inf, zero-norm query, k of 0 or less. Printed to stderr as Error: <message> |
2 | Usage error, including a missing --space |
Examples
Search the wemm-2b@256 space of a multimodal corpus and assert its model:
urna search-space corpus.urna "$(cat image-query.json)" --space wemm-2b@256 -k 5 \
--expect-model-hash sha256:<64 hex digits from urna stats>On a file with no named spaces, such as the quickstart corpus, the lookup fails:
urna search-space examples/quickstart/out/quickstart.urna "$(cat query.json)" --space wemm-2b@256Error: embedding space not found: wemm-2b@256urna search-graph
Reference for urna search-graph, which seeds from the exact top ef, expands over the chunk graph for a number of hops, and reranks the union by cosine.
urna cite
Reference for urna cite, which resolves a urna://content_hash/chunk_id citation into the chunk's stored text and source span after checking the content_hash.