The embedded block feature of SiYuan supports querying using JavaScript syntax. This plugin adjusts the API structure, adds new features, and optimizes the DataView interface, making JS queries in SiYuan simpler and more convenient, with richer and more customizable data visualization.
Drop the following code into an embedded block, and your document renders a "recently updated documents" table:
//!js
let dv = Query.DataView(protyle, item, top);
let docs = await Query.sql(`select * from blocks where type = 'd' order by updated desc limit 5`);
dv.addtable(docs, { cols: ['content', 'updated'], fullwidth: true });
dv.render();
💡 The code above is only a minimal demo; the complete basic template and the step-by-step guide live in "Start from the Template", and more copyable effects are in the "Example Overview".
⚠️ This document assumes that you have a basic understanding of JavaScript syntax concepts (at minimum, basic variables, control flow, function calls, and async/await).
🔔 The complete documentation lives in the in-plugin documentation site.
This plugin ships an in-plugin documentation site with every release: after installing, click "Help" in the top-bar plugin menu to open it inside SiYuan. The documentation site matches the installed plugin version and works offline, and it never creates or updates notes in your knowledge base; help notes left over from older versions are kept as-is and are no longer updated by the plugin.
If the in-plugin documentation site is not available, you can also browse the same content directly under the
docs/directory of this repository via the links below.
💡 The plugin provides a rich set of querying and rendering features (an overview impression; detailed usage is covered in the corresponding pages of the documentation site).
1️⃣ Use the Query API for embedded block / SQL queries.
Example: query the child documents of a document by ID, and display only the first three:
2️⃣ Use the DataView object to render embedded block content in a custom way.
Example: query the backlinks of the current document and render them in the embedded block as a list of block links:
3️⃣ Integrate with SiYuan's built-in Agent.
The plugin registers its bundled Agent Skill with SiYuan's built-in Agent, so the Agent can write Query&View embed blocks and insert them directly into your documents:
🖋️ Learn from examples
The best way to learn this plugin is to start from some examples and quickly get familiar with its basic usage. After installing, open the "Examples" page of the documentation site to view, copy, and customize them; you can also browse the Example Overview right here in the repository.
The full documentation is organized into Quickstart, Topics, Examples, and Agent Reference, available in both Chinese and English. The pages below are exactly what the in-plugin documentation site renders (the site renders these pages directly), and can be browsed right here on GitHub:
Quickstart
- Basic Concepts: What is a JS Embedded Block — embedded blocks, the execution environment, and the
protyle/item/topvariables. - Start from the Template — copy the template, insert the embedded block, run and customize, and get your first Query View running.
Topics
- Query — the Query API, SQL queries, WrappedList/WrappedBlock, Query.Utils, fb2p, pruneBlocks.
- DataView Views — list/table/md and all the view components.
- DataView Advanced Features — custom view components, useState, the lifecycle, and read-only suggestions.
- External Editor & Tips — the external editor, debugging, and working with SiYuan templates.
Examples
- Example Overview — find examples by purpose/tags, copy, and customize them.
Agent Reference
- Query API — the
Querymembers: SQL and wrapped queries, utilities, andDataViewconstruction. - DataView — every DataView component and its options.
- Wrapped Lists — the
IWrappedList/IWrappedBlockprocessing methods and their element shapes. - Types — the shared option and data types.
You can also open or download the types.d.ts type declaration of the installed version from the documentation site's home page.
Agent Skill
- Agent Skill — the Agent Skill shipped with the plugin, providing rules and references for AI agents working with Query&View.
BREAKCHANGE
The plugin avoids breaking existing API usage and does not introduce breaking updates casually. When a breaking update does happen, it is announced in the BREAKCHANGE document, and legacy usage keeps working with compatibility support for several versions before the actual breaking change lands.
If you hit a deprecated or unsupported API, refer to the BREAKCHANGE document, or copy the "Copy Agent prompt" action at the bottom-right of the documentation site and hand it to SiYuan's built-in Agent.
If you are not using DataView to build visual components, return should return a list of block IDs (BlockID[]). In that case, the embedded block acts essentially as a "premium SQL" replacement and does not affect SiYuan's native embedded block rendering logic.
If you are using DataView, do not return a meaningful object.
If you are an existing user of Query View, you may remember the old generic style, which looked like:
//!js
const query = async () => {
let dv = Query.Dataview(protyle, item, top);
let blocks = await Query.backlink(protyle.block.rootID);
blocks = await Query.fb2p(blocks);
dv.addList(blocks, { type: 'o', columns: 2 });
dv.render();
}
return query();The const query = async () => ... wrapper was a must — in older versions of SiYuan, JS embedded query blocks did not allow top-level await statements, so the code had to be wrapped in an async function.
After the 3.8.0 update, this restriction is history (though the old style still works). The new version recommends the more concise style:
//!js
let dv = Query.Dataview(protyle, item, top);
let blocks = await Query.backlink(protyle.block.rootID);
blocks = await Query.fb2p(blocks);
dv.addList(blocks, { type: 'o', columns: 2 });
dv.render();Thanks to Zxhd's Basic Data Query plugin — one of the earliest extensions of SiYuan's JS query capabilities. This plugin adjusts the API structure and adds features on its basis, and is deeply inspired by it.