Skip to content
LiveNew tools this week
Submit
AIMarketly
understanding-db-schema logo

Understanding Logseq DB Schema

understanding-db-schema

Deep expertise in Logseq's Datascript database schema. Auto-invokes when users ask about Logseq DB schema, Datascript attributes, built-in classes, property types, entity relationships, schema validation, or the node/block/page data model. Provides authoritative knowledge of the DB graph architec...

aiskillstore/marketplace0installs430stars

SKILL.md

Full skill instructions

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

TypeValidatorClosed ValuesUse Case
:defaulttext-entity?✅Text blocks with titles
:numbernumber-entity?✅Numeric values
:datedate?❌Journal page entities
:datetimedatetime?❌Time-based scheduling
:checkboxboolean?❌Toggle properties
:urlurl-entity?✅URL strings or macros
:nodenode-entity?❌Block/​page references
:classclass-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

NamespacePurposeExample
logseq.propertyCore system properties:logseq.property/​type
logseq.property.classClass-related:logseq.property.class/​extends
logseq.property.tableTable views:logseq.property.table/​columns
user.propertyUser-defined:user.property/​author
plugin.propertyPlugin-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

  1. Entity transformation: Properties → [property-map value] tuples
  2. Schema dispatch: Validation dispatches on :logseq.property/​type
  3. Value validation: Individual values checked against type schemas
  4. Cardinality handling: Automatic :many vs :one handling
  5. 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: