Obsidian dataview插件：用类SQL语法把笔记变成可查询数据库

简介：Obsidian Dataview 插件是一款面向个人知识管理用户、笔记爱好者与效率工作者的功能扩展资源，主要解决 Obsidian 原生笔记在动态查询、数据聚合与任务追踪方面的不足。它适合希望把静态笔记升级为可检索、可统计知识库的中级使用者，也便于开发者了解插件内部结构。压缩包共 4 个文件，约 460KB，包含 2 个 json 配置与数据文件、1 个 js 核心逻辑文件以及 1 个 css 样式文件，分别承担插件元数据与示例数据、功能实现、视觉呈现等用途。借助该插件，读者可以实践倒计时、表格创建、任务查询等能力，例如按截止日期筛选未完成任务、对表格数据过滤排序，从而把笔记转化为动态任务清单与轻量数据分析面板。目前已有 860 人学习下载，适合需要提升知识工作效率、构建个性化管理系统的用户参考。

1. Obsidian dataview插件：把散落笔记变成可查询数据库的那把钥匙

很多人用 Obsidian 记了半年笔记，文件夹越建越多，标签越打越乱，最后想找一条三个月前记的读书摘录，只能靠搜索框碰运气。dataview 插件解决的正是这个问题：它让你用类似 SQL 的语法，把笔记的 frontmatter、文件夹、标签、任务状态当成数据表来查询，结果实时渲染在笔记里。换句话说，它把 Obsidian 从「一堆 Markdown 文件」变成「一个可以写查询语句的个人数据库」。这篇内容面向已经装好 Obsidian、会写基本 Markdown、但还没把 dataview 用起来的人，也面向用了一阵子却只会抄LIST FROM #tag的熟手。下面从安装配置讲到 DQL 查询、DataviewJS、性能调优和踩坑排查，每一步都能直接抄。

2. dataview 的安装配置与数据模型：先搞清楚它在读什么

2.1 安装与开启的完整步骤

dataview 属于社区插件，不在核心插件列表里。安装路径是：设置 → 第三方插件 → 关闭安全模式 → 浏览 → 搜索 dataview → 安装 → 启用。启用后设置面板里会多出 dataview 一栏，里面有几个关键开关需要留意。

# 这不是命令行操作，而是设置面板里的路径，用文字描述清楚 # 设置 → 第三方插件 → 已安装插件 → dataview 右侧齿轮 # 关键开关： # Enable JavaScript Queries → 开启后才能用 dataviewjs 代码块 # Enable Inline JavaScript Queries → 开启后才能用 `$= ...` 行内查询 # Enable Inline Field Highlighting → 开启后正文里的 [key:: value] 会高亮 # Date Format → 建议设为 yyyy-MM-dd，避免日期解析歧义 # Default Date Locale → 中文环境填 zh-cn

逻辑说明：JavaScript 查询默认是关闭的，因为执行任意 JS 有安全风险，但 dataviewjs 恰恰是最灵活的部分，自己用可以开。日期格式如果不统一，后面WHERE date >= date(today) - dur(7 days)这类查询会静默返回空结果，这是新手最常见的翻车点之一。参数上，Date Format只影响显示，不影响解析，解析靠的是 frontmatter 里写的格式，所以最好从一开始就固定成yyyy-MM-dd。

2.2 dataview 到底能读到哪些字段

理解 dataview 的数据模型，比背语法重要。它把每个 Markdown 文件解析成一个对象，能读到的字段分四类：

隐式字段里最常用的是file.mtime（修改时间）、file.ctime（创建时间）、file.tags（含嵌套标签）、file.inlinks和file.outlinks（双链关系）。这里有个容易忽略的点：file.tags会把#project/alpha拆成#project和#project/alpha两个，查询时用contains(file.tags, "#project")能匹配到所有子标签，而FROM #project只匹配精确标签。选哪个取决于你要不要包含子标签，这是设计查询时必须先想清楚的。

frontmatter 的写法直接决定查询能力。推荐每个笔记都带上date、tags、status三个基础字段：

--- date: 2024-11-05 tags: - project - reading status: in-progress rating: 4 ---

逻辑说明：date用 ISO 格式，dataview 会自动识别为日期类型，可以直接做减法；tags用列表而不是逗号分隔字符串，这样contains(file.tags, "#reading")才可靠；status和rating是自定义字段，查询时直接当列名用。参数上，YAML 里的日期不要加引号，加了引号会变成字符串，date(today) - date(date)就会报类型错误。

