# Defining relationship types

Relationship types allow you to define, manage, and visualize relationships between entities within your Cortex workspace, ensuring your organization's structures and dependencies are accurately represented.

## Understanding relationship types in Cortex

A relationship type defines how two entities relate to either other, and constrains the types of entities that can be the source and destination entities within the relationship.

Cortex provides multiple options for defining a relationship:

* **Entity relationship**: As described on this page, you can customize a relationship type (hierarchical or cyclical) between any entity type.
* **Team hierarchy**: You can define a hierarchical relationship between team entities. Teams can have [ownership](https://docs.cortex.io/ingesting-data-into-cortex/entities/ownership) over other entities. Learn more in [Add teams](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/teams#understanding-hierarchies).
* **Domain hierarchy**: You can define a hierarchical relationship between domain entities. You can also configure inheritance; the owner of an entity can be inherited from entities higher in the domain hierarchy. Learn more in [Add domains](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/domains#display-in-hierarchy).
* **Dependencies**: You can define a cyclical relationship between non-team entities. Learn more in [Defining dependencies](https://docs.cortex.io/ingesting-data-into-cortex/entities/adding-entities/dependencies).

{% hint style="info" %}
Want to learn more? Check out the [Cortex Academy course on Catalogs, Entities, and Relationships](https://academy.cortex.io/courses/understanding-understanding-catalogs-entities-and-relationships), available to all Cortex customers and POVs.
{% endhint %}

### Common use cases of custom relationship types

<table><thead><tr><th width="162.05206298828125">Relationship type</th><th width="255.739501953125">Description</th><th width="144.203125">Source</th><th>Destination</th></tr></thead><tbody><tr><td>Repository</td><td>Mapping services to repositories to view the hierarchy of repos and the services they contain. For example, a service is linked to its code repository.</td><td>Service</td><td>Repository</td></tr><tr><td>Cloud account to resource</td><td>Associating cloud accounts (like AWS, Google Cloud Project, or Azure subscription) with their respective resources (such as EC2 instances or other cloud resources).</td><td><ul><li>AWS account</li><li>GCP</li><li>Azure subscription</li></ul></td><td><ul><li>AWS resources (e.g., EC2)</li><li>Google Cloud resources</li><li>Azure resources</li></ul></td></tr><tr><td>Service to environment</td><td>Linking services to their deployment environments.</td><td>Service</td><td>Environment</td></tr><tr><td>Monorepo</td><td>Mapping multiple services to a single repository.</td><td>Repository</td><td>Service</td></tr><tr><td>Service to endpoint</td><td>Associating services with their endpoints.</td><td>Service</td><td>Endpoint</td></tr><tr><td>Data center modeling</td><td>epresenting data centers and their relationships to other infrastructure components.</td><td>Data center</td><td>Component</td></tr></tbody></table>

Note that you should not create custom relationship types to represent ownership; [teams can be designated as owners of entities](#understanding-relationship-types-in-cortex).

## View relationship types

### View all configured relationship types

To view all relationship types, go to **Catalogs > All entities** then click the [Relationship types tab](https://app.getcortexapp.com/admin/entities?activeTab=relationships).

<figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-5096deea1007b1a113e3b58c37b3d3398caf1e0f%2Frelationship-types.jpg?alt=media" alt=""><figcaption><p>On the Entities page, click the "Relationship types" tab.</p></figcaption></figure>

To view the details of a specific relationship type, click its name from the list.

### View relationships on entity pages

If an entity belongs to a relationship, you can explore that context directly from its [entity details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details). Select **Relationships** in the left sidebar to see all relationship types associated with the entity.

In the example below, the entity `California` belongs to a relationship called `Geography` . Relationships default to a **Graph view**, giving you a visual map of parent/child connections.&#x20;

<figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2FIyPSnMJmTtxH1Q3sx8FB%2FScreenshot%202026-02-18%20at%202.18.29%E2%80%AFPM.png?alt=media&#x26;token=a56d8f1c-cd4b-4ee1-b804-c9aa088e83db" alt=""><figcaption></figcaption></figure>

From the graph, click any entity to view a quick summary of its metadata. Select **Go to entity** to navigate directly to that entity's detail page.

<figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2FDQLuo9YnWsSVjCDljE4v%2FScreenshot%202026-02-18%20at%202.38.00%E2%80%AFPM.png?alt=media&#x26;token=aabfe35b-74a8-443d-973c-755ef215eeb5" alt=""><figcaption></figcaption></figure>

Toggle to **Table view** to see the same data in a structured list. useful for quickly scanning or sorting related entities.

<figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2FUvgRqP3uqkJa3B9ryKcE%2FScreenshot%202026-02-18%20at%202.21.22%E2%80%AFPM.png?alt=media&#x26;token=e8a161f9-22c3-4ec2-b6e1-495516202379" alt=""><figcaption></figcaption></figure>

## Manage relationship types

### Create relationship types and relationship connections

{% tabs %}
{% tab title="Cortex UI" %}
**Create relationship types in the Cortex UI**

1. Navigate to **Catalogs > All entities** then click the [Relationship types tab](https://app.getcortexapp.com/admin/entities?activeTab=relationships).
2. In the upper right corner, click **Create > Create new relationship type**. \\

   <figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-547d1553448cf9f72f1cfbbd24f2e558412a3a83%2Fcreate-relationship-type.jpg?alt=media" alt="In the upper right, click Create, then click &#x22;Create new relationship type&#x22;."><figcaption></figcaption></figure>
3. Configure the details and entity types:
   * **Name**: Enter a name for the relationship type.
   * **Identifier**: Enter a unique identifier, used to specify this relationship in YAML definitions for this relationship type.
   * **Description**: Add a description of the relationship to help others understand its purpose.
   * **Create relationship type catalog**: Enable this option to create a catalog for this relationship type.
   * **Source entity types**: Search for and select the entity types which will be the source for this relationship. Selecting no entity type means that all entity types are available as sources.
     * You can also customize the singular and plural wording of the entity types and the cardinality.
   * **Destination entity types**: Search for and select the entity types which will be the destination for this relationship. Selecting no entity type means that all entity types are available as destinations.
     * You can also customize the singular and plural wording of the entity types and the cardinality.
4. Configure the relationship constraints:
   * **Architecture**: If you are configuring hierarchical data, such as an org chart, we recommend choosing **Acyclical**. If you are configuring graph-like data, such as dependencies, we recommend choosing **Cyclical**.
   * **Definition location**: Configure where relationships can be defined — from destination entities, from source entities, or from either.
5. Configure metadata inheritance.
   * Enable the **Ownership** toggle to configure inheritance for the relationship type, then select how metadata will be inherited:
     * **Fallback**: This option uses the source's data only if the destination does not have anything defined.
     * **Append**: This option appends the source's data to the destination, even if it already has data defined.
     * Learn more about inheritance in [Defining ownership](https://docs.cortex.io/ingesting-data-into-cortex/ownership#ownership-inheritance).
6. Click **Create**.

**Create relationship connections between entities in the UI**

After creating the relationship type, you can configure connections between entities in a relationship. You can do this via the [entity descriptor](#entity-descriptor) or in the UI, as described below:

1. Navigate to an [entity details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details). In the upper right corner, click **Configure entity**.
2. Click the **Relationships** link on the left.
3. At the top of the Relationship Type section, click the dropdown to select which relationship type you are configuring connections for.\\

   <div align="left"><figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-fe5ec1f58c145209e0f7f5a1456c3b93352bdb3a%2Frt-dropdown.jpg?alt=media" alt="Click the dropdown under Relationships to choose a type." width="563"><figcaption></figcaption></figure></div>
4. After selecting the relationship type, you can search for and select entities in the Sources dropdown and in the Destinations dropdown.\
   ![Configure source or destination entities.](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-c2dac712708084c0bebf854cf80cae8a4f903872%2Fselect-entities-relationship.jpg?alt=media)
5. At the bottom of the page, click **Save changes**.
   {% endtab %}

{% tab title="Entity descriptor" %}
**Create relationship connections between entities in the entity descriptor**

Relationship types must be [created in the Cortex UI](#cortex-ui) or via the API. 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.&#x20;

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`.&#x20;

```
  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.
{% endtab %}

{% tab title="API" %}
**Create 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).&#x20;

**Create relationship connections between entities via the API**&#x20;

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

### Edit relationship types

<details>

<summary>Edit relationship type</summary>

To edit an existing relationship type:

1. Navigate to **Catalogs > All entities** then click the [Relationship types tab](https://app.getcortexapp.com/admin/entities?activeTab=relationships).
2. In the row containing the relationship type, click the pen icon.\
   ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-51146cf5ca648ddb2e799913a70bd40b4ef010bc%2Fedit-relationship-type.jpg?alt=media)
3. Make any necessary changes, then at the bottom of the page, click **Save**.

</details>

### Delete relationship types

<details>

<summary>Delete relationship types</summary>

1. Navigate to **Catalogs > All entities** then click the [Relationship types tab](https://app.getcortexapp.com/admin/entities?activeTab=relationships).
2. Click the relationship type name.
3. On its details page, in the upper right corner, click **Remove**.\
   ![](https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-37b76a836d3c7f785f48e154fcc915fb60470792%2Fremove-relationship-type.jpg?alt=media)

</details>

## Entity relationship CQL

You can create Scorecard rules and write CQL queries based on entity relationships.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

<details>

<summary>Entity relationship destinations</summary>

All recursive destinations an entity for a relationship type, with an optional depth parameter to expand results

**Definition**: `entity.destinations(relationshipType = "my-relationship")`

**Examples**

You could write a Scorecard rule to ensure that an entity has at least one destination with the "my-relationship" type:

```
entity.destinations(relationshipType = "my-relationship").length > 0
```

</details>

<details>

<summary>Entity relationship sources</summary>

All recursive sources an entity for a relationship type, with an optional depth parameter to expand results

**Definition**: `entity.sources(relationshipType = "my-relationship")`

**Examples**

You could write a Scorecard rule that ensures an entity has at least one source with the "my-relationship" type:

```
entity.sources(relationshipType = "my-relationship").length > 0
```

</details>