Agent skill

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 architecture.

View SKILL.md on GitHub Repository
Stars 3
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/C0ntr0lledCha0s/claude-code-plugin-automations/tree/main/logseq-expert/skills/understanding-db-schema

SKILL.md

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

clojure
;; 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

clojure
: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

clojure
{: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

clojure
;; 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

clojure
;; 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

clojure
;; 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:

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

C0ntr0lledCha0s/claude-code-plugin-automations

analyzing-docs

Expert at analyzing documentation quality, coverage, and completeness. Auto-invokes when evaluating documentation health, checking documentation coverage, auditing existing docs, assessing documentation quality metrics, or analyzing how well code is documented. Provides frameworks for measuring documentation effectiveness.

3 0
Explore
C0ntr0lledCha0s/claude-code-plugin-automations

writing-docs

Expert at writing high-quality documentation for code, APIs, and projects. Auto-invokes when generating docstrings, creating README files, writing API documentation, adding code comments, or producing any technical documentation. Provides language-specific templates and best practices for effective documentation writing.

3 0
Explore
C0ntr0lledCha0s/claude-code-plugin-automations

managing-docs

Expert at organizing and managing documentation structure across projects. Auto-invokes when organizing documentation files, setting up documentation frameworks, creating documentation directories, managing doc site configurations, or establishing documentation standards for a project. Provides guidance on documentation architecture and tooling.

3 0
Explore
C0ntr0lledCha0s/claude-code-plugin-automations

Hook Development

This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.

3 0
Explore
C0ntr0lledCha0s/claude-code-plugin-automations

MCP Integration

This skill should be used when the user asks to "add MCP server", "integrate MCP", "configure MCP in plugin", "use .mcp.json", "set up Model Context Protocol", "connect external service", mentions "${CLAUDE_PLUGIN_ROOT} with MCP", or discusses MCP server types (SSE, stdio, HTTP, WebSocket). Provides comprehensive guidance for integrating Model Context Protocol servers into Claude Code plugins for external tool and service integration.

3 0
Explore
C0ntr0lledCha0s/claude-code-plugin-automations

Agent Development

This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.

3 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results