Understanding Logseq DB Schema

When to Use This Skill

This skill auto-invokes when:

User asks about Logseq's database schema or Datascript
Questions about built-in classes (Tag, Page, Task, Property, etc.)
Property type system questions (:default, :number, :date, :checkbox, etc.)
Entity relationship questions (block/tags, block/refs, block/parent)
Schema validation or Malli schemas
Node model or unified page/block concept
User mentions :db/ident, :logseq.class/*, or :logseq.property/*

Reference Material: See {baseDir}/references/built-in-classes.md for complete class hierarchy.

You have expert knowledge of Logseq's database schema architecture.

Datascript Foundation

Logseq DB graphs are built on Datascript, a Clojure/ClojureScript in-memory database that supports:

Entity-Attribute-Value (EAV) data model
Datalog queries
Schema-driven attribute definitions

Attribute Types

;; Value types
:db.type/ref      ; References to other entities
:db.type/string   ; Text values
:db.type/long     ; Integer numbers
:db.type/double   ; Floating point numbers
:db.type/boolean  ; True/false
:db.type/instant  ; Timestamps
:db.type/keyword  ; Clojure keywords
:db.type/uuid     ; UUIDs

;; Cardinality
:db.cardinality/one   ; Single value
:db.cardinality/many  ; Multiple values (set)

Core Reference Attributes

:block/tags    ; Classes/tags assigned to the entity
:block/refs    ; Outgoing references to other entities
:block/alias   ; Alternative names for a page
:block/parent  ; Parent block in hierarchy
:block/page    ; Page containing this block

Built-in Classes Hierarchy

:logseq.class/Root
├── :logseq.class/Page
├── :logseq.class/Tag (classes themselves)
├── :logseq.class/Property
├── :logseq.class/Task
│   └── Status, Priority, Deadline, Scheduled
├── :logseq.class/Query
├── :logseq.class/Asset
├── :logseq.class/Code-block
└── :logseq.class/Template

All non-Root classes extend :logseq.class/Root via :logseq.property.class/extends.

Property Type System

Type	Validator	Closed Values	Use Case
`:default`	`text-entity?`	✅	Text blocks with titles
`:number`	`number-entity?`	✅	Numeric values
`:date`	`date?`	❌	Journal page entities
`:datetime`	`datetime?`	❌	Time-based scheduling
`:checkbox`	`boolean?`	❌	Toggle properties
`:url`	`url-entity?`	✅	URL strings or macros
`:node`	`node-entity?`	❌	Block/page references
`:class`	`class-entity?`	❌	Class entities

Property Configuration Keys

{:db/ident :user.property/my-property
 :logseq.property/type :default           ; Property type
 :logseq.property/cardinality :one        ; :one or :many
 :logseq.property/hide? false             ; Hide by default
 :logseq.property.ui/position :properties ; UI placement
 :logseq.property/closed-values [...]     ; Restricted choices
 :logseq.property/schema-classes [...]    ; Associated classes
 :block/title "My Property"}              ; Display name

Property Namespaces

Namespace	Purpose	Example
`logseq.property`	Core system properties	`:logseq.property/type`
`logseq.property.class`	Class-related	`:logseq.property.class/extends`
`logseq.property.table`	Table views	`:logseq.property.table/columns`
`user.property`	User-defined	`:user.property/author`
`plugin.property`	Plugin-defined	`:plugin.property/custom`

Schema Versioning

;; Version format
{:major 65 :minor 12}

;; Stored in
:logseq.kv/schema-version  ; Graph's current version
db-schema/version          ; Expected version

Migrations handle schema upgrades between versions (65.0 → 65.12+).

Malli Validation Flow

Entity transformation: Properties → [property-map value] tuples
Schema dispatch: Validation dispatches on :logseq.property/type
Value validation: Individual values checked against type schemas
Cardinality handling: Automatic :many vs :one handling
Transaction validation: validate-tx-report ensures integrity

Node Model

Unified Node Concept

In DB version, nodes represent both pages and blocks:

Node
├── Page (unique by tag combination)
│   ├── Journal pages (#Journal)
│   ├── Regular pages (#Page)
│   └── Class pages (#Tag)
└── Block (within pages)
    ├── Content blocks
    ├── Property blocks
    └── Convertible to page via #Page tag

Page Uniqueness

Pages are unique by their tag combination:

"Apple #Company" ≠ "Apple #Fruit"
Both can coexist as separate entities

Common Patterns

Creating a Custom Class

;; Define a class with properties
{: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]}

Creating a Typed Property

;; Number property with choices
{:db/ident :user.property/rating
 :block/title "Rating"
 :logseq.property/type :number
 :logseq.property/cardinality :one
 :logseq.property/closed-values [1 2 3 4 5]}

Resources

When users need more information, reference:

understanding-db-schema