DQL Overview

Basalt includes a built-in, native query engine for DQL (Dataview Query Language), compatible with Obsidian Dataview syntax. Instead of executing on the UI thread in JavaScript, Basalt processes queries in compiled Rust via crates/basalt-tables against memory-mapped vault indexes.

This delivers sub-5ms query times over vaults with 25,000+ notes without UI lag or frame drops.

Basic Usage

Embed a query anywhere in your Markdown by creating a fenced code block with the dataview or dql language tag:

```dataview
TABLE status, rating, file.mtime AS "Last Modified"
FROM #books AND "Reading"
WHERE rating >= 4
SORT rating DESC
LIMIT 10
```

Query Types

Basalt supports three primary query forms:

1. TABLE

Presents metadata in a structured grid with customizable columns and headers:

TABLE file.name AS "Note", author, status
FROM #project
WHERE status != "completed"

2. LIST

Produces an unordered Markdown bullet list, optionally displaying an evaluated expression next to each link:

LIST "Rating: " + rating
FROM #books
WHERE rating != null

3. TASK

Collects checklist tasks matching metadata conditions across notes:

TASK
FROM #work
WHERE !completed

Anatomy of a Query

DQL commands execute in written order (matching Dataview pipeline semantics):

TABLE file.name, due, priority      -- 1. Output projection
FROM #projects                      -- 2. Source filter (folder, tag, link)
WHERE priority = "high"             -- 3. Row-level filter
FLATTEN tags AS tag                 -- 4. Array expansion (optional)
GROUP BY tag                        -- 5. Aggregation (optional)
SORT due ASC                        -- 6. Ordering
LIMIT 20                            -- 7. Truncation

Available Fields

Note Frontmatter

Any key defined in a note's YAML frontmatter is accessible directly by name:

TABLE author, rating, category, summary

Note Metadata (file.*)

Each note automatically exposes a rich set of built-in file properties:

Field	Type	Description
file.name	string	The note's filename without extension (e.g. Meeting 2026-10)
file.path	string	Relative path from vault root (e.g. Work/Meetings/2026-10.md)
file.folder	string	Parent directory path (e.g. Work/Meetings)
file.size	number	File size in bytes
file.ctime	date	Creation timestamp
file.mtime	date	Last modified timestamp
file.tags	array	All tags occurring in the note (frontmatter + inline #tags)
file.outlinks	array	Links originating from this note
file.inlinks	array	Backlinks referencing this note
file.tasks	array	Tasks contained within this note

Boolean Expressions & Operators

Comparison Operators

=, !=, <, <=, >, >=

WHERE rating >= 8 AND status != "abandoned"

Logical Operators

AND, OR, NOT (or !)

WHERE (#work OR #freelance) AND !archived

Built-in Functions

• contains(haystack, needle) — Checks substring existence in text or item membership in lists:

  WHERE contains(file.tags, "#urgent")
  WHERE contains(file.name, "Sprint")

• length(value) — Returns list size, text character count, or number value:

  WHERE length(file.outlinks) > 5

Next Steps

• Perform grouping and calculations with Aggregation (GROUP BY & FLATTEN)
• Learn how queries achieve sub-5ms speed in Execution & Performance
• Complete syntax specification in DQL Syntax Reference