Plex Search¶

Use plex_search to select existing library items when Kometa runs. For Plex-maintained membership that updates as library data changes, use Smart Filters.

Query structure¶

Start with exactly one root all (AND) or any (OR). Place filters beneath it; sort_by, limit, validate, and type are query options outside that root. Nest all and any for complex rules. For repeated group names at the same level, use a YAML list of groups rather than duplicate dictionary keys.

Value type	Example	Meaning
String	`genre: Action`	Match a genre
Boolean	`hdr: true`	Require HDR
Number	`audience_rating.gte: 7.5`	Inclusive minimum rating
Date	`release.after: 01/01/2020`	Released after the date
Relative interval	`added.last: 30`	Added in the last 30 days

Select the item level

Use builder_level for collections of seasons, episodes, albums, or tracks. Filter and sort availability depends on the library and selected level; see the references below.

Plex builder attributes¶

These options also apply to smart_filter:

Attribute	Value	Default
`limit`	`all` or a positive integer	`all`
`sort_by`	Supported sort string or YAML list	`random`
`validate`	Boolean; whether validation errors fail the collection	`true`

Use collection_order: custom to preserve search order in a manual collection, and sync_mode: sync to synchronize membership on Kometa runs.

Examples¶

AND / ORNested logicBoolean, decimal, and limitMultiple sort fieldsEpisode level

The first collection requires both Dave Chappelle and Comedy; the second accepts either. Names are strings; all and any control the logic.

collections:
  Dave Chappelle Comedy:
    plex_search:
      all:
        actor: Dave Chappelle
        genre: Comedy

  Dave Chappelle or Comedy:
    plex_search:
      any:
        actor: Dave Chappelle
        genre: Comedy

Requires a year of 2020 or later and either Action or Comedy. The outer all combines the year rule with the inner any group.

collections:
  Recent Action or Comedy:
    plex_search:
      all:
        year.gte: 2020
        any:
          genre:
            - Action
            - Comedy

Selects up to 20 HDR movies rated at least 7.5 by the audience, highest rated first. true is a boolean, 7.5 is a decimal, and 20 is an integer.

collections:
  Highly Rated HDR Movies:
    collection_order: custom
    sync_mode: sync
    plex_search:
      all:
        hdr: true
        audience_rating.gte: 7.5
      sort_by: audience_rating.desc
      limit: 20

Selects up to 20 movies from 2010 onward, sorting by year newest first and audience rating within each year. Earlier sort entries take priority.

collections:
  Best Recent Movies by Year:
    collection_order: custom
    plex_search:
      all:
        year.gte: 2010
      sort_by:
        - year.desc
        - audience_rating.desc
      limit: 20

Selects up to 100 episodes from shows whose title ends in Simpsons, highest audience rating first. builder_level makes the collection contain episodes; type: episode selects that search level.

collections:
  Top 100 Simpsons Episodes:
    collection_order: custom
    builder_level: episode
    plex_search:
      type: episode
      sort_by: audience_rating.desc
      limit: 100
      all:
        title.ends: "Simpsons"

TMDb people¶

Set tmdb_person to TMDb person IDs or URLs, then use tmdb as the value for actor, director, producer, or writer. Kometa resolves IDs to names before searching. The same approach works with smart_filter.

Selects movies with Quentin Tarantino in any of the four roles. 138 is a TMDb person ID; tmdb requests name resolution.

collections:
  Quentin Tarantino:
    tmdb_person: 138
    plex_search:
      any:
        actor: tmdb
        director: tmdb
        producer: tmdb
        writer: tmdb

Building and checking a query¶

Use Plex's Advanced Filters UI to check the rules you want to reproduce. For help, share filter settings in Discussions or Discord.

Plex search options¶

Use attribute.modifier: value, such as title.not: "Harry Potter". The attribute and value are required; modifiers depend on the filter type below. These options are shared by plex_search and smart_filter.

Boolean filtersDate filtersNumber filtersString filtersTag filters

Boolean Filters take no modifier and can only be either true or false.

Boolean attributes¶

Attribute	Matches / constraints	Supports
`hdr`	Is HDR	Movies, Shows
`hdr10plus`	Has HDR10+	Movies, Shows
`atmos`	Has Dolby Atmos	Movies, Shows
`unmatched`	Is Unmatched (Music: Artist)	Movies, Music
`duplicate`	Is Duplicate	Movies
`unplayed`	Is Unplayed	Movies
`progress`	Is In Progress	Movies
`trash`	Is Trashed (Music: Track)	Movies, Shows, Music
`unplayed_episodes`	Has Unplayed Episodes	Shows
`episode_unplayed`	Has Episodes Unplayed	Shows
`episode_duplicate`	Has Duplicate Episodes	Shows
`episode_progress`	Has Episode Progress	Shows
`episode_unmatched`	Has Episodes Unmatched	Shows
`show_unmatched`	Has Shows Unmatched	Shows
`artist_unmatched`	Is Artist's Unmatched	Music
`album_unmatched`	Is Album's Unmatched	Music
`track_trash`	Is Track Trashed	Music
`dovi`	Has Dolby Vision	Movies, Shows

