logseq-schema

Logseq 架构

概述

使用此技能，依据 Logseq 的架构编写 Datascript 查询：包括核心块/页面/文件属性、内置属性、内置类，以及带有 :db/ident 的架构实体。请加载 references/logseq-datascript-schema.md，以获取权威来源和查询模式；并加载 references/logseq-datascript-query-examples.md，以获取基于场景的查询示例。

术语表

• db/id：内部数字实体 ID（与 --id 等 CLI 标志搭配使用）。
• :block/uuid：块实体的稳定 UUID；需要持久引用时优先使用。
• :block/name：小写的页面名称，用于页面查找和联接。
• :block/title：存储在 DB 图中的块或页面标题（查询需要内容文本时使用）。
• :block/tags：将块链接到标签/页面实体的多值引用属性。
• :user.property/<name>：直接存储在块实体上的用户自定义属性命名空间。
• :logseq.property/*：直接存储在块实体上的内置属性命名空间。

重要说明

• 在 query 或 pull 中绝不要使用以下块属性。这些属性仅存在于文件图中，不用于 DB 图： :block/format、:block/level、:block/level-spaces、:block/pre-block?、:block/properties-order、:block/properties-text-values、:block/invalid-properties、:block/macros、:block/file、:block.temp/ast-body、:block.temp/ast-blocks、:block/marker、:block/content、:block/priority、:block/scheduled、:block/deadline、:block/properties、:block/left。
• 用户属性以 :user.property/<name> 属性的形式存储在块/页面实体上。
• Pull 选择器不支持命名空间通配符，例如 :user.property/* 或 :logseq.property/*。在 pull 中只允许使用 *（所有属性）或明确指定的属性。
• 要获取用户属性，可以：
  • 查询 datom，并按命名空间（例如 user.property）筛选属性，然后合并到实体映射中；或
  • 找出明确的用户属性 ident（通过 :db/ident），并在 pull 选择器中明确列出。
• 属性值通常是实体/引用（并非总是标量）。呈现值时，先检查值实体上是否有 :block/title、:block/name 或 :logseq.property/value，再退回到字符串化处理。
• 许多属性的基数为 :db.cardinality/many（值可能是集合/向量）。在查询和格式化时，应将其视为集合。

应避免的 Datascript 查询错误

• 在 query 的 :where/pull/find 中，属性不能使用命名空间通配符（例如 :logseq.property/*、:user.property/*）；必须使用完整的属性 :db/ident 值（例如 :logseq.property/status、:user.property/background）。在 pull 中，只有 *（所有属性）是特殊值。
• 避免在 :where 中的谓词内嵌套函数调用（某些 Datascript 引擎会拒绝或错误处理）。先绑定函数结果，再进行比较。

安全的命名空间筛选示例：

[:find [?a ...]
 :where
 [?e :db/ident ?a]
 [(namespace ?a) ?ns]
 [(= ?ns "user.property")]]

工作流

1) 查找架构信息

• 打开 references/logseq-datascript-schema.md。
• 查看核心属性列表和辅助集合，了解引用/基数详情。
• 查看内置属性和类，了解可用属性和必需字段。

2) 编写或验证查询

• 块/页面查询优先使用 :block/* 属性；仅在需要时使用属性/类。
• 如果不确定有哪些 :db/ident 实体，请运行参考文件中列出的 CLI 查询。
• 对于用户属性，直接查询 :user.property/<name>；对于内置属性，使用 :logseq.property/<name>。

3) 确保查询符合架构

• 关联时遵循引用与标量属性的区别，并考虑 :db.cardinality/many。
• 向用户提供查询前，使用属性/类定义确认其是否公开且可查询。

资源

references/

• logseq-datascript-schema.md
• logseq-datascript-query-examples.md

快速示例

提取块的用户属性

;; Discover idents, then pull explicitly.
[:db/id :block/title :user.property/background :user.property/notes]

查询具有用户属性的块

[:find ?b ?v
 :where
 [?b :user.property/background ?v]]

渲染属性值

当值为映射/实体时的优先顺序：

1. :block/title
2. :block/name
3. :logseq.property/value