Skip to content

Relationships

The core API owns the portable relationship model and the backend-neutral Rel shortcut. Directional, bidirectional, and layout helper APIs are backend-specific contrib APIs:

c4.diagrams.core.Rel

Bases: Relationship

A unidirectional relationship between two elements.

c4.diagrams.core.Relationship

Bases: BaseDiagramElement

Represents a connection between two elements.

Supports direct construction and fluent chaining using >> and << operators. Subclasses are registered by RelationshipType.

__init__ 

__init__(
    label: str | None = None,
    description: str | None = None,
    technology: str | None = None,
    from_element: TElement | None = None,
    to_element: TElement | None = None,
    relationship_type: RelationshipType | None = None,
    extensions: ElementExtensions | None = None,
    plantuml: Mapping[str, Any] | None = None,
    mermaid: Mapping[str, Any] | None = None,
) -> None

Parameters:

Name Type Description Default
label str | None

The label shown on the relationship edge.

 None
description str | None

Additional details about the relationship.

 None
technology str | None

The technology used in the communication.

 None
from_element TElement | None

The source element. Optional.

 None
to_element TElement | None

The destination element. Optional.

 None
relationship_type RelationshipType | None

Type of the relationship. Defaults to the class-level relationship_type.

 None
extensions ElementExtensions | None

Backend-specific extension data.

 None
plantuml Mapping[str, Any] | None

PlantUML-specific extension data.

 None
mermaid Mapping[str, Any] | None

Mermaid-specific extension data.

 None
Notes

If both from_element and to_element are provided, the relationship will be registered in the current diagram immediately.

get_attrs 

get_attrs() -> dict[str, Any]

Return the constructor attributes for this relationship.

copy 

copy(**overrides: Any) -> Relationship

Clone this relationship, optionally overriding constructor fields.

Parameters:

Name Type Description Default
**overrides Any

Field values to override in the cloned relationship.

 {}

Returns:

Type Description
Relationship

A new relationship with copied properties.

get_relationship_by_type classmethod 

get_relationship_by_type(
    relationship_type: RelationshipType,
) -> type[Relationship]

Retrieve the relationship class associated with the given RelationshipType.

Parameters:

Name Type Description Default
relationship_type RelationshipType

The enum value representing the type of relationship.

 required

Returns:

Type Description
type[Relationship]

The corresponding Relationship subclass.

Raises:

Type Description
KeyError

If no class is registered for the provided relationship type.

set_property_header 

set_property_header(*args: str) -> Self

Sets the column headers for the element's property table.

This must be called either before adding any property rows, or the header length must match the number of values.

Parameters:

Name Type Description Default
*args str

Column names to use as the property header.

 ()

Returns:

Type Description
Self

The updated diagram element.

Raises:

Type Description
ValueError

If header length does not match the number of values.

without_property_header 

without_property_header() -> Self

Disables the rendering of the header row in the property table.

Returns:

Type Description
Self

The updated diagram element.

add_property 

add_property(*args: str) -> Self

Adds a row to the property table.

The number of arguments must match the number of header columns.

Parameters:

Name Type Description Default
*args str

Values for each column in the property row.

 ()

Returns:

Type Description
Self

The updated diagram element.

Raises:

Type Description
ValueError

If the number of values does not match the header length.