Search Syntax¶
This document describes the search query syntax supported by the entity search system.
Default Search¶
By default, the first search term searches across tags, filename, and display_name. Subsequent only terms search tags.
Examples:
bob
Searches for entities with tag "bob" OR filename/display_name containing "bob".
bob music
Searches for entities with tag "bob" AND (filename/display_name containing "bob") AND tag "music".
Search Variations¶
| Prefix | Behavior |
|---|---|
| (none) | First term: tags + filename/name/display_name. Subsequent terms: tags only |
~ |
Search path, filename, name, and display_name |
|
Search tags only (for first term) |
Examples:
~bob # Search path/filename/name/display_name for "bob"
bob # Search tags only for "bob" (space prefix)
bob # Search tags + filename/name/display_name for "bob"
Path/Filename/Name Search¶
Prefix your search with ~ (with or without a space after) to search for entities whose path, filename, name, or description contains the term:
~term
~ term
This adds @path:like:%description%, @path:like:%term%, @filename:like:%term%, @name:like:%term%, and @display_name:like:%term% to your search, all OR'ed together.
Examples:
~AC
~AC & Music
The first example returns entities whose path, filename, name, or display_name contains "AC", which might include "AC Invoice" The second example restricts to those with the tag "Music".
Returns entities whose path, filename, name, or display_name contains "invoice".
Basic Tag Searches¶
Search for entities that have a specific tag:
tagname
Example:
moo
This returns all entities that have the tag "moo".
Tags with Spaces¶
To search for a tag containing spaces, simply type the tag name with spaces - no quotes needed:
rock music
This matches entities with the tag "rock music" (exact match).
The query parser treats the entire string as a single term when it doesn't match known operators.
Category Separator¶
Categories must start with /:
/genre/rock
This matches tags in the "/genre" category with "rock" as the value.
Logical Operators¶
OR¶
Use | or OR to check for either conditions:
tag1 | tag2
AND¶
Use & or AND to combine conditions (both must match):
tag1 & tag2
Example:
punk & rock
Returns entities that have both "punk" AND "rock" tags.
NOT¶
Use - or NOT to exclude entities with a tag:
tag1 & -tag2
Example:
moo & -muu
Returns entities that have "moo" but NOT "muu".
You can also use parentheses with NOT:
moo & -(muu)
Attribute Searches¶
Use @ to search by entity attributes.
General Attributes¶
Search by any attribute with comparison operators:
@attribute:operator:value
Operators:
- : - equals
- <: - less than
- >: - greater than
- <=: - less than or equal
- >=: - greater than or equal
- like: - SQL LIKE pattern matching
Examples:
@rating:>=:5
@artist:like:%Brit%
Special Attributes¶
Some entity fields have special support:
path¶
Search by file path:
@path:like:%pattern%
@path:=:exactpath
Examples:
@path:like:%moo%
@path:=:/moo/bill
filename¶
Search by filename:
@filename:like:%pattern%
Example:
@filename:like:%ill%
Category Searches¶
Tags can be organized in hierarchical categories using / as a separator.
Direct Children¶
Search for entities with tags that are direct children of a category:
/category/tag
Example:
/x/y
Returns entities with tag "/x/y" (direct child of "/x").
Any Children (Single Level)¶
Use * to match any direct children of a category:
/category/*
Example:
/x/*
Returns entities with any tag directly under "/x" (e.g., "/x/y", "/x/z").
All Children (Any Depth)¶
Use ** to match all descendants at any depth:
/category/**
Example:
/x/**
Returns entities with any tag that starts with "/x/" at any depth.
Category Only¶
Search for the category itself:
/category
Returns entities with the exact tag "/x".
Combining Searches¶
You can combine multiple search types:
tag1 & @attribute:operator:value & /category/**
Example:
moo & @age:<=:19 & /x/**
This returns entities that: - Have the "moo" tag - Have an "age" attribute <= 19 - Have any tag under the "/x" category