Define Relationships Between Entities
Learn how to define and manage one-to-one, one-to-many, and self-relation relationships between entities in Amplication.
Relationships are the links that connect your entities, allowing you to model complex data structures and build sophisticated resources. This guide will walk you through creating and managing entity relationships, enabling you to establish clear connections between your data models.
Amplication Relationships feature is available when using the .NET or Node.js blueprints.
What are Entity Relationships in Amplication?
Entity relationships in Amplication represent how different data models interact and are connected within your resource. They are generated as foreign keys in the database schema and navigation properties on the models and DTOs.
Amplication abstracts this complexity, allowing you to define relationships visually. This makes it straightforward to:
- Navigate between related data: Easily access related entities in your application code and APIs.
- Simplify GraphQL queries: Retrieve related data efficiently with automatically generated GraphQL resolvers.
- Enforce data integrity: Maintain consistency and accuracy across your data model by clearly defining how entities are linked.
Types of Relationships
Amplication supports the following core relationship types:
One-to-One
One-to-One
A relationship where each instance of one entity is related to at most one instance of another entity, and vice-versa.
Example: A User entity and a UserProfile entity. Each user has only one profile, and each profile belongs to only one user.
One-to-Many (Many-to-One)
One-to-Many (Many-to-One)
A relationship where one instance of an entity can be related to multiple instances of another entity. From the perspective of the “many” side, it’s a Many-to-One relationship.
Example: A Project entity and a Task entity. One project can have many tasks, but each task belongs to only one project.
Many-to-Many
Many-to-Many
A relationship where multiple instances of one entity can be related to multiple instances of another entity.
Example: A Student entity and a Course entity. Many students can enroll in many courses, and each course can have many students.
Currently, true Many-to-Many relationships are configured in Amplication by creating two One-to-Many relationships and an intermediary “join” entity. This provides flexibility and explicit control over the relationship.
Self-Relation
Self-Relation
Sometimes, an entity needs to relate to itself. This is common for hierarchical data structures, such as organizational charts or comment threads. Amplication supports self-relations.
When you create a “Relation to Entity” field and select the same entity as the “Related Entity”, you are creating a self-relation. Amplication will automatically create two relationship fields on the same entity to represent both directions of the relationship.
Example: In a User entity, you could create a self-relation to represent managers and employees, where each user can have one manager and multiple employees.
How to Create a Relationship
Creating relationships in Amplication is straightforward using the UI. You’ll use the “Relation to Entity” data type to create these connections.
Navigate to Entity Fields
Go to the Entities tab and select the entity you want to modify to create a relationship from. Then, navigate to the Fields tab of that entity.
Add a New Field and Select 'Relation to Entity'
Click Add Field. In the “Data Type” dropdown for the new field, choose Relation to Entity.
Selecting 'Relation to Entity' data type
Choose the Related Entity
In the Related Entity dropdown, select the entity you want to connect to. This is the entity that will be related to the current entity you are modifying.
Selecting the related entity
Configure Relationship Details
Configure the cardinality for both sides of the relationship. The options will dynamically adjust based on the relationship type you are creating.
For example, when creating a One-to-Many relationship from Project to Task:
-
On the
Projectentity’s “Tasks” field, you would select: “One ‘Project’ can be related to many ‘Tasks’”. -
Amplication automatically creates a corresponding relationship field on the
Taskentity (e.g., “Project”). On theTaskentity’s “Project” field, the cardinality would be pre-selected as: “One ‘Task’ can be related to one ‘Project’”.
Configuring One-to-Many Relationship Cardinality
For One-to-One relationships, you need to specify which entity will hold the Foreign Key. The Foreign Key is how the database links the two entities.
- “This side”: The current entity you are editing will hold the Foreign Key.
- “Other side”: The related entity will hold the Foreign Key.
The placement of the Foreign Key impacts data dependencies. If Entity B holds the Foreign Key referencing Entity A, then Entity B cannot exist without Entity A. However, Entity A can exist independently.
For complex data models, we recommend using Amplication’s AI, Jovu, to help you establish entities and relationships efficiently.
Visualize Relationships with the ERD View
Amplication’s Entity Relationship Diagram (ERD) view becomes even more valuable when working with relationships. It provides a visual map of how your entities are connected, making it easier to understand and manage complex data models.
Access ERD View
Navigate to the Entities tab and switch to the ERD view using the toggle near the search bar.
Examine Relationships
In the ERD view, you will see lines visually connecting related entities. The type of relationship (One-to-One, One-to-Many) is indicated by the line style or icons on the connector.
ERD View showing relationships between entities
The ERD view is crucial for:
- Validating your data model: Quickly ensure relationships are set up as intended.
- Communicating data structure: Easily explain the data model to team members and stakeholders.
- Identifying potential issues: Spot circular dependencies or incorrect relationship types early in the development process.
Next Steps
With a solid understanding of entity relationships, you can now build more sophisticated and interconnected data models in Amplication.
Entities
Review the fundamentals of entity creation and management in Amplication.
Fields
Explore all available field types and customization options for your entities.
Roles & Permissions
Learn how to control access and permissions for your entities and their relationships.
AI Jovu
Learn how to utilize Jovu to create your entities and their relationships using natural language.
Define Relationships Between Entities
Learn how to define and manage one-to-one, one-to-many, and self-relation relationships between entities in Amplication.
Relationships are the links that connect your entities, allowing you to model complex data structures and build sophisticated resources. This guide will walk you through creating and managing entity relationships, enabling you to establish clear connections between your data models.
Amplication Relationships feature is available when using the .NET or Node.js blueprints.
What are Entity Relationships in Amplication?
Entity relationships in Amplication represent how different data models interact and are connected within your resource. They are generated as foreign keys in the database schema and navigation properties on the models and DTOs.
Amplication abstracts this complexity, allowing you to define relationships visually. This makes it straightforward to:
- Navigate between related data: Easily access related entities in your application code and APIs.
- Simplify GraphQL queries: Retrieve related data efficiently with automatically generated GraphQL resolvers.
- Enforce data integrity: Maintain consistency and accuracy across your data model by clearly defining how entities are linked.
Types of Relationships
Amplication supports the following core relationship types:
One-to-One
One-to-One
A relationship where each instance of one entity is related to at most one instance of another entity, and vice-versa.
Example: A User entity and a UserProfile entity. Each user has only one profile, and each profile belongs to only one user.
One-to-Many (Many-to-One)
One-to-Many (Many-to-One)
A relationship where one instance of an entity can be related to multiple instances of another entity. From the perspective of the “many” side, it’s a Many-to-One relationship.
Example: A Project entity and a Task entity. One project can have many tasks, but each task belongs to only one project.
Many-to-Many
Many-to-Many
A relationship where multiple instances of one entity can be related to multiple instances of another entity.
Example: A Student entity and a Course entity. Many students can enroll in many courses, and each course can have many students.
Currently, true Many-to-Many relationships are configured in Amplication by creating two One-to-Many relationships and an intermediary “join” entity. This provides flexibility and explicit control over the relationship.
Self-Relation
Self-Relation
Sometimes, an entity needs to relate to itself. This is common for hierarchical data structures, such as organizational charts or comment threads. Amplication supports self-relations.
When you create a “Relation to Entity” field and select the same entity as the “Related Entity”, you are creating a self-relation. Amplication will automatically create two relationship fields on the same entity to represent both directions of the relationship.
Example: In a User entity, you could create a self-relation to represent managers and employees, where each user can have one manager and multiple employees.
How to Create a Relationship
Creating relationships in Amplication is straightforward using the UI. You’ll use the “Relation to Entity” data type to create these connections.
Navigate to Entity Fields
Go to the Entities tab and select the entity you want to modify to create a relationship from. Then, navigate to the Fields tab of that entity.
Add a New Field and Select 'Relation to Entity'
Click Add Field. In the “Data Type” dropdown for the new field, choose Relation to Entity.
Selecting 'Relation to Entity' data type
Choose the Related Entity
In the Related Entity dropdown, select the entity you want to connect to. This is the entity that will be related to the current entity you are modifying.
Selecting the related entity
Configure Relationship Details
Configure the cardinality for both sides of the relationship. The options will dynamically adjust based on the relationship type you are creating.
For example, when creating a One-to-Many relationship from Project to Task:
-
On the
Projectentity’s “Tasks” field, you would select: “One ‘Project’ can be related to many ‘Tasks’”. -
Amplication automatically creates a corresponding relationship field on the
Taskentity (e.g., “Project”). On theTaskentity’s “Project” field, the cardinality would be pre-selected as: “One ‘Task’ can be related to one ‘Project’”.
Configuring One-to-Many Relationship Cardinality
For One-to-One relationships, you need to specify which entity will hold the Foreign Key. The Foreign Key is how the database links the two entities.
- “This side”: The current entity you are editing will hold the Foreign Key.
- “Other side”: The related entity will hold the Foreign Key.
The placement of the Foreign Key impacts data dependencies. If Entity B holds the Foreign Key referencing Entity A, then Entity B cannot exist without Entity A. However, Entity A can exist independently.
For complex data models, we recommend using Amplication’s AI, Jovu, to help you establish entities and relationships efficiently.
Visualize Relationships with the ERD View
Amplication’s Entity Relationship Diagram (ERD) view becomes even more valuable when working with relationships. It provides a visual map of how your entities are connected, making it easier to understand and manage complex data models.
Access ERD View
Navigate to the Entities tab and switch to the ERD view using the toggle near the search bar.
Examine Relationships
In the ERD view, you will see lines visually connecting related entities. The type of relationship (One-to-One, One-to-Many) is indicated by the line style or icons on the connector.
ERD View showing relationships between entities
The ERD view is crucial for:
- Validating your data model: Quickly ensure relationships are set up as intended.
- Communicating data structure: Easily explain the data model to team members and stakeholders.
- Identifying potential issues: Spot circular dependencies or incorrect relationship types early in the development process.
Next Steps
With a solid understanding of entity relationships, you can now build more sophisticated and interconnected data models in Amplication.
Entities
Review the fundamentals of entity creation and management in Amplication.
Fields
Explore all available field types and customization options for your entities.
Roles & Permissions
Learn how to control access and permissions for your entities and their relationships.
AI Jovu
Learn how to utilize Jovu to create your entities and their relationships using natural language.