Melodee Query Language (MQL)

MQL is a powerful query language for searching your music library. It allows you to search by specific fields, use comparisons, combine conditions with boolean logic, and more.

Quick Start

Access MQL search by clicking the Advanced button in the Search page. Select an entity type (Songs, Albums, or Artists) and enter your query.

Basic Examples

artist:"Pink Floyd" AND year:>=1970
genre:Jazz rating:>=4
title:/.*remix.*/i
starred:true lastPlayedAt:-30d

Syntax Overview

MQL queries consist of terms that can be combined with boolean operators.

Term Types

Boolean Operators

Combine terms using boolean logic:

• AND: Both conditions must match (default when omitted)
• OR: Either condition must match
• NOT: Exclude matching results
• ( ): Group conditions

Operator Precedence (highest to lowest):

1. Parentheses ( )
2. NOT
3. AND
4. OR

Examples

# All conditions must match (implicit AND)
artist:Beatles album:"Abbey Road"

# Explicit boolean logic
(rock OR metal) AND NOT live

# Complex grouping
(artist:Beatles OR artist:"Rolling Stones") AND year:1965-1970

Field Reference

Song Fields

Album Fields

Artist Fields

Operators

Comparison Operators

Range Operator

Use a hyphen for inclusive ranges:

year:1970-1980       # 1970 to 1980 inclusive
duration:180-300     # 3 to 5 minutes
rating:3-5           # Ratings 3, 4, or 5

Regex Operator

For advanced pattern matching (case-insensitive with i flag):

title:/.*remix.*/i           # Contains "remix" (any case)
artist:/^The .*/             # Starts with "The "
album:/.*\(live\)$/i         # Ends with "(live)"

Note: Regex queries are limited for performance. Use sparingly on large libraries.

Date Values

Absolute Dates

Use ISO format: YYYY-MM-DD

added:2024-01-01
lastPlayedAt:2024-06-15

Relative Dates

Named shortcuts:

• today - Current day
• yesterday - Previous day
• last-week - Past 7 days
• last-month - Past 30 days
• last-year - Past 365 days

Duration syntax:

• -7d - Past 7 days
• -3w - Past 3 weeks
• -12h - Past 12 hours
• -6m - Past 6 months

added:last-week          # Added in past 7 days
lastPlayedAt:-30d        # Played in past 30 days
starredAt:last-month     # Starred in past 30 days

Common Query Patterns

Finding Unplayed Music

# Songs never played
plays:0

# Albums added recently but not played
added:last-month plays:0

Finding Your Favorites

# Highly rated songs
rating:>=4

# Starred songs from a specific artist
starred:true artist:"Pink Floyd"

# Your top rated albums
rating:5

Discovery Queries

# Jazz you haven't heard in a while
genre:Jazz lastPlayedAt:<-90d

# Short songs (under 3 minutes) you might have missed
duration:<180 plays:0

# High BPM tracks for workout
bpm:>140 genre:(Electronic OR Dance)

By Era

# Classic rock from the 70s
year:1970-1979 genre:Rock

# Recent additions to your library
added:-7d

# Music from this millennium
year:>=2000

Complex Searches

# Pink Floyd or Roger Waters, but not compilations
(artist:"Pink Floyd" OR artist:"Roger Waters") NOT album:/.*greatest.*/i

# Jazz or Blues albums you've rated highly
(genre:Jazz OR genre:Blues) rating:>=4

# Long prog rock tracks
genre:"Progressive Rock" duration:>600

Tips and Best Practices

Quote Strings with Spaces

# Correct
artist:"Pink Floyd"
album:"The Dark Side of the Moon"

# Incorrect (will search for separate terms)
artist:Pink Floyd

Use Parentheses for Clarity

# Clear intent
(rock OR metal) AND year:>=2000

# Ambiguous (AND has higher precedence than OR)
rock OR metal AND year:>=2000

Combine with Simple Search

For quick searches, use the simple search box. Switch to MQL Advanced mode when you need:

• Field-specific searches
• Numeric comparisons
• Date ranges
• Boolean logic

Performance Tips

• Be specific with fields to narrow results faster
• Avoid regex on very large libraries
• Use date ranges instead of open-ended comparisons when possible

Error Messages

If your query has a syntax error, MQL will show:

• Error position: Where the problem occurred
• Suggestions: Possible fixes or similar field names
• Valid fields: List of fields available for the entity type

Common errors:

• Unknown field: Check spelling (e.g., artistt → artist)
• Invalid literal: Check value format (e.g., year:abc should be year:2024)
• Unbalanced parentheses: Ensure all ( have matching )
• Invalid date format: Use ISO dates or relative shortcuts

API Access

MQL is also available via the API:

Parse/Validate Query

POST /api/v1/query/parse
Content-Type: application/json

{
  "entity": "songs",
  "query": "artist:\"Pink Floyd\" AND year:>=1970"
}

Query Suggestions (Autocomplete)

POST /api/v1/query/suggest
Content-Type: application/json

{
  "entity": "songs",
  "query": "art",
  "cursorPosition": 3
}

For more details on the API, see the API Reference.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.