> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/defining-relationship-types/managing-relationships.md).

# Managing relationships

Cortex captures your organization's structure through two complementary concepts: **relationship types** and **relationship connections**.

A **relationship type** defines the rules of a connection: what it means, which entity types can participate, whether it flows in one direction or can form cycles, and whether metadata should inherit across it. Think of it as a template (e.g. "Repository," "Cloud account to resource," or "Service to environment") that describes *how* two kinds of entities relate before any specific entities are linked.

A **relationship connection** is a concrete instance of that template: the actual link between two specific entities. For example, once you've defined a "Repository" relationship type, a connection is what ties your `payments-service` entity to its specific GitHub repository entity.

This separation gives you flexibility and consistency. You define the shape of a relationship once, then apply it across as many entity pairs as needed. Relationships can be hierarchical (acyclical, like an org chart) or graph-like (cyclical, like service dependencies), and they can carry ownership metadata that flows from parent to child.

Together, relationship types and connections give Cortex a way to reflect how your systems actually fit together.

## Creating relationship types

Users with the `Edit Relationships` permission can create a relationship type.

Relationship types must be created via the Cortex UI or the API.

### Creating relationship types via the Cortex UI

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. In the upper-right corner, click **Create**, then click **Create new relationship type**.\
   The **Create new relationship** page is displayed.
4. In the **Details** section, do the following:
   1. Under **Name**, enter a name for the relationship type (required).
   2. The **Identifier** auto-populates based on the relationship type name and is made up of letters, digits, and hyphens.
   3. Under **Description**, enter a description of the relationship to help others understand its purpose.
   4. Toggle on **Create relationship type catalog** to create a catalog for this relationship type.
5. In the **Source entity types** section, do the following:
   1. From the drop-down menu, select an entity type. If no entity type is selected, all entity types are available as sources.
   2. Toggle on **Exclude** to hide all entity types from sources, or leave toggled off to include all.
   3. Optionally, customize the singular and plural wording of the entity types and the cardinality.
6. In the **Destination entity types** section, do the following:
   1. From the drop-down menu, select an entity type. If no entity type is selected, all entity types are available as destinations.
   2. Toggle on **Exclude** to hide all entity types from destinations, or leave toggled off to include all.
   3. Optionally, customize the singular and plural wording of the entity types and the cardinality.
7. In the **Relationship constraints** section, do the following:
   1. Select an architecture:
      1. **Acyclical** - Recommended for hierarchical data such as an org chart or product hierarchy.
      2. **Cyclical** - Recommended for graph-like data such as dependencies.
   2. Under **Definition location**, select a location:
      1. **From destination** - If selected, relationships can only be defined from destination entities.
      2. **From source** - If selected, relationships can only be defined from source entities.
      3. **Either source or destination** - If selected, relationships can be defined by either destination or source entities.
   3. Toggle on **Ownership** to configure inheritance for the relationship type, then select how metadata will be inherited. Learn more in [Ownership inheritance](/ingesting-data-into-cortex/entities-overview/entities/ownership/ownership-inheritance.md).
      1. **Fallback**: This option uses the source's data only if the destination does not have anything defined.
      2. **Append**: This option appends the source's data to the destination, even if it already has data defined.
8. Click **Create**.

### Creating relationship types via the API

You can create, update, and delete relationship types using the [Cortex API](https://docs.cortex.io/api/readme/entity-relationship-types).

## Creating relationship connections between entities

After creating a relationship type, connections between entities can be made via the Cortex UI, an entity descriptor, the API, or an integration.

### **Creating relationship connections via the UI**

1. Navigate to the [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md).
2. In the upper-right corner, click **Configure entity**.
3. From the left entity sidebar, click **Relationships**.
4. In the **Relationship type** section, select a relationship type to configure from the drop-down menu.
5. Select the entities you want to connect. The available fields depend on the relationship type selected.
6. Click **Save changes**.

### Creating relationship connections via an entity descriptor

Once a relationship type exists, you can define the connection in either the source or destination entity's YAML using the `x-cortex-relationships` tag.

In the example below, a source entity's YAML has a defined relationship type called `app-components` and has destination entities `production-ui` and `backend-app`.

```yaml
  x-cortex-relationships:
  - type: app-components
    destinations:
    - tag: production-ui
    - tag: backend-app
```

Optionally, this can be configured in the YAML of the destination by replacing `source` with `destination` in the YAML above.

The relationship between entities in Cortex is based on the relationship being defined in the entity's YAML file; Cortex does not set hierarchies or relationships based on a YAML file's location in your repository.

### Creating relationship connections via the API

You can create, update, and delete relationships between entities using the [Cortex API](https://docs.cortex.io/api/readme/entity-relationships).

### Creating relationship connections via an integration

At this time, Cortex only supports integration-based relationship creation via AWS. See [Configuring tag-based auto-linking](/ingesting-data-into-cortex/integrations/aws/importing-entities-from-aws.md#configuring-tag-based-auto-linking-for-aws) for more information.

## Editing a relationship type

Users with the `Edit Relationships` permission can edit a relationship type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Locate the relationship type you want to edit, then click the **pencil icon** next to it.
4. Make any necessary changes.
5. Click **Save**.

## Deleting a relationship type

Users with the `Edit Relationships` permission can delete a relationship type.

1. From the main sidebar, expand **Catalogs**, then select **All entities**.
2. Select the **Relationship types** tab.
3. Select the relationship type you want to delete.
4. Click the **Overflow menu** icon, then click **Delete relationship type**.