SQL 查询块
在文档（docs / Wiki 等 Markdown）里可以用 sqlite-query、duckdb-query 或 mdb-query 围栏代码块嵌入一条只读查询；Web 界面的阅读视图会把块渲染成实时查询结果，而不是死代码。编辑模式下仍显示原始块文本。mdb-query 以 Access 库为数据源，写法与字段同本页，详见 MDB 查询块。
块语法
```sqlite-query
source: backlog/databases/shop.sqlite
view: table
sql: |
SELECT product, price, stock
FROM inventory
ORDER BY price DESC
```
| 字段 | 必填 | 默认 | 说明 | |
|---|---|---|---|---|
source |
是 | — | 数据源路径，项目相对路径（见下） | |
sql |
是 | — | 查询语句，支持 `sql: | ` 多行写法 |
view |
否 | table |
table（表格）/ list（逐行字段列表）/ value（单值）/ echarts（直接出图，见 图表块） |
|
refresh |
否 | manual |
仅支持手动刷新；自动/定时刷新不支持 |
安全约束与只读保证
source一律按项目相对路径解析：绝对路径（含以/开头）、..逃逸、指向项目外的符号链接、隐藏/排除目录都会被拒绝；扩展名必须在白名单内，SQLite 源还会校验确实是 SQLite 文件。- SQL 必须只读：只能以
SELECT或WITH … SELECT开头，不允许内部分号（容忍一个结尾;），写关键字黑名单对注释也生效（注释掉的DROP同样被拒绝）。 - 真正的兜底在引擎层：SQLite 用只读句柄加
PRAGMA query_only打开，DuckDB 用READ_ONLY模式打开——即使绕过了文本校验，写操作也会被引擎拒绝。
数据源
sqlite-query：source指向项目内的.sqlite/.sqlite3/.db文件。duckdb-query：除.duckdb数据库外，source还可以直接指向 CSV / Excel（.csv / .xlsx）文件——此时 DuckDB 以内存实例打开并直接FROM 'file.csv'查询；xlsx 依赖官方 excel 扩展的自动加载，首次使用需要联网下载（离线时会显示可读的块错误）。DuckDB 块还支持可选的copy_to字段把结果另存为项目内的 csv/xlsx 文件。
行数上限与分页
- 预览模式默认最多显示 500 行，超出时提示「已截断至 N 行（共 M 行）」，会如实报告总行数。
- 上限可配置：
backlog/config.yml的query_max_rows（默认 500，预览模式硬性封顶 5000），Web 设置页的「Query / Data preview」分区同样可以修改。 - 块头部有「分页浏览」开关：开启后结果按页浏览（
← 第 X / Y 页 →），每页行数由pagination_page_size（默认 50）控制，default_pagination: true可让块默认进入分页模式。分页是真正的引擎侧分页（LIMIT/OFFSET下推 + 单独COUNT(*)），因此不受 5000 行上限约束，适合浏览大结果集。 - 表格视图与列表视图都带行号（
#/ 序号）列，分页模式下显示全局行号。
块上的四个动作
| 动作 | 说明 |
|---|---|
| Refresh | 重新执行查询，刷新结果 |
| Show/Hide Query | 展开/收起只读的 source 与 SQL 面板（默认收起；不发出请求） |
| Copy Markdown | 把当前结果以 GitHub 风格 Markdown 表格复制到剪贴板（value 视图复制标量；NULL 为空单元格） |
| Export CSV | 把结果导出为 CSV 文件（UTF-8 BOM + CRLF，Excel 可直接打开中文）；SQLite 块写入数据库旁的 <库名>-<时间戳>.csv（绝不覆盖），DuckDB 块由浏览器保存文件；导出沿用预览行数上限 |
四个动作对四种引擎的块完全一致。设置页的修改会通过广播即时生效，无需刷新页面。
在阅读视图内编辑
展开查询面板后，其首行右端会出现编辑入口：进入编辑态后，SQL/Cypher 语句变为语法高亮编辑器，可点 Save 把新语句写回源 Markdown 并立即重跑，点 Test 先空跑验证而不写盘，点 Discard 恢复原语句。SQL 引擎另有一个 Format 按钮可原地重排缩进（不写文件）。本功能对 sqlite-query / duckdb-query / mdb-query / cypher-query 四种块通用；没有已知来源路径的块（如里程碑描述）保持只读。