Defining relationship types

The ability to add relationship types is in public beta. Please reach out to Cortex Customer Engineering with any feedback.

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 over other entities. Learn more in Add teams.

• 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.

• Dependencies: You can define a cyclical relationship between non-team entities. Learn more in Defining dependencies.

Want to learn more? Check out the Cortex Academy course on Catalogs, Entities, and Relationships, available to all Cortex customers and POVs.

Common use cases of custom relationship types

Relationship type	Description	Source	Destination
Repository	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.	Service	Repository
Cloud account to resource	Associating cloud accounts (like AWS, Google Cloud Project, or Azure subscription) with their respective resources (such as EC2 instances or other cloud resources).	AWS account GCP Azure subscription	AWS resources (e.g., EC2) Google Cloud resources Azure resources
Service to environment	Linking services to their deployment environments.	Service	Environment
Monorepo	Mapping multiple services to a single repository.	Repository	Service
Service to endpoint	Associating services with their endpoints.	Service	Endpoint
Data center modeling	epresenting data centers and their relationships to other infrastructure components.	Data center	Component

Note that you should not create custom relationship types to represent ownership; teams can be designated as owners of entities.

View relationship types

View all configured relationship types

To view all relationship types, go to Catalogs > All entities then click the Relationship types tab.

On the Entities page, click the "Relationship types" tab.

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. 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.

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.

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

Manage relationship types

Create relationship types and relationship connections

Cortex UI

Create relationship types in the Cortex UI

1. Navigate to Catalogs > All entities then click the Relationship types tab.

2. In the upper right corner, click Create > Create new relationship type. \

   
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.

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 or in the UI, as described below:

1. Navigate to an entity details page. 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.\

   
4. After selecting the relationship type, you can search for and select entities in the Sources dropdown and in the Destinations dropdown.

5. At the bottom of the page, click Save changes.

Entity descriptor

API

Edit relationship types

Edit relationship type

To edit an existing relationship type:

1. Navigate to Catalogs > All entities then click the Relationship types tab.

2. In the row containing the relationship type, click the pen icon.

3. Make any necessary changes, then at the bottom of the page, click Save.

Delete relationship types

Delete relationship types

1. Navigate to Catalogs > All entities then click the Relationship types tab.

2. Click the relationship type name.

3. On its details page, in the upper right corner, click Remove.

Entity relationship CQL

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

See more examples in the CQL Explorer in Cortex.

Entity relationship destinations

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

Entity relationship sources

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