Tool

query

Ask questions about the repository as data: count files, join symbols to their callers, or compare results across projects.

query runs DuckDB SQL against RepoQL’s index and its registered functions. Files, declarations, relationships, and annotations are available as tables or views. SQL lets you specify the exact grouping, filter, or comparison you want.

Use SQL when the shape of the answer is clear

Search is useful for finding likely locations. SQL is useful for questions such as “which files have the most functions?” or “how many warnings come from each rule?”. The database computes the result before it is returned, so a large input can produce a small answer.

Start with readable views such as Files, Functions, and Types. The underlying graph is available when you need to traverse relationships. A relationship is evidence recorded by a parser or resolver; its absence is only meaningful if the relevant format and analysis settings support it.

Combine sources through tables

Registered functions expose operations such as git history, text search, and structured-data parsing. Their rows can be joined with indexed files. Approved external MCP tools can also be called through SQL functions.

Most graph queries run locally. A query can still access the network when it invokes cloud inference, cloud search services, or an external tool. The fact that an operation is written in SQL does not change its data or permission requirements.

Example: count source files by extension

Terminal

rql query "SELECT extension, count(*) AS files, sum(token_count) AS tokens
FROM Files
WHERE matches_glob(uri, 'file:///src/**') AND extension <> ''
GROUP BY extension ORDER BY files DESC LIMIT 6"

matches_glob understands RepoQL addresses. SQL LIKE uses a different pattern language, with % and _; do not use a URI glob as a LIKE pattern.

Keep the result explicit

Select the columns you need, aggregate when the question is about totals, and use ORDER BY whenever order matters. Without it, row order is unspecified. A token budget limits the rendered response; it does not make an oversized result complete.

If a result exceeds the budget, the response reports truncation. A SQL comment can supply intent for an attempted summary, but that summary is not a substitute for complete rows when correctness depends on them.

Reference

Terminal

rql query "DESCRIBE Files"

Surface	Use
Files · Functions · Types	Files and parsed declarations.
node · edge	Graph structure and reference relationships.
Annotations	Diagnostics and other annotations.
git_status · git_diff · git_blame	Information read from git.
glob_files · matches_glob	Select indexed files with URI patterns.
grep_matches · regex_matches	Search indexed text.
parse · xlsx	Read structured data as rows.
ask	Generate a language-model answer from supplied data.
mcp_tools	Discover the configured MCP bridge tools.

MCP parameter	Use
sql	Required. DuckDB SQL statement.
tokenBudget	Optional. Maximum rendered response size.
timeoutMs	Optional. Time limit for the query.

Further reference

In the installed manual: help:///tools/query.md, help:///schema/core.md, help:///schema/functions/**.