Task Queries Reference
Complete reference for Basalt's line-based task query language used inside ```tasks code blocks.
Filter Clauses
All query lines are processed in order and combined with logical AND by default unless explicitly combined with OR.
Status
not done # Matches todo, in_progress, on_hold
done # Matches done, cancelled
status is todo
status is in progress
status is on hold
status is done
status is cancelled
Dates
Date targets can be ISO format (YYYY-MM-DD) or relative terms (today, tomorrow, yesterday, this week, next week, this month).
Supported date fields: due, start, scheduled, created, done, cancelled, and happens (matches due, scheduled, or start).
due before tomorrow
due on 2026-10-15
due on or before today
due this week
no due date
due exists
happens before next week
scheduled on or after today
start before next month
Priority
Supported priority levels: highest, high, medium, none, low, lowest.
priority is highest
priority above medium # Matches highest, high
priority below high # Matches medium, none, low, lowest
no priority
Text, Tags, & Vault Scope
description includes "text"
description does not include "text"
tags include #urgent
tags do not include #archive
path includes Projects/
folder includes "Daily Notes"
filename includes "2026"
Recurrence & Dependencies
is recurring
is not recurring
is blocked # Has unresolved depends_on task
is not blocked
Boolean Expressions
Combine sub-filters using parentheses and uppercase operators:
(not done) AND (due before next week)
(priority is highest) OR (due today)
(tags include #work) AND NOT (folder includes "Archive")
Sorting Clauses
Syntax: sort by <field> [reverse]
| Field | Sort Order |
|---|---|
urgency | Numeric urgency score (descending by default) |
due | Earliest due date first |
priority | Highest priority first (Highest → Lowest) |
status | Open tasks before completed tasks |
description | Alphabetical |
path | Alphabetical by file path |
scheduled | Earliest scheduled date first |
start | Earliest start date first |
created | Creation timestamp |
line | Document order in note |
Example:
sort by priority
sort by due reverse
Grouping Clauses
Syntax: group by <field>
Creates visual collapsible sections in the rendered output.
| Field | Grouping Key |
|---|---|
status | Groups by task status name |
priority | Groups by priority level |
due | Groups by due date (Overdue, Today, Upcoming, Undated) |
scheduled | Groups by scheduled date |
folder | Groups by containing folder |
filename | Groups by parent note |
tags | Groups by task tags |
recurring | Groups by recurring vs one-off |
Output Control & Formatting
limit 25 # Return at most 25 tasks
short mode # Compact display without breadcrumbs
full mode # Expanded metadata display
hide priority # Suppress priority badge
hide due date # Suppress due date pill
hide backlink # Suppress note origin link
hide tags # Suppress tag badges