Searching

The search bar at the top of the page accepts the same query language as tessera find on the command line.

genre/rock and year>=2020
(jazz or blues) and not live
type:image and landscape
artist=Kraftwerk

Press Enter to run the search. Results replace the current directory listing. The composer supports a block editor and a raw-text editor for the same query; switching editors does not change its meaning.

A standalone search term such as horse performs a broad discovery search across all available information:

  • tags, subjects, and AI-generated tags;
  • filenames and directory names;
  • indexed document content;
  • indexed image and video content.

Document, image, and video content is found through semantic embeddings. Configure and index embeddings under Settings → Embeddings to enable those matches. Filename and tag matches continue to work when embeddings are not configured.

Use explicit query syntax when you want precise filtering, for example type:image and horse. Use name: for a file-path match, dirname: to return matching directories themselves, or use ~ for semantic ranking.

The query composer below the toolbar keeps directory scopes separate from query criteria. Selecting a tag, subject, or person adds it to the current expression without replacing manually typed terms. Directory scopes can be switched between direct children and all subfolders without modifying the query text.

Click an and or or block in the composer to switch that operator. Criteria can also be grouped, negated, reordered, or removed without rebuilding the whole expression. Clear criteria preserves directory scopes; Clear all removes both.

For the full query language reference, see Query syntax.

Prefix your query with ~ to switch to semantic search — a vector similarity search using embedding models rather than tag matching.

~ a red sports car at sunset
~ jazz piano solo
~ aerial landscape photography

Semantic search requires embedding models to be configured and files to be indexed. See Semantic search for setup instructions.

Click Clear criteria, or press Escape outside an editor, to clear query criteria and return to the active directory listing. Escape does not remove the directory scope chip. Use the chip's remove button or Clear all when you also want to leave that scope.

Filesystem index and fallback

Filename discovery uses a disk-backed FTS index under each Tessera database. It is rebuilt and reconciled in the background, so untagged files participate without keeping every path in process memory. While an index is not ready, scoped searches fall back to a bounded live walk. Full walks run serially and do not follow directory symlinks, avoiding duplicate traversal through overlapping or cyclic trees.

dirname: always uses a bounded live directory walk because the filename index contains files, not directory objects.

Scope

Clicking a directory makes it the sole direct scope. Cmd/Ctrl-click or Shift-click adds scopes; scopes may come from different roots. Multiple scopes are ORed together, then ANDed with the query criteria. Each chip can search only direct children or include every subfolder.

Without a directory scope, searches use the roots selected by the current web context. Linked child and ancestor databases participate unless the server was started with --no-parents.