Plex Builders¶

Plex Builders utilize media that already exists within your Plex library to place them into a Collection.

Plex has two categories of Collections - Smart and Manual. The same search criteria can be used to build a Smart or Manual collection in most instances.

To keep things simple we will use the term Smart Builders and Manual Builders, which refers to the criteria that is used to build the Collection.

Smart Builders use filters (rules) to build collections that match the criteria of the Builder. When new media is added to your library, or if metadata of any item in your library changes to match the Builder's rules, the media is automatically included in the collection without the need to run Kometa again.

Manual (also known as Dumb or non-Smart) Builders are static in nature and will not dynamically update as new media is added/metadata criteria changes across your library - you will have to run Kometa any time you want the Builder to re-run.

Smart Builders are usually the recommended approach as they are lightweight and faster to process than Dumb Builders

Understanding Smart vs Manual Collections¶

There are some key differences that you should understand before choosing if you want to use a Smart or Manual Builder, this table shows you the key differences between the Collections that are built from each type of Builder.

Feature	Smart Collection	Manual (Dumb) Collection
Automation	Automatically includes or removes items as your library changes	Requires manual updates—items must be added or removed by hand
Use Case	Great for auto-generating groups like “Movies Released This Year” or “Top-Rated Thrillers”	Ideal for curated lists like “My Favorites” or “Family Movie Night Picks”
Customization	Built using Plex’s filter system; limited to available filter options	Fully customizable—any item from the library can be included
Accuracy	Always reflects real-time library data based on filter criteria	Remains the same unless manually edited
Icon	Identified with a gear icon in the Plex UI (⚙️)	No special icon—just a standard collection
Behavior After Library Scan	Automatically refreshes based on updated metadata	No change unless edited manually
Editing	Filters can be edited to change which items are included	Items must be individually added/removed
Metadata Changes (via Refresh or Kometa updates)	Filters remain intact; collection contents may shift as metadata changes	Content stays fixed unless explicitly modified by scripts or user

There are some exceptions to the above when using a Smart Builder (namely when using a Smart Label Definition), but the above should offer a basic understanding of the key differences.

Builder Attributes¶

The majority of Smart and Manual Builders utilize the same Builder Attributes. Any deviation from this will be highlighted against the specific Builder.

Attribute	Description & Values
`limit`	Description: The max number of item for the filter. Default: `all` Values: `all` or a number greater than 0
`sort_by`	Description: This will control how the filter is sorted in your library. You can do a multi-level sort using a list. Default: `random` Values: Any sort options for your filter type in the Sorts Options Table
`validate`	Description: Determines if a collection will fail on a validation error Default: `true` Values: `true` or `false`

Plex Builder Types¶

Builder	Description	Works with Movies	Works with Shows	Works with Playlists and Custom Sort
`smart_filter`	use Plex's Advanced Filters to create a smart collection based on the filter parameters provided.
`plex_all`	Gets every movie/show in your library. Useful with Filters
`plex_search`	Gets every movie/show based on the search parameters provided
`plex_watchlist`	Gets every movie/show in your Watchlist.
`plex_pilots`	Gets the first episode of every show in your library
`plex_collectionless`	Gets every movie/show that is not in a collection

Plex Search Options¶

When using a Plex Builder, there are three elements that correlate to Plex's Advanced Filters in the Web UI.

Attribute: What attribute you wish to filter.
Modifier: Which modifier to use.
Value: Actual value to filter.

These three elements combined would look like attribute.modifier: value, in a Builder this may be something like title.not: Harry Potter or episode_added: 7.

Attribute and Value elements are mandatory, whilst modifiers are optional. Typically speaking, Plex will have a default modifier of "is" or "contains" if you do not specify a modifier.

The majority of Smart and Manual Builders utilize the same Search Options, meaning that the criteria for the builders is largely interchangeable between the two. Any deviation from this will be highlighted against the specific Builder.

Boolean FiltersDate FiltersNumber FiltersString FiltersTag Filters

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

Boolean Filter Attributes¶

