Per-field population control in the Local (and REST) API

[MurzNN]

Problem

The current depth parameter in payload.find() is a single integer applied uniformly to all relationship and upload fields in a document.

There is no way to say "populate field A but not field B" in a single query. The only existing per-field mechanism is maxDepth on the field config, which is a static, config-time cap — not a dynamic, per-query override.

The existing populate option (keyed by collection slug) controls which fields to select from an already-populated document, not whether to populate a given relationship field at all.

Motivating Use Case

Consider a Classes collection with two relationship fields pointing to Users:

{
  slug: 'classes',
  fields: [
    { name: 'teacher',  type: 'relationship', relationTo: 'users', hasMany: false },
    { name: 'students', type: 'relationship', relationTo: 'users', hasMany: true  },
  ],
}

A list page needs to display the teacher's name and the count of students. The ideal query is:

const classes = await payload.find({
  collection: 'classes',
  depth: 1, // populates teacher — but ALSO populates every student, which is wasteful
})

With depth=1, Payload populates both teacher (desired) and every document in students (not desired — only the count/IDs are needed). A class with 200 students triggers 200 extra database lookups and returns a large payload.

The only current workarounds are:

• Use depth=0 and issue a separate payload.findByID for each teacher — N+1 problem.
• Set maxDepth: 0 on the students field in the collection config — permanently disables population for all queries, not just this one.
• Post-process: fetch with depth=1 and discard the student objects — wastes DB and memory.

---

Proposed Solutions

Option A: A new populateFields option — per-field depth map

Add a new top-level option to find / findByID / findGlobal that maps field paths (on the queried document) to a depth override:

const classes = await payload.find({
  collection: 'classes',
  depth: 0,                // default: do not populate anything
  populateFields: {
    teacher: 1,            // populate `teacher` to depth 1
    // students omitted → stays as array of IDs
  },
})

Or using a boolean shorthand:

populateFields: {
  teacher: true,   // use the global `depth` value for this field
  students: false, // force depth=0 for this field regardless of global depth
}

Type sketch:

type PopulateFieldsType = Record<string, boolean | number>

// Added to BaseFindOptions:
populateFields?: PopulateFieldsType

Where the change would live:

The population decision is made in relationshipPopulationPromise.ts, specifically the shouldPopulate check:

const shouldPopulate = depth && currentDepth <= depth

This check would also consult the populateFields map (threaded through afterRead → promise.ts → relationshipPopulationPromise.ts) using the current field's name or dot-notation path.

The promise.ts Args type already carries populate and depth through the traversal:

populateFields would be added alongside populate in that args chain.

---

Option B: Extend select to accept objects on relationship fields

Extend the existing select option so that a relationship field can receive an object value meaning "populate this field AND use this as the select for the populated document". A true value retains existing behavior (include the field; population controlled by depth).

const classes = await payload.find({
  collection: 'classes',
  depth: 0,  // default: do not populate anything
  select: {
    teacher: { id: true, name: true },  // populate teacher, return only id + name
    students: true,                      // include students as IDs (depth=0 → no population)
  },
})

Note: select keys are field names on the queried collection, not collection slugs.

Why this is type-compatible today:

SelectIncludeType is already defined as a recursive object:

export type SelectIncludeType = {
  [k: string]: SelectIncludeType | true
}

An object value on a relationship field is already syntactically valid — no type changes are strictly required.

Why sanitizeSelect is safe:

sanitizeSelect already stops recursing when it encounters a relationship or upload field, so the object value is preserved as-is and not misinterpreted as a nested group/tab select at the DB level:

Where the change would live:

relationshipPopulationPromise currently decides whether to populate based solely on depth:

const shouldPopulate = depth && currentDepth <= depth

And uses populateArg?.[relatedCollection.config.slug] for the select of the populated doc:

The required changes:

1. promise.ts passes the field-specific select value (i.e., select[field.name]) down to relationshipPopulationPromise.
2. relationshipPopulationPromise checks: if the field's select value is an object, force shouldPopulate = true and use that object as the select for the populated document (overriding populateArg and defaultPopulate).

Semantics summary:

select value for a relationship field	Behavior
omitted	include field; population controlled by depth
true	include field; population controlled by depth (existing behavior)
false	exclude field entirely (existing behavior)
{ id: true, name: true }	NEW: force-populate field; select only specified sub-fields from populated doc

---

Expected Outcome

With Option B, the motivating query becomes:

const classes = await payload.find({
  collection: 'classes',
  depth: 0,
  select: {
    teacher: { id: true, name: true },
    students: true,
  },
})

Result shape:

{
  "docs": [
    {
      "id": "...",
      "teacher": { "id": "...", "name": "Jane Smith" },
      "students": ["id1", "id2", "id3"]
    }
  ]
}

This eliminates unnecessary database lookups, reduces response size, and avoids N+1 patterns — all without requiring config changes or post-processing.

---

What do you think about the proposed options?