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 the common search surfaces:

• sqry query — runs the structured boolean query grammar. It supports relation fields (callers:, callees:, imports:, exports:) when the workspace has been indexed.
• sqry search — runs regex or literal pattern matching over symbol names. It accepts filters such as --kind and --lang, but it does not accept boolean predicates like kind:function AND lang:rust.

Operators

Regex patterns use Rust regex 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.

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.

Call-resolution and framework predicates

# C indirect calls into my_read recovered via the binding plane
sqry plan-query "callers:my_read resolved_via:binding_plane lang:c"

# Functions detected as belonging to a web framework (route coverage expanding)
sqry plan-query "kind:function framework:axum"

resolved_via:<kind> and framework:<name> are also accepted by the sqry_query MCP tool and are available as resolved_via / framework filter parameters on the relation_query, direct_callers, direct_callees, and semantic_search MCP tools.

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 need regex, literal, or fuzzy symbol-name matching without writing a boolean predicate.

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 is part of the pattern-search surface, not the boolean sqry query grammar. Use the top-level shorthand or sqry search; it requires an index.

# Enable fuzzy matching
sqry --fuzzy "authentcate"

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

# Choose algorithm
sqry --fuzzy "authentcate" --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

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