Indexes - Payload — ContextQMD

Database indexes are a way to optimize the performance of your database by allowing it to quickly locate and retrieve data. If you have a field that you frequently query or sort by, adding an index to that field can significantly improve the speed of those operations.

When your query runs, the database will not scan the entire document to find that one field, but will instead use the index to quickly locate the data.

To index a field, set the index option to true in your field's config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  fields: [
    // ...
    {
      name: 'title',
      type: 'text',
      // highlight-start
      index: true,
      // highlight-end
    },
  ],
}

<Banner type="info"> **Note:** The `id`, `createdAt`, and `updatedAt` fields are indexed by default. </Banner> <Banner type="success"> **Tip:** If you're using MongoDB, you can use [MongoDB Compass](https://www.mongodb.com/products/compass) to visualize and manage your indexes. </Banner>

Compound Indexes

In addition to indexing single fields, you can also create compound indexes that index multiple fields together. This can be useful for optimizing queries that filter or sort by multiple fields.

To create a compound index, use the indexes option in your Collection Config:

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  fields: [
    // ...
  ],
  indexes: [
    {
      fields: ['title', 'createdAt'],
      unique: true, // Optional, if you want the combination of fields to be unique
    },
  ],
}

Unique Fields

Setting unique: true on a field creates a collection-wide database unique index on that field's path. This means no two documents in the collection can share the same value for that field.

<Banner type="warning"> **Using `unique` on fields nested inside `array` or `blocks`** creates a collection-wide unique index on the dotted path (e.g. `items.key`). This is **not** the same as enforcing uniqueness within a single document's array rows — it prevents *any two documents* from having the same value at that path.

Additionally, on MongoDB, if the nested field also has required: true, Payload creates a non-sparse unique index. Documents that do not contain the array will share a null value at that path, causing a duplicate key error when saving a second document without the array. Removing required: true restores the sparse index and avoids this collision.

If you need to enforce uniqueness within a document's array rows (e.g. no duplicate keys in the same document), use a custom validate function on the array field instead.

</Banner>

Localized fields and MongoDB indexes

When you set index: true or unique: true on a localized field, MongoDB creates one index per locale path (e.g., slug.en, slug.da-dk, etc.). With many locales and indexed fields, this can quickly approach MongoDB's per-collection index limit.

If you know you'll query specifically by a locale, you can insert a custom MongoDB index for the locale path manually or with a migration script.