sql-tap过滤语法完整教程：6种过滤表达式，快速定位慢查询与错误SQL

sql-tap 是一款实时 SQL 流量嗅探工具，以透明代理方式捕获 PostgreSQL、MySQL、TiDB 的每一条查询，并在 TUI 终端界面中实时展示。它的过滤语法支持 6 种结构化表达式，可以按耗时、错误、N+1、操作类型等维度筛选查询，帮助你在海量 SQL 流量中快速定位慢查询与错误 SQL，无需改动一行应用代码。

sql-tap 过滤模式：按一个 f 键进入

在 sql-tap 的列表视图中：

• 按f键进入过滤模式（底部提示filter:），输入结构化过滤条件
• 按/键进入增量文本搜索（仅子串匹配）
• 按Esc随时清空当前过滤条件
• 两种模式可同时生效：先应用过滤条件，再用文本搜索进一步缩小结果

过滤的解析逻辑在 tui/filter.go 中实现，Web UI 也使用完全相同的语法（见 web/static/app.js 中parseFilterTokens函数），所以在终端和浏览器里输入的条件通用。

6种过滤表达式语法一览

1️⃣ 耗时过滤：d>与d<

最常用的就是按执行耗时筛选，例如：

d>100ms 找出所有耗时超过 100ms 的查询 d<50ms 找出所有耗时低于 50ms 的查询

支持的时间单位：us（微秒，µs也可）、ms（毫秒）、s（秒）、m（分钟），数字支持小数，如d>0.5s。这是排查慢查询的第一步：先d>1s揪出耗时最长的语句。

2️⃣ 错误过滤：error

输入error后，列表只显示带错误的执行事件，适合快速复盘线上报错：

error 只看执行失败的 SQL op:update error 只看 UPDATE 语句中的报错

大小写不敏感，Error与error等价。

3️⃣ N+1 过滤：n+1

sql-tap 内置 N+1 查询检测（同一 SELECT 模板在短时间内被高频重复执行，默认阈值 5 次 / 1 秒窗口，由--nplus1-threshold、--nplus1-window配置）。命中后对应查询会带上N+1标记，此时只需：

n+1 直接列出所有被标记的 N+1 查询

别名nplus1效果相同，不用敲加号也能用。

4️⃣ 慢查询过滤：slow

慢查询由代理侧的--slow-threshold参数判定（默认 100ms，设为 0 可关闭）。slow关键字只显示被代理标记为慢的查询，与d>100ms的区别在于它读取的是服务端标记位，筛选更可靠：

slow 只看慢查询 op:select slow 只看 SELECT 类型的慢查询

5️⃣ 操作类型过滤：op:

op:前缀支持两类匹配：

• SQL 关键字前缀：op:select、op:insert、op:update、op:delete，按语句开头的关键字匹配；
• 协议操作：op:begin、op:commit、op:rollback，此外还支持op:query、op:exec、op:prepare、op:bind、op:execute等底层操作名。

排查事务问题时特别有用：

op:commit 只看提交操作 op:rollback 只看回滚操作，配合 error 一起分析异常事务

6️⃣ 文本子串：直接输入任意内容

不匹配上述任何模式的词会被当作文本子串，对查询内容做不区分大小写的包含匹配：

users 查询里包含 users 的语句 WHERE id 包含 WHERE id 的语句（按空格拆成两个条件）

⚠️ 注意：WHERE id会被拆分为where和id两个 AND 条件，而op:、error、slow、n+1是保留关键字，不能当作普通文本搜索。

组合使用：空格分隔，AND 逻辑

多个过滤词之间用空格分隔，所有条件按AND（与）逻辑叠加，可以任意组合出精准的查询场景：

op:select d>100ms 只看耗时超过 100ms 的 SELECT —— 定位慢查询 op:update error 只看 UPDATE 报错 —— 定位错误 SQL slow n+1 既是慢查询又被标记 N+1 的问题语句 d>1s users 耗时超过 1 秒且涉及 users 表的语句

Web UI 的过滤输入框（占位符Filter (d>100ms op:select error ...)）与 TUI 完全一致，语法同样生效：

实战：3步定位慢查询与错误SQL

1. 先缩小范围：op:select d>500ms，找出最慢的读查询；
2. 确认是否 N+1：加上n+1，若同一模板反复出现，优先优化索引或改为批量查询；
3. 复盘报错：error+ 文本关键字（如error orders），定位具体失败语句，再按Enter查看详情、按x执行 EXPLAIN 分析执行计划。

过滤 vs 文本搜索：选哪个？

相关资源

• 过滤解析与匹配实现：tui/filter.go
• Web 端过滤语法实现：web/static/app.js
• 过滤行为测试用例：tui/filter_test.go
• 代理事件协议定义：proto/tap/v1/tap.proto
• 示例工程（PostgreSQL / MySQL / TiDB）：example/

掌握这套 6 种过滤表达式，sql-tap 就从"SQL 流量监控器"升级为你的慢查询定位器和错误 SQL 排查工具——输入越精准，定位越快。