安装配置 → 第一个查询 → 常用代码库，全程无盲点

⚠️v5.0 新手修正：DataviewJS 不作为新手必学内容。第一阶段只学普通 LIST、TABLE、TASK 查询。只有当你明确知道为什么需要 JavaScript 查询时，再进入进阶学习。

1 安装后必做的设置

1-1 安装并启用 Dataview 后：设置 → 社区插件 → 已安装插件 → Dataview → 点击⚙️进入设置
1-2 找到"Enable JavaScript Queries"（启用 JavaScript 查询），打开此开关（DataviewJS 功能）
1-3 找到"Enable Inline Queries"（启用行内查询），打开（支持在文本中用 =字段名插入动态值）
1-4 日期格式改为 yyyy-MM-dd，时间格式 HH:mm

✅预期结果：设置保存。现在可以在任意笔记的代码块里写 Dataview 查询代码了。

"Enable JavaScript Queries" 这个开关，说句实话：新手可以先不开。不开的代价只是用不了 dataviewjs 代码块，普通 LIST/TABLE/TASK 完全不受影响。等哪天你真的需要算复杂指标了，再回来打开。

日期格式这一项要在一开始就定，因为它决定查询结果里日期显示成什么样。yyyy-MM-dd 是最不容易看错的写法，别改成 dd/MM/yyyy 这种。

三个开关分别管什么：

Enable JavaScript Queries：只控制 dataviewjs 代码块，关掉不影响普通查询。
Enable Inline Queries：控制正文里 = 字段名 的行内取值，建议打开，这是被低估最多的功能。
Enable Inline Field Highlighting：正文里写了 优先级:: 高 这种行内字段时给不给底色，纯视觉开关，不影响查询。

行内查询打开后，正文里这样写：

这篇笔记的状态是 `= this.status`，最后修改于 `= this.file.mtime`。

渲染出来就是实际值。反引号里必须以 = 开头，且 = 后面要有一个空格——写 =this.status 不渲染，这是最常见的一处失手。

2 写第一个 Dataview 查询

LIST FROM ""
SORT file.mtime DESC
LIMIT 10

2-1 在笔记中输入三个反引号 ``` 后紧接输入 dataview（不加空格），按 Enter
2-2 输入查询内容（如上面的三行），再输入三个反引号 ``` 结束代码块
2-3 在实时预览模式下，代码块自动渲染为查询结果列表

✅预期结果：代码块渲染为你知识库中最近修改的10篇笔记的列表，每条都是可点击的链接。如果显示"No results"说明库中还没有笔记。

⚠️显示代码而不是查询结果？确认是"实时预览"模式而非"源码模式"；确认语言名写的是 dataview 而非其他；确认插件已启用。

把这三行拆开看：

LIST 决定输出长什么样，这里输出一个纯列表，每行只有笔记标题。
FROM "" 是数据来源，空字符串代表整个库。想只查某个文件夹就写 FROM "01-Projects"。
SORT file.mtime DESC 按修改时间倒序，DESC 是从新到旧，ASC 是从旧到新。
LIMIT 10 只保留前 10 条。库大的时候不加这句，渲染会明显卡一下。

想让它多显示一列，就把 LIST 换成 TABLE，并在后面加字段名，比如 TABLE status, deadline。这是 LIST 和 TABLE 唯一的区别。

让第一条查询一定出结果的做法：空库直接查，大概率看到 "No results"，然后你就不知道该怀疑哪里了。稳妥的顺序是反过来——先造数据，再写查询。

建三篇笔记，命名随意，比如 会议-周一.md、会议-周三.md、读书-原则.md
每篇顶部加一段属性区：

---
type: 会议
status: 进行中
deadline: 2026-06-01
---

再跑这条：

TABLE status, deadline
FROM ""
WHERE type = "会议"

如果能看到两行结果、状态和日期都在，说明整条链路（属性区 → 字段识别 → 查询 → 渲染）全通了。后面再复杂都是在这条链路上加条件。

查询写在哪个文件里？可以写在任何笔记里，包括专门建一个 看板.md 只放查询。惯例是后者：查询集中放在索引页，内容笔记只放数据。这样改看板不用翻遍全库，也不怕误删内容笔记时连带删掉查询。

3 Dataview 语法核心规则（先记这4条）

FROM	指定从哪里查数据	FROM "Projects"从Projects文件夹；FROM #标签按标签
WHERE	过滤条件	WHERE status = "进行中"；WHERE date = date(today)
SORT	排序	SORT file.mtime DESC按修改时间降序
LIMIT	限制条数	LIMIT 10只显示10条

这四条之外，还有三条迟早要用：

关键字	干什么	典型写法
GROUP BY	把结果按某字段分组	`GROUP BY type` 把会议、读书分开列
FLATTEN	把数组字段拆成多行	`FLATTEN tags` 一条笔记多个标签时按标签展开
WITHOUT ID	去掉 TABLE 默认的文件链接列	`TABLE WITHOUT ID status, deadline`

WITHOUT ID 尤其值得记：TABLE 默认第一列永远是文件名链接，做紧凑看板时那一列很占地方，加上它就能省掉。

两个容易拌人的规则：

字段名区分大小写：status 和 Status 是两个字段。
FROM 后面什么都不写，等价于 FROM ""，都是全库。

4 四种查询的最小可运行版本

LIST——只要一列链接，最快：

LIST
FROM #读书笔记
SORT file.ctime DESC
LIMIT 10

TABLE——要带字段列：

TABLE file.mtime AS "修改时间", tags AS "标签"
FROM "01-Projects"
SORT file.mtime DESC
LIMIT 15

TASK——只抓 - [ ] 复选框：

TASK
FROM "06-Daily"
WHERE !completed
GROUP BY file.link

CALENDAR——把日期画成月历：

CALENDAR file.mtime
FROM "01-Projects"

区别一句话说清：LIST 只出一列，TABLE 能带任意字段，TASK 只抓复选框，CALENDAR 挑一个日期字段画日历。

两个细节：LIST 后面只能跟一个字段，想要两列就得换 TABLE；TABLE 的第一列永远是文件链接，不想看就在 TABLE 后面加 WITHOUT ID。

⚠️上面第 8 个示例里的 TASK 查询写了两个 WHERE。如果你照抄后报错或查不出东西，把两行合成一行：WHERE !completed AND date = date(today)。

AS 别名纯粹是显示用，不改变数据。TABLE file.mtime AS "修改时间" 能把整张表从「程序员风格」变成「同事能看懂」。做给别人看的看板，这一句必加。

TASK 查询有两个前提：目标笔记里必须有真正的复选框语法 - [ ]（写成 - [x] 算已完成），普通列表项抓不到；GROUP BY file.link 的作用是把同一篇笔记的任务收在一个标题下，任务多的时候不加它，你分不清哪条属于哪篇。

CALENDAR 后面必须跟日期类型的字段。写 CALENDAR file.mtime 可以，写 CALENDAR status 不行，除非 status 存的就是日期。日历空白，八成是那批笔记压根没有有效日期字段，而不是查询写错。

5 FROM 的三种来源写法

文件夹：FROM "01-Projects"，双引号包裹，路径相对库根，自动包含子文件夹。
标签：FROM #读书笔记。标签有层级就写全，比如 #读书笔记/已读，只写父级不一定匹配到子标签。
链接：FROM 索引笔记，查这篇笔记链出去的所有笔记；反过来查链进来的用 incoming(索引笔记)。

三种可以混着用：FROM "01-Projects" AND #进行中取交集，OR 取并集，前面加减号是排除，比如 -"99-归档"。FROM 整个不写，默认就是全库。

路径写法最容易错的三处：

必须带双引号：FROM 01-Projects 会被当成表达式，直接无结果。
路径相对库根：写 "01-Projects"，不要写 /Users/me/vault/01-Projects 这种绝对路径。
自动递归：FROM "01-Projects" 已包含它下面所有子文件夹，不需要写 "01-Projects/**"。

排除写在引号外面：

FROM "01-Projects" AND -"01-Projects/99-归档"

查 01-Projects 但去掉 99-归档子文件夹。模板笔记、草稿目录都用这招挡掉。

6 WHERE 里最常用的几个函数

contains(file.name, "会议")：文件名含关键词
contains(tags, "读书笔记")：标签数组里含这个值
date(deadline) >= date(today)：还没到期的
date(today) - dur(7 days)：七天前这个时间点，配合 >= 就是"最近一周"
startswith(file.name, "2026")：前缀匹配，endswith 是后缀
length(file.inlinks) > 0：至少被链接过一次的笔记
!completed：只留未完成的复选框
choice(done, "✅", "⬜")：在 TABLE 里做条件列

日期最容易踩坑。frontmatter 里写 deadline: 2026-06-01，Dataview 有时把它当字符串，直接比大小结果会很怪。比较之前统一套一层 date()，写成 WHERE date(deadline) >= date(today)，稳。

再加四个够用的：

icontains(file.name, "meeting")：不区分大小写的包含，中文无所谓，英文关键词用它。
econtains(tags, "读书笔记")：精确匹配整个字段值（contains 是子串匹配，容易误中）。
length(file.tasks) > 0：有任务清单的笔记。
regexmatch("^2026-0[1-3]", file.name)：正则匹配，做「2026 年第一季度」这类筛选。

「最近一周」这类区间：

TABLE file.mtime AS "修改时间"
FROM ""
WHERE date(file.mtime) >= date(today) - dur(7 days)
SORT file.mtime DESC

dur(7 days) 是时间段写法，也可以写 dur(1 week)、dur(1 month)。

多条件用 AND / OR 连接，复杂条件加括号明确优先级：

WHERE (type = "会议" OR type = "评审") AND status != "已归档"

不加括号时优先级容易记错，养成加括号的习惯。

7 字段从哪来

frontmatter：在 --- 之间写的 key，查询里直接用名字，比如 status。
行内字段：正文里写优先级:: 高，这一篇就能被查到，不用改 frontmatter。
隐式字段：file.name、file.path、file.folder、file.link、file.ctime、file.mtime、file.size、file.tags、file.inlinks、file.outlinks、file.tasks，不用自己定义就能用。
某篇没有这个字段不会报错，只是那一格空着，所以别看见空白就以为查询坏了。

属性区的正确写法：

---
type: 会议
status: 进行中
deadline: 2026-06-01
tags:
  - 项目/一期
  - 会议
---

三个细节决定它能不能被读到：

必须在文件第一行，前面不能有空行、不能有标题。
冒号后面要有一个空格，写 status:进行中 不生效。
不要用 Tab 缩进，YAML 只认空格，混进一个 Tab 整块属性区都会失效。

不想改属性区时，正文里写行内字段也行：

优先级:: 高
负责人:: 老王

写在正文任意位置，Dataview 照样能查到。适合临时打标，或者一篇笔记里要记多组同类信息。缺点是散落在正文里不好维护，字段多了还是回属性区更清楚。

字段类型是自动推断的：2026-06-01 认成日期，42 认成数字，进行中 认成文本，[a, b] 认成数组。所以 WHERE deadline > "2026-06-01" 这种把日期当字符串比的写法，结果会莫名其妙——要么两边都套 date()，要么确保格式统一。

值里带冒号要用引号包起来，否则 YAML 会把冒号当成新的分隔符直接报错：

title: "会议：第一季度复盘"

8 DataviewJS 是什么，为什么先别碰

语言名写成 dataviewjs 才是 JS 查询，和普通查询是两套东西。它能做普通查询做不了的事（算复杂指标、画图），代价也实在：

