cflow 数据库
cflow 数据库是一类特殊附件:以结构化 JSON 形式保存数据,用 SQL 直接操作。允许用户通过AI或者API执行SQL来查询,变更里面的内容。
适合记账、清单、库存、统计等需要「表 + 行」结构的数据场景。
创建
- 入口:笔记编辑器 → 附件菜单(回形针)→ cflow 数据库;
- 在 设置 → 偏好设置 → 需要启用的附件类型 中开启对应开关(默认关闭);
- 创建时输入名称(支持中文表名),创建成功后自动挂进当前笔记的附件列表,点击附件图标即可打开 SQL 面板;
- 每个数据库的体积上限与你的单文件上传上限一致,占用计入个人存储空间(含历史版本)。
SQL 面板

点击附件图标即可打开近全屏面板:左侧是表结构(表名、行数、字段),上半是 SQL 编辑器(Ctrl/⌘ + Enter 运行),下半是结果区。
编辑器内容自动本地缓存(按附件区分):写了没执行的语句,下次打开该附件时自动恢复。
执行规则
- 多条语句用
;分隔,一次运行在同一事务中执行:任何一条失败,整批回滚,并提示第几条失败与原因; - 成功批次只返回最后一条语句的结果;
- 编辑器里框选部分文本后运行(按钮变为「运行部分语句」),只执行选中部分;
- 查询语句显示结果表格(最多 1000 行,超出提示截断);增删改语句显示影响行数与耗时;
- 只有真正改动了数据的批次才会推进版本号;纯查询不产生版本。
约束
| 项目 | 限制 |
|---|---|
| 单库体积 | 与个人单文件上传上限一致,超出则整批拒绝并回滚 |
| SQL 文本 / 语句数 / 执行时长 | 1 MB / 500 条 / 5 秒 |
| 禁用语句 | PRAGMA、ATTACH/DETACH、BEGIN/COMMIT/ROLLBACK、VACUUM、REINDEX、CREATE VIRTUAL TABLE、CREATE TEMP |
方言:SQLite 方言(特殊支持 DESC 表名 简写查看表结构);日期函数为 strftime / date 族;默认弱类型,建议建表时勾选 STRICT 强类型(STRICT 下类型选择器只提供 TEXT/INTEGER/REAL/BLOB/ANY,日期时间等场景用 TEXT 存储)。
可视化操作(不写 SQL 也能用)
- 左栏顶部 建表 按钮:表名、列名、类型(带通俗说明)、主键/自增/必填/唯一/默认值、STRICT——底部实时预览生成的语句,确认后执行;
- 表上 右键:查看数据(插入
SELECT语句查看前 20 行)、查看表结构、插入一条数据(值按类型留好占位)、增加列(已有列锁定,只能追加)、删除列(插入带注释的模板语句)、删除表(确认后直接执行)。
AI 生成 SQL AI
对于不会写SQL的用户,可以直接使用AI来生成。
编辑器下方工具栏左侧的 ✨ 按钮打开 AI 面板:用一句话描述需求(如「统计每张表的行数」「建一张标签表并插入几条示例数据」),AI 会结合当前库的表结构生成 SQL,自动插入到编辑器末尾——只插入、不执行,确认后再运行。
- 需求可以是查询、增删改,也可以是建表、加列等;
- AI 判断需求无法用 SQL 实现(如与数据库无关、超出 SQLite 能力)时,会直接说明原因并建议换一种提法;
图卡

图卡(Chart Card)是挂在某个 cflow 数据库附件上的可视化图表:一条查询 SQL + 一段 ECharts 代码,适合对数据库里面的表需要可视化的时候配置。
入口
- 资源管理页:鼠标悬浮数据库附件缩略图,点击右下角的 图卡 按钮;
- 笔记内附件条:附件名旁的 📊 图标。
面板结构:左侧是图卡列表,右侧是当前图卡的渲染结果;点 新建图卡 时可选择新建空白图卡,或从模板新建——从自己已保存的图卡(可跨数据库)中挑一张,复制它的 SQL 和画图代码作为新图卡的起点。
图卡编辑

