Filtering by frontmatter

Once a note carries a frontmatter block, its keys and values become something the search box can be asked about directly. status:draft finds notes where status is draft, not notes containing the words "status" and "draft".

This only works for keys your vault actually uses. A vault with no frontmatter behaves exactly as it always has: every word you type is a search term.

An aliases: key is filterable like any other, but it also does something extra: see Other names a note answers to.

Writing a filter

Type a key, a colon, and a value:

status:draft

To do this	Type
Match a value	status:draft
Match the start of a value	status:dra*
Match a value that's literally dra*	status:dra\*
Match either of two values	status:draft,review
Match a value with spaces in it	project:"Q3 planning"
Exclude a value	-status:done
Require the key, any value	has:due
Require the key to be absent	no:due
Compare numbers or dates	due:<2026-09-01

Values are matched without regard to case: status:Draft and status:draft find the same notes.

A key repeated ORs; different keys AND. status:draft status:review is either status. status:draft project:halcyon is both, together. -status:done -status:archived also ANDs, so it excludes both: a negated key repeated narrows further each time, rather than widening like a positive one does.

Excluding a value includes notes with no value at all. -status:done matches every note that isn't done, including notes that don't carry status at all.

A filter that matches nothing shows an empty list. It doesn't fall back to searching for the words you typed. If status:archived finds nothing, that's because nothing in this vault has that status, not because the filter failed.

Comparing numbers and dates

<, >, <= and >= work on a value that's a number or a date, in the usual sense:

due:<2026-09-01
priority:>=3

modified: and created: also take 7d, today and yesterday:

modified:7d

finds notes touched in the last week. These read the clock on your Mac at the moment you search, not a fixed date.

Type a value that isn't a number or a date after a comparator, like due:<soon, and the chip says so: it's marked as a mismatch and matches nothing, rather than guessing at an ordering that doesn't exist. Comparing against a key that holds words rather than numbers, like status:<3, also matches nothing: there's no number on those notes to compare, so they're excluded rather than guessed at.

The pseudo-fields

A handful of keys aren't frontmatter at all. They're always available, even in a vault with no frontmatter:

Key	Matches
in:	Notes inside a folder, same as clicking it in the sidebar
is:pinned	Pinned notes
title:	A word in the title
path:	A word anywhere in the file's path
modified:	When the note was last changed, see below
created:	When the note was made, see below
links:	Notes the one you name links to
backlinks:	Notes that link to the one you name

If a note in your vault happens to use one of these words as a frontmatter key too, the built-in meaning wins, and its chip says so: path (built-in): work.

Writing created: or updated: changes the sort order

This one isn't about the search box. A note whose frontmatter carries a created: or updated: date, written in its own block, sorts by that date everywhere Halcyon shows notes by recency: the default note list order, the [[ link completion list, and breaking a tie between two equally good search results. modified: and created: in the table above search against whichever date that turns out to be.

This is separate from the file's real modified time on disk, which Halcyon still uses to decide when to re-read a file and never to decide what you see. A note claiming updated: 2020-01-01 sorts as if it's from 2020 without Halcyon losing track of the fact that you edited it five minutes ago. A value that isn't a date is ignored, and the note falls back to its file's own timestamp.

Chips, and seeing what you typed

Every part of your search that turned into a filter gets a chip underneath the box, so you can tell which of your words became a query and which stayed words. Click the × on a chip to remove just that filter and leave the rest of your search text alone.

Completion

Start typing a key and a dropdown offers the ones your vault uses. Accept one and type a colon, and it switches to that key's values, with a count beside each so you can see how many notes you're about to match. A key added to a note a moment ago shows up the next time you type, with no need to reopen or rescan anything.