feat(content): support indexed custom field sorting

Author: logelog

.changeset/indexed-custom-field-sorting.md

@@ -0,0 +1,6 @@
+---
+"emdash": minor
+"@emdash-cms/admin": minor
+---
+
+Adds opt-in database indexes for scalar custom fields and stable cursor pagination when ordering content lists by those fields.

docs/src/content/docs/concepts/collections.mdx

@@ -216,6 +216,7 @@ Every field supports these properties:
 | `type`         | `FieldType` | One of the 16 field types                    |
 | `required`     | `boolean`   | Whether the field must have a value          |
 | `unique`       | `boolean`   | Whether values must be unique across entries |
+| `indexed`      | `boolean`   | Allow efficient sorting by this field        |
 | `defaultValue` | `unknown`   | Default value for new entries                |
 | `validation`   | `object`    | Type-specific validation rules               |
 | `widget`       | `string`    | Custom widget identifier                     |
@@ -228,6 +229,15 @@ Every field supports these properties:
 	`version`, `live_revision_id`, `draft_revision_id`, `terms`, `bylines`, `byline`.
 </Aside>
 
+Set `indexed: true` when a collection query needs to use a custom field in `orderBy`. Indexes are
+supported for `string`, `url`, `number`, `integer`, `boolean`, `datetime`, `select`, `reference`,
+and `slug` fields. EmDash rejects indexed JSON, rich content, and other non-scalar field types.
+
+<Aside type="caution">
+	Indexes improve ordered reads but use additional storage and add work to content writes. Only index
+	fields that are used for sorting.
+</Aside>
+
 ## Validation rules
 
 The `validation` object varies by field type. Its full shape is:

docs/src/content/docs/reference/field-types.mdx

@@ -386,12 +386,18 @@ All fields support these common properties:
 | `type`         | `FieldType` | Field type (required)               |
 | `required`     | `boolean`   | Require a value (default: false)    |
 | `unique`       | `boolean`   | Enforce uniqueness (default: false) |
+| `indexed`      | `boolean`   | Enable indexed custom-field sorting |
 | `defaultValue` | `unknown`   | Default value for new entries       |
 | `validation`   | `object`    | Type-specific validation rules      |
 | `widget`       | `string`    | Custom widget override              |
 | `options`      | `object`    | Widget configuration                |
 | `sortOrder`    | `number`    | Display order in admin              |
 
+`indexed` is available for scalar fields: `string`, `url`, `number`, `integer`, `boolean`,
+`datetime`, `select`, `reference`, and `slug`. An indexed field can be passed as the `orderBy`
+field in content list queries. Avoid indexing fields that are not used for sorting because every
+index adds storage and write overhead.
+
 ## Reserved field slugs
 
 These slugs are reserved and cannot be used:

docs/src/content/docs/reference/mcp-server.mdx

@@ -351,6 +351,7 @@ Add a new field to a collection's schema. This adds a column to the database tab
 | `validation` | `object` | No | Constraints: `min`, `max`, `minLength`, `maxLength`, `pattern`, `options` |
 | `options` | `object` | No | Widget config: `collection` (for references), `rows` (for textarea) |
 | `searchable` | `boolean` | No | Include in full-text search index |
+| `indexed` | `boolean` | No | Enable indexed sorting by this field |
 | `translatable` | `boolean` | No | Whether this field is translatable (default true) |
 
 Field types: `string`, `text`, `number`, `integer`, `boolean`, `datetime`, `select`, `multiSelect`, `portableText`, `image`, `file`, `reference`, `json`, `slug`.

docs/src/content/docs/themes/seed-files.mdx

@@ -132,6 +132,7 @@ Each collection definition creates a content type in the database:
 | `type`         | `string`  | Yes      | Field type                           |
 | `required`     | `boolean` | No       | Validation: field must have a value  |
 | `unique`       | `boolean` | No       | Validation: value must be unique     |
+| `indexed`      | `boolean` | No       | Enable indexed sorting by this field |
 | `defaultValue` | `any`     | No       | Default value for new entries        |
 | `validation`   | `object`  | No       | Additional validation rules          |
 | `widget`       | `string`  | No       | Admin UI widget override             |

packages/admin/src/components/FieldEditor.tsx

