Query syntax

Tessera queries combine tags, file properties, paths, subjects, and optional semantic ranking in one boolean expression. The language is used by tessera find, tessera view, and the web query composer. Features that depend on the live filesystem are identified below.

Literals, quoting, and operators

Tag names are plain tokens. Quote values that contain spaces:

genre/rock
"Extra models"
artist="Kraftwerk live"

Precedence is not, then and, then or. Parentheses override it:

(genre/rock or genre/metal) and not live

Tags and values

A bare tag matches files carrying that tag. tag: makes the same intent explicit and is useful when a single bare word in the web UI would otherwise start broad discovery.

favourite
tag:favourite
genre/rock

Key/value tags support =, !=, <, <=, >, and >=:

year=2024
rating>=4
artist!=Unknown

Numeric-looking values compare numerically. Other values compare as strings. Property contracts may additionally validate types, units, ranges, cardinality, and controlled concepts; see Property contracts and concepts.

Use * to match tag namespaces:

genre/*

Names, paths, and directories

name: (aliases filename: and file:) matches the complete root-relative file path. A plain pattern is a case-insensitive substring; a pattern containing * or ? is a glob over the whole path.

name:invoice
name:"summer holiday"
name:photos/*.jpg

dir: restricts results to one concrete root-relative directory. Without a trailing slash it selects direct children; with a trailing slash it includes all descendants:

dir:Photos
dir:Photos/
dir:Photos/2026/

In the web UI, directory scope chips are kept separately from the text query. Multiple chips are ORed together; their combined scope is ANDed with all query criteria, including any dir: criterion. Scope chips carry a root ID, so they remain unambiguous across multiple or nested databases.

dirname: searches for directory objects by basename in the web interface. Like name:, it uses a case-insensitive substring unless * or ? is present:

dirname:holiday
dirname:"Old photos"
dirname:project-20??

The matching directories themselves appear in the results. An active directory scope limits where Tessera searches. dirname: is currently web-only because the CLI query universe consists of file records rather than live directory entries.

Regular-expression literals match root-relative file paths:

/IMG_\d{4}/

File types

Use type: to select a logical file category:

Aliases include img, photo, and pic for images; vid and movie for video; aud and music for audio; doc for documents; and arc for archives.

Subjects

subject: matches a subject and its descendants. Subject groups bind several conditions to the same subject assignment:

subject:person/alice
{species=bird and colour=blue}

Subject and concept synonyms are resolved within their own domains; a subject alias does not broaden an unrelated plain-tag query.

Intrinsic properties

Intrinsic file predicates compose with tags and other criteria. Available forms cover dimensions, aspect ratio, orientation, dominant colour, and GPS location. Common examples:

width>=1920 and height>=1080
ratio>=16:9
megapixels>=12
orientation=landscape
color:blue
gps
near:52.37:4.90:10

near: is latitude, longitude, then radius in kilometres.

Semantic ranking

~ ranks the candidates selected by the rest of the expression using an embedding:

~"sunset over the ocean"
~"jazz piano" and type:audio
~"invoice from 2023" and dir:Documents/

A semantic term may occur only on the positive and spine. It cannot be used under or, not, or inside a subject group because those placements do not define one coherent candidate ranking. See Semantic search for setup and indexing.

Combined examples

(genre/rock or genre/metal) and year>=2000 and not live
type:image and width>=3000 and color:blue
dirname:archive and dir:Projects/
~"technical drawing" and type:document and not status=obsolete