Date filters can be used with no modifier or with .last, .notlast, .before, or .after. The legacy .not modifier is also accepted as .notlast.

No date filter can take multiple values.

Date attributes¶

Attribute	Matches / constraints	Supports
`added`	date added	Movies, Shows
`episode_added`	date added	Shows
`release`	release date attribute (originally available) to match	Movies, Shows
`episode_air_date`	air date attribute (originally available) of the show's episodes to match	Shows
`last_played`	date last played	Movies, Shows
`episode_last_played`	date last played	Shows
`artist_added` / `date_artist_added`	Artist's date added	Music
`artist_last_played`	Artist's last played	Music
`album_last_played`	Album's last played	Music
`album_added` / `date_album_added`	Album's date added	Music
`album_released` / `date_album_released`	Album's release date	Music
`track_last_played`	Track's date last played	Music
`track_last_skipped`	Track's date last skipped	Music
`track_last_rated`	Track's date last rated	Music
`track_added` / `track_added_at`	Track's date added	Music

Date Filter Modifiers

Date Modifier	Description	Plex Web UI Display
No Modifier / `.last`	In the last given interval; days by default, or suffix `s`, `min`, `h`, `d`, `m`, `y`. Example: `10h`.	`is in the last`
`.notlast` / `.not`	Not in the last given interval; same format as `.last`. Example: `30` days.	`is not in the last`
`.before`	Before a date as `MM/DD/YYYY`, or `today`.	`is before`
`.after`	After a date as `MM/DD/YYYY`, or `today`.	`is after`

For example, date_album_added.last: 10h matches albums added in the last 10 hours.

Number filters can use .is, .isnot, .gt, .gte, .lt, or .lte as a modifier. Only rating filters can use .rated.

No number filter can take multiple values.

Number attributes¶

Attribute	Matches / constraints	Supports
`duration`	duration using minutes Minimum: `0`	Movies
`year`	year (Music: Album) Minimum: `0`	Movies, Shows, Music
`plays`	plays Minimum: `0`	Movies, Shows
`critic_rating`	critic rating Range: `0.0` - `10.0`	Movies, Shows
`audience_rating`	audience rating Range: `0.0` - `10.0`	Movies, Shows
`user_rating`	user rating Range: `0.0` - `10.0`	Movies, Shows
`commonsense_rating`	Uses Plex's Common Sense Media age rating to match Range: `1` - `18`	Movies, Shows
`episode_year`	Episode's year Minimum: `0`	Shows
`episode_plays`	Episode's plays Minimum: `0`	Shows
`episode_critic_rating`	critic rating Range: `0.0` - `10.0`	Shows
`episode_audience_rating`	audience rating Range: `0.0` - `10.0`	Shows
`episode_user_rating`	user rating Range: `0.0` - `10.0`	Shows
`album_year`	Album's year Minimum: `0`	Music
`album_decade`	Album's decade Minimum: `0`	Music
`album_plays`	Album's plays Minimum: `0`	Music
`track_plays`	Track's plays Minimum: `0`	Music
`track_skips`	Track's skips Minimum: `0`	Music
`artist_rating` / `artist_user_rating`	Artist's user rating Range: `0.0` - `10.0`	Music
`album_rating` / `album_user_rating`	Album's user rating Range: `0.0` - `10.0`	Music
`album_critic_rating`	Album's critic rating Range: `0.0` - `10.0`	Music
`track_rating` / `track_user_rating`	Track's user rating Range: `0.0` - `10.0`	Music

Number Filter Modifiers

Number Modifier	Description	Plex Web UI Display
`.is`	Equal to the number.	`is`
`.isnot`	Not equal to the number.	`is not`
`.gt`	Greater than the number.	`is greater than`
`.gte`	Greater than or equal to the number.	N/A
`.lt`	Less than the number.	`is less than`
`.lte`	Less than or equal to the number.	N/A
`.rated`	Rated / unrated; takes `true` or `false`, and only applies to rating filters.	N/A

.rated only works for rating filters

String filters can be used with either no modifier or with .not, .is, .isnot, .begins, or .ends.

String filter can take multiple values only as a list.

String attributes¶

Attribute	Matches / constraints	Supports
`title`	title	Movies, Shows
`episode_title`	title	Shows
`studio`	studio	Movies, Shows
`edition`	edition	Movies, Shows
`artist_title`	Artist's Title	Music
`album_title`	Album's Title	Music
`track_title`	Track's Title	Music
`record_label` / `album_record_label`	Album's Record Label	Music
`audio_codec`	Track's audio codec	Music

