<!--
{
  "availability" : [
    "iOS: 3.0.0 -",
    "iPadOS: 3.0.0 -",
    "macCatalyst: 13.1.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "MediaPlayer",
  "identifier" : "/documentation/MediaPlayer/MPMediaQuery",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Media Player"
    ],
    "preciseIdentifier" : "c:objc(cs)MPMediaQuery"
  },
  "title" : "MPMediaQuery"
}
-->

# MPMediaQuery

A query that specifies a set of media items from the device’s media library using a filter and a grouping type.

```
class MPMediaQuery
```

## Overview

Filter and grouping types are both optional; an unqualified query matches the entire library.

A query has at most one grouping type. A query’s filter can consist of any number of media property predicates. You build filters using [`MPMediaPropertyPredicate`](/documentation/MediaPlayer/MPMediaPropertyPredicate) objects, based on property keys described in [`MPMediaItem`](/documentation/MediaPlayer/MPMediaItem).

After creating and configuring a query, you use it to retrieve media items or media item collections. You can also use a query to retrieve an array of [`MPMediaQuerySection`](/documentation/MediaPlayer/MPMediaQuerySection) instances, useful for displaying the results of a query in the user interface of your app. See the [`itemSections`](/documentation/MediaPlayer/MPMediaQuery/itemSections) and [`collectionSections`](/documentation/MediaPlayer/MPMediaQuery/collectionSections) properties.

This class includes several convenience constructors that each apply a grouping type and, in most cases, match a subset of the library. The following table summarizes the features of these constructors. See [`MPMediaItem`](/documentation/MediaPlayer/MPMediaItem) for descriptions of the entries in the Filter column. See [`MPMediaGrouping`](/documentation/MediaPlayer/MPMediaGrouping) for descriptions of the entries in the Grouping type column.

|Constructor name                                                                     |Matches entire library|Filter                                                                                                                                                                   |Grouping type                                                                         |
|-------------------------------------------------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/albums()``      |-                     |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/music``                                                                                              |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/album``       |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/artists()``     |-                     |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/music``                                                                                              |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/artist``      |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/audiobooks()``  |-                     |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/audioBook``                                                                                          |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/title``       |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/compilations()``|-                     |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/any`` with ``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaItemPropertyIsCompilation``|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/album``       |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/composers()``   |Yes                   |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/any``                                                                                                |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/composer``    |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/genres()``      |Yes                   |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/any``                                                                                                |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/genre``       |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/playlists()``   |Yes                   |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/any``                                                                                                |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/playlist``    |
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/podcasts()``    |-                     |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/podcast``                                                                                            |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/podcastTitle``|
|``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaQuery/songs()``       |-                     |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaType/music``                                                                                              |``doc://com.apple.mediaplayer/documentation/MediaPlayer/MPMediaGrouping/title``       |

## Topics

### Creating media queries

The class methods in this section create queries which you can use directly or modify as described in Configuring media queries.

For each class method, the system sets the query’s [`groupingType`](/documentation/MediaPlayer/MPMediaQuery/groupingType)

The grouping for collections retrieved with the media query. property automatically according to the name of the method. For example, the [`+  albumsQuery`](/documentation/MediaPlayer/MPMediaQuery/albums())

Creates a media query that matches music items and that groups and sorts collections by album name. method assigns a grouping type of [`MPMediaGroupingAlbum`](/documentation/MediaPlayer/MPMediaGrouping/album)

Groups and sorts media item collections by album, and sorts songs within an album by track order.. The grouping type specifies the nature of the media item collections you can then retrieve from the query. Some class methods match the entire Music library while others match a subset, as described in the Discussion sections for each method.

[`+  albumsQuery`](/documentation/MediaPlayer/MPMediaQuery/albums())

Creates a media query that matches music items and that groups and sorts collections by album name.

[`+  artistsQuery`](/documentation/MediaPlayer/MPMediaQuery/artists())

Creates a media query that matches music items and that groups and sorts collections by artist name.

[`+  songsQuery`](/documentation/MediaPlayer/MPMediaQuery/songs())

Creates a media query that matches music items and that groups and sorts collections by song name.

[`+  playlistsQuery`](/documentation/MediaPlayer/MPMediaQuery/playlists())

Creates a media query that matches the entire library and that groups and sorts collections by playlist name.

[`+  podcastsQuery`](/documentation/MediaPlayer/MPMediaQuery/podcasts())

Creates a media query that matches podcast items and that groups and sorts collections by podcast name.

[`+  audiobooksQuery`](/documentation/MediaPlayer/MPMediaQuery/audiobooks())

Creates a media query that matches audio book items and that groups and sorts collections by audio book name.

[`+  compilationsQuery`](/documentation/MediaPlayer/MPMediaQuery/compilations())

Creates a media query that matches compilation items and that groups and sorts collections by album name.

[`+  composersQuery`](/documentation/MediaPlayer/MPMediaQuery/composers())

