Entity Associations

Entities can have relations. You express them as follows:

Association	Type	Description
assocTo	[EntityName\|AssocToConfig]	has-one relationship to another entity
assocToMany	[EntityName\|AssocToManyConfig]	has-many relationship with references to the other entity at this
assocFrom	[EntityName\|AssocFromConfig]	has-many as relationship to another entity as opposite site of a has-one or has-many relationship with references at the other entity
assocBy	[EntityName\|AssocByConfig]	has-one as relationship to another entity as opposite site of a has-one relationship with references at the other entity
assocThrough	[EntityName\|AssocFromConfig]	has-one as relationship to another entity as opposite site of a has-one relationship with references at the other entity

Configuration

All associations are arrays of the respective type. If you do have only one association you can simply skip the array notation. Just adding the entityName of the other entity of this entity's association is in fact a (suggested) shortcut for { type: 'OtherEntity'}. So the following two expressions are equivalent:

entity:    
  Car: 
    attributes: 
      brand: string!
    assocTo: Trailer

entity:    
  Car: 
    attributes: 
      brand: string!
    assocTo: 
      - type: Trailer

assocTo

Defines a to one association from one entity to another. With the foreign key on this entity.

[Car] -----1- [Driver]

Configuration

Option	Type	Default	Description
type	`string`		the another entity
required	`boolean`	`false`	if `true` validates the existence of the other entity's foreignKey in the entity's input (not the existence of the other entity's item with that `id`)
delete	`vanish`\|`prevent`\|`cascade`	`vanish`	see delete policy below
input	`boolean`	`false`	if `true` adds the input of the other entity's attributes to this entity's `createInput` and creates an item of the other entity on the fly.
fieldName	`string`	`typeQueryName` of the referenced entity	the name of the associated item in this entity item
foreignKeyField	`string`	`foreignKey` of the referenced entity	name of the field that holds the foreignKey of the associated entity

Configuration

entity:    
  Car:    
    assocTo: Driver
  Driver:
    attributes:
      name: String!

Resolved

entity:    
  Car:    
    assocTo: 
    - type: Driver
      required: false
      input: false
      delete: vanish
      foreignKeyField: driverId
      fieldName: driver
  Driver:
    attributes:
      name: String!

Delete Policy

If you delete an item of this Entity it has the following effects on the associated entity:

Option	Description
vanish	no effect; if the other entity has an `assocFrom` association, it would simply no longer include the deleted item
prevent	if the item that should be deleted has a reference to an existing item of the other entity (foreignKeyId is not null and there is an other entity item with this id) - the deletion of this item will be prevented. The `deleteMutation` would return a string with the entity that prevents the deletion
cascade	if the item that should be deleted has a reference to an existing item of the other entity (foreignKeyId is not null and there is an other entity item with this id) this item (of the other entity) will also be deleted.

Input & Validation

An assocTo relation adds an input field with the name foreignKeyField to the input type of the entity. ActiveQL will validate if any id belongs to an existing entity item.

assocToMany

Defines a to many association from one entity to another where the ids of the other entity are stored in the entity that holds this association.

[Car] -----*- [Driver]

Configuration

Option	Type	Default	Description
type	`string`		the another entity
delete	`vanish`\|`prevent`\|`cascade`	`vanish`	see delete policy below
fieldName	`string`	`typesQueryName` of the referenced entity	the name of the associated items in this entity item
foreignKeyField	`string`	`foreignKeys` of the referenced entity	name of the field that holds the foreignKeys of the associated entity

Configuration

entity:    
  Car:    
    assocToMany: Driver
  Driver:
    attributes:
      name: String!

Resolved

entity:    
  Car:    
    assocToMany: 
    - type: Driver      
      delete: vanish
      foreignKeyField: driverIds
      fieldName: drivers
  Driver:
    attributes:
      name: String!

Delete Policy

If you delete an item of this Entity it has the following effects on the associated entity:

Option	Type	Description
vanish	default	no effect; if the other entity has an `assocFrom` association, this would simply no longer include the deleted item
prevent		if the item that should be deleted has references to an existing item of the other entity (foreignKeyId is not null and there is an other entity item with this id) - the deletion of this item will be prevented. The `deleteMutation` would return a string with the entity that prevents the deletion
cascade		if the item that should be deleted has any reference to an existing item of the other entity (foreignKeyId is not null and there is an other entity item with this id) this item (of the other entity) will also be deleted.

Input & Validation

An assocToMany relation adds an input field with the name foreignKeyField to the input type of the entity. ActiveQL will validate if any id belongs to an existing entity item.

assocFrom

Defines a to many association from one entity to another where the id of the entity that holds this association is stored in the other entity. This association needs a assocTo or assocToMany in the opposite entity.

[Car] -*-----1- [Driver]

Configuration

Option	Type	Default	Description
type	`string`		the another entity
delete	`prevent`\| `nullify` \| `cascade` \| `ignore`	`nullify` or `prevent` when opposite assocTo is `required`	see delete policy below
fieldName	`string`	`typesQueryName` of the referenced entity	the name of the associated items in this entity item
foreignKeyField	`string`	`foreignKey` of the this entity	name of the field that holds the foreignKey of the this entity at the associated entity
through	`boolean`	`false`	marks this as a many-to-many association, see `assocThrough association`

Configuration

entity:    
  Car:    
    assocTo: Driver
  Driver:
    assocFrom: Car

Resolved

entity:    
  Car:    
    assocTo: Driver      
  Driver:
    assocFrom: 
      type: Car
      delete: nullify
      fieldName: cars
      foreignKeyField: driverId
      through: false

Opposite AssocTo / AssocToMany

An assocFrom relation needs an opposite assocTo / assocToMany relationship. You cannot add or edit anything to this relationship on the assocFrom side.

Delete Policy

If you delete an item of this Entity it has the following effects on the associated entity:

Option	Type	Description
nullify	any item of the other entity that holds reference to the item that should be deleted will be updated so the foreignKey on this item will be `null` thus preventing any reference to an non-existing item
prevent	if there is any item of the other entity holding a reference to the item that should be deleted, the deletion of this item will be prevented. The `deleteMutation` would return a string with the entity that prevents the deletion
cascade	any item of the other entity holding a reference to the item that should be deleted, will also be deleted.
ignore	any item of the other entity holding a reference to the item will left untouched, keeping an invalid reference in this item (this should be avoided)

assocBy

Defines a to one association from one entity to another where the id of the entity that holds this association is stored in the other entity. This association needs a assocTo in the opposite entity. Think of this as the same as an assocFrom association but with only one item referencing to this entity instead of many.

[Car] -0...1-------1- [Driver]

Configuration

Option	Type	Default	Description
type	`string`		the another entity
delete	`prevent`\| `nullify` \| `cascade` \| `ignore`	`nullify` or `prevent` when opposite assocTo is `required`	see delete policy below
fieldName	`string`	`typeQueryName` of the referenced entity	the name of the associated item in this entity item
foreignKeyField	`string`	`foreignKey` of the this entity	name of the field that holds the foreignKey of the this entity at the associated entity

Configuration

entity:    
  Car:    
    assocTo: Driver
  Driver:
    assocBy: Car

Resolved

entity:    
  Car:    
    assocTo: Driver      
  Driver:
    assocBy: 
      type: Car
      delete: nullify
      fieldName: car
      foreignKeyField: driverId

Delete Policy

If you delete an item of this Entity it has the following effects on the associated entity:

Option	Type	Description
nullify	default	any item of the other entity that holds reference to the item that should be deleted will be updated so the foreignKey on this item will be `null` thus preventing any reference to an non-existing item
prevent		if there is any item of the other entity holding a reference to the item that should be deleted, the deletion of this item will be prevented. The `deleteMutation` would return a string with the entity that prevents the deletion
cascade		any item of the other entity holding a reference to the item that should be deleted, will also be deleted.
ignore	any item of the other entity holding a reference to the item will left untouched, keeping an invalid reference in this item (this should be avoided)

Opposite AssocTo / AssocToMany

An assocFrom relation needs an opposite assocTo / assocToMany relationship. You cannot add or edit anything to this relationship on the assocFrom side.

assocThrough

Defines a many to many association from one entity to another where the id of the entities are hold in an extra association entity.

[Car] -*-----*- [Driver]

Configuration

Option	Type	Default	Description
type	`string`		the another entity
delete	`prevent`\| `nullify` \| `cascade` \| `ignore`	`nullify` or `prevent` when opposite assocTo is `required`	see delete policy below
fieldName	`string`	`typesQueryName` of the referenced entity	the name of the associated items in this entity item
foreignKeyField	`string`	`foreignKey` of the this entity	name of the field that holds the foreignKey of the this entity at the associated entity
through	`boolean`	`true`	marks this as a many-to-many association

Configuration

entity:    
  Car:    
    assocFrom: 
    - type: Driver
      through: true
  Driver:
    assocFrom: 
    - type: Car
      through: true

Resolved

entity:    
  Car:    
    assocFrom: Driver
    - type: Driver
      through: true
      fieldName: drivers
      foreignKeyField: driverIds      
  Driver:
    assocFrom: 
    - type: Car
      through: true
      fieldName: cars
      foreignKeyField: carIds
      
  CarDrivers: 
    assocTo: 
    - Car
    - Driver

Input & Validation

Since there is no opposite assocTo or assocToMany relation both sides of an assocThrough relation get a field of the name foreignKeyField to its input type. ActiveQL will validate if any id belongs to an existing entity item.

Attribute configuration Seed configuration