2.3 从零写第一条能跑的查询

装好之后，在任意笔记里插入一个代码块，语言标记写dataview：

```dataview TABLE date, status, rating FROM "Notes/Reading" WHERE status = "in-progress" SORT date DESC LIMIT 10 ```

逻辑说明：TABLE决定输出表格，后面跟要显示的字段；FROM指定数据来源，可以是文件夹路径（带引号）、标签（#tag）或双链（[[某笔记]]）；WHERE过滤条件；SORT排序；LIMIT限制条数。参数上，FROM "Notes/Reading"会递归包含子文件夹，如果只想当前层，用FROM "Notes/Reading" AND -"Notes/Reading/Archive"排除归档目录。这条查询跑通，说明数据模型和语法都对了，后面所有复杂查询都是在这个骨架上加条件。

3. DQL 查询语法进阶：从 LIST 到 GROUP BY 的实战写法

3.1 LIST、TABLE、TASK、CALENDAR 四种输出怎么选

dataview 有四种查询类型，选错类型会让结果很难看。LIST只输出文件链接和可选的一个表达式，适合「列出所有相关笔记」；TABLE输出多列，适合做看板；TASK专门查任务行，能显示复选框状态；CALENDAR把带日期的笔记渲染成日历，适合日记和排期。

```dataview TASK FROM "Daily" WHERE !completed AND due <= date(today) + dur(3 days) GROUP BY file.link

逻辑说明：`TASK` 查询会扫描所有任务行，`!completed` 表示未完成，`due <= date(today) + dur(3 days)` 表示三天内到期。`GROUP BY file.link` 把同一篇笔记里的任务归到一组，避免任务散落。参数上，`dur(3 days)` 是 dataview 的时长函数，支持 `dur(1 week)`、`dur(2 months)`，注意 `days` 是复数，写 `day` 会解析失败。这个查询适合放在日记模板顶部，每天打开就能看到临近截止的任务。 ### 3.2 WHERE 里的日期、标签和空值判断 WHERE 是过滤的核心，但日期和空值最容易出问题。日期比较必须两边都是日期类型，frontmatter 里写 `date: 2024-11-05` 是日期，写 `date: "2024-11-05"` 是字符串，后者和 `date(today)` 比较会返回 false 而不是报错，属于静默失败。 ```markdown ```dataview TABLE date, rating FROM #reading WHERE date AND date >= date(today) - dur(30 days) SORT rating DESC

逻辑说明：`WHERE date` 先判断字段存在，避免没有 `date` 字段的笔记参与比较导致报错；`date >= date(today) - dur(30 days)` 取最近 30 天。参数上，`date(today)` 返回今天零点，`date(now)` 返回当前时刻，做「最近 N 天」用 `today` 更稳。标签判断用 `contains(file.tags, "#reading")` 比 `FROM #reading` 更灵活，因为前者可以放在 WHERE 里和其他条件组合，后者只能作为数据源。 ### 3.3 GROUP BY 与 FLATTEN：把嵌套数据摊平 当笔记里有列表型 frontmatter，比如 `authors: [张三, 李四]`，直接 TABLE 会显示成一行数组。用 `FLATTEN` 把数组摊开，每个元素一行，再配合 `GROUP BY` 做聚合。 ```markdown ```dataview TABLE rows.file.link AS 笔记, length(rows) AS 数量 FROM #reading FLATTEN authors GROUP BY authors SORT length(rows) DESC

逻辑说明：`FLATTEN authors` 把每篇笔记的 `authors` 数组拆成多行，每行一个作者；`GROUP BY authors` 再按作者聚合；`rows.file.link` 拿到该组下所有笔记链接，`length(rows)` 统计数量。参数上，`rows` 是 GROUP BY 之后自动生成的组内数据集合，`rows.file.link` 和 `rows.date` 都能取。这个写法适合做「按作者统计读书量」「按项目统计任务数」这类看板。注意 FLATTEN 之后原字段名会被覆盖，如果还要用原数组，先 `FLATTEN authors AS author` 起别名。 ## 4. DataviewJS 与实战场景：把查询嵌进工作流 ### 4.1 什么时候该从 DQL 换到 DataviewJS DQL 能覆盖八成需求，但遇到「根据查询结果动态生成内容」「调用外部 API」「复杂字符串处理」就力不从心。DataviewJS 在代码块里写 JavaScript，能拿到 `dv` 对象，调用 `dv.pages()`、`dv.table()`、`dv.list()` 等方法。判断标准很简单：如果查询结果需要二次加工再展示，或者要写条件分支，就换 JS。 ```javascript ```dataviewjs // 统计每个标签下的笔记数量，按数量降序 const pages = dv.pages('"Notes"'); const tagCount = {}; for (const page of pages) { for (const tag of page.file.tags) { tagCount[tag] = (tagCount[tag] || 0) + 1; } } const sorted = Object.entries(tagCount).sort((a, b) => b[1] - a[1]); dv.table(["标签", "数量"], sorted);

逻辑说明：`dv.pages('"Notes"')` 拿到 Notes 文件夹下所有页面对象；遍历 `page.file.tags` 累加计数；`Object.entries` 转成数组后按数量排序；`dv.table` 渲染成表格。参数上，`dv.pages()` 的参数和 DQL 的 FROM 一致，支持文件夹、标签、链接。这段代码比 DQL 的 GROUP BY 更直观的地方在于，它能同时统计多个标签维度，而 DQL 一次只能 GROUP BY 一个字段。 ### 4.2 用 dataview 做阅读清单和任务看板 把 dataview 查询放进模板，新建笔记时自动生成看板，是最实用的落地方式。阅读清单用 frontmatter 的 `status` 字段驱动，任务看板用 `TASK` 查询驱动。 ```markdown ```dataview TABLE WITHOUT ID file.link AS 书名, status AS 状态, rating AS 评分, date AS 读完日期 FROM #reading WHERE status != "archived" SORT choice(status = "reading", 1, choice(status = "to-read", 2, 3)) ASC

逻辑说明：`TABLE WITHOUT ID` 去掉默认的文件链接列，自己用 `file.link AS 书名` 控制显示；`choice` 函数做自定义排序，正在读的排最前，想读的其次，读完的垫底。参数上，`choice(条件, 真值, 假值)` 可以嵌套，但嵌套超过三层就该换 DataviewJS 了，可读性会急剧下降。这个查询放在阅读笔记的索引页，每次打开就是一份动态更新的书单。 ### 4.3 把 dataview 和双链、标签体系接起来 dataview 和 Obsidian 双链是互补的：双链负责建立关系，dataview 负责把关系查出来。比如每篇笔记 frontmatter 里写 `project: [[项目A]]`，就能用 dataview 反查某个项目下的所有笔记。 ```markdown ```dataview LIST FROM [[项目A]] WHERE file.name != "项目A" SORT file.mtime DESC

