Defining custom indexes

The Distribution API supports a predefined set of request patterns that can be used by any consuming application to handle most common scenarios. You can extend its built-in filtering capabilities by defining custom distribution indexes to support business-specific workflows. This ensures that only authorized query patterns are allowed.

Why define custom indexes?

To filter content using the Distribution API, all query parameters must correspond to fields included in at least one index defined on the target distribution collection in MongoDB.
For example, to retrieve all stories where the title is set to Test, you might use the following request:

/v2/content/en-us/stories?title=Test

Before executing the query, the Distribution API checks if the collection en-us__stories contains an index for the title field.
If the field is indexed, the request is accepted. Otherwise, it will be rejected with an error similar to:
Only indexed fields can be used as query filters.

Note: This mechanism checks whether at least one index matches the query. However, this does NOT guarantee that your query will actually hit an index!

It's your responsibility to analyze query patterns and define indexes that best suit your use cases.

For example, if your only index is a compound index defined as:

{ "description": 1, "title": 1 }

DAPI may allow the query, but MongoDB will not use this index because the field title is not a prefix of the compound index.
A prefix in MongoDB indexing refers to a subset consisting of one or more keys starting from the beginning of the index key pattern.

For more details, refer to the official MongoDB documentation.

How to define custom distribution indexes

To simplify index management across all supported languages, FORGE allows you to define indexes using a JSON schema via the Administration panel, under Distribution Indexes.

FORGE supports two index types:

• Extended fields
• System fields

Each behaves slightly differently in how they’re declared and used in filtering.

Indexes on extended fields

To define an index on an extended field, use the following JSON schema structure:

{
  "type": "object",
  "index": {
    "indexVersion": 1,
    "key": {
      "fields.yourExtendedField": [index_type]
    }
  }
}

To define a compound index, specify multiple fields:

{
  "type": "object",
  "index": {
    "indexVersion": 1,
    "key": {
      "fields.yourExtendedField1": [index_type],
      "fields.yourExtendedField2": [index_type]
    }
  }
}

Valid values for index_type:

• "1" — ascending order
• "-1" — descending order
• "text" — full-text index
• "2dsphere" — geospatial index (see MongoDB docs)

Note: Field names are case-sensitive and must exactly match the name defined in the Extended Fields section of the FORGE Administration panel.

Recommendation: Use camelCase for all extended field names to ensure consistency with the output schema served by the Distribution API.

Indexes on system fields

To define an index on system fields, use the following JSON schema:

{
  "type": "object",
  "index": {
    "indexVersion": 1,
    "key": {
      "system.content": [index_type]
    }
  }
}

To define a compound system index:

{
  "type": "object",
  "index": {
    "indexVersion": 1,
    "key": {
      "system.systemField1": [index_type],
      "system.systemField2": [index_type],
      "system.systemField3": [index_type]
    }
  }
}

Valid values for index_type are the same as for extended fields:

• "1" — ascending
• "-1" — descending
• "text" — text-based
• "2dsphere" — geospatial (MongoDB docs)

Important: Field names are persisted in camelCase and index definitions must match this casing exactly.

Important Note:
When defining indexes on a system field related to tags (e.g. extraTags), the tag values must follow camelCase convention. If not, indexing will fail, and filters will not work as expected.

Invalid example:

{
  "myExtraTags": [
    { "notCamelCase": "value1" },
    { "NotCamelCase": "value2" }
  ]
}

Since the Distribution API uses string-based filtering, all values must be indexed as strings.
If you use another type (e.g., numbers), the query will fail because DAPI cannot infer the correct type conversion.

How to apply custom indexes

Once your index definition is complete, follow these steps to apply it:

1. Stop all instances of the Distribution Indexer service.
2. Rebuild indexes via the back-office interface.
3. Restart the Distribution Indexer service after rebuilding completes.

Note:
Defining many indexes in MongoDB can affect performance, especially during writes.
MongoDB enforces limits on index key size, name length, and the number of indexes per collection.
For more details, refer to the MongoDB index limits and official documentation.