Skip to main content

Build a relational projection

Relational projections compose one search document per root record from catalog-backed relations. They do not execute arbitrary user SQL.

Prerequisites​

  • ENABLE_RELATIONAL_PROJECTIONS=true.
  • A validated PostgreSQL source.
  • A collection reserved for the projection.
  • Editor, admin, or owner role.
  • Stable root identity and suitable indexes for every join path.

Create the draft​

  1. Open Data Sources and select the PostgreSQL source.
  2. Choose Create projection.
  3. Select the root dataset and its stable identity field(s).
  4. Add related datasets using discovered foreign-key paths.
  5. Select scalar fields and define bounded one-to-one or aggregated one-to-many output.
  6. Select the target collection.
  7. Save the draft.

Validate and preview​

Run Validate to compare the draft with the live catalog. Indexlume records a schema fingerprint and reports missing keys, unsafe relationships, invalid paths, or mapping conflicts. Resolve every blocking issue.

Run Preview with a small limit. Check document IDs, nested/aggregated fields, null behavior, and Typesense field types against representative records.

Publish​

Publishing requires the validated version ID and explicit eventual-consistency acceptance. The version becomes immutable, the collection points to it, and a snapshot job is queued. Monitor Indexing Jobs until completion, then search representative records.

Updates and hard deletes​

Root and dependency changes are processed with checkpoint-safe replay. Supported soft-delete fields can remove documents during sync. Otherwise, use reconciliation preview, inspect the candidate set, and submit the matching confirmation token before deletion is applied.

warning

Reconciliation is intentionally separate from incremental sync. Never automate confirmation without reviewing the candidate count and deployment health.