Select

By default, Payload's APIs will return all fields for a given collection or global. But, you may not need all of that data for all of your queries. Sometimes, you might want just a few fields from the response.

With the Select API, you can define exactly which fields you'd like to retrieve. This can impact the performance of your queries by affecting the load on the database and the size of the response.

Local API

To specify select in the Local API, you can use the select option in your query:

1import type { Payload } from 'payload'
2
3// Include mode
4const getPosts = async (payload: Payload) => {
5  const posts = await payload.find({
6    collection: 'posts',
7    select: {
8      text: true,
9      // select a specific field from group
10      group: {
11        number: true,
12      },
13      // select all fields from array
14      array: true,
15    },
16  })
17
18  return posts
19}
20
21// Exclude mode
22const getPosts = async (payload: Payload) => {
23  const posts = await payload.find({
24    collection: 'posts',
25    // Select everything except for array and group.number
26    select: {
27      array: false,
28      group: {
29        number: false,
30      },
31    },
32  })
33
34  return posts
35}

REST API

To specify select in the REST API, you can use the select parameter in your query:

1fetch(
2  'https://localhost:3000/api/posts?select[color]=true&select[group][number]=true',
3)
4  .then((res) => res.json())
5  .then((data) => console.log(data))

To understand the syntax, you need to understand that complex URL search strings are parsed into a JSON object. This one isn't too bad, but more complex queries get unavoidably more difficult to write.

For this reason, we recommend to use the extremely helpful and ubiquitous qs-esm package to parse your JSON / object-formatted queries into query strings:

1import { stringify } from 'qs-esm'
2import type { Where } from 'payload'
3
4const select: Where = {
5  text: true,
6  group: {
7    number: true,
8  },
9  // This query could be much more complex
10  // and QS would handle it beautifully
11}
12
13const getPosts = async () => {
14  const stringifiedQuery = stringify(
15    {
16      select, // ensure that `qs` adds the `select` property, too!
17    },
18    { addQueryPrefix: true },
19  )
20
21  const response = await fetch(
22    `http://localhost:3000/api/posts${stringifiedQuery}`,
23  )
24  // Continue to handle the response below...
25}

defaultPopulate collection config property

The defaultPopulate property allows you specify which fields to select when populating the collection from another document. This is especially useful for links where only the slug is needed instead of the entire document.

With this feature, you can dramatically reduce the amount of JSON that is populated from Relationship or Upload fields.

For example, in your content model, you might have a Link field which links out to a different page. When you go to retrieve these links, you really only need the slug of the page.

Loading all of the page content, its related links, and everything else is going to be overkill and will bog down your Payload APIs. Instead, you can define the defaultPopulate property on your Pages collection, so that when Payload "populates" a related Page, it only selects the slug field and therefore returns significantly less JSON:

1import type { CollectionConfig } from 'payload'
2
3// The TSlug generic can be passed to have type safety for `defaultPopulate`.
4// If avoided, the `defaultPopulate` type resolves to `SelectType`.
5export const Pages: CollectionConfig<'pages'> = {
6  slug: 'pages',
7  // Specify `select`.
8  defaultPopulate: {
9    slug: true,
10  },
11  fields: [
12    {
13      name: 'slug',
14      type: 'text',
15      required: true,
16    },
17  ],
18}

Populate

Setting defaultPopulate will enforce that each time Payload performs a "population" of a related document, only the fields specified will be queried and returned. However, you can override defaultPopulate with the populate property in the Local and REST API:

Local API:

1import type { Payload } from 'payload'
2
3const getPosts = async (payload: Payload) => {
const posts = await payload.find({
  collection: 'posts',
  populate: {
    // Select only `text` from populated docs in the "pages" collection
    // Now, no matter what the `defaultPopulate` is set to on the "pages" collection,
    // it will be overridden, and the `text` field will be returned instead.
    pages: {
      text: true,
    }, 
  },
})
15
return posts
17}

REST API:

1fetch('https://localhost:3000/api/posts?populate[pages][text]=true') 
2  .then((res) => res.json())
3  .then((data) => console.log(data))

Depth

Select

With the Select API, you can define exactly which fields you'd like to retrieve. This can impact the performance of your queries by affecting the load on the database and the size of the response.

Local API

To specify select in the Local API, you can use the select option in your query:

1import type { Payload } from 'payload'
2
3// Include mode
4const getPosts = async (payload: Payload) => {
5  const posts = await payload.find({
6    collection: 'posts',
7    select: {
8      text: true,
9      // select a specific field from group
10      group: {
11        number: true,
12      },
13      // select all fields from array
14      array: true,
15    },
16  })
17
18  return posts
19}
20
21// Exclude mode
22const getPosts = async (payload: Payload) => {
23  const posts = await payload.find({
24    collection: 'posts',
25    // Select everything except for array and group.number
26    select: {
27      array: false,
28      group: {
29        number: false,
30      },
31    },
32  })
33
34  return posts
35}

REST API

To specify select in the REST API, you can use the select parameter in your query:

1fetch(
2  'https://localhost:3000/api/posts?select[color]=true&select[group][number]=true',
3)
4  .then((res) => res.json())
5  .then((data) => console.log(data))

For this reason, we recommend to use the extremely helpful and ubiquitous qs-esm package to parse your JSON / object-formatted queries into query strings:

1import { stringify } from 'qs-esm'
2import type { Where } from 'payload'
3
4const select: Where = {
5  text: true,
6  group: {
7    number: true,
8  },
9  // This query could be much more complex
10  // and QS would handle it beautifully
11}
12
13const getPosts = async () => {
14  const stringifiedQuery = stringify(
15    {
16      select, // ensure that `qs` adds the `select` property, too!
17    },
18    { addQueryPrefix: true },
19  )
20
21  const response = await fetch(
22    `http://localhost:3000/api/posts${stringifiedQuery}`,
23  )
24  // Continue to handle the response below...
25}

defaultPopulate collection config property

With this feature, you can dramatically reduce the amount of JSON that is populated from Relationship or Upload fields.

For example, in your content model, you might have a Link field which links out to a different page. When you go to retrieve these links, you really only need the slug of the page.

1import type { CollectionConfig } from 'payload'
2
3// The TSlug generic can be passed to have type safety for `defaultPopulate`.
4// If avoided, the `defaultPopulate` type resolves to `SelectType`.
5export const Pages: CollectionConfig<'pages'> = {
6  slug: 'pages',
7  // Specify `select`.
8  defaultPopulate: {
9    slug: true,
10  },
11  fields: [
12    {
13      name: 'slug',
14      type: 'text',
15      required: true,
16    },
17  ],
18}

Populate

Local API:

1import type { Payload } from 'payload'
2
3const getPosts = async (payload: Payload) => {
const posts = await payload.find({
  collection: 'posts',
  populate: {
    // Select only `text` from populated docs in the "pages" collection
    // Now, no matter what the `defaultPopulate` is set to on the "pages" collection,
    // it will be overridden, and the `text` field will be returned instead.
    pages: {
      text: true,
    }, 
  },
})
15
return posts
17}

REST API:

1fetch('https://localhost:3000/api/posts?populate[pages][text]=true') 
2  .then((res) => res.json())
3  .then((data) => console.log(data))

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Select

Local API

REST API

defaultPopulate collection config property

Populate

Depth

Select

Local API

REST API

defaultPopulate collection config property

Populate