Logseq DB Knowledge Base

Overview

This skill provides comprehensive knowledge about Logseq DB (database) graphs, which use a fundamentally different data model from the older file-based (markdown) version of Logseq.

CRITICAL: When the user is working with Logseq DB graphs, the traditional file-based Logseq knowledge does NOT apply. Always reference this skill to ensure accuracy.

Keywords: logseq database, logseq db, db graphs, nodes, new tags, supertags, classes, tag properties, logseq properties, datalog queries

Core Concepts

Nodes - The Foundation

In Logseq DB, nodes are the fundamental building block. Both pages and blocks are now called "nodes" because they behave similarly.

Key Node Behaviors:

• Nodes are referenced using [[]] syntax (same as before)
• All nodes can have properties, tags, and references
• Blocks can be converted to pages by tagging with #Page
• Nodes are collapsible with an arrow on the left (appears on hover)
• Nodes can be favorited, embedded, and have linked/unlinked references
• Nodes share the same keybindings for properties and editing

Pages vs Blocks:

• Pages: Have unique names by tag (e.g., Apple #Company and Apple #Fruit can coexist)
• Blocks: Created within pages; tagged blocks don't require unique names
• Conversion: Top-level blocks can become pages by adding #Page tag

Example:

Aug 29th, 2025
  My meeting notes #Page

This converts the block "My meeting notes" into a namespaced page under "Aug 29th, 2025"

New Tags (Classes/Types/Supertags)

CRITICAL DISTINCTION: In Logseq DB, "new tags" are NOT the same as file-based tags!

New tags (also called classes, types, or supertags) are created with #NAME syntax and serve as templates for nodes.

Creating New Tags:

1. Open Search and type #Person
2. A dialog appears to configure tag properties
3. Add properties like "lastName" and "birthday"
4. Now any node tagged with #Person inherits these properties

Tag Features:

• Tags can have parent tags via the Extends property
• Tags inherit properties from all parent tags
• Tags can have their own properties on the tag page
• Tag properties automatically appear on all tagged nodes

Parent Tag Example:

#Book (has property: author)
  └─ #AudioBook (has property: narrator)
     └─ Inherits: author, narrator

#MediaObject (has property: duration)
  └─ #AudioBook
     └─ Inherits: author, narrator, duration

Properties System

Properties in Logseq DB are powerful and type-safe.

Property Types:

1. Text: Default type, allows any text, behaves like a block
2. Number: Actual numbers (not strings), sorts correctly
3. Date: Date picker, links to journal pages, supports repetition
4. DateTime: Date + time picker, supports repetition
5. Checkbox: Boolean values (checked/unchecked)
6. Url: Only allows valid URLs
7. Node: Links to other nodes, can be restricted by tag

Key Property Features:

• Default Values: Properties can have defaults
• Multiple Values: Properties can hold multiple values (except checkbox/datetime)
• Property Choices: Limit property to specific choices (like enums)
• UI Position: Control where property displays (inline, below, beginning, end)
• Hide by Default: Hide properties unless zoomed in
• Tag Properties: Properties inherited by all nodes with that tag

Property Shortcuts:

• Cmd-p (or Ctrl-Alt-p): Add property to current node
• Cmd-j: Quick edit properties
• p a: Toggle display all properties
• p t: Add/remove tags
• p i: Set icon
• p s: Set Status (tasks)
• p p: Set Priority (tasks)
• p d: Set Deadline (tasks)

Configuring Properties:

• Click property name for dropdown menu
• Cmd-click to navigate to property page
• Configure: type, default value, choices, UI position, multiple values, hide settings

Tasks in Logseq DB

CRITICAL: Tasks work completely differently in Logseq DB!

Old Way (File-based Logseq) - DOES NOT WORK IN DB:

- TODO This is a task
- DOING Working on this
- DONE Completed

New Way (Logseq DB):

Tasks are blocks tagged with #Task
Status is a PROPERTY with these values:
- Backlog
- Todo
- Doing
- In Review
- Done
- Canceled

Creating Tasks:

1. Type /todo in a block (adds Status property + #Task tag)
2. Type text and end with #Task
3. Add Deadline or Scheduled property
4. Use Cmd-Enter to cycle through Todo → Doing → Done

Task Properties:

• Status: Property with choices (not a marker!)
• Priority: A, B, C priorities
• Deadline: Date property
• Scheduled: Date property

Querying Tasks:

❌ WRONG (File-based approach):

[:find (pull ?b [*])
 :where [?b :block/marker "DOING"]]

✅ CORRECT (DB approach):

{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :block/title "Task"]
         [?b :logseq.property/status ?s]
         [?s :block/title "Doing"]]}

Customizing Tasks:

1. Customize Status property choices on the Status page
2. Add custom properties to #Task tag
3. Create custom task types by extending #Task:
   • Example: #ProjectTask extends #Task + adds "project" property

Repeated Tasks

Repeated tasks work with Deadline or Scheduled properties:

