Cypher 查询块
在文档（任务 / 文档 / 决策 / Wiki 等 Markdown）里可以用 cypher-query 围栏代码块嵌入一条只读 Cypher 查询；Web 界面的阅读视图会把块渲染成实时查询结果，编辑模式下仍显示原始块文本。它是 SQL 查询块在图数据库上的对应物：交互语义与安全模型一致，执行栈换成图引擎。
```cypher-query
source: demo
view: graph
refresh: auto
query: |
MATCH (p:Person)-[r:WORKS_AT]->(c:Company)
RETURN p, r, c
```
| 字段 | 必填 | 默认 | 说明 | |
|---|---|---|---|---|
source |
是 | — | 数据库注册名（backlog graph list 列出的名称），不是文件路径 |
|
query |
是 | — | 查询语句，支持 `query: \ | ` 多行写法；必须只读 |
view |
否 | table |
table（表格）/ list（逐行字段列表）/ value（单值）/ graph（力导向图）/ echarts（直接出图，见 图表块） |
|
refresh |
否 | manual |
manual（手动）/ auto（图数据变化时自动重跑） |
未知字段一律报错并列出可用字段，不会静默忽略。
source 是注册名，不是路径
SQL 块的 source 是项目相对文件路径，而 Cypher 块一律是注册名——图数据库是目录下的存储格式，没有单文件语义。未注册的名称、以及任何路径形态的写法（相对路径、绝对路径、..）都会被拒绝，块内给出可读错误并列出可用数据库名。
四种视图
| 视图 | 渲染 |
|---|---|
table |
标准网格，一行一条记录 |
list |
每条记录竖向 key–value 列表 |
value |
只取首行首单元格，纯文本内联（适合嵌一个聚合值） |
graph |
力导向图渲染节点与关系，图例与 Databases 页共用同一份配置 |
graph 视图结果超过约 3000 个节点时会自动降级为表格并给出说明。Cypher 的返回值除标量外还有节点、关系与路径：节点会剥掉内部句柄后序列化为 JSON，关系渲染为 (起点)-[类型]->(终点)，路径为节点与关系交替的紧凑串——graph 视图直接使用原始结构。
实时刷新
refresh: auto 订阅图数据的变更广播：图内容变化后块会在短暂静默期（500 毫秒）后自动重跑，批量导入期间的连续变化只触发一次重跑；结果与当前值相同时不重新渲染，避免闪烁。块头会显示 Live 徽标与暂停/恢复开关，暂停只停止重跑。该能力依赖图数据库有变更广播——目前只有派生的语料图具备，用户数据库写 refresh: auto 时行为等同手动刷新。
只读保证
写类 Cypher（CREATE / MERGE / DELETE / SET / DROP / UPDATE）会被拒绝并在块内显示错误；查询块结构上接触不到写入通道。
行数上限与块动作
- 行数上限与 SQL 块同源，取配置里的查询行数上限（默认 500，硬顶 5000），超出即截断并在块内提示；Cypher 不提供分页——超限应当改查询而不是翻页。
- 块头四个动作与 SQL 块一致：Refresh（重新执行）、Show/Hide Query（展开/收起只读的
source与语句，默认收起、展开不触发查询；语句带与代码块一致的语法着色）、Copy Markdown（复制为 GitHub 风格表格）、Export CSV（导出为 CSV 文件）。 - 空结果与错误都有明确文案，不会出现静默的空白块。
查询写法注意事项
图引擎目前不支持无类型关系模式（-[r]-> 匹配不到任何行）与多类型并集（-[r:A|B]-> 会报错），查询必须写具体的关系类型。