Boolean Search	Description	Movie Libraries	Show Libraries	Music Libraries
`hdr`	Is HDR
`unmatched`	Is Unmatched
`duplicate`	Is Duplicate
`unplayed`	Is Unplayed
`progress`	Is In Progress
`trash`	Is Trashed
`unplayed_episodes`	Has Unplayed Episodes
`episode_unplayed`	Has Episodes Unplayed
`episode_duplicate`	Has Duplicate Episodes
`episode_progress`	Has Episode Progress
`episode_unmatched`	Has Episodes Unmatched
`show_unmatched`	Has Shows Unmatched
`artist_unmatched`	Is Artist's Unmatched
`album_unmatched`	Is Album's Unmatched
`track_trash`	Is Track Trashed
`dovi`	Has Dolby Vision

Date filters can be used with either no modifier or with .not, .before, or .after.

No date filter can take multiple values.

Date Filter Attributes¶

Date Search	Description	Movie Libraries	Show Libraries	Music Libraries
`added`	Uses the date added attribute to match
`episode_added`	Uses the date added attribute of the show's episodes to match
`release`	Uses the release date attribute (originally available) to match
`episode_air_date`	Uses the air date attribute (originally available) of the show's episodes to match
`last_played`	Uses the date last played attribute to match
`episode_last_played`	Uses the date last played attribute of the show's episodes to match
`artist_added`	Uses the Artist's date added attribute to match
`artist_last_played`	Uses the Artist's last played attribute to match
`album_last_played`	Uses the Album's last played attribute to match
`album_added`	Uses the Album's date added attribute to match
`album_released`	Uses the Album's release date attribute to match
`track_last_played`	Uses the Track's date last played attribute to match
`track_last_skipped`	Uses the Track's date last skipped attribute to match
`track_last_rated`	Uses the Track's date last rated attribute to match
`track_added`	Uses the Track's date added attribute to match

Date Filter Modifiers

Date Modifier	Description	Plex Web UI Display
No Modifier	Matches every item where the date attribute is in the last X days Format: number of days Example: `30`	`is in the last`
`.not`	Matches every item where the date attribute is not in the last X days Format: number of days Example: `30`	`is not in the last`
`.before`	Matches every item where the date attribute is before the given date Format: MM/DD/YYYY or `today` for the current day Example: `01/01/2000`	`is before`
`.after`	Matches every item where the date attribute is after the given date Format: MM/DD/YYYY or `today` for the current day Example: `01/01/2000`	`is after`

Number filters must use .gt, .gte, .lt, or .lte as a modifier only the rating filters can use .rated.

No number filter can take multiple values.

Number Filter Attributes¶

Number Search	Description	Movie Libraries	Show Libraries	Music Libraries
`duration`	Uses the duration attribute to match using minutes Minimum: `0`
`year`	Uses the year attribute to match Minimum: `0`
`plays`	Uses the plays attribute to match Minimum: `0`
`critic_rating`	Uses the critic rating attribute to match Range: `0.0` - `10.0`
`audience_rating`	Uses the audience rating attribute to match Range: `0.0` - `10.0`
`user_rating`	Uses the user rating attribute to match Range: `0.0` - `10.0`
`episode_year`	Uses the Episode's year attribute to match Minimum: `0`
`episode_plays`	Uses the Episode's plays attribute to match Minimum: `0`
`episode_critic_rating`	Uses the critic rating attribute of the show's episodes to match Range: `0.0` - `10.0`
`episode_audience_rating`	Uses the audience rating attribute of the show's episodes to match Range: `0.0` - `10.0`
`episode_user_rating`	Uses the user rating attribute of the show's episodes to match Range: `0.0` - `10.0`
`album_year`	Uses the Album's year attribute to match Minimum: `0`
`album_decade`	Uses the Album's decade attribute to match Minimum: `0`
`album_plays`	Uses the Album's plays attribute to match Minimum: `0`
`track_plays`	Uses the Track's plays attribute to match Minimum: `0`
`track_skips`	Uses the Track's skips attribute to match Minimum: `0`
`artist_user_rating`	Uses the Artist's user rating attribute to match Range: `0.0` - `10.0`
`album_user_rating`	Uses the Album's user rating attribute to match Range: `0.0` - `10.0`
`album_critic_rating`	Uses the Album's critic rating attribute to match Range: `0.0` - `10.0`
`track_user_rating`	Uses the Track's user rating attribute to match Range: `0.0` - `10.0`

Number Filter Modifiers

