---
title: "Database Indexes"
aliases: [payload-indexes, payload-db-indexes, compound-indexes]
tags: [payloadcms, database, performance, mongodb, postgres]
sources: [raw/database__indexes.md]
created: 2026-05-15
updated: 2026-05-15
---

## Overview

Database indexes let the DB engine locate records without full-collection scans. Add `index: true` to any field you frequently filter or sort on.

`id`, `createdAt`, and `updatedAt` are indexed by default.

## Single-Field Index

```ts
{
  name: 'title',
  type: 'text',
  index: true,
}
```

## Compound Indexes

Index multiple fields together — useful when queries filter/sort by several fields at once.

```ts
export const MyCollection: CollectionConfig = {
  fields: [...],
  indexes: [
    {
      fields: ['title', 'createdAt'],
      unique: true, // optional: enforce uniqueness on the combination
    },
  ],
}
```

Defined at the **Collection** level via the `indexes` array, not on individual fields.

## Unique Fields

`unique: true` creates a collection-wide unique index — no two documents can share the same value.

### Gotcha: `unique` on nested array/blocks fields

- Creates a unique index on the **dotted path** (e.g. `items.key`) across the entire collection.
- This is **not** per-document uniqueness — it prevents any two documents from having the same value at that path.
- **MongoDB + `required: true` on a nested unique field:** creates a non-sparse index. Documents without the array share `null`, causing a duplicate key error on the second save. Fix: remove `required: true` to restore sparse index.
- For within-document array uniqueness → use a custom `validate` function on the array field instead.

## Localized Fields and MongoDB

- `index: true` or `unique: true` on a localized field → MongoDB creates one index **per locale path** (`slug.en`, `slug.da-dk`, etc.).
- Many locales + many indexed fields can hit MongoDB's per-collection index limit.
- Workaround: add custom MongoDB indexes for specific locale paths via migration script.

## Key Takeaways

- Add `index: true` to fields used in frequent `where` filters or `sort` operations.
- Use Collection-level `indexes: [{ fields: [...] }]` for compound indexes.
- `unique: true` = collection-wide uniqueness, not per-document array row uniqueness.
- MongoDB: nested `unique` + `required` = non-sparse index → duplicate-null bug. Remove `required` to fix.
- Localized fields on MongoDB: one index per locale — watch the index limit with large locale sets.
- MongoDB Compass is the recommended GUI for visualizing and managing indexes.

## Related

- [[wiki/payloadcms/collection-config|Collection Config]] — `indexes` option lives here
- [[wiki/payloadcms/queries|Queries]] — where operators and sort that benefit from indexes
- [[wiki/payloadcms/localization|Localization]] — localized fields context
- [[wiki/payloadcms/production|Production & Performance]] — broader performance patterns

## Sources

- `raw/database__indexes.md` — https://payloadcms.com/docs/database/indexes
