// OPENBOX DOCS

Search syntax

The full grammar of the library search box.

The library search box supports field-targeted terms, quoted values, and negative terms. Terms are combined with implicit AND; a space-separated list narrows the results.

Interactive Search & Acronym Playground

Test initials matching, capability rules, field tokens, and negative filters

Live Filter Engine
Try query:
Matches 1 of 8 sample games Acronym matching active

The Legend of Zelda: Ocarina of Time

Nintendo 64
Nintendo·Action-Adventure·1998
#classic#favorite#3d

Field terms

Prefix a term with a field name and a colon to target one field:

FieldMatches
title:Name, sort title, and alternate names
platform: (alias plat:)Platform value (quote multi-word values: platform:"PlayStation 2")
dev: (alias developer:)Developer
pub: (alias publisher:)Publisher
series:Series
genre:Genre
region:Region
notes:Notes
source: (aliases store:, storefront:)Import source (Steam, Heroic, Lutris, ...)
progress:Progress status
status:Status
play: (alias playmode:)Play mode
rating:Rating
favorite: (alias fav:)favorite:yes / favorite:no
installed:installed:yes / installed:no
hidden: (alias hide:)hidden:yes / hidden:no
broken:broken:yes / broken:no
portable:portable:yes / portable:no
controller:Controller support
tag: (alias tags:)Tag (see below)
import_batch_id: (alias import_batch:)Import batch id, matched exactly rather than as a substring
all:Every field at once: name, sort title, alternate names, platform, genre, developer, publisher, series, region, notes, source, play mode, status, progress, controller support, and tags

Your own ratings (v1.14.0)

Every game carries a personal star rating (user_rating, 0–5, where 0 is unrated) that is separate from the provider's rating. These clauses read your rating, not the metadata one — they are distinct clause kinds, not aliases of rating::

FormAliasMatches
myrating:4my_rating:4, my-rating:4Games you rated 4 or higher (a floor, so myrating:4+ is the same)
my 4 starsmy rating at least 4The same floor, in words
unrated by menot rated by meGames with no rating from you

rating:4 and myrating:4 answer different questions and both are supported side by side. unrated on its own is the provider rating; unrated by me is yours. See Backlog for where you set a personal rating.

Negative terms

Prefix any term with - to exclude it:

  • -tag:demo excludes games carrying a demo tag.
  • -platform:Windows excludes Windows games.
  • -title:hollow excludes games whose name contains "hollow".

Quoted values

Quote values that contain spaces or special characters:

  • platform:"PlayStation 2"
  • title:"The Legend of Zelda"

Bare terms

A bare term is matched against the title fields only: the game name, its sort title, and its alternate names. A token without a field prefix is treated as a title: term, so hollow finds Hollow Knight but does not look at platform, genre, developer, or any other field.

To search every field at once, use the all: key. all:<term> searches the name, sort title, alternate names, platform, genre, developer, publisher, series, region, notes, source, play mode, status, progress, controller support, and tags.

Acronym matching

Short terms (2 to 8 alphanumeric characters) match title acronyms and initials in the command palette and in all: queries:

  • oot matches The Legend of Zelda: Ocarina of Time
  • mgs matches Metal Gear Solid
  • sotn matches Castlevania: Symphony of the Night
  • ff matches Final Fantasy

This is not a bare-term behaviour of the sidebar search, where a bare term is a plain title match. Leading articles (The, A, An) are handled cleanly so searches match with or without the leading word.

Tags

  • tag:<name> filters to a single tag. Clicking a tag in the Tags dialog applies exactly this.
  • Tag search is case-insensitive; tags are stored canonicalized.

Examples

QueryResult
title:hollowGames with "hollow" in the name/sort title/alternates
platform:"PlayStation 2"PS2 games
genre:rpg -tag:demoRPGs that do not carry the demo tag
dev:team favorite:yesFavorited games by "team"
installed:noOwned-but-uninstalled titles

Natural-language grammar (Backlog Radio query bar)

The query bar above the field syntax also accepts short natural phrases, parsed deterministically by crates/openbox-discovery/src/query.rs and rendered as removable chips. Thresholds are named constants, surfaced in the chips:

PhraseMeaning
short / quickTime-to-beat at most 5.0h (SHORT_GAME_HOURS)
long / epicTime-to-beat at least 20.0h (LONG_GAME_HOURS)
highly ratedRating at least 4.0 (HIGH_RATING_MIN)
top rated / best ratedRating at least 4.5 (TOP_RATING_MIN)
retro / classicReleased 2000 or earlier (RETRO_YEAR_MAX)
recently played / newly addedWithin the last 31 days (RECENT_DAYS)

Typed keys (platform:PC, genre:rpg, source:, tag:, progress:, ESRB, region, series, player counts, ratings, time/idle phrases) combine with implicit AND. POST /api/v2/library/query/parse accepts query text up to 2,000 characters (crates/openbox-http/src/handlers/library.rs) and returns rules, clauses, chips, leftover unparsed words with a hint, and plain_query; input with nothing parsable stays a plain substring search. Clauses fail closed on missing metadata: ttb/year/played_within filters never match a game lacking the field (None → False), and idle/never-played semantics keep never-played games in the idle set (True) rather than guessing. See Backlog Radio.

The sidebar search box has a Title | Smart toggle (default Title, persisted). Title mode is the grammar above. Smart mode runs fully offline — no cloud, no downloads — using classical information retrieval: BM25 plus a curated 151-concept lexicon (English, with German, Spanish, French, and Portuguese overlays) hashed into 1024 dimensions, with a 250 ms debounce. Smart results carry why explanation chips showing which concepts matched. More like this is available in the details pane, the card context menu, and Big Box (gamepad-operable toggle feeding the hybrid search, with why-chips as subtitle lines). The atomic sidecar index lives at <APP_DIR>/dna_index.json and is excluded from cloud sync; library mutations invalidate it automatically, and it can be rebuilt on demand.

See also