编辑页为 2×2 分步布局(移动端按使用顺序纵向排列):
- 左上 SQL:点「运行」单独执行查询;
- 左下 查询结果:字段名与数据都在这里,SQL 报错也显示在此;
- 右上 画图代码:SQL 跑出正常结果前不可编辑;
- 右下 绘制预览:点「绘制」出图;
编辑图卡时,左侧表结构的每个表名旁有 + 按钮,点击直接在 SQL 编辑器光标处插入 SELECT 字段1, 字段2, ... FROM 表名;。
制作一张图卡
- 写 SQL:只能是一条
SELECT查询(允许WITH ... SELECT),查询结果的每个字段就是一个可引用的数据列; - 运行 SQL 看到结果后,编辑器下方会出现全部字段 chip,点击即在光标处插入
$列名$。另外有两个快捷插入:- 插入名称-数值对:插入
$name:点击更换字段|value:点击更换字段$,胶囊按键名拆开,点某一段只换这一段的列; - 插入数组:先选需要几个值,再插入
$flat:点击更换字段,点击更换字段,...$;
- 插入名称-数值对:插入
- 写图表配置(option):与 DSL 图表 同语法,直接写 ECharts 的 option 内容(JSON5 格式)。数据不要手写数组,用下面三种占位符,绘制时再换成查询结果;
- 点击代码里已有的字段胶囊会弹出字段列表,选择后只替换被点的那一段。chip 行最右侧的 格式化 按钮可把当前代码一键排版对齐;
- 点击 绘制:在右下看到图后即可保存——绘制成功前保存按钮不可用(新建与编辑同理)。配置代码区顶部提供常用模板(柱状图、堆叠柱状图、折线图、面积图、饼图、环形图、散点图、K 线图),点击即插入。
占位符
占位符写在一对 $ 中间,不要自己再加中括号。列名必须是这条 SQL 结果里真实存在的字段。
1. 单列数组 $列名$
换成这一列的全部取值,数字和字符串会按原类型保留。
SQL 返回 month、total 时:
{
xAxis: { type: 'category', data: $month$ },
yAxis: { type: 'value' },
series: [{ type: 'bar', data: $total$ }],
}
绘制后相当于 data: ['2024-01', '2024-02'] 和 data: [120, 80]。
2. 字典数组 $键:列名|键:列名|...$
每一行收成一个对象。冒号左边是对象的键(ECharts 要的属性名),右边是 SQL 列名。至少两个键,三个、四个或更多也可以,用 | 继续接。
饼图、环形图、玫瑰图、漏斗图的 data 用 name 和 value:
series: [{
type: 'pie',
data: $name:category|value:amount$,
}]
若查询结果是:
| category | amount |
|---|---|
| 食品 | 120 |
| 交通 | 80 |
绘制后变成:
data: [
{ name: '食品', value: 120 },
{ name: '交通', value: 80 },
]
需要更多属性时按同样格式加键,例如 $name:category|value:amount|extra:note$,每个元素就是 { name, value, extra }。编辑器里这颗胶囊会按键切开,每一段显示键名(name、value、extra),点某一段只更换对应的列。
3. 扁数组 $flat:列1,列2,列3,...$
每一行收成一个数组,适合一个点要带多个数的图。列名之间用英文逗号分隔。编辑器底部的 插入数组 会先让你选择需要几个值,再插入对应数量的胶囊;每一段可以单独点选字段。
K 线的每个点必须是四个数,顺序固定为 开盘、收盘、最低、最高:
{
xAxis: { type: 'category', data: $trade_date$ },
yAxis: { type: 'value', scale: true },
series: [{
type: 'candlestick',
data: $flat:open_px,close_px,low_px,high_px$,
}],
}
某一行 20, 34, 10, 38 会变成 [20, 34, 10, 38](开盘 20、收盘 34、最低 10、最高 38)。scale: true 让纵轴不要从 0 起画。散点图同样用两个值:$flat:x,y$,绘制后是 [[x1, y1], [x2, y2], ...]。
4. 原文 $ori:列名$
这一列必须恰好有一个值。字符串会原样嵌进 option,不再加引号,也不再包成数组。SQL 已经拼好整段 JSON5(例如旭日图、矩形树图的 children)时用它:
series: [{
type: 'sunburst',
data: $ori:tree$,
}]
tree 这一格的内容就是 [{ name: 'A', value: 10, children: [...] }, ...]。写成 $tree$ 会变成 ["这段文本"],图是空的,option 本身仍然合法,所以绘制区不会报错。
AI 生成图卡 AI
编辑图卡时标题栏的 ✨ 按钮打开 AI 面板,用一句话生成图卡的 SQL 和 option(自动选择合适的图表类型);草稿里已有内容时为编辑模式,AI 在当前配置基础上按新需求修改。
也可以直接提问咨询(如「按月分组该怎么写」「饼图 radius 有哪些写法」);
嵌入笔记正文
图卡可以直接插入笔记正文,浏览笔记时即席执行图卡保存的查询并把图表渲染在正文里。
入口:编辑笔记时,数据库附件条上的插入按钮(需在「设置 → 编辑器」开启「正文插入资源」)。
- 插入的 Markdown 语法:
;尺寸后缀|宽与!高可单独或组合使用,如、、; - 加载或执行出错时显示带重试的错误提示;
- 笔记正文引用了图卡时,对应数据库附件不可从笔记移除,图卡本身也不可删除,需先删除正文中的引用。
历史版本
与普通附件共用「附件版本历史」体系:
- 开启后,每次变更前的完整内容会自动存为历史版本,版本号单调递增;历史占用同样计入个人存储空间;
- 在资源管理页对附件点右键查看版本列表并可恢复到任意历史版本(恢复时当前内容也会先存为历史,不会丢);
- 历史版本可单独导出(该版本的整库 JSON)。
通过 API 操作
支持用 API Token 以脚本方式创建与操作,见 API:
- 创建:
POST /api/v1/resource/db/create,传笔记 ID 与名称,为笔记创建数据库; - 执行 SQL:
POST /api/v1/resource/db/exec/{resourceId}。
插入多条数据务必合并成一次请求(多值 INSERT 或分号分隔多条语句),不要每条数据请求一次,否则容易被限频。
AI 智能体(MCP / AI Bot / Agent)也已内置同款的创建与执行工具。