⚡

理解Logseq数据库架构Skill understanding-db-schema

此技能提供对Logseq数据库架构的深入了解，包括Datascript基础、属性类型、核心引用属性、内置类层次结构、属性类型系统、属性配置键、属性命名空间、架构版本控制、Malli验证流程、节点模型等，是理解和使用Logseq数据库的权威指南。

低代码开发 0 次安装 0 次浏览 更新于 3/3/2026

理解 Logseq 数据库架构

何时使用此技能

此技能在以下情况下自动触发：

  • 用户询问关于 Logseq 的数据库架构或 Datascript
  • 有关内置类（标签、页面、任务、属性等）的问题
  • 属性类型系统问题（:default、:number、:date、:checkbox 等）
  • 实体关系问题（块/标签、块/引用、块/父级）
  • 架构验证或 Malli 架构
  • 节点模型或统一页面/块概念
  • 用户提及 :db/ident、:logseq.class/* 或 :logseq.property/*

参考材料：查看 {baseDir}/references/built-in-classes.md 以获取完整的类层次结构。

您对 Logseq 的数据库架构有专家级的理解。

Datascript 基础

Logseq 数据库图基于 Datascript，这是一个 Clojure/ClojureScript 内存数据库，支持：

  • 实体-属性-值 (EAV) 数据模型
  • Datalog 查询
  • 架构驱动的属性定义

属性类型

;; 值类型
:db.type/ref      ; 引用其他实体
:db.type/string   ; 文本值
:db.type/long     ; 整数
:db.type/double   ; 浮点数
:db.type/boolean  ; 真/假
:db.type/instant  ; 时间戳
:db.type/keyword  ; Clojure 关键字
:db.type/uuid     ; UUID

;; 基数
:db.cardinality/one   ; 单值
:db.cardinality/many  ; 多值（集合）

核心引用属性

:block/tags    ; 分配给实体的类/标签
:block/refs    ; 指向其他实体的引用
:block/alias   ; 页面的替代名称
:block/parent  ; 层级中的父块
:block/page    ; 包含此块的页面

内置类层次结构

:logseq.class/Root
├── :logseq.class/Page
├── :logseq.class/Tag （类本身）
├── :logseq.class/Property
├── :logseq.class/Task
│   └── 状态、优先级、截止日期、计划
├── :logseq.class/Query
├── :logseq.class/Asset
├── :logseq.class/Code-block
└── :logseq.class/Template

所有非 Root 类通过 :logseq.property.class/extends 扩展 :logseq.class/Root。

属性类型系统

类型 验证器 封闭值 使用案例
:default text-entity? ✅ 带有标题的文本块
:number number-entity? ✅ 数值
:date date? ❌ 日记页面实体
:datetime datetime? ❌ 基于时间的调度
:checkbox boolean? ❌ 切换属性
:url url-entity? ✅ URL 字符串或宏
:node node-entity? ❌ 块/页面引用
:class class-entity? ❌ 类实体

属性配置键

{:db/ident :user.property/my-property
 :logseq.property/type :default           ; 属性类型
 :logseq.property/cardinality :one        ; :one 或 :many
 :logseq.property/hide? false             ; 默认隐藏
 :logseq.property.ui/position :properties ; UI 放置
 :logseq.property/closed-values [...]     ; 限制选择
 :logseq.property/schema-classes [...]    ; 相关类
 :block/title "我的属性"}              ; 显示名称

属性命名空间

命名空间 目的 示例
logseq.property 核心系统属性 :logseq.property/type
logseq.property.class 类相关的 :logseq.property.class/extends
logseq.property.table 表格视图 :logseq.property.table/columns
user.property 用户定义的 :user.property/author
plugin.property 插件定义的 :plugin.property/custom

架构版本控制

;; 版本格式
{:major 65 :minor 12}

;; 存储在
:logseq.kv/schema-version  ; 图的当前版本
db-schema/version          ; 预期版本

迁移处理架构升级（65.0 → 65.12+）。

Malli 验证流程

  1. 实体转换：属性 → [property-map value] 元组
  2. 架构调度：验证根据 :logseq.property/type 调度
  3. 值验证：根据类型架构检查单个值
  4. 基数处理：自动 :many 与 :one 处理
  5. 事务验证：validate-tx-report 确保完整性

节点模型

统一节点概念

在数据库版本中，节点 代表页面和块：

Node
├── Page （通过标签组合唯一）
│   ├── 日记页面 （#Journal）
│   ├── 常规页面 （#Page）
│   └── 类页面 （#Tag）
└── Block （在页面内）
    ├── 内容块
    ├── 属性块
    └── 可转换为页面的 #Page 标签

页面唯一性

页面通过其标签组合唯一：

  • “Apple #Company” ≠ “Apple #Fruit”
  • 两者可以作为单独的实体共存

常见模式

创建自定义类

;; 定义具有属性的类
{:db/ident :user.class/Book
 :block/tags [:logseq.class/Tag]
 :block/title "Book"
 :logseq.property.class/extends :logseq.class/Root
 :logseq.property/schema-classes
   [:user.property/author
    :user.property/isbn
    :user.property/rating]}

创建类型化属性

;; 带选择的数字属性
{:db/ident :user.property/rating
 :block/title "评分"
 :logseq.property/type :number
 :logseq.property/cardinality :one
 :logseq.property/closed-values [1 2 3 4 5]}

资源

当用户需要更多信息时，参考：