// 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
The Legend of Zelda: Ocarina of Time
Nintendo 64Field terms
Prefix a term with a field name and a colon to target one field:
| Field | Matches |
|---|---|
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::
| Form | Alias | Matches |
|---|---|---|
myrating:4 | my_rating:4, my-rating:4 | Games you rated 4 or higher (a floor, so myrating:4+ is the same) |
my 4 stars | my rating at least 4 | The same floor, in words |
unrated by me | not rated by me | Games 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:demoexcludes games carrying ademotag.-platform:Windowsexcludes Windows games.-title:hollowexcludes 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:
ootmatches The Legend of Zelda: Ocarina of Timemgsmatches Metal Gear Solidsotnmatches Castlevania: Symphony of the Nightffmatches 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
| Query | Result |
|---|---|
title:hollow | Games with "hollow" in the name/sort title/alternates |
platform:"PlayStation 2" | PS2 games |
genre:rpg -tag:demo | RPGs that do not carry the demo tag |
dev:team favorite:yes | Favorited games by "team" |
installed:no | Owned-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:
| Phrase | Meaning |
|---|---|
short / quick | Time-to-beat at most 5.0h (SHORT_GAME_HOURS) |
long / epic | Time-to-beat at least 20.0h (LONG_GAME_HOURS) |
highly rated | Rating at least 4.0 (HIGH_RATING_MIN) |
top rated / best rated | Rating at least 4.5 (TOP_RATING_MIN) |
retro / classic | Released 2000 or earlier (RETRO_YEAR_MAX) |
recently played / newly added | Within 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.
Game DNA smart search
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
- Library overview, browse and search in context
- Library organizing, saved filters, presets, and explorer facets