Index Refresh and Cache Controls

Overview

sqry index creates the persistent graph snapshot under .sqry/graph/. If that snapshot already exists, sqry index . exits without rebuilding unless you pass --force or --no-incremental. To refresh an existing graph after source changes, run sqry update ..

When --cache-dir <DIR> is supplied, sqry also writes a hash snapshot to <DIR>/file_hashes.bin. Current releases use this as a cache side channel for update/rebuild workflows; it is safe to delete and should normally be treated as local build state rather than committed project content.

How it works

sqry index .          ──▶ create .sqry/graph when missing; otherwise exit
sqry index --force .  ──▶ rebuild .sqry/graph and .sqry/analysis
sqry update .         ──▶ refresh an existing graph snapshot
--cache-dir DIR       ──▶ also write DIR/file_hashes.bin for that run

For the CLI surface:

sqry index . creates the graph if it is missing.
sqry index --force . rebuilds the graph even when a snapshot exists.
sqry index --no-incremental . also bypasses the existing-snapshot early exit and rebuilds.
sqry update . refreshes an existing graph; it reports git-aware mode when a git HEAD is available and hash-based mode otherwise.
--cache-dir <DIR> writes file_hashes.bin for the configured run.

The on-disk graph snapshot at .sqry/graph/snapshot.sqry is updated atomically. Concurrent reads (CLI/LSP/MCP queries) see a consistent view at all times.

Forcing a full rebuild

Two ways to bypass the existing-snapshot early exit:

sqry index --force .          # Rebuild even if .sqry/graph already exists
sqry index --no-incremental . # Rebuild and bypass the existing-snapshot early exit

Flag	Effect
`--force` (`-f`)	Rebuild even if `.sqry/graph/` already exists. Use after a major sqry upgrade or when the snapshot version bumps.
`--no-incremental`	Bypass the existing-snapshot early exit and run the rebuild path. Useful when comparing the normal early-exit behavior with a fresh build.
`--add-to-gitignore`	Appends the legacy `.sqry-index/` ignore entry if missing. For current graph state, add `.sqry/` and `.sqry-cache/` yourself if you want those directories ignored.

Custom cache directory

By default, sqry uses <workspace>/.sqry-cache/ for project cache state. Override the hash-snapshot location for a command with --cache-dir:

sqry index . --cache-dir /tmp/sqry-cache

This is most useful in:

Read-only or sandboxed source trees — point the cache at a writable scratch directory while keeping the project read-only.
Ephemeral CI runners — write cache state to a host-mounted volume instead of the checked-out tree.
Multi-checkout workflows — keep cache state outside individual worktrees.

The --cache-dir path is created if it does not exist. Relative paths are resolved against the current working directory.

Metrics export

sqry index --status prints metadata about the existing index — age, symbol count, languages, validation health. Combine it with --metrics-format for machine-readable output:

# JSON (default)
sqry index --status --json

# Prometheus / OpenMetrics text
sqry index --status --json --metrics-format prometheus

The Prometheus output is OpenMetrics-compatible and exports the status fields available from sqry index --status:

Metric	Type	Description
`sqry_index_exists`	gauge	Whether the graph index exists
`sqry_index_supports_fuzzy`	gauge	Whether fuzzy search is enabled
`sqry_index_supports_relations`	gauge	Whether relation queries are supported
`sqry_index_age_seconds`	gauge	Seconds since the snapshot was last written
`sqry_index_symbol_count`	gauge	Total indexed symbols
`sqry_index_file_count`	gauge	Total files indexed
`sqry_index_stale`	gauge	Whether sqry considers the index stale
`sqry_index_cross_language_relation_count`	gauge	Cross-language relation count when present

Pipe the output directly into a Prometheus push gateway, or scrape it from a CI job:

sqry index --status --json --metrics-format prometheus \
  | curl --data-binary @- "http://pushgateway:9091/metrics/job/sqry/instance/$(hostname)"

Validation modes

Independently of the cache, --validate <mode> on sqry search and sqry query controls how strict sqry is about source-file drift detected during a query:

Mode	Behaviour
`warn` (default)	Log a warning on drift, return results from the snapshot.
`fail`	Exit with code `2` if more than 20% of indexed files are missing on disk.
`off`	Skip validation entirely (fastest).

sqry search "test" --validate fail   # CI-friendly strict mode
sqry search "test" --validate off    # Hot-path performance mode

Inside the daemon

When sqry runs as a daemon (see Daemon (sqryd)), the file-system watcher debounces events over debounce_ms (default 2000 ms) and triggers the daemon rebuild path automatically for loaded workspaces. Use sqry daemon rebuild <path> when you want to request that refresh explicitly.

Troubleshooting

“Snapshot version mismatch”: A major sqry upgrade bumped the snapshot format. Run sqry index --force . once to rewrite the snapshot in the new format. Hash cache survives across version bumps; the snapshot does not.
Stale results after editing files outside the editor: If you edit files via a tool sqry’s daemon watcher doesn’t see (e.g. git checkout of a different branch), run sqry update . to refresh, or call sqry daemon rebuild <path> to refresh a daemon-loaded workspace.
Hash index corrupt: remove the configured cache directory, then run sqry update . or sqry index --force ..
Cache dir on a slow filesystem (NFS, shared SMB): set --cache-dir /tmp/sqry-cache to keep the hash index on local disk.
Disk full during an index run: sqry writes the snapshot atomically — a partial write is rolled back. Free space and rerun.

Daemon (sqryd) — keep the graph warm in memory; integrates with the same hash-index machinery.
Configuration — environment variables that influence cache and indexing throughput.
Performance — measured benchmarks for cold and warm index runs.

Edit this page on GitHub →