Query Syntax
A Source Graph search is not a query language with filters. It is a small set of structured fields that mean what the matching rg options mean: a pattern matched line by line against file contents, plus switches for literal matching, case folding, globs and directories. The service compiles them into its own engine query; callers never write engine syntax, and text such as file: or lang: inside a pattern is matched literally.
| Meaning | rg | HTTP body | MCP search | CLI | Website |
|---|---|---|---|---|---|
| Pattern | PATTERN, -e | Pattern | pattern | PATTERN or -e | Search box |
| Literal text | -F | FixedStrings: true | fixed_strings | -F | Regular expression toggle off |
| Ignore case | -i | IgnoreCase: true | ignore_case | -i | Match case toggle off |
| Globs | -g | Glob: [...] | glob | -g, repeatable | Include and exclude fields |
| Directories | PATH... | Paths: [...] | paths | Arguments after the pattern | — |
| Paths only | -l | Output: "files" | output: "files" | -l | — |
| Revision | — | Revision | revision | -revision | Branch or commit selector |
Patterns
- A pattern is an RE2 regular expression, close to
rg's default syntax, matched against file contents, never against paths. - Matching is line-oriented, like
rgwithout-U: a pattern that could match a newline is rejected. Search for each line separately. - A pattern must consume at least one character. Patterns that match the empty string, or only zero-width assertions, are rejected.
- Lookaround and backreferences are not supported; use
FixedStringsto match such text literally. - The pattern must be non-empty valid UTF-8 of at most 8,192 bytes.
- Searches are case-sensitive by default.
IgnoreCasefolds case for the whole pattern.
Invalid patterns return 400 INVALID_PATTERN with the reason.
Globs
Globs follow rg -g and gitignore conventions:
| Glob | Matches |
|---|---|
*.go | Files named *.go at any depth — a glob without / matches names anywhere |
src/**/*.ts | TypeScript files under src/, anchored at the repository root because it contains / |
!**/*_test.go | Excludes test files |
!vendor/ | Excludes everything under any vendor directory |
*.{ts,tsx} | Either extension |
* and ? never cross /, ** spans directories, and [...] character classes are supported. When includes are given, a file must match at least one of them; when includes and excludes overlap, the later glob wins, as in rg. An include glob ending in / is rejected — use Paths, or append /**. Up to 64 globs of at most 1,024 bytes each are allowed; bad ones return 400 INVALID_GLOB. On the website, the include and exclude fields take comma-separated globs; commas inside {a,b} belong to the glob.
Paths and output
Paths lists repository-relative directories to search, like rg's trailing PATH arguments, up to 64. In a monorepo registration they must lie inside the registered path groups (PATH_NOT_REGISTERED otherwise); omitting them searches every registered group at the same commit, never mixing versions.
Output is content (the default), returning matching lines, or files, returning only paths, like rg -l. Over MCP, max_lines_per_file (1–1000, default 10) bounds how many matching lines are shown per file in content mode.
Reading the results
Each result names its Repository and Commit; read surrounding code at that same commit. Results are a bounded first page — up to 100 files and 1,000 matches with two context lines, reduced automatically if the response would exceed 2 MiB — so check the metadata before drawing conclusions:
| Field | Meaning |
|---|---|
Partial | The engine stopped early, for example at its 10,000-match cap or because shards were skipped |
Truncated | More files or matches existed than were returned |
Coverage | What the index covers: index mode, registered paths and groups, text-only profile without symbols, and skipped unsupported paths |
A search with no hits is not proof of absence outside that coverage or beyond the limits. Text files the index skipped, such as generated or very large files, can still be read directly at that commit within the read limits.
Website search links
The website's search page encodes the same request in its address, using the API field names: repo, pattern, fixed_strings=1, ignore_case=1, repeated glob, and either commit (a full SHA) or revision (a branch). Code pages accept repo, path and commit or revision, with a line range in the fragment such as #L20-L40. Links copied from the website therefore reproduce the exact search or read at the same commit.
Examples
| Goal | HTTP body | CLI |
|---|---|---|
| Find a function call | {"Pattern":"WithTimeout\\("} | sourcegraph-cli search -repo R 'WithTimeout\(' |
| Literal text, any case | {"Pattern":"todo:","FixedStrings":true,"IgnoreCase":true} | sourcegraph-cli search -repo R -F -i 'todo:' |
| Only Go files, no tests | {"Pattern":"func New","Glob":["*.go","!*_test.go"]} | sourcegraph-cli search -repo R -g '*.go' -g '!*_test.go' 'func New' |
| Within two directories | {"Pattern":"retry","Paths":["internal/service","cmd"]} | sourcegraph-cli search -repo R retry internal/service cmd |
| List matching files | {"Pattern":"deprecated","Output":"files"} | sourcegraph-cli search -repo R -l deprecated |
搜索语法
Source Graph 搜索不是带过滤器的查询语言，而是一小组结构化字段，含义与对应的 rg 选项一致：一个逐行匹配文件内容的模式，加上字面量匹配、大小写折叠、glob 和目录等开关。服务会把它们编译成自己的引擎查询；调用方从不编写引擎语法，模式中出现的 file: 或 lang: 等文本会按字面匹配。
| 含义 | rg | HTTP 请求体 | MCP search | CLI | 网站 |
|---|---|---|---|---|---|
| 模式 | PATTERN、-e | Pattern | pattern | PATTERN 或 -e | 搜索框 |
| 字面量匹配 | -F | FixedStrings: true | fixed_strings | -F | 关闭 Regular expression 开关 |
| 忽略大小写 | -i | IgnoreCase: true | ignore_case | -i | 关闭 Match case 开关 |
| glob | -g | Glob: [...] | glob | -g，可重复 | 包含与排除字段 |
| 目录 | PATH... | Paths: [...] | paths | 模式之后的参数 | — |
| 仅输出路径 | -l | Output: "files" | output: "files" | -l | — |
| 版本 | — | Revision | revision | -revision | 分支或提交选择器 |
模式
- 模式是 RE2 正则表达式，与
rg的默认语法接近，匹配的是文件内容，从不匹配路径。 - 匹配是按行进行的，与不带
-U的rg相同：可能匹配换行符的模式会被拒绝。请对每一行分别搜索。 - 模式必须至少消耗一个字符。匹配空字符串或只包含零宽断言的模式会被拒绝。
- 不支持环视和反向引用；如需匹配此类文本，请用
FixedStrings按字面匹配。 - 模式必须是非空、合法的 UTF-8，且不超过 8,192 字节。
- 搜索默认区分大小写。
IgnoreCase会对整个模式忽略大小写。
无效的模式返回 400 INVALID_PATTERN，并附带原因。
glob
glob 遵循 rg -g 和 gitignore 的约定：
| glob | 匹配 |
|---|---|
*.go | 任意深度下名为 *.go 的文件；不含 / 的 glob 会匹配任何位置的文件名 |
src/**/*.ts | src/ 下的 TypeScript 文件；因为包含 /，所以锚定在仓库根目录 |
!**/*_test.go | 排除测试文件 |
!vendor/ | 排除任意 vendor 目录下的所有内容 |
*.{ts,tsx} | 两种扩展名任选其一 |
* 和 ? 从不跨越 /，** 可跨越多级目录，并支持 [...] 字符类。给出包含规则时，文件必须至少匹配其中一条；包含与排除规则重叠时，与 rg 一样以后出现的 glob 为准。以 / 结尾的包含 glob 会被拒绝，请改用 Paths，或在末尾追加 /**。最多允许 64 个 glob，每个不超过 1,024 字节；不合法的 glob 返回 400 INVALID_GLOB。在网站上，包含与排除字段接受以逗号分隔的 glob；{a,b} 中的逗号属于 glob 本身。
路径与输出
Paths 列出要搜索的仓库相对目录，类似 rg 末尾的 PATH 参数，最多 64 个。在 Monorepo 登记中，这些目录必须位于已登记的路径组内（否则返回 PATH_NOT_REGISTERED）；省略时会在同一提交上搜索所有已登记的路径组，从不混用版本。
Output 可取 content（默认），返回匹配行；或取 files，像 rg -l 一样只返回路径。通过 MCP 调用时，max_lines_per_file（1–1000，默认 10）限制内容模式下每个文件显示的匹配行数。
解读结果
每条结果都会注明其 Repository 和 Commit；请在同一提交上阅读周边代码。结果是有上限的第一页：最多 100 个文件、1,000 条匹配，带两行上下文；若响应会超过 2 MiB 则自动缩减。因此在下结论前请先检查元数据：
| 字段 | 含义 |
|---|---|
Partial | 引擎提前停止，例如达到 10,000 条匹配上限，或跳过了部分分片 |
Truncated | 实际存在的文件或匹配多于返回的数量 |
Coverage | 索引的覆盖范围：索引模式、已登记的路径和路径组、不含符号的纯文本配置，以及被跳过的不支持路径 |
搜索没有命中，并不能证明在该覆盖范围之外或超出限制的部分不存在相关内容。被索引跳过的文本文件（例如生成文件或超大文件），仍可在读取限制内直接按该提交读取。
网站搜索链接
网站的搜索页会把同一个请求编码到地址中，使用 API 字段名：repo、pattern、fixed_strings=1、ignore_case=1、可重复的 glob，以及 commit（完整 SHA）或 revision（分支）二者之一。代码页接受 repo、path 以及 commit 或 revision，行范围写在片段中，例如 #L20-L40。因此从网站复制的链接能在同一提交上精确复现当时的搜索或阅读。
示例
| 目标 | HTTP 请求体 | CLI |
|---|---|---|
| 查找函数调用 | {"Pattern":"WithTimeout\\("} | sourcegraph-cli search -repo R 'WithTimeout\(' |
| 字面量文本，忽略大小写 | {"Pattern":"todo:","FixedStrings":true,"IgnoreCase":true} | sourcegraph-cli search -repo R -F -i 'todo:' |
| 只搜 Go 文件，排除测试 | {"Pattern":"func New","Glob":["*.go","!*_test.go"]} | sourcegraph-cli search -repo R -g '*.go' -g '!*_test.go' 'func New' |
| 限定在两个目录内 | {"Pattern":"retry","Paths":["internal/service","cmd"]} | sourcegraph-cli search -repo R retry internal/service cmd |
| 列出匹配的文件 | {"Pattern":"deprecated","Output":"files"} | sourcegraph-cli search -repo R -l deprecated |