Skip to main content

Querying Tasks

Basalt provides native task query capabilities. Because all task signifiers are indexed into memory via the Rust backend, task queries run in sub-millisecond times across tens of thousands of notes without locking the UI.

You can query tasks using dedicated tasks code blocks or through the comprehensive DQL engine.

The tasks Code Block​

To embed a dynamic task view inside any note, create a fenced code block with the tasks language tag:

```tasks
not done
due before tomorrow
sort by urgency
```

Each line in the block represents a single query instruction. Instructions are processed in order and combined with logical AND.

Filtering Tasks​

Status Filters​

  • not done — Matches all open tasks (todo, in_progress, on_hold).
  • done — Matches completed tasks (done, cancelled).
  • status is in progress — Matches only in-progress tasks ([/]).
  • status is on hold — Matches paused tasks ([?]).
  • status is cancelled — Matches cancelled tasks ([-]).

Date Filters​

Filter tasks by date proximity using natural language or ISO dates:

  • due before tomorrow
  • due on or before 2026-10-15
  • due this week
  • no due date
  • due exists
  • happens before next week (checks due, scheduled, or start date)
  • scheduled today
  • start before next month

Priority Filters​

  • priority is highest
  • priority above medium (matches Highest and High)
  • priority below high (matches Medium, Low, Lowest, and None)
  • no priority

Text & Path Filters​

  • description includes "client meeting"
  • tags include #work
  • path includes Projects/
  • folder includes "Daily"
  • filename includes "2026"

Recurrence & Dependencies​

  • is recurring / is not recurring
  • is blocked (waiting on another task via ⛔)
  • is not blocked

Boolean Logic​

Group expressions with parentheses and logical operators:

(not done) AND (due before next week)
(priority is highest) OR (due today)

Sorting Tasks​

Use sort by <field> [reverse] to order your tasks. Multiple sort clauses are applied hierarchically in the order written.

Available sort fields:

  • urgency — Calculated composite urgency score (priority + due proximity + status)
  • due — Due date
  • priority — Priority rank
  • status — Checkbox status
  • description — Alphabetical by text
  • path — Note filepath
  • scheduled — Scheduled date
  • start — Start date
  • created — Creation date

Default Sort Order​

If you omit sort by, Basalt automatically applies an optimal default sort:

  1. status.type (open before completed)
  2. urgency (highest urgency first)
  3. due (earliest due dates first)
  4. priority
  5. path

Grouping Tasks​

Use group by <field> to split the query output into visual sections with collapsible headers:

not done
group by status
group by priority

Supported grouping fields: status, priority, due, scheduled, folder, filename, tags.

Display Options & Limits​

  • limit <n> — Restricts results to the first n tasks (e.g. limit 10).
  • short mode — Hides filename and backlink paths for a compact list.
  • hide priority / hide due date / hide recurrence — Hides specific signifiers from the rendered task item.

Common Recipes​

Today's Focus​

```tasks
not done
happens on or before today
sort by urgency
```

Overdue High-Priority Items​

```tasks
not done
due before today
priority above low
sort by due
```

Project Backlog​

```tasks
not done
path includes Projects/App
no due date
group by priority
sort by priority
```

Interactive Capabilities​

Tasks rendered within query blocks are fully interactive:

  • Clicking the checkbox toggles the task state in the underlying Markdown file on disk immediately.
  • Hovering shows full date metadata and backlinks.
  • Double-clicking or using the edit icon opens the Task Modal.