Obsidian Dataview 查询语言速查

一、什么是 Dataview

Dataview（仓库 github.com/blacksmithgu/obsidian-dataview）把 Obsidian 库当作一个实时索引 + 查询引擎：给笔记打上元数据，再用查询语言把它们列出来、过滤、排序、分组。它只负责展示与计算，不负责编辑笔记。

数据来自三个来源：

---
rating: 8            # 1. YAML frontmatter
reviewed: false
---

基本字段:: 值         # 2. 内联字段（Inline Field）
**加粗字段**:: 也行   #    支持 Markdown 强调包裹键名

第 3 类来源是隐式字段（file.*），由 Dataview 自动维护，无需手动书写（见下文）。

二、数据来源（Metadata）

1. Frontmatter

笔记顶部 --- 包裹的 YAML。支持对象、列表等嵌套结构：

---
thoughts:
  rating: 8
  reviewable: false
tags: [one, two]
---

2. 内联字段

正文中直接写 键:: 值：

Basic Field:: Value
**Bold Field**:: Nice!
[mood:: okay]
[length:: 2 hours]

规则：内联字段的文本值遇到换行即结束；同一文件内重复的键会自动合并为列表。

3. 隐式字段（file.*，全部可用）

三、数据类型

要点：

• 日期可用 .year/.month/.week/.weekday/.day/.hour/.minute/.second 等属性；日期 + 时长 = 新日期，日期 - 日期 = 时长。
• 列表：内联文本值要带引号才是列表（"a", "b"）；yes, or, no 是纯文本。
• 链接写在 YAML frontmatter 里必须加引号（key: "[[Link]]"），否则 YAML 非法；引号链接 Dataview 认，但 Obsidian 自身不认（无出链、不随重命名更新）。

四、四种查询方式

```dataview
table time-played, length, rating
from "games"
sort rating desc

```markdown
我们正在看 `= this.file.name` 这一页。

dv.taskList(dv.pages().file.tasks.where(t => !t.completed));

本页最后修改于 `$= dv.current().file.mtime`。

五、DQL 查询结构

QUERY-TYPE <字段> FROM <来源> <数据命令> <表达式> <数据命令> <表达式> ...

只有查询类型是必填，其余可选。

查询类型

TABLE due, file.tags AS "tags", average(working-hours)

CALENDAR file.cday

数据命令

除 FROM 外，其余命令可多次使用、任意顺序，按书写顺序执行。

LIST WHERE due AND due < date(today)

LIST FROM #status/open SORT file.ctime DESC LIMIT 10

TASK WHERE !completed SORT created ASC LIMIT 10 GROUP BY file.link SORT rows.file.ctime ASC

TABLE L.text AS "My lists" FROM "dailys" FLATTEN file.lists AS L WHERE contains(L.author, "Surname")

类型安全示例：字段为 null 时比较会产生反直觉结果（null <= date(today) 为 true），应写成 WHERE typeof(due) = "date" AND due <= date(today)。

六、来源（Sources）

用于 FROM，或 JS 中 dv.pages(source)。

组合与取反：and / or（或 AND/OR）组合，- 前缀取反，括号分组：

LIST FROM #food and -#fastfood

LIST FROM #tag and ("folder" or #other-tag)

⚠️ 不写 FROM 会扫描整个库，大库可能卡住 Obsidian，尽量限定来源。

七、表达式（Expressions）

运算符

访问

• 列表索引（0 起）：list("A", "B", "C")[0] → "A"
• 对象字段：object.field 或 object["field"]
• 关键字字段名用下标：row["where"]
• 跟随链接：[[Link]].value 取目标页字段（若已有 Class:: [[Math]] 字段，用 Class.timetable 而非 [[Class]].timetable）

Lambda

CALENDAR file.day
FLATTEN all(map(file.tasks, (x) => x.completed)) AS "allCompleted"
WHERE !allCompleted

语法 (arg1, arg2) => 表达式，常用于 map/filter/minby/maxby 等。

八、函数速查

Dataview 内置函数大多支持向量化（对列表逐元素应用）。

构造函数

object(k,v,...) · list(...)（别名 array）· date(text[, format]) · dur(text) · number(text) · string(any) · link(path[, display]) · embed(link) · elink(url[, display]) · typeof(any)

数值

