urna 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 search-graph searches a .urna file through its chunk-to-chunk graph with a query vector you supply as a JSON array. It seeds from the exact-cosine top chunks, walks the graph a bounded number of hops, and reranks the union of seeds and neighbours by exact cosine. If the file has no usable graph, it runs the exact path instead.
Usage
urna search-graph [OPTIONS] <FILE> <QUERY>Arguments
| Argument | Description |
|---|---|
<FILE> | Path to the .urna file |
<QUERY> | The query vector as a JSON array of numbers, with exactly embedding_dim values |
Options
| Option | Default | Description |
|---|---|---|
-k, --k <K> | 10 | Number of hits to return. Must be greater than 0 |
--hops <HOPS> | 1 | How many graph steps to expand from the seeds |
--ef <EF> | 100 | Seed count: the seeds are the exact top max(ef, k) chunks, capped at the chunk count |
-h, --help | Print help |
Behavior
- Opens the file with the full runtime check. The graph is decoded only when the
graph_adjacencysection (0x0C) is present and the manifest setscapabilities_ext.graph_present. - Parses
<QUERY>as JSON. - Without a usable graph, runs urna search and prints its result (
index_type: exact). - Otherwise validates and L2-normalizes the query, scores every chunk to pick the seeds, expands them breadth-first for
--hopssteps over every edge type, and stops adding nodes atmax(8 * seeds, seeds). - Rescores the union by exact cosine and returns the top
k.
Graphs written by urna.build and the forge hold two edge types: next-chunk edges in both directions, and up to graph_top_m (default 8) semantic edges per chunk taken from the HNSW graph.
The hits equal the exact hits
The seeds are already the exact top max(ef, k), and the rerank uses the same scores and tie order as the exact path. A neighbour the graph adds can only enter the top k by beating a seed, which it cannot do. In 0.5.1 the graph path returns the same hits as urna search, at the cost of a full exact scan plus the traversal. ask and retrieve never take this path.
There is no model gate on this verb: embed the query with the model the file names.
Output
The same block as urna search. On the graph path the result says index_type: graph, recall is printed as (not computed; rerank guarantees real cosine), and every hit has reranked=true.
Exit codes
| Code | Meaning |
|---|---|
0 | Search ran and printed its result |
1 | Any error: file missing or unreadable, a failed integrity check or a malformed graph payload, invalid query JSON, wrong dimension, NaN or Inf, zero-norm query, k of 0 or less. Printed to stderr as Error: <message> |
2 | Usage error: a missing or unparseable argument |
Examples
The quickstart corpus carries a graph. query.json holds the stored embedding of its first chunk:
urna search-graph examples/quickstart/out/quickstart.urna "$(cat query.json)" -k 2 --hops 2index_type: graph
recall: (not computed; rerank guarantees real cosine)
truncated: true
k_requested: 2
k_returned: 2
query_time: 0.014 ms
hits:
[ 1] chunk_id=sha256:19f36b3e072d553eb83626bf30db5e8f3b1f729a495f7826999ffeae53848e6e score=1.000000 score_type=cosine source_uri=demo/01-what-is-urna.md offset=0-1 model=minishlab/potion-base-8M/v1 index_type=graph reranked=true file_hash=sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832 content_hash=sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df citation_id=urna://sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df/sha256:19f36b3e072d553eb83626bf30db5e8f3b1f729a495f7826999ffeae53848e6e
[ 2] chunk_id=sha256:47ecc7e1141759d285f08545d74de807a0196a73d5db27b024e7bbe3b2f78bb4 score=0.664475 score_type=cosine source_uri=demo/03-citations.md offset=6-7 model=minishlab/potion-base-8M/v1 index_type=graph reranked=true file_hash=sha256:e4d5f8907faad38c192dc6929e36dbf16db558410b2dae5abb4d65f10f508832 content_hash=sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df citation_id=urna://sha256:1147b2560863331b21bd9d60fe6bdd99507dc34e17108444dc38194f8e6f09df/sha256:47ecc7e1141759d285f08545d74de807a0196a73d5db27b024e7bbe3b2f78bb4The hits and scores match urna search on the same query.
urna search-ann
Reference for urna search-ann, which forces the HNSW path with a JSON query vector, reranks the candidates by exact cosine, and falls back to exact.
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.