How to Use BFS Attributes and Live Queries Day to Day

BFS can store typed attributes with each file and maintain per-volume indexes over selected attributes. Tracker exposes those fields as columns and its Find window turns indexed predicates into live result windows. This is structured metadata attached to real files—not a tag database hidden inside one application—but it works reliably only when types, indexes, volumes, and backup behavior are understood.

Inspect existing attributes before inventing one

Open a folder in Tracker’s list view, then use the Attributes menu or right-click a column heading to show fields registered for that file type. Mail, People, and media files demonstrate the intended model: one file per item, with fields such as sender, company, artist, or title available as sortable columns.

In Terminal, inspect a file without changing it:

listattr example.txt
listattr -l example.txt

listattr names the attributes; -l also displays their contents. To read one field explicitly, use its real name:

catattr BEOS:TYPE example.txt

Attribute names and types are part of a workflow’s schema. Reusing one name sometimes as a string and elsewhere as an integer creates confusing query behavior. Prefix custom names with an application or organization namespace, document their type and allowed values, and avoid changing system-defined fields casually.

Create a small typed workflow

For a review queue, use a string field named MyApp:Status. Add it to a disposable BFS test file:

touch report.txt
addattr -t string MyApp:Status Reviewed report.txt
catattr MyApp:Status report.txt

The documented addattr syntax is addattr [-t type] attr value file...; quoting values with spaces is necessary. Supported types include string, MIME, integer, long integer, floating point, boolean, icon, and raw values. Choose the type the query should compare, not merely one that accepts the first sample.

Removing a value is distinct from assigning an empty string:

rmattr MyApp:Status report.txt

Practice on copies. Attributes can contain the only copy of useful metadata, and common archive, network, or non-BFS destinations may not preserve it.

Inspect indexes on the correct volume

An attribute can exist without being indexed. Tracker can display it, but Haiku’s fast query engine requires an index for attribute queries. Indexes belong to each BFS volume independently; creating one on the boot volume does nothing for files on another BFS data disk.

Change to a directory on the target volume and list its indexes:

cd /boot/home
lsindex
lsindex -l

The previous article’s listattr -r /boot pattern is not an index inventory: listattr examines file attributes, while lsindex examines the volume’s index definitions.

Create the string index while pointing at the intended volume:

mkindex -d /boot/home -t string MyApp:Status

Run lsindex -l again and verify the name and type. Do not create hundreds of speculative indexes; every maintained index has storage/write cost and unnecessary indexes complicate administration.

Reindex data that predates the index

The official index guide warns that creating an index does not automatically add all existing files carrying that attribute. New or subsequently changed files are maintained, but older data must be reindexed.

For a controlled test directory:

reindex -rv MyApp:Status /boot/home/review-test

Review reindex --help on the installed release before running it across a large hierarchy. Scope it to known files, preserve output, and verify results. Do not use the historical workaround of copying and deleting originals when the supplied reindex command exists.

Index type must match attribute type. If an existing workflow has mixed types under one name, inventory and normalize copies first rather than deleting/recreating a production index blindly.

Build the query in Tracker

Invoke Find… from Deskbar, Tracker, or Desktop; the documented shortcut is Alt+F. Choose the target volume(s), select the relevant file type when one is registered, switch the method to by attribute, and select MyApp:Status. Search for Reviewed.

If the custom field is absent from the attribute menu, confirm its index and file-type registration. The Find panel can expose additional available attributes, but a field merely existing on one file does not guarantee a useful typed query across every volume.

Add predicates incrementally. Tracker supports logical AND/OR combinations, and time fields accept useful relative expressions. Start with one condition known to match, then add type, status, and date constraints. This prevents an empty result from becoming an argument about which of five clauses failed.

Switching the finished search to by formula reveals the generated predicate. That is safer than guessing the formula grammar. The official guide shows that the formula, enclosed in single quotes, can be passed to the Terminal query command for scripting and diagnosis.

Understand what “live” actually means

Tracker query result windows are live: when a matching file appears, disappears, or its indexed attribute changes, the open result updates in real time. There is no separate “Live query” checkbox required by the current user guide.

A live result is not a background automation service and it is not a folder containing copies. Moving or deleting an item in the result acts on the underlying file. Closing the result window stops observing it. Opening a saved query runs its stored formula again and produces a current result.

Test this explicitly with two Tracker windows or Terminal:

Open the MyApp:Status == Reviewed result.
Add the value to a second file and watch it appear.
Change that value to Draft and watch it leave.
Restore Reviewed and verify it returns.
Move the file to a non-indexed or non-BFS volume and observe the boundary.

If updates fail, check the exact attribute name/type, selected volume, index, and whether the file operation preserved attributes before restarting Tracker.

Save queries and templates for different purposes

Use the Find window’s Query menu to save a query. The saved object contains the formula and scope, not a static list of paths. Haiku keeps recent queries under /boot/home/queries/ and the user guide notes a default seven-day retention; save durable workflow queries deliberately in a named folder you back up.

A query template opens the Find panel with reusable criteria so values can be adjusted before searching. A saved query immediately runs its fixed criteria. Use a template for “mail from [person] in [period]” and a saved query for a stable queue such as “status is Reviewed.”

Customize result columns by file type using Tracker’s documented DefaultQueryTemplates workflow. This controls presentation, not the query’s truth conditions.

Preserve attributes and validate backups

BFS is the native environment for arbitrary attributes and queries. Copying files to FAT, many cloud-sync systems, generic ZIP archives, or protocols that do not support Haiku attributes can retain bytes while discarding the workflow. Verify with listattr after a round trip.

Back up the files, their attributes, the saved query definitions, and a text description of custom index names/types. On restore, recreate the correct index on each target BFS volume and reindex restored legacy data as needed. A saved query without restored attributes/indexes is only a formula returning nothing.

Used this way, live queries replace repeated manual filing without concealing the underlying state: files remain ordinary files, attributes remain inspectable, indexes remain per-volume infrastructure, and every result can be explained by a typed predicate.

Related:

Sources: