# 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 解析能力，提升了性能与第三方集成能力。

原文：/knowledge/crawler-036a5c7815249801851eb2a166064c30aac2fb7d50ef04c68015ea530c8c8c7a

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

## 数据提取机制：YAML 与 Inline Fields

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

1. **YAML Frontmatter**：位于文件顶部的 `---` 分隔的 YAML 块。例如：
   ```yaml
   ---
   alias: "document"
   last-reviewed: 2021-08-17
   thoughts:
     rating: 8
   ---
   ```
2. **Inline Fields**：Dataview 特有的功能，允许在文档正文中直接嵌入键值对，语法为 `Key:: Value`。例如：
   ```markdown
   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` 字段，用于追踪任务中的链接。

<!-- knowledgefill:references -->
## 参考资料

- [obsidian-dataview/CHANGELOG.md at master · blacksmithgu/obsidian-dataview · GitHub](https://github.com/blacksmithgu/obsidian-dataview/blob/master/CHANGELOG.md)
- [GitHub - blacksmithgu/obsidian-dataview: A data index and query language over Markdown files, for https://obsidian.md/. · GitHub](https://github.com/blacksmithgu/obsidian-dataview)
