Search Guide
Choose a retrieval route, narrow the workspace, and tune Zvec-Grep results.
Zvec-Grep offers complementary routes behind one zg query command. Start with the route that matches what you know, then narrow the search space before increasing the result count.
Choose a Route
| Your intent | Command | Behavior |
|---|---|---|
| Discover by meaning or combine meaning with keywords | zg query "authentication flow" | Hybrid ranked sample |
| Rank known terms by relevance | zg query --fts "AuthService" | BM25-ranked sample |
| Search only by conceptual similarity | zg query --vector "where credentials are validated" | Vector-ranked sample |
| Find every literal or regex occurrence | zg query --rg -n -F "AuthService" src | Exhaustive unless bounded |
Use --rg for exact or exhaustive work. Use indexed retrieval when wording or location is unknown, or when the answer requires relationships across files.
The default positional query combines lexical and vector retrieval:
zg query --human "where are user preferences restored at startup" --limit 5When a question also contains exact anchors, fuse them into one ranked plan:
zg query --hybrid "authentication flow" --fts "ForbiddenError" --fuse --limit 10Narrow the Workspace
zg query "plugin lifecycle" -g "src/**" -g "!src/generated/**" -t ts| Option | Use it to |
|---|---|
-g, --glob, --iglob | Include or exclude paths |
-t, --type, -T, --type-not | Filter file types |
--modified-after / --modified-before | Filter by modification time |
Control Results and Freshness
| Option | Effect |
|---|---|
--limit <n> | Maximum results per query group |
--human | Fuller terminal-oriented previews |
--preview none|short|full | Indexed source preview size |
--debug / --trace | Query and per-hit diagnostics |
--refresh background|wait|off | Index freshness policy |
Indexed results report fresh or possibly_stale. Use --refresh wait only when the latest file changes must be included.
Improve Weak Results
- Confirm the workspace root and index state with
zg status. - Restrict the query to relevant paths or file types.
- Add one or two concrete anchors with
--fts. - Switch to
--rgwhen the target text is known. - Review Supported Content and the selected Embedding Models.
Run zg help query for the installed version's complete flag reference. If results remain weak, follow Troubleshooting.