ER Diagrams¶

Overview¶

Entity-Relationship (ER) Diagrams are a graphical representation of the structure of a schema.

LinkML uses the Mermaid ER Diagram syntax to represent ER diagrams.

To run:

gen-erdiagram personinfo.yaml

This will generate a single markdown-ready ER diagram file, that can be embedded in a mkdocs or sphinx site, or included in a GitHub issue.

By default, the output includes markdown fence blocks:

```mermaid
erDiagram
   ...
```

To generate the mermaid without the fencing block, use --format mermaid:

gen-erdiagram --format mermaid personinfo.yaml

Customization¶

The default behavior is:

Check if the schema has a tree root assigned
- If assigned, then include this entity, and everything reachable from it
- If not assigned, then include all entities

Here, “reachable” means reachable via inlined references

If you want to draw a diagram for a particular class, and all reachable nodes, you can pass these on the command line:

gen-erdiagram personinfo.yaml -c MedicalEvent

This generates:

        erDiagram
MedicalEvent {
    date started_at_time
    date ended_at_time
    float duration
    boolean is_current
}
ProcedureConcept {
    string id
    string name
    string description
    string image
}
DiagnosisConcept {
    string id
    string name
    string description
    string image
}

MedicalEvent ||--|o Place : "in_location"
MedicalEvent ||--|o DiagnosisConcept : "diagnosis"
MedicalEvent ||--|o ProcedureConcept : "procedure"

By default, only inlined references are followed. State --follow-references to also follow non-inlined references.

For large ER diagrams, to get a big-picture overview, you may want to exclude attributes:

gen-erdiagram personinfo.yaml -c Person --exclude-attributes

Generates:

        erDiagram
Person {

}
MedicalEvent {

}
ProcedureConcept {

}
DiagnosisConcept {

}
FamilialRelationship {

}
EmploymentEvent {

}
Address {

}

Person ||--|o Address : "current_address"
Person ||--}o EmploymentEvent : "has_employment_history"
Person ||--}o FamilialRelationship : "has_familial_relationships"
Person ||--}o MedicalEvent : "has_medical_history"
MedicalEvent ||--|o Place : "in_location"
MedicalEvent ||--|o DiagnosisConcept : "diagnosis"
MedicalEvent ||--|o ProcedureConcept : "procedure"
FamilialRelationship ||--|| Person : "related_to"
EmploymentEvent ||--|o Organization : "employed_at"

Also you can include upstream entities into selected entities diagram. This is helpful for creating smaller, focused diagrams that display the immediate neighborhood of a selected class.

For example this

erdiagramgen  kitchen-sink.yaml -c MedicalEvent --max-hops 0 --include-upstream --exclude-attributes

Generates:

        erDiagram
MedicalEvent {
}
Person {
}
DiagnosisConcept {
}
ProcedureConcept {
}

MedicalEvent ||--|o Place : "in location"
MedicalEvent ||--|o DiagnosisConcept : "diagnosis"
MedicalEvent ||--|o ProcedureConcept : "procedure"
MedicalEvent ||--|o AnyObject : "metadata"
Person ||--}o MedicalEvent : "has medical history"

Limitations¶

There is currently no way to directly generate PNGs/PDFs/etc from the mermaid code. You can use the mermaid live editor to generate these.
The mermaid diagrams are not yet directly integrated into the documentation generated by gen-docs.

Docs¶

Command Line¶

gen-erdiagram¶

Generate a mermaid ER diagram from a schema.

By default, all entities traversable from the tree_root are included. If no tree_root is present, then all entities are included.

To create an ER diagram for selected classes, use the –classes option.

gen-erdiagram [OPTIONS] YAMLFILE

Options

-V, --version¶: Show the version and exit.

--include-upstream¶: Include upstream classes

-c, --classes <classes>¶: List of classes to serialize

--max-hops <max_hops>¶: Maximum number of hops

--follow-references, --no-follow-references¶: If True, follow references even if not inlined

--exclude-abstract-classes, --no-exclude-abstract-classes¶: If True, do not include abstract classes in the diagram

--exclude-attributes, --no-exclude-attributes¶: If True, do not include attributes in entities

--structural, --no-structural¶: If True, then only the tree_root and entities reachable from the root are drawn

-f, --format <format>¶

Output format

Default:: 'markdown'
Options:: markdown | mermaid

--metadata, --no-metadata¶

Include metadata in output

Default:: True

--useuris, --metauris¶

Use class and slot URIs over model uris

Default:: True

-im, --importmap <importmap>¶: Import mapping file

--log_level <log_level>¶

Logging level

Default:: 'WARNING'
Options:: CRITICAL | ERROR | WARNING | INFO | DEBUG

-v, --verbose¶: Verbosity. Takes precedence over –log_level.

--mergeimports, --no-mergeimports¶: Merge imports into source file (default=mergeimports)

--stacktrace, --no-stacktrace¶

Print a stack trace when an error occurs

Default:: False

Arguments

YAMLFILE¶: Required argument

Code¶

class linkml.generators.erdiagramgen.ERDiagramGenerator(schema: str | ~typing.TextIO | ~linkml_runtime.linkml_model.meta.SchemaDefinition | ~linkml.utils.generator.Generator | ~pathlib.Path, schemaview: ~linkml_runtime.utils.schemaview.SchemaView | None = None, format: str | None = None, metadata: bool = True, useuris: bool | None = None, log_level: int | None = 30, mergeimports: bool | None = True, source_file_date: str | None = None, source_file_size: int | None = None, logger: ~logging.Logger | None = None, verbose: bool | None = None, output: str | None = None, namespaces: ~linkml_runtime.utils.namespaces.Namespaces | None = None, directory_output: bool = False, base_dir: str = None, metamodel_name_map: dict[str, str] = None, importmap: str | ~collections.abc.Mapping[str, str] | None = None, emit_prefixes: set[str] = <factory>, metamodel: ~linkml.utils.schemaloader.SchemaLoader = None, stacktrace: bool = False, include: str | ~pathlib.Path | ~linkml_runtime.linkml_model.meta.SchemaDefinition | None = None, structural: bool = True, exclude_attributes: bool = False, exclude_abstract_classes: bool = False, genmeta: bool = False, gen_classvars: bool = True, gen_slots: bool = True, no_types_dir: bool = False, use_slot_uris: bool = False, preserve_names: bool = False)[source]¶

A generator for serializing schemas as Entity-Relationship diagrams.

Currently this generates diagrams in mermaid syntax, but in future this could easily be extended to have for example a direct SVG or PNG generator using PyGraphViz, similar to erdantic.

serialize() → str[source]¶

Serialize a schema as an ER Diagram.

If a tree_root is present in the schema, then only Entities traversable from here will be included. Otherwise, all Entities will be included.

Returns:: mermaid string

serialize_classes(class_names: list[str | ClassDefinitionName], follow_references=False, max_hops: int = None, include_upstream: bool = False) → str[source]¶

Serialize a list of classes as an ER Diagram.

This will also traverse the reference graph and include any Entities reachable from the specified classes.

By default, all reachable Entities are included, unless max_hops is specified.

Parameters:

class_names – initial seed
follow_references – if True, follow references even if not inlined
max_hops – maximum number of hops to follow references

Returns: