安装 Obsidian
你需要先安装 Obsidian 桌面端或移动端，并准备一个存放 Markdown 笔记的 Vault。
了解更多Dataview Query Builder Tutorial：分步学习 DQL
这篇 Dataview Query Builder Tutorial 会带你不用手写每一行代码，也能创建第一条可用的 DQL 查询。
按照下面 5 个步骤选择查询类型、设置数据来源、添加过滤条件、复制生成代码，并把它粘贴到 Obsidian 笔记中。
打开 Dataview Query Builder →
无需注册。免费使用，所有生成过程都在浏览器本地完成。
开始之前
安装并启用 Dataview 社区插件
进入 Obsidian 设置，启用社区插件，搜索 Dataview，安装后将它开启。
了解更多准备一些带字段或标签的笔记
一个小型测试 Vault 就够了。可以给笔记添加 status、due、priority 或 tags 等 frontmatter 字段，让查询有数据可读。
用 5 步创建第一条 DQL 查询
第 1 步：打开工具
打开 Dataview Query Builder 时，先从预填好的 demo 查询开始，而不是面对一个空白界面。这个步骤很重要，因为一条可运行的 TABLE 查询能给你一个安全参照：你可以同时看到查询类型、Projects 文件夹来源、status 过滤条件、排序规则以及生成出来的 DQL。很多新手一开始就同时修改多个控件，结果无法判断是哪一处改动导致输出异常。建议先阅读预览区，把每个可视化控件和它生成的 DQL 行对应起来，再开始编辑。一个实用技巧是先保留 demo 查询，把它复制到 Obsidian 的测试笔记中；如果你只改了文件夹名后它能正常渲染，就说明 Dataview 插件和代码块格式都是正常的。
打开首页工具，先观察右侧生成的查询预览。
第 2 步：选择查询类型
在调整字段之前，先选择查询类型，因为 TABLE、LIST、TASK 和 CALENDAR 分别解决不同的问题。需要带列的仪表盘时使用 TABLE，例如展示 status、due date、owner、rating 或 project 等字段。只需要紧凑结果时使用 LIST，例如阅读队列、带标签的笔记集合或最近编辑的索引。想收集笔记内部的 Markdown 任务项时使用 TASK，而不是返回笔记本身。常见错误是明明只需要链接却使用 TABLE，导致列过多；或者需要比较多个字段时却使用 LIST。小技巧是先想清楚你希望 Obsidian 中最终呈现什么样的结果，再选择最匹配的查询类型。
在构建器顶部选择 TABLE、LIST 或 TASK。
第 3 步：用 FROM 设置数据来源
设置 FROM 来源，是为了让 Dataview 知道应该搜索 vault 的哪一部分。当笔记集中在同一个位置时，可以使用 Projects、Meetings、Reading 或 Daily 这样的文件夹；当相关笔记分散在多个文件夹时，可以使用 #project 或 #research 这样的标签。这个步骤很关键，因为大多数空结果并不是 WHERE 条件写坏了，而是来源路径不正确。要注意文件夹大小写、嵌套文件夹名称以及文件夹路径外的引号；Projects/Active 和 Projects 不是同一个来源。使用标签时，也要确认笔记中确实有 Dataview 能读取到的标签。实用做法是先用一个简单的 LIST 查询单独测试来源，再添加筛选、排序或数量限制。
选择 Folder 或 Tag，然后输入对应的数据来源。
第 4 步：用 WHERE 添加过滤条件
确认来源能返回结果后，再添加 WHERE 过滤条件，因为过滤器的作用是缩小已有结果集，而不是从零发现笔记。比如 status != archived 可以隐藏已完成或不活跃的项目笔记，priority >= 3 可以突出重要事项，contains(tags, work) 可以查找包含特定标签值的笔记，due < date(today) 可以用于逾期复盘。最常见的错误是过滤一个并非每篇笔记都有的字段，或者字段值类型和 frontmatter 不匹配。例如，如果你想可靠地比较日期，日期字段应保存为真正的日期值。建议每次只添加一个过滤条件，检查预览，并在 Obsidian 中测试后再添加下一个。一个好方法是当查询没有结果时，临时移除 WHERE 行；如果结果出现，说明来源没有问题，需要排查过滤条件。
一次只添加一个 WHERE 条件，方便排查为什么查询结果为空。
第 5 步：复制并粘贴生成的 DQL
只有当预览内容符合你想测试的查询时，再复制生成的 DQL。粘贴到 Obsidian 时，请粘贴完整的 dataview 代码块，而不只是 DQL 行，因为 Obsidian 需要通过代码块语言把查询交给 Dataview 插件执行。如果笔记里显示的是普通文本，先检查开头代码围栏是否准确标记为 dataview，并确认插件已启用。如果出现 Dataview 错误，先阅读错误所在行；它通常指向字段名、引号、操作符或值类型问题。查询渲染成功后，再把文件夹名和字段名调整成真实 vault 中的名称。建议在 Obsidian 中保留一篇专门的测试笔记，先把新查询放进去验证，再移动到仪表盘或长期复盘笔记中。
使用预览面板里的复制按钮获取生成代码。
边学边练
阅读教程时可以同时打开 Dataview Query Builder ，再把生成结果和这些 Dataview query examples。 做对比。最快的学习方式是一次只改一个控件，然后观察 DQL 预览如何变化。
如果你已经知道自己 Vault 里的字段名，可以打开 Dataview Query Builder ，用自己的文件夹、标签和 WHERE 条件构建同类查询。
常见问题
生成的查询在 Obsidian 里不显示结果怎么办？
先确认 Dataview 社区插件已经安装、启用，并允许在当前 vault 中运行。接着把查询简化到只保留查询类型和 FROM 行，这样可以判断 Dataview 在应用过滤条件之前是否能找到匹配笔记。如果简化后的查询有效，再逐个把 WHERE 条件加回来，观察是哪一个条件让结果变为空。请重点检查文件夹拼写、标签拼写、字段名，以及日期、布尔值、数字、字符串等值类型。也可以打开一篇本应匹配的笔记，确认它的 frontmatter 或 inline fields 与查询使用的是同一组字段名。这种逐步缩小范围的方法比猜测更快，也能避免因为一个字段不匹配而重写整条查询。
支持哪些 Dataview 查询类型？
本教程覆盖 TABLE、LIST、TASK 和 CALENDAR 类查询的核心工作流，重点放在用户最常用的可视化构建模式上。当你需要列和字段对比时使用 TABLE；当你只需要简单的笔记索引时使用 LIST；当输出需要收集匹配笔记中的 Markdown 任务项时使用 TASK。CALENDAR 查询也遵循类似的来源和日期字段思路，但具体结果取决于你的 vault 如何存储日期元数据。如果不确定应该选择哪种类型，可以先用 LIST 确认来源有效，再在需要字段时切换到 TABLE，或在需要任务行时切换到 TASK。保持第一条查询足够简单，会让后续排错轻松很多。
我的数据会发送到服务器吗？
不会。构建器只在浏览器中生成 DQL 文本，不会把你的 Obsidian vault、笔记内容、文件夹、标签或 frontmatter 上传到服务器。你手动输入文件夹名、字段名、标签和筛选值，工具只是把这些输入转换成查询字符串。这个隐私模型很重要，因为很多 Obsidian vault 都包含个人笔记、客户信息、研究材料或私密计划。你可以把生成的代码复制到 Obsidian 中，但真正执行查询的是本地 Obsidian 应用里的 Dataview 插件。如果你处理的是敏感 vault，请避免把私人笔记内容粘贴到任何网页工具中；对这个构建器来说，只需要查询结构即可。