org-ql
Stability: stable (org-extensions-stability)
Modelled on the Emacs package org-ql: a query language for Org entries, search views and a dynamic block. Enable it with:
extensions = {
ql = {
files = "agenda", -- or "buffer", "all", a list of globs
default_predicate = "rifle", -- predicate of bare words
sort = nil, -- default sort of searches
views = { -- for :Org ql_view
["Work"] = { query = "todo: tags:work", sort = { "priority", "date" } },
},
views_file = vim.fn.stdpath("data") .. "/org/ql-views.json",
save_view_key = "<C-x><C-s>", -- in search buffers
include_hidden = false, -- true: also COMMENT/ARCHIVE subtrees
expand_repeaters = true, -- repeats count in date ranges
cache = true, -- remember results until files change
},
}
Queries
A query is a sexp, as in Emacs, or the plain ("non-sexp") syntax:
(and (todo "NEXT" "WAITING") (tags "work") (not (done)))
todo:NEXT,WAITING tags:work !done
In plain queries, space-separated terms are ANDed, ! negates a term, commas separate arguments (ORed), key=value is a keyword argument (ts:from=-7,to=today), "quoted text" keeps spaces and a bare word is (rifle word). A word: that is no predicate name (http://..., 10:30) is a plain word too. In a sexp query a bare string is (regexp STRING). From Lua a query can also be a table: { "and", { "todo", "NEXT" }, { "pred", function(hl) ... end } }.
Predicates (aliases in brackets):
and or not | combine queries |
todo [KW...] | a not-done TODO; with keywords, any of them |
done | a done keyword |
tags [TAG...] | any of the tags, inherited or local |
tags-all [tags&] | all of the tags |
tags-local [ltags] | own tags only |
tags-inherited [itags] | inherited tags only |
tags-regexp [tags*] | a tag matches a regexp |
priority [CMP] [P...] | (priority "A"), (priority '>= "B") |
deadline scheduled | planning dates; a single number N is :to N, (deadline auto) uses the warning period |
closed | closed; a single number N means the last N days (:from -N) |
planning | any of the three; a number is :to |
ts ts-active [ts-a] ts-inactive [ts-i] | timestamps in the entry, of either kind, active or inactive; a number is :to |
clocked | finished clocks (a running clock is ignored); a number N is the last N days |
property KEY [VAL] | :inherit t to inherit the property |
heading [h] | every string is in the heading |
heading-regexp [h*] | every regexp matches the heading |
regexp [r] | every regexp matches the entry |
rifle [smart] | every string is in the entry or its path |
level [CMP] N [N] | (level 2), (level 2 4), (level '> 1) |
effort [CMP] D [D] | like level, with durations ("1:30") |
category [CAT...] | the entry's category is one of them |
path [RE...] | matches the file name |
habit blocked | habits; TODOs that cannot be done yet |
outline-path [olp] | every string is in some path segment |
outline-path-segment [olps] | strings match consecutive segments |
parent ancestors children descendants [QUERY] | the relative exists (and matches QUERY) |
src :lang L :regexps (RE) | a source block |
link [TEXT] :description :target :regexp-p | the entry has a matching link |
pred FN | (Lua) FN(headline) is true |
Date arguments (:from, :to, :on) are a number of days from today, today, yesterday, tomorrow, now, or a date such as 2026-10-01 or 2026-10-01 14:00. :to without a time includes that whole day. :with-time t (or nil) keeps only timestamps with (without) a time. A repeating timestamp matches a range when one of its occurrences falls in it (expand_repeaters). Regexps are Emacs regexps and match case-insensitively, as do the strings of heading, rifle and outline-path (accented letters too). Priority comparisons and the priority sort follow the priority's value, so with numeric priorities (#+PRIORITIES: 1 20 10) (priority '> "10") matches [#9]. An impossible date (2026-02-30) is a query error. Results are cached per entry until its file changes (cache), except for queries with Lua functions or now.
Sorting
sort is one of date (the deadline, else the scheduled date), deadline, scheduled, closed, priority, todo (keyword order), random, reverse, a Lua comparator function(a, b) on headlines, or a list of those. As in org-ql, a list is applied in order, so the last one is the primary key: { "priority", "date" } sorts by date, then priority, and { "date", "reverse" } is newest first. Entries without the key go last.
Commands
:Org ql_search {query} | search files (prompts without a query) |
:Org ql_search_buffer {query} | search the current buffer |
:Org ql_view [name] | open a view of views (prompts for one) |
:Org ql_save_view [name] | save the search of the agenda buffer as a view (also save_view_key, <C-x><C-s>, in search buffers) |
:Org ql_find {query} | jump to a matching entry of the buffer (org-ql-find); ql_find_agenda searches the agenda files |
:Org ql_refile {query} | refile the subtree at the cursor under a matching entry (org-ql-refile) |
:Org ql_sparse_tree {query} | sparse tree of the matches in the buffer |
:Org ql_recent_items [N] [type] | entries with timestamps of type (ts, clocked, closed, ...) in the last N days, newest first (org-ql-view-recent-items) |
All of them are also actions, for mappings. Results open in the agenda buffer, so the agenda keys work on them. Saved views are kept in views_file and listed with the configured ones (which win on a name clash). A views_file that can't be read as JSON is left alone: saving a view then fails with an error instead of writing over it. The same view can be an agenda custom command:
agenda = { custom_commands = {
q = { type = "org-ql", query = "(and (todo) (scheduled :to today))",
sort = "date", description = "Due" },
} }
Dynamic block
#+BEGIN: org-ql :query "todo: tags:work" :columns (heading todo (priority "P") deadline) :sort priority :take 10
#+END:
C-c C-c on the block writes a table of the buffer's matching entries. :columns takes heading (a link), todo, priority, deadline, scheduled, closed and (property "NAME"), each optionally with a header: ((property "OWNER") "Who"). :take N keeps the first N results (the last N when negative), :ts-format formats dates (default "%Y-%m-%d") and :files searches other files.
Lua API
local ql = require("org.extensions.ql")
ql.select("agenda", "(todo)", { sort = "priority" }) -- headlines
ql.search("tags:work", { files = "buffer", title = "Work" })
ql.query.compile("(tags \"x\")") -- headline predicate
Differences from Emacs org-ql: COMMENT and ARCHIVE subtrees are skipped, as in the agenda, unless include_hidden is set; repeaters are expanded in date ranges (org-ql reads the timestamp only; expand_repeaters = false does the same); a timestamp range matches when it overlaps the period, where org-ql tests each end; (pred ...) needs a Lua function, as Lisp forms in queries are not evaluated; (level 2 4) means levels 2 to 4; the plain syntax also accepts comparators (priority:>=,B) and numbers (closed:7); there is no sidebar of views and no link to a search.