Managed indexes
Facet manages its own PostgreSQL indexes. When an author declares that a field is filterable or sortable, Facet computes the indexes that serve that declaration, builds them online, and drops them when the field changes. Your job as the operator is to watch the status surface and retry the rare failure.
When to use this
Section titled “When to use this”Check the index surface when:
- You check index health after a schema change or a domain import.
- An index build failed and you need it back.
- You want to know why an index exists or why one does not.
Before you start
Section titled “Before you start”- The status route needs a wildcard
readpermission on*.*— the same rule as the global audit log. - The retry command runs from a host that reaches the database.
- Index DDL is safe to run while the server is live. It never blocks reads or writes on the documents.
1. Read the index status
Section titled “1. Read the index status”Open the index status page under Configure → Platform, or call the route:
curl -s -H "Authorization: Bearer $FACET_API_KEY" \ "https://facet.localhost:3443/Api/Indexes?filters[status__eq]=error&filters[domain__eq]=hr"One row per managed index carries: id, domain, doc_type,
field_name, index_type, index_name, status, error_message,
created_at, and updated_at. The status lifecycle:
pending— the build is queued or running.active— the index is built and serving queries.error— the build failed.error_messageholds the reason.dropped— the field no longer wants the index.
Filterable fields: domain, doc_type, status, field_name. Sortable:
the same set plus index_type, created_at, updated_at.
2. Retry failed builds
Section titled “2. Retry failed builds”facet index:retry --domain hr --dry-run # print the plan, run nothingfacet index:retry --domain hr # run the retriesThe command retries two kinds of rows:
-
rows in
errorstatus, and -
pendingrows stale for more than 10 minutes — the shape a dead build process leaves behind.A fresh
pendingrow belongs to a live build in the running server, so the command never touches it. Each row is re-checked against the current doctype definition: a still-wanted index is rebuilt; a field that no longer exists drops the row. Rows are independent — one failure does not stop the others. The command exits0when every attempt succeeded and1when at least one failed.
Explanation
Section titled “Explanation”Where indexes come from
Section titled “Where indexes come from”The planner reads each field’s declared filters capabilities —
equality, comparison, text_search, interval, membership,
currency. One capability maps to one index family:
| Declared capability | Index created |
|---|---|
equality or comparison on a scalar field |
One B-tree |
text_search alone |
One GIN trigram |
equality / comparison plus text_search |
Two indexes: B-tree and GIN trigram |
membership on an array field |
One GIN JSONB |
interval on period / dateperiod |
One GiST range index |
A field with unique: true gets a unique B-tree with no capability needed.
A reference field always gets one B-tree, whatever its capabilities
declare. Computed, write-only, read-only, and free-form object fields take
no index.
Every managed index is partial. The WHERE clause scopes it to one domain,
one doctype, and live rows, so each index stays small:
WHERE domain = 'hr' AND doc_type = 'Employee' AND deleted_at IS NULLWhy failures are rare
Section titled “Why failures are rare”Builds run as CREATE INDEX CONCURRENTLY in background fibres, so the
doctype save itself always succeeds. A global advisory-lock gate serializes
all managed DDL across fibres and processes, which prevents the deadlock
two concurrent builds would otherwise hit. Deadlocks that still occur retry
with backoff: 3 attempts at runtime, 5 in index:retry.
Example
Section titled “Example”After a large domain import, one index failed. Recover it:
# What failed?curl -s -H "Authorization: Bearer $FACET_API_KEY" \ "https://facet.localhost:3443/Api/Indexes?filters[status__eq]=error"
# Read error_message on the row, then plan the retry:facet index:retry --domain crm --dry-run
# Run it, then confirm the row is active:facet index:retry --domain crmThe row moves pending → active, and the doctype’s list filters use the
index again.
Troubleshooting
Section titled “Troubleshooting”A row stays pending for a long time.
A big table builds for a while; CONCURRENTLY scans the whole table. Past
10 minutes of staleness, index:retry treats the row as dead and rebuilds
it.
An error row names a deadlock.
The build retried and gave up. Run facet index:retry for the domain. It
drops any half-built leftover first, then rebuilds.
A field declares filters but has no index row.
The field type takes no index for that capability — for example
membership is valid on arrays only, and color takes no index. Check
Field types for the capability rules.
A doctype save succeeded but a new index is missing.
The build runs in the background after the save. Re-check the status route before you investigate.
A dropped row reappears.
The field is back in the doctype definition, or the definition was re-imported. The planner wants the index again, so a new build starts.
Related
Section titled “Related”- Field types — where the
filterscapabilities come from. - Identifiers and unique constraints — the unique B-tree path.
- Evolving a schema — the schema changes that trigger builds.
- Bootstrap and CLI tasks — the CLI surface around
index:retry. - Internals on GitHub: index-management.md, cli.md.