1. Set Deadline/Scheduled on a task
2. In the popup, check "Repeat task"
3. Configure interval (Day, Week, Month, Year)
4. When Status changes to Done:
   • Status resets to Todo
   • Deadline/Scheduled advances by the interval

Tag-Based Features

Logseq DB uses new tags to power core features. Each has a built-in table for management.

Built-in Tags:

• #Journal: Daily journal pages
• #Task: Task management (see above)
• #Query: Simple and advanced queries
• #Card: Flashcards using spaced repetition
• #Asset: Files (images, PDFs, etc.)
• #Template: Reusable block templates
• #Code: Code blocks
• #Quote: Quote blocks
• #Math: LaTeX math blocks
• #PDF Annotation: PDF highlights and annotations

All these tags can be extended by adding custom properties on their tag pages!

Journals (#Journal)

• Automatically created for current day
• Reference with natural language: [[Today]], [[Next Friday]], [[Last Monday]]
• Use /Date picker command for specific dates
• Navigate: g n (next day), g p (previous day)

Queries (#Query)

• Create with /Query command (query builder)
• Advanced queries: /Advanced Query command
• All queries tagged with #Query
• View all queries on #Query page table

Cards (#Card)

• Tag blocks with #Card to create flashcards
• Uses new spaced repetition algorithm
• Review in "Flashcards" section (left sidebar)
• 4 rating levels for scheduling
• Due property shows next review date

Assets (#Asset)

• Drag and drop files onto blocks
• Batch upload from #Asset page
• Stored in graph's assets/ directory
• Gallery View available for visual assets

Templates (#Template)

• Create: Tag a block with #Template, add children
• Insert: Use /Template command
• Auto-apply: Use Apply template to tags property to auto-insert on tagged nodes
  • Example: Apply template to #Journal → appears on every journal page

Querying Logseq DB

Common DB Attributes

IMPORTANT: These are DB-specific attributes, different from file-based Logseq!

Node Attributes:

• :block/title - Node title (pages and named blocks)
• :block/content - Block text content
• :block/properties - Node properties (different structure than file-based)
• :block/tags - New tags assigned to node
• :block/refs - References to other nodes
• :block/uuid - Unique identifier
• :block/created-at - Creation timestamp
• :block/updated-at - Last update timestamp
• :db/id - Database entity ID
• :db/ident - Database identifier (e.g., :logseq.class/Task)

Property Attributes:

• :logseq.property/status - Status property
• :logseq.property/priority - Priority property
• :logseq.property/deadline - Deadline property
• Custom properties: :logseq.property/YOUR-PROPERTY-NAME

Tag Attributes:

• :logseq.class/Task - Task tag (built-in)
• :logseq.class/Journal - Journal tag (built-in)
• :logseq.class/Query - Query tag (built-in)
• :logseq.class/Card - Card tag (built-in)

Tag Matching: Built-in vs Custom Tags

CRITICAL: This is the most common source of query errors!

There are TWO ways to match tags in queries, and choosing the wrong one will cause your query to fail:

Method 1: Using :db/ident (Built-in tags ONLY)

[?b :block/tags ?t]
[?t :db/ident :logseq.class/Task]

Only works for built-in Logseq tags:

• :logseq.class/Task
• :logseq.class/Journal
• :logseq.class/Query
• :logseq.class/Card
• :logseq.class/Asset
• :logseq.class/Template
• :logseq.class/Page

Method 2: Using :block/title (UNIVERSAL - works for ALL tags)

[?b :block/tags ?t]
[?t :block/title "Task"]

Works for both built-in AND custom user-created tags:

• Built-in: "Task", "Journal", "Query", "Card", etc.
• Custom: "zotero", "Person", "Project", "Meeting", etc.

Best Practice: Use :block/title by default

RECOMMENDATION: Always use :block/title unless you have a specific reason to use :db/ident.

Why?

• ✅ Works universally for all tags (built-in and custom)
• ✅ More intuitive (matches the visible tag name)
• ✅ Easier to remember
• ✅ Prevents common query errors

Example: Mixing Built-in and Custom Tags

{:query [:find (pull ?b [*])
         :where
         ;; Find tasks (built-in tag)
         [?b :block/tags ?task-tag]
         [?task-tag :block/title "Task"]
         [?b :logseq.property/status ?status]
         [?status :block/title "Done"]

         ;; That reference pages with custom tag
         [?b :block/refs ?ref]
         [?ref :block/tags ?custom-tag]
         [?custom-tag :block/title "zotero"]]}

This query finds all Done tasks that reference pages tagged with #zotero.

Query Examples

CRITICAL: ALL queries in Logseq DB blocks MUST use this exact format:

Find all nodes with a specific tag:

{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :block/title "Task"]]}

Find tasks with specific status:

{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :block/title "Task"]
         [?b :logseq.property/status ?s]
         [?s :block/title "Doing"]]}

Find nodes by property value:

{:query [:find (pull ?b [*])
         :where
         [?b :logseq.property/author ?author]
         [?author :block/title "John Doe"]]}

Find all journals:

{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :block/title "Journal"]]}

