CREATE ASSOCIATION

Synopsis

CREATE [ OR MODIFY ] ASSOCIATION module.name
    FROM from_module.from_entity
    TO to_module.to_entity
    TYPE { Reference | ReferenceSet }
    [ OWNER { Default | Both | Parent | Child } ]
    [ ON DELETE { SET NULL | CASCADE | RESTRICT } [ ERROR MESSAGE 'text' ] ]

Description

CREATE ASSOCIATION defines a relationship between two entities in the domain model.

The FROM entity is the side that owns the foreign key (in database terms). The TO entity is the side being referenced. For a typical one-to-many relationship like “a Customer has many Orders,” the FROM side is the parent entity (Customer) and the TO side is the child entity (Order).

Two association types are supported:

Reference – a many-to-one relationship. Each object on the TO side references at most one object on the FROM side. Stored as a foreign key column in the TO entity’s database table.
ReferenceSet – a many-to-many relationship. Objects on both sides can reference multiple objects on the other side. Stored in a separate junction table.

The OWNER clause controls which side of the association can modify the relationship:

Owner	Description
`Default`	The default owner (child/TO side) can set and clear the reference
`Both`	Both sides can modify the association
`Parent`	Only the FROM side can modify the association
`Child`	Only the TO side can modify the association

The ON DELETE clause controls what happens when an object on the FROM side is deleted:

Action	Description
`SET NULL`	Delete the object and set references to null (the default)
`CASCADE`	Delete the object and all associated objects on the TO side
`RESTRICT`	Refuse the delete while anything still references the object; `ERROR MESSAGE '…'` is the text the user sees

The older DELETE_BEHAVIOR clause (DELETE_BUT_KEEP_REFERENCES, DELETE_AND_REFERENCES / CASCADE, DELETE_IF_NO_REFERENCES / PREVENT) still parses with the same meaning, but is deprecated (MDL-DEPR022); mxcli fmt --upgrade rewrites it.

If OR MODIFY is specified, the statement is idempotent: if the association already exists, it is updated to match the new definition.

A documentation comment (/** ... */) placed before the statement is preserved as the association’s documentation.

Parameters

OR MODIFY: Makes the statement idempotent. If the association already exists, its properties are updated. Without this clause, creating a duplicate association is an error.
module.name: The qualified name of the association in the form Module.AssociationName. By convention, association names follow the pattern Module.Child_Parent or Module.EntityA_EntityB.
FROM from_module.from_entity: The entity on the “from” side of the relationship. This is the entity that owns the foreign key in the database. In a one-to-many relationship, this is typically the “one” (parent) side.
TO to_module.to_entity: The entity on the “to” side of the relationship. In a one-to-many relationship, this is typically the “many” (child) side that holds the reference.
TYPE: Either Reference (many-to-one) or ReferenceSet (many-to-many).
OWNER: Which side can modify the association. Defaults to Default if omitted.; Between a persistent and a non-persistent entity, Mendix allows one shape only: FROM the non-persistent entity, with owner Default. A persistent FROM end or OWNER Both there fails the build with CE0001, so mxcli check and exec refuse it (MDL-ASSOC01). ALTER ASSOCIATION … SET OWNER Both is refused the same way.; Under OWNER Both the association is a member of the TO entity too, so its access rules get an entry for it — in the TO entity’s module, for a cross-module association. CREATE OR MODIFY that moves the TO end, or changes the owner, reconciles the old and the new TO module’s rules.
ON DELETE: What happens to associated objects when a FROM-side object is deleted. If omitted, references are kept (the default Mendix behavior).

Examples

Many-to-one: Order belongs to Customer

CREATE ASSOCIATION Sales.Order_Customer
    FROM Sales.Customer
    TO Sales.Order
    TYPE Reference
    OWNER Default
    ON DELETE SET NULL;

Many-to-many: Order has Products

CREATE ASSOCIATION Sales.Order_Product
    FROM Sales.Order
    TO Sales.Product
    TYPE ReferenceSet
    OWNER Both;

Cascade delete: Invoice deleted with Order

/** Invoice must be deleted when its Order is deleted */
CREATE ASSOCIATION Sales.Order_Invoice
    FROM Sales.Order
    TO Sales.Invoice
    TYPE Reference
    ON DELETE CASCADE;

Idempotent with OR MODIFY

CREATE OR MODIFY ASSOCIATION Sales.Order_Customer
    FROM Sales.Customer
    TO Sales.Order
    TYPE Reference
    OWNER Default;

Cross-module association

CREATE ASSOCIATION HR.Employee_Department
    FROM HR.Department
    TO HR.Employee
    TYPE Reference;

Notes

The naming convention Module.Child_Parent reflects that the child (TO) entity holds the reference to the parent (FROM) entity. This can be counterintuitive – the FROM entity is the parent, and the TO entity is the child.
Internally, Mendix stores the FROM entity pointer as ParentPointer and the TO entity pointer as ChildPointer. These BSON field names are inverted relative to what you might expect.
Entity access rules for associations (member access) must only be added to the FROM entity. Adding them to the TO entity triggers validation errors.

mxcli Documentation