Query JSON meta
Every successful nci query … --format json response includes a meta object next to data. Several fields look like performance signals; they answer different questions. This page is the contract for agents and automation.
See also JSON output schemas for the top-level envelope and per-subcommand data shapes.
meta.cost — query tier (not latency)
meta.cost is a fixed label per subcommand. It describes how “large” that query class is for agent workflow (bundle work vs a single lookup). It is not derived from meta.durationMs.
| Subcommand | meta.cost |
|---|---|
evidence | heavy |
find, symbols, active-package | moderate |
All other query subcommands (symbol, snippet, show, …) | light |
A fast find on a tiny index still returns moderate. A slow evidence call still returns heavy even when it finishes quickly. Use durationMs to ask whether this run was slow.
meta.durationMs — wall-clock time
durationMs is measured for this invocation only (milliseconds from query start to JSON print). Use it to detect a slow run on your machine or database size.
It does not change meta.cost.
meta.suggestions — slow and low-yield
suggestions is optional. It appears only when both are true:
- Slow:
durationMs >= 750by default. Override with theNCI_SLOW_QUERY_MSenvironment variable (see Environment variables). - Low yield: rules depend on the subcommand — for example zero hits on
find, orevidencewith no snippets / empty anchors.
When evidence returns useful data.snippets, no suggestions are attached even if the call took longer than the slow threshold.
Each suggestion is an object with subcommand and example (a copy-paste CLI line).
meta.truncated and the <truncated> sentinel
Two related signals when results hit a cap:
| Signal | Where | Meaning |
|---|---|---|
meta.truncated | meta | The query hit its row/limit cap. Extra fields vary by subcommand (returned, limit, uniqueHitsReturned, …). |
<truncated> | Last row of data.symbols (evidence only) | Sentinel hit: id, name, and kindName are the literal string <truncated>; other fields are empty. |
find / symbol: meta.truncated is true when the number of rows returned equals --limit (there may be more hits).
evidence: meta.truncated is true when deduplicated unique hits exceed --limit. The engine appends the sentinel row so clients can detect truncation from the symbol list without parsing only meta.