Find nodes by text content:

{:query [:find (pull ?b [*])
         :where
         [?b :block/content ?content]
         [(clojure.string/includes? ?content "history")]]}

Query Syntax in Logseq DB

CRITICAL FORMAT RULE:

Every advanced query in Logseq DB MUST start with {:query and end with }.

Correct format:

{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :block/title "Task"]
         [?b :logseq.property/status ?s]
         [?s :block/title "Doing"]]}

Common mistakes - DON'T DO THESE:

; ❌ WRONG - Extra {{query}} wrapper (this is old syntax)
{{query
{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]]}
}}

; ❌ WRONG - Missing {:query ...} wrapper entirely
[:find (pull ?b [*])
 :where
 [?b :block/tags ?t]
 [?t :block/title "Task"]]

; ❌ WRONG - Using :db/ident for custom user tags
{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :db/ident :logseq.class/zotero]]}  ; zotero is a custom tag!

; ✅ CORRECT - Use :block/title for custom tags
{:query [:find (pull ?b [*])
         :where
         [?b :block/tags ?t]
         [?t :block/title "zotero"]]}

Example: Find blocks referencing "Alice":

{:query [:find (pull ?b [*])
         :where
         [?person :block/title "Alice"]
         [?b :block/refs ?person]]}

Query Builder (Recommended)

Instead of writing raw queries, use Logseq DB's Query Builder:

1. Type /Query command in a block
2. Use the visual interface to build queries
3. Select tag (e.g., #Task)
4. Add property filters (e.g., Status = "Doing")
5. Logseq generates the correct query syntax automatically

See references/query-examples.md for more examples.

Views and Tables

Logseq DB provides powerful table views for managing tagged nodes.

Table Features:

• Built-in tables on all tag pages
• Sortable columns (by any property)
• Filterable rows
• Create new nodes directly in table
• Bulk actions on selected rows
• Multiple view types: Table, Gallery (for assets)

Accessing Tables:

1. Navigate to any tag page (e.g., #Task, #Journal)
2. See "Tagged Nodes" section with table
3. Click + to create new tagged node
4. Select multiple rows for bulk actions

Common Misconceptions

When working with Logseq DB, avoid these file-based assumptions:

❌ WRONG: Tasks use TODO/DOING/DONE markers ✅ CORRECT: Tasks use #Task tag + Status property

❌ WRONG: Query tasks with :block/marker ✅ CORRECT: Query tasks with tag matching and :logseq.property/status

❌ WRONG: Use :db/ident for custom user tags ✅ CORRECT: Use :block/title for all tags (works for both built-in and custom)

❌ WRONG: Tags are just hashtags for organization ✅ CORRECT: New tags are classes that define properties and behavior

❌ WRONG: Properties are frontmatter in markdown files ✅ CORRECT: Properties are structured, typed data in the database

❌ WRONG: Pages and blocks are fundamentally different ✅ CORRECT: Pages and blocks are both nodes with similar behavior

❌ WRONG: Can't have duplicate page names ✅ CORRECT: Pages are unique by tag: Apple #Company ≠ Apple #Fruit

Best Practices

1. Use New Tags for Structure

Create tags for your domain (e.g., #Person, #Project, #Meeting) and define their properties once. All tagged nodes inherit the structure.

2. Leverage Property Types

Use the right property type:

• Number for quantities (sorts correctly)
• Date for dates (links to journals, enables repetition)
• Node for relationships (type-safe references)

3. Extend Built-in Tags

Add custom properties to #Task, #Journal, etc. to customize for your workflow.

4. Use Templates for Automation

Set templates to auto-apply to tags for consistent structure.

5. Query by Tag First

Always start queries by filtering to a tag, then add property filters:

[?b :block/tags ?t]
[?t :block/title "YourTagName"]

Use :block/title for universal compatibility with both built-in and custom tags.

6. Use Tables for Bulk Management

Navigate to tag pages and use tables for sorting, filtering, and bulk operations.

Migration from File-based Logseq

If converting from file-based Logseq:

1. Tasks: Use DB Graph Importer in Logseq to convert TODO markers to #Task tags
2. Tags: File-based #tags become inline tags; evaluate if they should be new tags
3. Properties: Markdown frontmatter converts to database properties
4. Queries: Rewrite queries using DB attributes (see query examples)

Important: Test the importer on a copy of your graph first!

Additional Resources

For comprehensive information, refer to:

• references/data-model.md - Detailed DB schema and data model
• references/query-examples.md - Complete query cookbook
• references/db-vs-file.md - Side-by-side comparison guide
• Official docs: https://docs.logseq.com (DB graph sections)

When to Use This Skill

Invoke this skill whenever:

• User mentions Logseq DB or database graphs
• Working with Logseq queries and results don't match expectations
• User asks about tasks, properties, or tags in Logseq
• Debugging Logseq CLI or API queries
• Converting from file-based to DB graphs
• Creating custom workflows with new tags

Proactive Use: If you notice file-based Logseq assumptions in your responses, automatically reference this skill to correct them.