Skip to main content
Catalog upgrades refresh catalog rows, and a direct API edit marks a row dirty so upgrades skip it from then on, including fields you never touched. An overlay avoids both: it is a sparse patch you own, stored next to the pristine catalog row and merged over it when Relay builds its in-memory snapshot. Routing sees the merged result; catalog upgrades keep updating every field you did not override. Overlays apply to models. Use one to pin a context window, add an alias, or add tags to a catalog model.

​
How it works

The merge follows JSON merge patch rules:
  • A scalar or array in the patch replaces the template’s value.
  • A nested object merges field by field.
  • null removes the field.
  • aliases and tags are the exception: the patch’s entries are added to the template’s, so a catalog upgrade can still add aliases or tags. To remove one the template ships, edit the model directly.
  • enabled cannot be set through an overlay; enable or disable the model with a direct edit.
Because the effective row lives only in memory, reading the model through the CRUD endpoints or the database shows the template. The overlay endpoint returns the template, your patch and the effective spec in one response.

​
Managing an overlay

The overlay is a sub-resource of the model on the control API:
patch holds spec fields directly, not a spec wrapper; metadata cannot be patched.
PUT replaces the whole patch; it does not merge with the previous one. Send every field you want overridden. A PUT whose result would not be a valid model is rejected with 400.
Setting an overlay counts as an edit of the model, so it follows the same rules: the governance:model setting and, under RBAC, the caller’s permissions.

​
When the template changes underneath

If a catalog upgrade changes the template so that your patch no longer produces a valid model, Relay serves the template unchanged and the overlay response reports quarantined: true with a quarantineReason. Fix the patch with a new PUT, or delete it. Overlays are rows in Postgres, so backing up the database captures them. relay export includes them in an unscoped export, and relay apply can write them back.