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:

• Logseq DB Documentation

• Database Schema DeepWiki

• Logseq DB Unofficial FAQ