round(n[, digits]) · trunc(n) · floor(n) · ceil(n) · min(...) · max(...) · sum(array) · product(array) · average(array) · reduce(array, 运算)（+/-/*///&/|）· minby(array, fn) · maxby(array, fn)

列表 / 对象 / 数组

contains(容器, 值) · icontains（忽略大小写）· econtains（精确）· containsword · extract(obj, k1, k2...) · sort(list) · reverse(list) · length(x) · nonnull(array) · firstvalue(array) · all(array[, fn]) · any(array[, fn]) · none(array[, fn]) · join(array[, delim]) · filter(array, fn) · unique(array) · map(array, fn) · flat(array[, depth]) · slice(array[, start[, end]])

字符串

regextest(pat, s) · regexmatch(pat, s)（整串匹配）· regexreplace(s, pat, rep) · replace(s, pat, rep) · lower(s) · upper(s) · split(s, delim[, limit]) · startswith(s, pre) · endswith(s, suf) · padleft / padright · substring(s, start[, end]) · truncate(s, len[, suffix])

工具

default(field, value)（null 兜底）· ldefault（非向量化版）· display(any) · choice(bool, left, right)（三元表达式）· hash(seed[, text[, variant]]) · striptime(date) · dateformat(date, fmt) · durationformat(dur, fmt) · currencyformat(n[, code]) · localtime(date) · meta(link)

dateformat() 返回字符串（Luxon token 如 yyyy-MM-dd），不能直接与 date() 结果比较；sum([])/average([]) 空数组返回 null。

九、DataviewJS API 速查

dataviewjs 代码块内隐式变量 dv（或 dataview）。⌛ 表示异步（需 await）。

查询

dv.pages()              // 全库页面
dv.pages("#books")      // 带标签的页面
dv.pages('"folder"')    // 某文件夹（注意：文件夹在字符串内也要加引号）
dv.pagePaths("#books")  // 只返回路径
dv.page("Index")        // 按路径/链接取单页
dv.current()            // 当前脚本所在页面

渲染

dv.header(1, "标题");
dv.paragraph("段落文本");
dv.span("无内边距的 span");
dv.el("b", "加粗文本", { cls: "my-class", attr: { alt: "x" } });

dv.list(dv.pages().file.link);
dv.taskList(dv.pages("#project").file.tasks.where(t => !t.completed));
dv.taskList(dv.pages("#project").file.tasks, false); // 第二参 false = 不按文件分组
dv.table(["File", "Rating"],
  dv.pages("#book").sort(b => b.rating).map(b => [b.file.link, b.rating]));

返回 Markdown 的变体：dv.markdownTable() · dv.markdownList() · dv.markdownTaskList()（配合 dv.paragraph() 渲染）。

执行

dv.execute("LIST FROM #tag");     // 内嵌执行 DQL
dv.executeJs("dv.list([1,2,3])"); // 内嵌执行 JS
await dv.view("views/custom", { arg: 1 }); // 加载外部视图脚本（路径从库根算起）

工具

dv.array() · dv.isArray() · dv.fileLink() · dv.sectionLink() · dv.blockLink() · dv.date() · dv.duration() · dv.compare(a,b) · dv.equal(a,b) · dv.clone() · dv.parse()

查询求值

await dv.query("LIST FROM #tag");        // 结构化结果
await dv.tryQuery("LIST FROM #tag");     // 失败抛异常
await dv.queryMarkdown("LIST FROM #tag");// 返回 Markdown
dv.evaluate("2 + 2");                    // Result 对象（.successful / .value / .error）
dv.tryEvaluate("2 + 2");                 // 直接返回值，失败抛异常

文件 I/O（dv.io，⌛ 异步）

await dv.io.csv("data.csv");       // 读 CSV → 对象数组
await dv.io.load("File");          // 读文件内容字符串
dv.io.normalize("Test");           // 相对路径 → 绝对路径（同步）

十、安全须知

• DQL / 内联表达式是沙箱化的，无法对库做破坏性操作。
• dataviewjs / 内联 JS 拥有与插件同级的权限：可以改写、创建、删除文件，也能发起网络请求。只运行你信任的脚本。

来源

• 官方文档：https://blacksmithgu.github.io/obsidian-dataview/
• 仓库：https://github.com/blacksmithgu/obsidian-dataview