逻辑说明：`FROM [[项目A]]` 会匹配所有链接到「项目A」的笔记，包括正文里的双链和 frontmatter 里的链接；`WHERE file.name != "项目A"` 排除项目笔记本身。参数上，`FROM [[链接]]` 和 `FROM outgoing([[链接]])` 有区别，前者是入链，后者是出链，做「这个项目引用了哪些资料」用出链，做「哪些笔记提到了这个项目」用入链。这个查询配合标签体系，就能实现「按项目 + 按状态」的多维筛选。 ## 5. dataview 避坑与排查：那些让查询静默失败的细节 ### 5.1 查询返回空结果但语法没错 现象：代码块渲染出来是空白，没有报错，但明明有符合条件的笔记。原因通常是数据源路径写错或标签不匹配。`FROM "Notes"` 只匹配根目录下的 Notes 文件夹，如果笔记在 `Notes/Sub` 里，需要 `FROM "Notes"` 会递归包含，但如果写成 `FROM "notes"` 小写，在区分大小写的文件系统上就匹配不到。解决：先用 `LIST FROM ""` 列出所有笔记，确认路径和标签的实际写法，再逐步加条件缩小范围。 ### 5.2 日期比较永远返回 false 现象：`WHERE date >= date(today) - dur(7 days)` 一条都查不到。原因：frontmatter 里的日期被引号包成了字符串，或者格式不是 ISO。`date: 2024/11/05` 和 `date: "2024-11-05"` 都不会被解析成日期类型。解决：统一写成 `date: 2024-11-05`，不加引号，用 `typeof(date)` 在 DataviewJS 里验证类型，返回 `"object"` 才是日期。 ### 5.3 笔记多了之后查询卡顿 现象：仓库超过几千篇笔记后，每次打开带 dataview 查询的笔记都要等几秒。原因：dataview 默认每次渲染都全量扫描，没有索引缓存。解决：在设置里开启 `Refresh Interval` 并调大，减少自动刷新频率；把大范围查询拆成带 `FROM` 限定文件夹的查询，避免 `FROM ""` 全库扫描；对性能敏感的看板改用 DataviewJS 并手动缓存结果。常见做法是把看板查询放在单独笔记里，不放在日记模板中每次打开都触发。 ### 5.4 行内字段和 frontmatter 字段重名冲突 现象：frontmatter 里写了 `status: done`，正文里又写了 `[status:: pending]`，查询结果取到的是 pending。原因：dataview 解析时行内字段优先级高于 frontmatter，同名会覆盖。解决：行内字段加前缀区分，比如 `[task-status:: pending]`，或者干脆统一只用 frontmatter，行内字段只用于临时标记。这个坑很隐蔽，因为两处写法都合法，只有查询结果不对时才回头查。 ### 5.5 代码块语言标记写错导致不渲染 现象：代码块里写了查询，但显示成纯文本。原因：语言标记写成了 `dataview ` 带空格，或者写成了 `Dataview` 大写，或者用了 ```` ```dataviewjs ```` 却只开了 DQL。解决：DQL 用 `dataview`，JS 用 `dataviewjs`，全小写，前后不能有空格。如果还是不行，检查设置里 `Enable JavaScript Queries` 是否开启，JS 查询默认关闭。 ## 6. 让 dataview 查询跑得更快的三个调优习惯 第一个习惯是给查询加 `FROM` 限定。全库扫描是性能杀手，`FROM "Projects"` 比 `FROM ""` 快一个数量级，因为 dataview 只需要解析目标文件夹下的文件。我一般会在仓库根目录建一个 `Meta` 文件夹专门放看板笔记，所有看板查询都限定在具体业务文件夹，而不是全库。 第二个习惯是控制 `TABLE` 的列数。每多一列，dataview 就要多解析一个字段，尤其是 `file.inlinks`、`file.outlinks` 这类需要遍历关系的字段，列多了渲染明显变慢。看板上只保留必要列，详细字段点进笔记看。 第三个习惯是用 DataviewJS 做缓存。DQL 每次渲染都重新查询，DataviewJS 可以把结果存到 `window` 或 `dv.current()` 上，配合 `dv.view` 做条件刷新。下面这个模式我用了很久： ```javascript ```dataviewjs // 只在缓存过期时重新计算，减少重复查询 const cacheKey = "reading-stats"; const cache = window[cacheKey]; const now = Date.now(); if (!cache || now - cache.time > 60000) { const pages = dv.pages('"Notes/Reading"'); const stats = { total: pages.length, time: now }; window[cacheKey] = stats; dv.paragraph(`共 ${stats.total} 篇阅读笔记`); } else { dv.paragraph(`共 ${cache.total} 篇阅读笔记（缓存）`); }

逻辑说明：用 `window` 挂一个缓存对象，记录时间和结果，60 秒内重复渲染直接读缓存。参数上，`60000` 是毫秒，按需调整；`dv.pages` 的结果不要整个缓存，只缓存聚合后的数字，避免内存占用。这个模式适合放在侧边栏或首页看板，减少每次切换笔记时的重复计算。 最后一个技巧是验证查询是否真的生效。写完查询后，先用 `LIST` 不加任何条件跑一遍，确认数据源能读到笔记，再加 `WHERE`，再加 `SORT`，每加一步看一次结果。这个笨办法帮我省了很多「语法没错但结果不对」的排查时间。dataview 的查询是声明式的，出错时不会告诉你哪一步失败，只能靠逐步缩小范围定位。希望帮到你。 <p> <a href="https://download.csdn.net/download/weixin_40592845/89336114" style="color:#ec7500;font-size:14px;"> 本文还有配套的精品资源，点击获取 </a> <img alt="menu-r.4af5f7ec.gif" src="https://csdnimg.cn/release/wenkucmsfe/public/img/menu-r.4af5f7ec.gif" style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;"> </p>