Obsidian Dataview 插件允许用户将 Obsidian 笔记库(Vault)视为数据库,通过查询语言提取、过滤和排序 Markdown 文件中的元数据。该插件主要提供两种查询模式:基于管道的声明式查询语言(DQL)和基于 JavaScript 的 API(DataviewJS)。DQL 适合处理基础的过滤与展示需求,而 DataviewJS 则提供了对索引的完全访问权限和更复杂的逻辑处理能力。
数据提取机制:YAML 与 Inline Fields
Dataview 通过解析 Markdown 文件中的元数据来构建索引。主要支持两种元数据格式:
YAML Frontmatter:位于文件顶部的
---分隔的 YAML 块。例如:--- alias: "document" last-reviewed: 2021-08-17 thoughts: rating: 8 ---Inline Fields:Dataview 特有的功能,允许在文档正文中直接嵌入键值对,语法为
Key:: Value。例如:Basic Field:: Value **Bold Field**:: Nice! [field:: inline fields]
从 0.5.29 版本开始,空值的 Inline Fields(如 Key:: 无值)会被映射为 null 而非空字符串,这有助于修复之前因空字符串导致的查询错误。
DQL 查询语言核心语法
DQL 是一种类似 SQL 的管道式查询语言,支持以下核心命令:
基础查询与数据源
- FROM:指定查询范围,支持标签(
#tag)、文件夹("folder")或单文件("path/to/file")。 - WHERE:过滤条件。例如
WHERE Category表示筛选 Category 字段非空的记录;WHERE digitProperty = 123用于数值比较。 - SORT:排序,支持
asc和desc。例如SORT Year asc。 - GROUP BY:按字段分组。分组后,访问文件属性需通过
rows属性,如rows.file.name。 - FLATTEN:将数组类型的属性展开为多行。例如
FLATTEN Action会将 Action 数组中的每个元素显示为单独的行。 - LIMIT:限制返回结果数量。
高级操作
- CHOICE:将布尔值转换为自定义显示文本。例如
choice(read, "Yes", "No")。 - contains:检查数组是否包含特定元素,常用于检查文件链接。例如
contains(file.outlinks, [[My books]])。 - TASK 查询:专门用于处理任务列表。支持
due日期比较,但需注意处理无日期的任务,通常结合typeof(due) = "date"使用。
DataviewJS API 与扩展能力
DataviewJS 提供了基于 JavaScript 的编程接口,允许开发者访问 Dataview 的内部索引并执行复杂逻辑。相比 DQL,DataviewJS 更加灵活,但运行在插件权限下,需注意安全性。
核心 API 对象
- dv.pages():获取所有页面或指定标签/文件夹的页面集合。
- dv.current():获取当前页面的上下文信息。
- dv.taskList():渲染任务列表,支持分组和过滤。
- dv.array():将普通数组转换为 Dataview 数组,支持
.where()等链式查询方法。
版本演进与功能增强
- 0.5.31+:API 进行了重大重构,函数数量翻倍。引入了
extension功能,允许插件添加自定义 DQL/DataviewJS 函数、自定义渲染对象(如进度条)以及替代默认行为。 - 0.5.30+:引入了
typeof()函数用于类型检查,以及%取模运算符。 - 0.5.40+:添加了实验性的插件 API,允许直接查询 Dataview 并转换为 Markdown。
- 0.5.50+:暴露了
EXPRESSION和QUERY解析器,允许外部插件解析 Dataview AST。
性能与索引
从 0.5.21 版本开始,Dataview 缓存了元数据,首次加载后查询速度极快(目标 <10ms)。0.5.31 版本后,Dataview NPM 库暴露了内部类型和 AST 结构,便于第三方插件集成。
嵌套 Inline Fields 与子任务处理
嵌套 Inline Fields
Dataview 支持嵌套的 Inline Fields,但在早期版本(如 0.5.42)中曾出现解析不稳定导致崩溃的问题。后续版本改进了对嵌套结构的处理,使其更加健壮。在 DQL 中,可以通过点号访问嵌套属性,例如 file.tasks 获取文件中的所有任务。
子任务(Subtasks)支持
从 0.4.23 版本开始,Dataview 增强了对子任务的支持:
- 查询范围:查询现在覆盖所有列表项,包括子任务,而不仅仅是根元素。
- 数据结构:
file.tasks包含文件中的所有任务(包括子任务)。若要获取根任务,需过滤task.parent为空的项。 - 渲染:
dv.taskList能够智能地处理嵌套和去重,正确渲染子任务层级。 - 分组:支持对任务进行分组,例如
dv.pages().groupBy(page => page.file.folder).groupIn(page => page.title)可实现多级分组。
任务元数据
任务可以拥有独立的元数据,如 due(截止日期)、completed(完成状态)等。0.5.31 版本后,任务还增加了 outlinks 字段,用于追踪任务中的链接。
Conversation
评论