Query Syntax

sqry uses a structured boolean query language. Queries are composed of field predicates combined with logical operators. This page covers the full syntax and when to use each of the two query commands.

Basic Structure

A query is one or more predicates of the form field:value, combined with boolean operators:

field:value OPERATOR field:value

Examples:

sqry query "kind:function"
sqry query "kind:function AND async:true"
sqry query "lang:rust AND (kind:function OR kind:method)"

sqry provides two commands for running queries:

• sqry query — searches the pre-built index. Fast (4ms with a warm cache), supports all relation fields (callers:, callees:, imports:, exports:). Requires running sqry index . first.
• sqry search — parses files on demand, no index required. Slower, does not support relation queries. Useful for exploring unfamiliar codebases without setup.

Operators

Regex patterns use PCRE syntax and are wrapped in / delimiters: name~=/pattern/. Common patterns:

• name~=/^test_/ — starts with test_
• name~=/Handler$/ — ends with Handler
• name~=/auth/ — contains auth

Field Overview

Fields are organized into three categories:

See Field Reference for the complete list with all accepted values.

Worked Examples

All functions:

sqry query "kind:function"
# Returns every function symbol in the indexed codebase.

All async functions:

sqry query "kind:function AND async:true"
# Returns only functions marked async — no false positives from comments or strings.

Functions whose name starts with test_:

sqry query "name~=/^test_/"
# Regex match anchored to the start of the symbol name.

Everything that calls authenticate:

sqry query "callers:authenticate"
# Cross-file call graph traversal — returns the exact list of callers.

All Serialize implementations:

sqry query "impl:Serialize"
# Finds every struct/enum that implements the Serialize trait.

Public Rust symbols:

sqry query "lang:rust AND visibility:public"
# Filters by both language and visibility simultaneously.

Classes in the models directory:

sqry query "kind:class AND path:src/models/**"
# Glob pattern on the file path.

Non-test functions and methods:

sqry query "(kind:function OR kind:method) AND NOT name~=/test/"
# Grouping with OR, combined with a negated regex filter.

Structural Query Planner (sqry plan-query)

In addition to the boolean sqry query syntax above, sqry ships a structural query planner exposed as sqry plan-query (CLI) and sqry_query (MCP tool). The planner uses a flat, whitespace-separated chain of predicate steps, with subqueries nested in parentheses. Each step is compiled into a logical plan, fused across batches for shared scans, and executed against the derived analysis cache — so repeated queries are sub-millisecond.

sqry plan-query "kind:function has:caller"
sqry plan-query "kind:function callers:main"
sqry plan-query "kind:function traverse:reverse(calls,3)"
sqry plan-query "kind:function in:src/api/**"
sqry plan-query "kind:function references ~= /handle_.*/i"
sqry plan-query "kind:struct implements:Visitor"
sqry plan-query "kind:function callees:(kind:method name:visit_*)"

Predicate steps

Subqueries

Wrap a nested query in parentheses to use it as the right-hand value of any relation predicate:

sqry plan-query "kind:function callees:(kind:method name:visit_*)"
sqry plan-query "kind:struct implements:(kind:trait name:Display)"

When to use the planner

• Use sqry plan-query when you need composable structural predicates (especially traversal at fixed depth, or set membership like has:caller / unused), and when you want the planner’s cross-batch fusion and derived-cache acceleration.
• Use sqry query for boolean expressions over flat field predicates (AND, OR, NOT, parenthesised grouping). sqry query is the right tool for ad-hoc symbol search.
• The MCP tool sqry_query exposes the planner over JSON-RPC, so AI assistants can run structural queries directly.

sqry query vs sqry search

Use sqry query when you are working in a project regularly and need instant, precise results — especially for any query involving callers, callees, imports, or exports. The one-time indexing cost is recovered within the first few queries.

Use sqry search when you are exploring a codebase for the first time and do not want to build an index, or when you need results that reflect the very latest unsaved file state.

Query Variables

Use --var to inject values into queries at runtime. Reference variables with $name:

sqry query "callers:$fn AND lang:$lang" --var fn=authenticate --var lang=rust

Multiple variables can be passed. This is useful for scripting and batch workflows where the same query template runs against different targets:

for fn in authenticate authorize logout; do
  sqry query "callers:$fn" --var fn=$fn --json
done

Fuzzy Search

Fuzzy matching finds symbols even when the query contains typos or partial names. It requires an index.

# Enable fuzzy matching
sqry query "authentcate" --fuzzy

# Control similarity threshold (0.0–1.0, default 0.6)
sqry query "authentcate" --fuzzy --fuzzy-threshold 0.8

# Choose algorithm
sqry query "authentcate" --fuzzy --fuzzy-algorithm levenshtein

Algorithms

Additional options

Output Formats

By default, sqry prints human-readable tabular output. Use flags to switch formats:

# JSON (full symbol details)
sqry query "kind:function" --json

# CSV with headers
sqry query "kind:function" --csv --headers

# TSV for Unix pipelines
sqry query "kind:function" --tsv

# Select specific columns
sqry query "kind:function" --csv --columns name,file,line,kind

# Count only (no results)
sqry query "kind:function" --count

Available columns

name, qualified_name, kind, file, line, column, end_line, end_column, language, preview

CSV safety

CSV output has formula injection protection enabled by default — cell values starting with =, +, -, or @ are prefixed with a single quote. Use --raw-csv to disable this if you’re processing output programmatically and don’t need the protection.

Code preview

Add --preview to include source code context with each result:

# Show 3 lines of context (default)
sqry query "kind:function AND name:main" --preview

# Show 5 lines of context
sqry query "kind:function AND name:main" --preview 5

# Show match line only (no surrounding context)
sqry query "kind:function AND name:main" --preview 0