Creates a media query that matches all media items and that groups and sorts collections by composer name.

[`+  genresQuery`](/documentation/MediaPlayer/MPMediaQuery/genres())

Creates a media query that matches all media items and that groups and sorts collections by genre name.

[`-  initWithFilterPredicates:`](/documentation/MediaPlayer/MPMediaQuery/init(filterPredicates:))

Initializes a media query with a set of media property predicates.

### Creating media queries

The class methods in this section create queries which you can use directly or modify as described in Configuring media queries.

For each class method, the system sets the query’s [`groupingType`](/documentation/MediaPlayer/MPMediaQuery/groupingType)

The grouping for collections retrieved with the media query. property automatically according to the name of the method. For example, the [`+  albumsQuery`](/documentation/MediaPlayer/MPMediaQuery/albums())

Creates a media query that matches music items and that groups and sorts collections by album name. method assigns a grouping type of [`MPMediaGroupingAlbum`](/documentation/MediaPlayer/MPMediaGrouping/album)

Groups and sorts media item collections by album, and sorts songs within an album by track order.. The grouping type specifies the nature of the media item collections you can then retrieve from the query. Some class methods match the entire Music library while others match a subset, as described in the Discussion sections for each method.

[`+  albumsQuery`](/documentation/MediaPlayer/MPMediaQuery/albums())

Creates a media query that matches music items and that groups and sorts collections by album name.

[`+  artistsQuery`](/documentation/MediaPlayer/MPMediaQuery/artists())

Creates a media query that matches music items and that groups and sorts collections by artist name.

[`+  songsQuery`](/documentation/MediaPlayer/MPMediaQuery/songs())

Creates a media query that matches music items and that groups and sorts collections by song name.

[`+  playlistsQuery`](/documentation/MediaPlayer/MPMediaQuery/playlists())

Creates a media query that matches the entire library and that groups and sorts collections by playlist name.

[`+  podcastsQuery`](/documentation/MediaPlayer/MPMediaQuery/podcasts())

Creates a media query that matches podcast items and that groups and sorts collections by podcast name.

[`+  audiobooksQuery`](/documentation/MediaPlayer/MPMediaQuery/audiobooks())

Creates a media query that matches audio book items and that groups and sorts collections by audio book name.

[`+  compilationsQuery`](/documentation/MediaPlayer/MPMediaQuery/compilations())

Creates a media query that matches compilation items and that groups and sorts collections by album name.

[`+  composersQuery`](/documentation/MediaPlayer/MPMediaQuery/composers())

Creates a media query that matches all media items and that groups and sorts collections by composer name.

[`+  genresQuery`](/documentation/MediaPlayer/MPMediaQuery/genres())

Creates a media query that matches all media items and that groups and sorts collections by genre name.

[init](/documentation/MediaPlayer/MPMediaQuery-init)

Initializes a generic media query.

[`-  initWithFilterPredicates:`](/documentation/MediaPlayer/MPMediaQuery/init(filterPredicates:))

Initializes a media query with a set of media property predicates.

### Configuring media queries

[`filterPredicates`](/documentation/MediaPlayer/MPMediaQuery/filterPredicates)

The media property predicates of the media query.

[`-  addFilterPredicate:`](/documentation/MediaPlayer/MPMediaQuery/addFilterPredicate(_:))

Adds a media property predicate to a query.

[`-  removeFilterPredicate:`](/documentation/MediaPlayer/MPMediaQuery/removeFilterPredicate(_:))

Removes a filter predicate from a query.

[`groupingType`](/documentation/MediaPlayer/MPMediaQuery/groupingType)

The grouping for collections retrieved with the media query.

[`itemSections`](/documentation/MediaPlayer/MPMediaQuery/itemSections)

An array representing the section grouping of the query’s specified media items.

[`collectionSections`](/documentation/MediaPlayer/MPMediaQuery/collectionSections)

An array representing the section grouping of the query’s specified media item collections.

[`MPMediaGrouping`](/documentation/MediaPlayer/MPMediaGrouping)

Keys used to configure a media query.

### Performing media queries

You obtain a specified array of media items or media item collections from the iPod library by calling the [`items`](/documentation/MediaPlayer/MPMediaQuery/items)

An array of media items that match the media query’s predicate. or [`collections`](/documentation/MediaPlayer/MPMediaQuery/collections)

An array of media item collections whose contained items match the query’s media property predicate. accessor methods.

[`items`](/documentation/MediaPlayer/MPMediaQuery/items)

An array of media items that match the media query’s predicate.

[`collections`](/documentation/MediaPlayer/MPMediaQuery/collections)

An array of media item collections whose contained items match the query’s media property predicate.

## Relationships

### Conforms To

[`NSCopying`](/documentation/Foundation/NSCopying)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

[`Equatable`](/documentation/Swift/Equatable)

[`CVarArg`](/documentation/Swift/CVarArg)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`NSCoding`](/documentation/Foundation/NSCoding)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)