Querying

Many plugins use a “query” to search for music in your library.

The query must be in the format field:value where field is, by default, a track’s field to match and value is the field’s value (case-insensitive). To match an album’s field or an extra’s field, prepend the field with a: or e: respectively. Internally, this field:value pair is referred to as a single “term”.

Note

Some fields such as a track’s audio_format cannot be queried and are noted as such in the field docs.

By default, tracks will be returned by the query, but you can choose to return albums by using the -a, --album option, or you can return extras using the -e, --extra option.

Normal Queries

If you would like to specify a value with whitespace or multiple words, enclose the term in quotes.

'title:Hip Hop Hooray'

Important

If specifying a query with spaces on the command-line, you’ll need two sets of quotes since the first set simply delineates the argument from others and doesn’t retain the spaces in the term. For example, if executing the above query using the ls command, you should write the following:

moe ls "'title:Hip Hop Hooray'"

For powershell users, it’s necessary to use " as the outer quotes.

Note

When querying for a field that supports multiple values, query for one term per value. For example, to query for tracks with the genres ‘hip hop’ and ‘pop’, use:

"'genre:hip hop' genre:pop"

Numeric Range Queries

Queries on numeric fields can specify a range of acceptable values by using two dots .. in the beginning, middle, or end of the value. Dots in the beginning let you specifiy a minimum e.g. 1.., dots and the end let you specify a maximum e.g. ..10, and dots in the middle let you specify a range e.g. 1..10.

For instance, the following will query for any albums released between 2010 and 2020:

"a:year:2010..2020"

Whereas this query will find any albums released prior to 2020:

"a:year:..2020"

And finally, this query will find any albums released after 2010:

"a:year:2010.."

Note

Query ranges are inclusive i.e. items matching the minimum or maximum value will also be included.

SQL Like Queries

SQL LIKE query syntax is used for normal queries, which means the _ and % characters have special meaning:

• % - The percent sign represents zero, one, or multiple characters.

• _ - The underscore represents a single character.

To match these special characters as normal, use / as an escape character.

'title:100/%'

Regular Expression Queries

The value can also be a regular expression. To enforce this, use two colons e.g. field::value.*

'title::[a-m].*'

As a shortcut to matching all entries, use * as the term.

'*'

Tip

Normal queries may be faster when compared to regular expression queries. If you are experiencing performance issues with regex queries, see if you can make an equivalent normal query using the % and _ wildcard characters.

Multiple Query Terms

You can also specify any number of terms. For example, to match all Wu-Tang Clan tracks that start with the letter ‘A’, use:

"'artist:wu-tang clan' title:a%"

Note

When using multiple terms, they are joined together using AND logic, meaning all terms must be true to return a match.

Tip

Fields of different types can be mixed and matched in a query string. For example, the query --extras 'album:The College Dropout' e:path:%jpg$ will return any extras with the ‘jpg’ file extension belonging to the album titled ‘The College Dropout’.