@@ -32,6 +32,32 @@ import { AllowedTypesEditor } from "./AllowedTypesEditor";
 
 const SLUG_INVALID_CHARS_REGEX = /[^a-z0-9]+/g;
 const SLUG_LEADING_TRAILING_REGEX = /^_|_$/g;
+const SEARCHABLE_FIELD_TYPES = new Set<FieldType>([
+	"string",
+	"text",
+	"portableText",
+	"slug",
+	"url",
+]);
+const INDEXABLE_FIELD_TYPES = new Set<FieldType>([
+	"string",
+	"url",
+	"number",
+	"integer",
+	"boolean",
+	"datetime",
+	"select",
+	"reference",
+	"slug",
+]);
+
+function isSearchableFieldType(type: FieldType | null): type is FieldType {
+	return type !== null && SEARCHABLE_FIELD_TYPES.has(type);
+}
+
+function isIndexableFieldType(type: FieldType | null): type is FieldType {
+	return type !== null && INDEXABLE_FIELD_TYPES.has(type);
+}
 
 // ============================================================================
 // Types
@@ -67,6 +93,7 @@ interface FieldFormState {
 	required: boolean;
 	unique: boolean;
 	searchable: boolean;
+	indexed: boolean;
 	minLength: string;
 	maxLength: string;
 	min: string;
@@ -89,6 +116,7 @@ function getInitialFormState(field?: SchemaField): FieldFormState {
 			required: field.required,
 			unique: field.unique,
 			searchable: field.searchable,
+			indexed: field.indexed ?? false,
 			minLength: field.validation?.minLength?.toString() ?? "",
 			maxLength: field.validation?.maxLength?.toString() ?? "",
 			min: field.validation?.min?.toString() ?? "",
@@ -111,6 +139,7 @@ function getInitialFormState(field?: SchemaField): FieldFormState {
 		required: false,
 		unique: false,
 		searchable: false,
+		indexed: false,
 		minLength: "",
 		maxLength: "",
 		min: "",
@@ -138,7 +167,7 @@ export function FieldEditor({ open, onOpenChange, field, onSave, isSaving }: Fie
 		}
 	}, [open, field]);
 
-	const { step, selectedType, slug, label, required, unique, searchable } = formState;
+	const { step, selectedType, slug, label, required, unique, searchable, indexed } = formState;
 	const { minLength, maxLength, min, max, pattern, options } = formState;
 	const setField = <K extends keyof FieldFormState>(key: K, value: FieldFormState[K]) =>
 		setFormState((prev) => ({ ...prev, [key]: value }));
@@ -312,12 +341,8 @@ export function FieldEditor({ open, onOpenChange, field, onSave, isSaving }: Fie
 		}
 
 		// Only include searchable for text-based fields
-		const isSearchableType =
-			selectedType === "string" ||
-			selectedType === "text" ||
-			selectedType === "portableText" ||
-			selectedType === "slug" ||
-			selectedType === "url";
+		const isSearchableType = isSearchableFieldType(selectedType);
+		const isIndexableType = isIndexableFieldType(selectedType);
 
 		const input: CreateFieldInput = {
 			slug,
@@ -326,6 +351,7 @@ export function FieldEditor({ open, onOpenChange, field, onSave, isSaving }: Fie
 			required,
 			unique,
 			searchable: isSearchableType ? searchable : undefined,
+			indexed: isIndexableType ? indexed : undefined,
 			validation: Object.keys(validation).length > 0 ? validation : null,
 		};
 
@@ -441,17 +467,20 @@ export function FieldEditor({ open, onOpenChange, field, onSave, isSaving }: Fie
 								onCheckedChange={(checked) => setField("unique", checked)}
 								label={<span className="text-sm">{t`Unique`}</span>}
 							/>
-							{(selectedType === "string" ||
-								selectedType === "text" ||
-								selectedType === "portableText" ||
-								selectedType === "slug" ||
-								selectedType === "url") && (
+							{isSearchableFieldType(selectedType) && (
 								<Switch
 									checked={searchable}
 									onCheckedChange={(checked) => setField("searchable", checked)}
 									label={<span className="text-sm">{t`Searchable`}</span>}
 								/>
 							)}
+							{isIndexableFieldType(selectedType) && (
+								<Switch
+									checked={indexed}
+									onCheckedChange={(checked) => setField("indexed", checked)}
+									label={<span className="text-sm">{t`Indexed`}</span>}
+								/>
+							)}
 						</div>
 
 						{/* Type-specific validation */}

packages/admin/src/lib/api/schema.ts

@@ -59,6 +59,7 @@ export interface SchemaField {
 	required: boolean;
 	unique: boolean;
 	searchable: boolean;
+	indexed: boolean;
 	defaultValue?: unknown;
 	validation?: {
 		min?: number;
@@ -113,6 +114,7 @@ export interface CreateFieldInput {
 	required?: boolean;
 	unique?: boolean;
 	searchable?: boolean;
+	indexed?: boolean;
 	defaultValue?: unknown;
 	validation?: {
 		min?: number;
@@ -132,6 +134,7 @@ export interface UpdateFieldInput {
 	required?: boolean;
 	unique?: boolean;
 	searchable?: boolean;
+	indexed?: boolean;
 	defaultValue?: unknown;
 	validation?: {
 		min?: number;

packages/admin/tests/components/ContentTypeEditor.test.tsx

@@ -42,6 +42,7 @@ function makeField(overrides: Partial<SchemaField> = {}): SchemaField {
 		required: false,
 		unique: false,
 		searchable: false,
+		indexed: false,
 		sortOrder: 0,
 		createdAt: "2025-01-01T00:00:00Z",
 		...overrides,

packages/admin/tests/components/FieldEditor.test.tsx

@@ -42,6 +42,7 @@ function makeField(overrides: Partial<SchemaField> = {}): SchemaField {
 		required: true,
 		unique: false,
 		searchable: true,
+		indexed: false,
 		sortOrder: 0,
 		createdAt: new Date().toISOString(),
 		...overrides,
@@ -127,6 +128,7 @@ describe("FieldEditor", () => {
 		it("shows searchable checkbox for string type", async () => {
 			const screen = await render(<FieldEditor {...defaultProps} field={stringField} />);
 			await expect.element(screen.getByText("Searchable")).toBeInTheDocument();
+			await expect.element(screen.getByText("Indexed")).toBeInTheDocument();
 		});
 
 		it("shows min/max length validation for string type", async () => {
@@ -162,6 +164,7 @@ describe("FieldEditor", () => {
 			const screen = await render(<FieldEditor {...defaultProps} field={numberField} />);
 			await expect.element(screen.getByLabelText("Min Value")).toBeInTheDocument();
 			await expect.element(screen.getByLabelText("Max Value")).toBeInTheDocument();
+			await expect.element(screen.getByText("Indexed")).toBeInTheDocument();
 		});
 
 		it("does not show searchable for number type", async () => {
@@ -201,6 +204,7 @@ describe("FieldEditor", () => {
 		it("shows searchable checkbox for text type", async () => {
 			const screen = await render(<FieldEditor {...defaultProps} field={textField} />);
 			await expect.element(screen.getByText("Searchable")).toBeInTheDocument();
+			expect(screen.getByText("Indexed").query()).toBeNull();
 		});
 	});
 

packages/core/src/api/schemas/schema.ts

@@ -126,6 +126,7 @@ export const createFieldBody = z
 		options: fieldWidgetOptions,
 		sortOrder: z.number().int().min(0).optional(),
 		searchable: z.boolean().optional(),
+		indexed: z.boolean().optional(),
 		translatable: z.boolean().optional(),
 	})
 	.meta({ id: "CreateFieldBody" });
@@ -142,6 +143,7 @@ export const updateFieldBody = z
 		options: fieldWidgetOptions,
 		sortOrder: z.number().int().min(0).optional(),
 		searchable: z.boolean().optional(),
+		indexed: z.boolean().optional(),
 		translatable: z.boolean().optional(),
 	})
 	.meta({ id: "UpdateFieldBody" });
@@ -208,6 +210,7 @@ export const fieldSchema = z
 		options: z.record(z.string(), z.unknown()).nullable(),
 		sortOrder: z.number().int(),
 		searchable: z.boolean(),
+		indexed: z.boolean(),
 		translatable: z.boolean(),
 		createdAt: z.string(),
 		updatedAt: z.string(),