Obsidian Dataview 插件查询语言与 API 扩展能力解析

本文解析了 Obsidian Dataview 插件的查询语言(DQL)与 API 扩展能力。DQL 提供类似 SQL 的管道式查询,支持 FROM、WHERE、SORT、GROUP BY 等命令,适用于基础数据过滤与展示。DataviewJS 则提供基于 JavaScript 的 API,允许访问内部索引并执行复杂逻辑,支持自定义函数与渲染扩展。插件通过解析 YAML Frontmatter 和 Inline Fields 提取元数据,支持嵌套字段与子任务的递归查询。版本演进中,API 在 0.5.31 后大幅增强,引入了扩展机制与 AST 解析能力,提升了性能与第三方集成能力。

READ

Obsidian Dataview 插件允许用户将 Obsidian 笔记库(Vault)视为数据库,通过查询语言提取、过滤和排序 Markdown 文件中的元数据。该插件主要提供两种查询模式:基于管道的声明式查询语言(DQL)和基于 JavaScript 的 API(DataviewJS)。DQL 适合处理基础的过滤与展示需求,而 DataviewJS 则提供了对索引的完全访问权限和更复杂的逻辑处理能力。

数据提取机制:YAML 与 Inline Fields

Dataview 通过解析 Markdown 文件中的元数据来构建索引。主要支持两种元数据格式:

  1. YAML Frontmatter:位于文件顶部的 --- 分隔的 YAML 块。例如:

    ---
    alias: "document"
    last-reviewed: 2021-08-17
    thoughts:
     rating: 8
    ---
    
  2. 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

评论

正在加载评论