Skip to navigation

Collection fields

Collections of entries and assets are exposed through collection fields in the root query object and in one-to-many relationship fields. For example:

type FriendlyUserCollection {
  skip: Int!
  limit: Int!
  total: Int!
  items: [FriendlyUser]!
}
input FriendlyUserFilter {
  # ... field based filters
}
type Query {
  # ...
  friendlyUserCollection(
    skip: Int
    limit: Int
    where: FriendlyUserFilter
  ): FriendlyUserCollection
}

Arguments

The following optional arguments are available when querying a collection:

ArgumentTypeDescription
skipNumberZero-indexed offset in the collection from which items are fetched. Defaults to 0.
limitNumberMaximum number of items to fetch. Defaults to 100; maximum is 1000.
whereInputTypeFilter specifications to apply on the collection query. See Collection Filters.
orderInputTypeOrder specifications to apply on the collection query. See Collection Order.
previewBooleanWhen set to true the field will be resolved with non-published content. Defaults to false.
localeStringLocale for the collection items. If not set, the default locale is used.
useFallbackLocaleBooleanWhen set to false, fields without a value in the requested locale return null instead of the fallback locale. Defaults to true. See Disabling locale fallback.

Return value

The value returned from a collection field contains the meta fields skip, limit, total, and the requested items in the items field. The skip and limit fields correspond to their respective input arguments. The total field contains the total number of items in that collection.

Don’t use skip to iterate through an entire collection. Performance degrades as the offset grows, particularly for complex queries and deep link resolution. skip/limit is intended for random access into a bounded result set (for example, “page 3 of 20” in a UI).

To fetch or process every item in a large collection, such as exports, analytics, migrations, or any exhaustive traversal, use cursor pagination instead.