Indexing Custom Case Fields

Overview

If your team frequently filters, searches, or reports on specific custom case fields, enabling indexing on those fields can significantly improve query performance — especially in instances with large test case volumes.

Indexing is opt-in and admin-controlled. You choose which fields benefit from it, and TestRail enforces safeguards to prevent over-indexing from degrading write performance or increasing storage costs.

Prerequisites

• You must have Admin access to manage custom case fields.
• Indexing is only available for eligible field types (see Eligible Field Types below).
• A maximum of 5 custom case fields can be indexed per instance.

Eligible Field Types

Only the following field types support indexing:

• Checkbox
• Date
• Dropdown
• Integer
• Milestone
• User

Field types such as String, Text, Steps, and Result fields do not support indexing and will not display the Enable Indexing option.

Enabling Indexing on a Custom Case Field

1. Go to Administration → Customization → Case Fields.
2. Click Add Case Field to create a new field, or click the name of an existing field to edit it.

3. In the field form, check the Enable Indexing checkbox.

   Note: This option is only visible for eligible field types. If you don't see it, the selected field type does not support indexing.

4. Click Save to apply your changes.

Once saved, TestRail creates the index. For instances with fewer than 200,000 test cases, the index is created immediately. For larger instances, index creation runs as a background job — the field will show as indexed once the job completes.

Disabling Indexing

1. Go to Administration → Customization → Case Fields.
2. Click the field you want to update.
3. Uncheck the Enable Indexing checkbox.
4. Click Save.

TestRail automatically removes the index. If the field is deleted, its index is also removed automatically.

Viewing Indexed Fields

In the Admin → Customization → Case Fields list, indexed fields are marked with an index icon. Hover over the icon to see the tooltip: "This field is indexed for faster queries."

Limits and Trade-offs

Indexing improves read performance for filters and reports, but comes with trade-offs to consider before enabling it:

TestRail enforces a limit of 5 indexed fields per instance to protect system performance. If you attempt to enable indexing on a sixth field, you will see the message: "You can only index up to 5 custom case fields."

Choose the fields your team uses most frequently in filter and reporting workflows for the greatest benefit.

API

The indexing state of a field is exposed in the TestRail API:

• get_case_fields — includes an is_indexed boolean in the response for each field.
• add_case_field — accepts an is_indexed parameter to enable indexing when creating a field programmatically (subject to the same eligibility and limit rules).