> For the complete documentation index, see [llms.txt](https://doc.telosys.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.telosys.org/models/link.md).
# Link
A **link** is a reference from an entity to another entity. It's a relationship with a cardinality (one to many, many to one, etc).
The syntax is similar to that of attributes; \
simply replace the neutral type with the **name of the referenced entity**.
To reference a **collection** of entities just add "**\[ ]**" after the entity name.
Examples:
```
department : Department ; // link = single Department
```
```
items : PurchaseOrderItem[] ; // link = collection of PurchaseOrderItem
```
### Cardinalities
#### "Many To One"
Example with 2 entities "**Employee**" and "**Department**"
* a Department can have many Employees
* each **Employee** works in **one Department**
So we have a "**Many-to-One"** relationship from Employee to Department\
**N employees → 1 department**
```
Employee {
department : Department ; // Many-to-One due to single reference to Department
}
```
When using a **single reference** to an entity the cardinality is "**Many-to-One**" **by default**.
#### "One To One"
Example with 2 entities "**Employee**" and "**Computer**"
* each Employee is assigned one Computer
* each Computer is assigned to one Employee
So we have a "**One-To-One**" relationship between Employee and Computer
To indicate that this is a "**one-to-one**" relationship, add the annotation **@OneToOne**
```
Employee {
computer : Computer { @OneToOne } ; // One-to-One due to single ref and "@OneToOne"
// Owning-side (with default FK)
}
```
```
Computer {
employee : Employee { @OneToOne @MappedBy(computer) } ;
// Inverse-side due to "@MappedBy"
}
```
#### "One To Many"
Example with 2 entities "**PurchaseOrder**" and "**PurchaseOrderItem**"
* each PurchaseOrder has many PurchaseOrderItem
* each PurchaseOrderItem is assigned to a single PurchaseOrder
So we have a "**One-to-Many"** relationship from PurchaseOrder to PurchaseOrderItem
```
PurchaseOrder {
items : PurchaseOrderItem[] ;
// One-to-Many due to "[ ]" (many references)
// mappedBy will be inferred from the owning side if possible
}
```
```
PurchaseOrder {
items : PurchaseOrderItem[] { @MappedBy(purchaseOrder) } ;
// One-to-Many due to "[ ]" (many references)
// mappedBy explicitly defined
}
```
#### "Many To Many"
Example with 2 entities "**Employee**" and "**Skill**"
* an Employee can have many Skills
* a Skill can be assigned to several Employees
So we have a "**Many-toMany**" relationship between Employee and Skill
In a relational database, a "**join table**" (association table) is required to represent a Many-to-Many relationship. In the Telosys model, this "join table" is materialized by a "**join entity**" (a special entity that allows the "join table" to be represented in the model).
```
@JoinEntity // marks this entity as a "join entity" (just for relationship)
EmpSkill {
empId : int { @Id @FK(Employee) @DbName(EMP_ID) }; // 1rst Foreign Key
skillId : long { @Id @FK(Skill) @DbName(SKILL_ID)}; // 2nd Foreign Key
}
```
```
Employee {
skills : Skill[] { @ManyToMany @LinkByJoinEntity(EmpSkill) };
// use @LinkByJoinEntity on the "owning-side" of the relationship
}
```
```
Skill {
employees : Employee[] { @ManyToMany @MappedBy(skills) @FetchTypeEager };
// use @MappedBy on the "inverse-side" of the relationship (like with JPA)
}
```
### Links and database joins
#### Link based on an explicit Foreign Key
When a Foreign Key is explicitly defined (with a name) in the entity (see the @FK annotation), \
it can be used in the link definition using **@LinkByFK(*****foreignKeyName*****)** .
Example
```
subjectId : int { @FK(FK_TICKET_SUBJECT, Subject) } ; // the Foreign Key
subject : Subject { @LinkByFK(FK_TICKET_SUBJECT) }; // the link based on FK
```
#### Link based on model attributes
When a foreign key is not explicitly defined in the entity, but all the attributes usable for the link are defined, it is possible to use them directly. To do this, use **@LinkByAttr(*****attributeName(s)*****)**
Example
```
empId : int ; // the attribute (its database column) usable for the link
employee : Employee { @LinkByAttr(empId) } ;
```
#### Link based on a join table
For a **Many-to-Many** relationship a join table is required, in the model this join table is materialized by a "**join entity**". The link "owning side" is defined with **@LinkByJoinEntity(*****joinEntityName*****)**
Example
skills : Skill[] { @ManyToMany @LinkByJoinEntity(EmpSkill) };
### Other annotations for links
* **@Insertable(*****true*****|*****false*****)** and **@Updatable(*****true*****|*****false*****)**
* **@FetchTypeEager** and **@FetchTypeLazy**
* **@Cascade(*****type*****)**
* **@OrphanRemoval**
See [Annotations](/models/annotations.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://doc.telosys.org/models/link.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.