Number Modifier	Description	Plex Web UI Display
`.gt`	Matches every item where the number attribute is greater than the given number Format: number Example: `30`, `1995`, or `7.5`	`is greater than`
`.gte`	Matches every item where the number attribute is greater than or equal to the given number Format: number Example: `30`, `1995`, or `7.5`	N/A
`.lt`	Matches every item where the number attribute is less than the given number Format: number Example: `30`, `1995`, or `7.5`	`is less than`
`.lte`	Matches every item where the number attribute is less than or equal to the given number Format: number Example: `30`, `1995`, or `7.5`	N/A
`.rated`	Matches every item either rated or not rated Format: `true` or `false`	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 Filter Attributes¶

String Search	Description	Movie Libraries	Show Libraries	Music Libraries
`title`	Uses the title attribute to match
`episode_title`	Uses the title attribute of the show's episodes to match
`studio`	Uses the studio attribute to match
`edition`	Uses the edition attribute to match
`artist_title`	Uses the Artist's Title attribute to match
`album_title`	Uses the Album's Title attribute to match
`track_title`	Uses the Track's Title attribute to match
`album_record_label`	Uses the Album's Record Label attribute to match

String Filter Modifiers

String Modifier	Description	Plex Web UI Display
No Modifier	Matches every item where the attribute contains the given string	`contains`
`.not`	Matches every item where the attribute does not contain the given string	`does not contain`
`.is`	Matches every item where the attribute exactly matches the given string	`is`
`.isnot`	Matches every item where the attribute does not exactly match the given string	`is not`
`.begins`	Matches every item where the attribute begins with the given string	`begins with`
`.ends`	Matches every item where the attribute ends with the given 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 Filter Attributes¶

Tag Search	Description	Movie Libraries	Show Libraries	Music Libraries
`actor`	Uses the actor tags to match
`episode_actor`	Uses the episode actor tags to match
`audio_language`	Uses the audio language tags to match
`collection`	Uses the collection tags to match for top level collections
`season_collection`	Uses the collection tags to match for season collections
`episode_collection`	Uses the collection tags to match for episode collections
`content_rating`	Uses the content rating tags to match
`country`	Uses the country tags to match
`decade`	Uses the year tag to match the decade
`director`	Uses the director tags to match
`genre`	Uses the genre tags to match
`label`	Uses the label tags to match for top level collections
`season_label`	Uses the label tags to match for season collections
`episode_label`	Uses the label tags to match for episode collections
`network`	Uses the network tags to match Only works with the New Plex TV Agent
`producer`	Uses the actor tags to match
`resolution`	Uses the resolution tags to match
`subtitle_language`	Uses the subtitle language tags to match
`writer`	Uses the writer tags to match
`year`	Uses the year tag to match
`episode_year`	Uses the year tag to match
`artist_genre`	Uses the Artist's Genre attribute to match
`artist_collection`	Uses the Artist's Collection attribute to match
`artist_country`	Uses the Artist's Country attribute to match
`artist_mood`	Uses the Artist's Mood attribute to match
`artist_style`	Uses the Artist's Style attribute to match
`artist_label`	Uses the Artist's Label attribute to match
`album_genre`	Uses the Album's Genre attribute to match
`album_mood`	Uses the Album's Mood attribute to match
`album_style`	Uses the Album's Style attribute to match
`album_format`	Uses the Album's Format attribute to match
`album_type`	Uses the Album's Type attribute to match
`album_collection`	Uses the Album's Collection attribute to match
`album_source`	Uses the Album's Source attribute to match
`album_label`	Uses the Album's Label attribute to match
`track_mood`	Uses the Track's Mood attribute to match
`track_source`	Uses the Track's Source attribute to match
`track_label`	Uses the Track's Label attribute to match

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

Tag Filter Modifiers

Tag Modifier	Description	Plex Web UI Display
No Modifier	Matches every item where the attribute matches the given string	`is`
`.not`	Matches every item where the attribute does not match the given string	`is not`

Plex Sort Options¶

The majority of Smart and Manual Builders utilize the same Sort Options. Any deviation from this will be highlighted against the specific Builder.

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

Sort Option Examples¶

collections:
  Best 2024 Movies:
    smart_filter:
      limit: 100
      all:
        year: 2024
      sort_by: audience_rating.desc

collections:
  Newly Released Movies:
    smart_filter:
      limit: 100
      all:
        release: 30
      sort_by: release.desc