Logseq DB Plugin API Skill

Version: 2.1.0
Updated: 2025-12-18

A comprehensive Claude Code skill for developing Logseq plugins specifically for DB (database) graphs, now with modular documentation and production-tested patterns.

Overview

This skill provides essential knowledge for building Logseq plugins that work with the new DB graph architecture. It covers the complete plugin API verified against LSPlugin.ts TypeScript definitions, including tag/class management (with CORRECTED method names), property handling (with complete upsertProperty signature), icon management, tag inheritance, comprehensive type definitions, and proper Vite bundling setup.

Target Audience: Developers building plugins for Logseq DB graphs using Claude Code.

What's New in v2.1.0

Advanced Query Patterns 🔍

This update adds production-tested patterns for complex Datalog queries, including tag inheritance and disjunctive query patterns discovered through real-world plugin development.

New Query Capabilities:

1. Tag Inheritance Queries - Query items tagged with parent tags OR any child tags that extend them

   • Use :logseq.property.class/extends to traverse tag hierarchies
   • Find all tasks including #shopping, #feedback, etc. that extend #task
   • Production-tested or-join pattern for reliable results

2. Disjunctive Queries with or-join - Combine query branches with different variables

   • Solve "All clauses in 'or' must use same set of free vars" errors
   • Understand when to use or-join [?vars] vs standard or
   • Complete explanation with error examples and fixes

3. :block/title vs :block/name - Clear documentation of tag attribute differences

   • :block/title = Display name (case-sensitive, "Task")
   • :block/name = Normalized name (lowercase, "task")
   • When to use each in queries (app vs CLI contexts)

4. Query Context Guide - Same Datalog works across different contexts

   • Plugin API: logseq.DB.datascriptQuery(query)
   • App query blocks: Direct Datalog syntax
   • CLI: logseq query command patterns

Documentation Updates:

• queries-and-database.md: New "Advanced Query Patterns" section (~140 lines)
• core-apis.md: Tag hierarchy creation examples with cross-references
• pitfalls-and-solutions.md: Pitfall #9 about or-join variable mismatch
• SKILL.md: Updated search patterns and inheritance query examples

Real-World Use Case: Query all tasks of status "Todo" with any priority, including items tagged with tags that extend #task:

{:query [:find (pull ?b [*])
         :where
         (or-join [?b]
           ;; Direct #task tags
           (and [?b :block/tags ?t]
                [?t :block/title "Task"])
           ;; Tags extending #task
           (and [?b :block/tags ?child]
                [?child :logseq.property.class/extends ?parent]
                [?parent :block/title "Task"]))
         [?b :logseq.property/status ?s]
         [?s :block/title "Todo"]
         [?b :logseq.property/priority ?p]]}

This pattern is essential for plugins that work with tag hierarchies and need to query derived relationships.

What's New in v2.0.0

Major Restructuring: Modular Documentation 📚

Breaking Change: SKILL.md is now lean (~420 lines) with detailed content in modular reference files.

Why This Matters:

• Performance: Only loads what's needed (SKILL.md loads on trigger, references load as needed)
• Maintainability: Each file has clear scope, easier to update specific topics
• Context Efficiency: Claude only loads relevant documentation for current task

New Structure:

logseq-db-plugin-api-skill/
├── SKILL.md                          # Lean entry point (~420 lines)
└── references/                       # Modular detailed docs
    ├── core-apis.md                  # Essential API methods
    ├── event-handling.md             # DB.onChanged patterns
    ├── plugin-architecture.md        # Best practices
    ├── property-management.md        # Property iteration patterns
    ├── queries-and-database.md       # Datalog query patterns
    ├── tag-detection.md              # Multi-layered detection
    └── pitfalls-and-solutions.md     # Common errors & fixes

How to Use:

• SKILL.md provides overview and quick start
• Each reference file covers specific functionality in detail
• Claude automatically loads reference files as needed
• Search patterns provided for finding specific topics

Benefits:

• ✅ 87% reduction in SKILL.md size (3200+ lines → 420 lines)
• ✅ Faster skill loading - core guidance available immediately
• ✅ Better organization - find what you need quickly
• ✅ Easier maintenance - update one file without affecting others
• ✅ Context-aware loading - only load what's relevant

Content Preserved from v1.8.0

All content from v1.8.0 has been preserved and reorganized:

Previous Updates

v1.8.0 - Event Handling & Architecture Patterns

Production Patterns from Real Plugins 🎯

This update adds practical, battle-tested patterns discovered while building the logseq-checklist plugin (v1.0.0). All examples are production-validated code from a working plugin.

New Sections Added ✨

1. Event-Driven Updates with DB.onChanged:

• Complete event structure and datom filtering
• Debouncing strategies (300ms pattern with Set-based deduplication)
• Real-world example: automatic checkbox change detection
• Performance optimization for UI responsiveness

2. Multi-Layered Tag Detection:

• Three-tier detection approach for reliability
• Content check → datascript query → properties fallback
• Handles block.properties.tags unreliability
• 80% fast path, 100% reliable fallback

3. Property Value Iteration:

• Reading property values from block objects via namespaced keys
• Iteration patterns for unknown property names
• Type-based property detection (boolean, number, string)
• Direct key access vs iteration performance trade-offs

4. Plugin Architecture Best Practices:

• File organization patterns (index.ts, events.ts, logic.ts, settings.ts, types.ts)
• Settings registration with Logseq's schema system
• Production-ready error handling and graceful degradation
• Complete mini-plugin example (~350 lines)
• TypeScript and Vite configuration
• Testing strategy and deployment checklist

Real-World Case Study 📚

logseq-checklist plugin referenced throughout as working example:

• GitHub: https://github.com/kerim/logseq-checklist
• Features: Automatic progress indicators for checklist blocks
• Architecture: Clean separation of concerns, zero configuration
• Lines of code: ~350 (maintainable, production-quality)

Key Patterns Documented

✅ Debouncing updates: 300ms delay with Set-based deduplication
✅ Multi-strategy tag detection: Fast path + reliable fallback
✅ Property iteration: Finding values without knowing exact names
✅ Error handling: Try/catch with user-friendly messages
✅ Settings system: Type-safe configuration with defaults

What's Changed

• ~1,200 lines of new content - Practical patterns and complete examples
• All code production-tested - From logseq-checklist v1.0.0
• Performance metrics included - Real-world optimization strategies
• Architecture guidance - How to structure maintainable plugins

See CHANGELOG.md for complete v1.8.0 details.

Previous Updates

v1.7.0 - API Corrections & New Methods

Critical Fixes:

• Method name corrections: addBlockTag() and removeBlockTag() (not addTag()/removeTag())
• Complete upsertProperty signature with cardinality, hide, public options

New APIs: Icon management (setBlockIcon, removeBlockIcon), tag inheritance (addTagExtends, removeTagExtends), utility methods (getAllTags, getAllProperties, etc.)

Type Definitions: Complete BlockEntity, PageEntity, IDatom interfaces

v1.6.0 - Property Value Formats (100% SOLVED)

v1.4.0 - Property Type Definition API

New: Project Setup & Bundling Section 🚀

• Complete Vite bundling guide: Proper setup for fast plugin loading
• vite-plugin-logseq: Essential bundler configuration
• Development workflow: Watch mode, hot reloading, production builds
• Common bundling issues: Solutions for slow loading, build errors
• Performance optimization: Minification, tree-shaking, single file output

Why this matters: Without proper bundling, plugins load slowly and provide poor user experience. This update ensures you set up Vite correctly from the start.

Previous Updates (v1.1.0)

Confirmed Working APIs ✅

• Tag Schema Definition: Documented working parent.logseq.api.add_tag_property() API
• Property Initialization: Proven temp page pattern for creating properties before schema definition
• Entity References: Complete explanation of how properties are stored as database entities
• Property Dereferencing: Datalog query patterns for reading actual property values

New Documentation

• Working POC: Reference to logseq-tag-schema-poc
• Property Namespacing: How plugin properties are auto-namespaced
• Common Pitfall #7: Property value dereferencing issues and solutions
• SDK Requirements: Updated minimum version to 0.3.0+ for DB graphs

See CHANGELOG.md for complete details.

What's Different in DB Graphs?

Logseq DB graphs use a fundamentally different data model than markdown-based graphs:

Aspect	Markdown Graphs	DB Graphs
Data Storage	Files (.md)	Database (SQLite)
Properties	YAML frontmatter	Typed database entities
Tags	Simple text markers	Classes with schemas
Pages	Unique by name	Unique by name + tag
Queries