String Filter Modifiers

String Modifier	Description	Plex Web UI Display
No Modifier	Contains the string.	`contains`
`.not`	Does not contain the string.	`does not contain`
`.is`	Exactly matches the string.	`is`
`.isnot`	Does not exactly match the string.	`is not`
`.begins`	Begins with the string.	`begins with`
`.ends`	Ends with the string.	`ends with`

Tag filters can be used with either no modifier or with .not except for decade and resolution which can only be used with no modifier.

Tag filter can take multiple values as a list or a comma-separated string.

Tag attributes¶

Attribute	Matches / constraints	Supports
`actor`	actor	Movies, Shows
`episode_actor`	episode actor	Shows
`audio_language`	audio language	Movies, Shows
`collection`	collection for top level collections	Movies, Shows
`season_collection`	collection for season collections	Shows
`episode_collection`	collection for episode collections	Shows
`content_rating`	content rating	Movies, Shows
`country`	country	Movies, Shows
`decade`	year tag to match the decade	Movies
`director`	director	Movies
`folder_location`	Plex library root folder location to match	Movies, Shows, Music
`genre`	genre	Movies, Shows
`label`	label for top level collections; in Music, matches the selected artist, album, or track type	Movies, Shows, Music
`season_label`	label for season collections	Shows
`episode_label`	label for episode collections	Shows
`network`	network Only works with the New Plex TV Agent	Shows
`producer`	Producer tags	Movies
`resolution`	resolution	Movies, Shows
`subtitle_language`	subtitle language	Movies, Shows
`writer`	writer	Movies
`year`	year tag to match (Music: Album)	Movies, Shows, Music
`episode_year`	year tag to match	Shows
`artist_genre`	Artist's Genre	Music
`artist_collection`	Artist's Collection	Music
`artist_country`	Artist's Country	Music
`artist_mood`	Artist's Mood	Music
`artist_style`	Artist's Style	Music
`artist_label`	Artist's Label	Music
`album_genre`	Album's Genre	Music
`album_mood`	Album's Mood	Music
`album_style`	Album's Style	Music
`album_format`	Album's Format	Music
`album_type`	Album's Type	Music
`album_collection`	Album's Collection	Music
`album_source`	Album's Source	Music
`album_label`	Album's Label	Music
`track_mood`	Track's Mood	Music
`track_genre`	Track's Genre	Music
`track_source`	Track's Source	Music
`track_label`	Track's Label	Music

You can use current_year to have Kometa use the current year. This can be combined with a -# at the end to subtract that number of years. i.e. current_year-2

folder_location values must match a root folder configured in the Plex library. Plex does not expose nested subfolders as Folder Location filter choices. In music libraries, folder_location is only available with builder_level: track.

Tag Filter Modifiers

Tag Modifier	Description	Plex Web UI Display
No Modifier	Matches the value.	`is`
`.not`	Does not match the value.	`is not`

Plex sort options¶

Append .asc for ascending or .desc for descending order, such as audience_rating.desc. random stands alone, without a direction suffix. Choose a field supported by the selected item level. To sort by several fields, supply a YAML list; earlier fields take priority.

Field	Orders by	Supports
`title`	Title	Movies, Shows, Episodes, Artists, Albums, Tracks
`season`	Season	Seasons
`show`	Show	Seasons, Episodes
`album_artist`	Album Artist	Albums, Tracks
`artist`	Artist	Tracks
`album`	Album	Tracks
`year`	Year	Movies, Shows, Episodes, Albums
`release`	Release Date (Originally Available)	Movies, Shows, Episodes, Albums
`episode_release`	Episode Release Date (Originally Available)	Shows, Seasons, Episodes
`critic_rating`	Critic Rating	Movies, Shows, Episodes, Albums
`audience_rating`	Audience Rating	Movies, Shows, Episodes
`user_rating`	User Rating	Movies, Shows, Seasons, Episodes, Artists, Albums, Tracks
`content_rating`	Content Rating	Movies, Shows
`duration`	Duration	Movies, Episodes, Tracks
`progress`	Progress	Episodes
`played`	Date Last Played	Artists, Albums, Tracks
`plays`	Number of Plays	Movies, Episodes, Artists, Albums, Tracks
`unplayed`	Unplayed	Shows
`episode_added`	Last Episode Date Added	Shows
`added`	Date Added	Movies, Shows, Seasons, Episodes, Artists, Albums, Tracks
`viewed`	Date Last Viewed	Movies, Shows, Episodes
`rated`	Date Last Rated	Tracks
`popularity`	Popularity	Tracks
`resolution`	Resolution	Movies, Episodes
`bitrate`	Bitrate	Movies, Episodes, Tracks
`random`	Random	Movies, Shows, Seasons, Episodes, Artists, Albums, Tracks