---
generator: "vaultspec-marketing discovery"
title: "Writing a query that finds the right result - vaultspec-rag documentation"
description: "Describe the behavior you want to find, then narrow the search with filters."
url: "https://vaultspec.neve.md/docs/rag/query-craft.html"
component: "vaultspec-rag"
source_repository: "https://github.com/nevenincs/vaultspec-rag"
source_path: "docs/query-craft.md"
source_commit: "d126f083802311e30300d2c5e98f087806172a52"
date_modified: "2026-10-04T20:56:03+02:00"

---

[View as Markdown](<https://vaultspec.neve.md/docs/rag/query-craft.md>)

# Writing a query that finds the right result

Describe the behavior you want to find, then narrow the search with filters.

Examples use the `uv run` prefix, which runs the command inside a project environment. If you installed vaultspec-rag as a standalone tool, drop the prefix and call `vaultspec-rag` directly; see the [installation guide](<https://vaultspec.neve.md/docs/rag/installation.html>).

## Check file coverage

If expected code is missing from results, [check which files would be indexed](<https://vaultspec.neve.md/docs/rag/verification.html#is-it-indexing-the-right-files>) and [check index status](<https://vaultspec.neve.md/docs/rag/verification.html#check-index-status>). A dry run previews file selection; it does not show what is already stored.

## Narrow results with filters

Keep your query and add a filter to select part of the index.

### Document results

Limit document results to ADRs. Replace the query with your own; it is a stand-in:

**Command**

```bash
uv run vaultspec-rag search "cache control on deployed assets" --type vault --doc-type adr
```

To search one feature across document types, replace `docs-site` with your feature tag:

**Command**

```bash
uv run vaultspec-rag search "cache control on deployed assets" --type vault --feature docs-site
```

### Code results

Exclude a directory you don’t want in results. Replace the query and the `.claude/*` glob with your own:

**Command**

```bash
uv run vaultspec-rag search "gpu lock around the forward pass" --type code --exclude-path ".claude/*"
```

Append `--language python` to limit code results to Python.

See the [filter reference](<https://vaultspec.neve.md/docs/rag/query-craft.html#the-filter-surface>) for more options.

## Name the nouns, and ask one thing

Describe the behavior you want to find. Include relevant identifiers or technical terms when you know them:

**Command**

```bash
uv run vaultspec-rag search "immutable cache-control on non-hashed assets" --type vault
```

Ask one question at a time. Split unrelated questions into separate searches.

## The filter surface

When no search type is specified (no `--type`), search defaults to source code and architecture decision records (ADRs), ranked together. `--doc-type plan` (or inline `type:plan`) overrides the default ADR filter while retaining code results.

An explicit `--type` picks the content domain: `vault`, `code`, `document`, or `combined`. `--type vault` searches all vault record types; `--type combined` searches all three indexes, including extracted documents. The filters below then split by what they narrow. A filter that does not apply to the chosen `--type` is rejected as a usage error, so a code filter with `--type vault` fails instead of being ignored. `--type combined` accepts them all.

Code results:

| Filter | Narrows to |
| --- | --- |
| `--language` | one programming language |
| `--path` | one exact project-relative path |
| `--include-path` / `--exclude-path` | paths matching or missing a pattern |
| `--function-name` / `--class-name` | one function or class |
| `--structure` | one source-code structure kind |

To favor production code, tests, or documentation without excluding other code results, use [`--prefer`](<https://vaultspec.neve.md/docs/rag/search-and-index.html#prefer-production-tests-or-documentation>).

Vault results:

| Filter | Narrows to |
| --- | --- |
| `--doc-type` | `adr` (decision), `plan`, `exec` (execution), `audit`, `research`, `reference` |
| `--feature` | one feature tag |
| `--date` | one date |
| `--tag` | one frontmatter tag |

`--doc-type` also takes a comma-separated union, such as `--doc-type adr,plan`.

Extracted-document results:

| Filter | Narrows to |
| --- | --- |
| `--source-path` | one originating file |
| `--extractor-id` | documents emitted by one extractor |
| `--extractor-version` | documents from one extractor version |
| `--locator-kind` | one kind of locator, such as `page` or `sheet` |

### Query markers

Write markers anywhere in the query text. Most mirror a flag, so `type:adr` does what `--doc-type adr` does. Five have no flag equivalent and can only be written this way.

| Group | Markers |
| --- | --- |
| Documents | `type:` `feature:` `date:` `tag:` |
| Code | `lang:` `path:` `func:` `class:` `nodetype:` |
| Noise, no flag | `only:` `exclude:` `include:` |
| Ranking, no flag | `status:` `intent:` |

The noise markers take one or more domains from `prod`, `tests`, `docs`, `locale`, `generated`, `vendored`, and `worktree`. The default profile hides some domains and demotes others, so `only:prod` keeps production code and `exclude:tests` drops a test tree that would otherwise still be returned, lower down. The defaults are listed under [filter noise by domain](<https://vaultspec.neve.md/docs/rag/search-and-index.html#filter-noise-by-domain>). Comma-separated sets accumulate when repeated.

`status:` and `intent:` apply to vault results only. `status:` takes `all`, `active`, or a comma-separated set such as `accepted,proposed`. `intent:` takes `orientation`, the default, or `debugging`, which reorders results for tracking down a fault rather than getting your bearings. `debug` is accepted as an alias for `debugging`.

**Command**

```bash
uv run vaultspec-rag search "auth token validation only:prod" --type code
uv run vaultspec-rag search "gpu lock decision type:adr status:active"
```

`path:` is the in-query spelling of `--include-path`: it takes a pattern, and a plain one matches that path and everything under it. `--path` is a different, exact-path filter.

### Inspect result scores

Show numeric scores alongside results:

**Command**

```bash
uv run vaultspec-rag search "graph rebuild race" --type vault --scores
```

Scores help compare ranked results; they aren’t probabilities that your question has been answered. Their meaning depends on the ranking configuration. No universal score cutoff establishes whether your index contains an answer.

When `VAULTSPEC_RAG_TYPESAFE_API_KEY` is set in the service’s environment, a hosted classifier also reweights candidates and can drop confidently irrelevant ones, so results and scores differ from local ranking. See [Typesafe enrollment](<https://vaultspec.neve.md/docs/rag/configuration.html#typesafe-enrollment>). The scores described in this documentation come from local ranking.

`--max-results` caps the results at 10 by default, but doesn’t guarantee that many matches. Results can be irrelevant, and empty output doesn’t explain why.

Use `--json` for structured output. See the [search options](<https://vaultspec.neve.md/docs/rag/cli.html#search>) for details.

## When a result looks wrong

1. Read the returned passages to check whether they answer your question.
2. [Check file coverage](<https://vaultspec.neve.md/docs/rag/query-craft.html#check-file-coverage>) and index status if expected code is missing.
3. Add the filter that states which kind of thing you want.
4. If results arrive doubled, exclude the duplicate tree with an `--exclude-path` pattern. The `worktree` domain already hides `.claude/worktrees/` and `.git/worktrees/` by default, so a sibling clone of the repository needs the path pattern.
5. If the query carries two ideas, split it into two searches.
6. Reword, naming the concrete nouns the target would contain.

If none of that helps, the [issue tracker](<https://github.com/nevenincs/vaultspec-rag/issues>) takes questions as well as bug reports. Include the query, the flags, and the `--scores` output.

## Related documentation

- [Retrieval recipes](<https://github.com/nevenincs/vaultspec-rag/blob/d126f083802311e30300d2c5e98f087806172a52/docs/examples.md>) shows worked searches, including the questions this tool answers badly.
- [Search and index](<https://vaultspec.neve.md/docs/rag/search-and-index.html>) covers running searches and refreshing the index.
- [CLI reference](<https://vaultspec.neve.md/docs/rag/cli.html>) lists every flag with its type and default.
- [Verify the index](<https://vaultspec.neve.md/docs/rag/verification.html>) covers health, currency, and coverage.
- [Indexing](<https://vaultspec.neve.md/docs/rag/indexing.html>) covers profiles, admission, the encoders, and how the two signals are [fused](<https://vaultspec.neve.md/docs/rag/indexing.html#hybrid-search-with-fusion>).
- [Glossary](<https://github.com/nevenincs/vaultspec-rag/blob/d126f083802311e30300d2c5e98f087806172a52/docs/glossary.md>) defines the vocabulary used here.