Relationships let you select an article's section and view all articles in that section. The model describes the relationship, the database stores the key, and the interface displays a readable record label. Changing the label does not require a new table; changing relationship storage affects the schema.
Creating a relationship
In Content, select the owning entity and click Create relation:
- Many-to-one: a reference to one record of another entity.
- One-to-many view: an inverse list based on an existing reference.
- Many-to-many: related records through a join table.
Choose the target entity, requirement and record label field. Save with Finish. See the article, section and tags example.
Relationship storage
For belongsTo, the foreign key is in the source entity. For example, Article.section uses the article's sectionId. Section's inverse hasMany displays articles with that sectionId; it creates no second foreign key.
ManyToMany has one owner and one join table. sourceField and targetField reference entity primary keys. Change membership on the owner; the inverse view reads the same relationship. The current contract cannot use an alternative unique key instead of the single PK.
Database checks
For belongsTo, enforce=true enables a physical foreign-key constraint. Available actions:
| Event | Options |
|---|---|
| Related-record deletion: on-delete | restrict rejects deletion; setNull clears the reference. |
| Key change: on-update | restrict rejects changes; cascade updates references. |
setNull requires an optional reference with coordinated settings. displayField chooses a user-facing label and does not match keys.
The generator may block changes to an already-generated physical relationship. Inspect the plan and diagnostic: existing data may require a separate migration. Force does not replace that migration.
The inverse side
For manyToMany, inverseName defines the inverse model name. inverseDisplayField enables a readable inverse view, for example Article.title in a Tag card. It displays relationships without editing membership and creates no additional join table.
The admin supports bounded related-record search, permitted filters and Related records. Empty collections, unavailable records and load errors represent different situations. The server checks access to both entities.
Applying changes
Create entities and compatible keys, configure the owner, then add inverse views. Review the plan, Generate and apply migrations.
For a NOT VALID constraint, find and fix violating rows, then run explicit validation. Do not delete data to bypass validation. See migrations.
Interface settings are in Content: relationships; commands for the same model are in CLI: relationships.