它跑的是完整 JavaScript，能读文件、能联网。从别人那儿复制来的 JS 片段，等于往自己库里粘一段陌生程序。
升级最容易坏的就是它。插件改个接口，昨天还能跑的脚本今天全是报错。
出错信息对新手基本没法读。

LIST/TABLE/TASK 能表达的，就别上 JS。真要用，先看清那段代码里有没有 fetch、require、eval 这类东西。

只有三种情况普通查询真做不到，那时候再考虑：跨行计算（先汇总再相除的指标）、自定义图表、需要先查一批再拿结果查另一批的联动。三种之外一律先用普通查询凑——大多数「必须用 JS」的需求，换个数据结构就能用 TABLE 解决。

9 查不出结果，按这个顺序查

显示的是代码本身：语言名不是 dataview、当前在源码模式、插件没启用，这三条占九成。
No results：FROM 的路径大小写不对、文件夹名拼错、标签压根没打。
字段列全空：key 拼错（Dataview 区分大小写），或者正文里忘了写成 key:: value。
只有部分笔记有数据：那几篇的 frontmatter 格式坏了，YAML 里少空格或用了 tab，整块 frontmatter 都会失效。
结果对但慢得离谱：先加 FROM 缩小范围，再加 LIMIT，别老查全库。看板查询集中放一个文件，避免每篇笔记都挂一条全库查询。
昨天还好今天全红：八成是插件更新了，先看更新日志再考虑回退版本。用 dataviewjs 的情况更常见——普通查询语法极其稳定，JS 接口才是变动区。

10 八个能直接抄的查询

攒模板比学语法省时间。这八条改掉文件夹名就能用。

最近改过的十篇

LIST FROM "" SORT file.mtime DESC LIMIT 10

本周新建的笔记

TABLE file.ctime AS "创建时间"
FROM ""
WHERE date(file.ctime) >= date(today) - dur(7 days)
SORT file.ctime DESC

某个标签下没写完的

LIST FROM #草稿 WHERE !completed

按类型分组的清单

TABLE rows.file.link AS "笔记", length(rows) AS "数量"
FROM "01-Projects"
GROUP BY type

所有未完成任务，按文件归拢

TASK FROM "06-Daily"
WHERE !completed
GROUP BY file.link

即将到期的三件事

TABLE deadline AS "截止", status AS "状态"
FROM ""
WHERE date(deadline) >= date(today)
SORT date(deadline) ASC
LIMIT 3

孤岛笔记（没人链接它）

LIST FROM ""
WHERE length(file.inlinks) = 0 AND file.name != "看板"
SORT file.mtime ASC
LIMIT 20

读书笔记按评分排

TABLE rating AS "评分", author AS "作者"
FROM #读书笔记
WHERE rating
SORT rating DESC

最后一条要求那批笔记的属性区里有 rating 字段。没有这个字段的笔记会自动被 WHERE rating 过滤掉，不会报错，也不会空着占位。

十分钟做完的完整练习

建文件夹 练习，里面建三篇笔记，各加属性区：type、status、deadline 三个字段，值各不相同。
新建 练习/看板.md，贴这条：

TABLE WITHOUT ID file.link AS "笔记", status AS "状态", deadline AS "截止"
FROM "练习"
WHERE type = "任务"
SORT date(deadline) ASC

改其中一篇的 status，回看板看结果有没有跟着变。
把 SORT 那行删掉再加回去，感受一次排序的作用。

四步做完，Dataview 的读写闭环就通了。剩下的是攒模板，不是学新语法。

🧪 实操提示
为什么要学：Dataview 用来从笔记里筛选信息，新手先不用 JS。
现在就做：创建 3 篇带标签的笔记，用一个简单查询列出来。
怎么算成功：能解释 list/table/task 的区别。
失败时先查：是否做错了文件夹或路径？是否少按了一次确认/保存/重启？是否把进阶步骤提前做了？先回到第一个最小案例，不要继续叠加复杂度。