19.9 KB671 lines
Blame
1> **Warning**
2>
3> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
4>
5> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/entityRelationshipDiagram.md](../../packages/mermaid/src/docs/syntax/entityRelationshipDiagram.md).
6
7# Entity Relationship Diagrams
8
9> An entity–relationship model (or ER model) describes interrelated things of interest in a specific domain of knowledge. A basic ER model is composed of entity types (which classify the things of interest) and specifies relationships that can exist between entities (instances of those entity types) [Wikipedia](https://en.wikipedia.org/wiki/Entity%E2%80%93relationship_model).
10
11Note that practitioners of ER modelling almost always refer to _entity types_ simply as _entities_. For example the `CUSTOMER` entity _type_ would be referred to simply as the `CUSTOMER` entity. This is so common it would be inadvisable to do anything else, but technically an entity is an abstract _instance_ of an entity type, and this is what an ER diagram shows - abstract instances, and the relationships between them. This is why entities are always named using singular nouns.
12
13Mermaid can render ER diagrams
14
15```mermaid-example
16---
17title: Order example
18---
19erDiagram
20 CUSTOMER ||--o{ ORDER : places
21 ORDER ||--|{ LINE-ITEM : contains
22 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
23```
24
25```mermaid
26---
27title: Order example
28---
29erDiagram
30 CUSTOMER ||--o{ ORDER : places
31 ORDER ||--|{ LINE-ITEM : contains
32 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
33```
34
35Entity names are often capitalised, although there is no accepted standard on this, and it is not required in Mermaid.
36
37Relationships between entities are represented by lines with end markers representing cardinality. Mermaid uses the most popular crow's foot notation. The crow's foot intuitively conveys the possibility of many instances of the entity that it connects to.
38
39ER diagrams can be used for various purposes, ranging from abstract logical models devoid of any implementation details, through to physical models of relational database tables. It can be useful to include attribute definitions on ER diagrams to aid comprehension of the purpose and meaning of entities. These do not necessarily need to be exhaustive; often a small subset of attributes is enough. Mermaid allows them to be defined in terms of their _type_ and _name_.
40
41```mermaid-example
42erDiagram
43 CUSTOMER ||--o{ ORDER : places
44 CUSTOMER {
45 string name
46 string custNumber
47 string sector
48 }
49 ORDER ||--|{ LINE-ITEM : contains
50 ORDER {
51 int orderNumber
52 string deliveryAddress
53 }
54 LINE-ITEM {
55 string productCode
56 int quantity
57 float pricePerUnit
58 }
59```
60
61```mermaid
62erDiagram
63 CUSTOMER ||--o{ ORDER : places
64 CUSTOMER {
65 string name
66 string custNumber
67 string sector
68 }
69 ORDER ||--|{ LINE-ITEM : contains
70 ORDER {
71 int orderNumber
72 string deliveryAddress
73 }
74 LINE-ITEM {
75 string productCode
76 int quantity
77 float pricePerUnit
78 }
79```
80
81When including attributes on ER diagrams, you must decide whether to include foreign keys as attributes. This probably depends on how closely you are trying to represent relational table structures. If your diagram is a _logical_ model which is not meant to imply a relational implementation, then it is better to leave these out because the associative relationships already convey the way that entities are associated. For example, a JSON data structure can implement a one-to-many relationship without the need for foreign key properties, using arrays. Similarly an object-oriented programming language may use pointers or references to collections. Even for models that are intended for relational implementation, you might decide that inclusion of foreign key attributes duplicates information already portrayed by the relationships, and does not add meaning to entities. Ultimately, it's your choice.
82
83## Syntax
84
85### Entities and Relationships
86
87Mermaid syntax for ER diagrams is compatible with PlantUML, with an extension to label the relationship. Each statement consists of the following parts:
88
89```
90 <first-entity> [<relationship> <second-entity> : <relationship-label>]
91```
92
93Where:
94
95- `first-entity` is the name of an entity. Names support any unicode characters and can include spaces if surrounded by double quotes (e.g. "name with space").
96- `relationship` describes the way that both entities inter-relate. See below.
97- `second-entity` is the name of the other entity.
98- `relationship-label` describes the relationship from the perspective of the first entity.
99
100For example:
101
102```
103 PROPERTY ||--|{ ROOM : contains
104```
105
106This statement can be read as _a property contains one or more rooms, and a room is part of one and only one property_. You can see that the label here is from the first entity's perspective: a property contains a room, but a room does not contain a property. When considered from the perspective of the second entity, the equivalent label is usually very easy to infer. (Some ER diagrams label relationships from both perspectives, but this is not supported here, and is usually superfluous).
107
108Only the `first-entity` part of a statement is mandatory. This makes it possible to show an entity with no relationships, which can be useful during iterative construction of diagrams. If any other parts of a statement are specified, then all parts are mandatory.
109
110#### Unicode text
111
112Entity names, relationships, and attributes all support unicode text.
113
114```mermaid-example
115erDiagram
116 "This ❤ Unicode"
117```
118
119```mermaid
120erDiagram
121 "This ❤ Unicode"
122```
123
124#### Markdown formatting
125
126Markdown formatting and text is also supported.
127
128```mermaid-example
129erDiagram
130 "This **is** _Markdown_"
131```
132
133```mermaid
134erDiagram
135 "This **is** _Markdown_"
136```
137
138### Relationship Syntax
139
140The `relationship` part of each statement can be broken down into three sub-components:
141
142- the cardinality of the first entity with respect to the second
143- whether the relationship confers identity on a 'child' entity
144- the cardinality of the second entity with respect to the first
145
146Cardinality is a property that describes how many elements of another entity can be related to the entity in question. In the above example a `PROPERTY` can have one or more `ROOM` instances associated to it, whereas a `ROOM` can only be associated with one `PROPERTY`. In each cardinality marker there are two characters. The outermost character represents a maximum value, and the innermost character represents a minimum value. The table below summarises possible cardinalities.
147
148| Value (left) | Value (right) | Meaning |
149| :----------: | :-----------: | ----------------------------- |
150| `\|o` | `o\|` | Zero or one |
151| `\|\|` | `\|\|` | Exactly one |
152| `}o` | `o{` | Zero or more (no upper limit) |
153| `}\|` | `\|{` | One or more (no upper limit) |
154
155**Aliases**
156
157| Value (left) | Value (right) | Alias for |
158| :----------: | :-----------: | ------------ |
159| one or zero | one or zero | Zero or one |
160| zero or one | zero or one | Zero or one |
161| one or more | one or more | One or more |
162| one or many | one or many | One or more |
163| many(1) | many(1) | One or more |
164| 1+ | 1+ | One or more |
165| zero or more | zero or more | Zero or more |
166| zero or many | zero or many | Zero or more |
167| many(0) | many(0) | Zero or more |
168| 0+ | 0+ | Zero or more |
169| only one | only one | Exactly one |
170| 1 | 1 | Exactly one |
171
172### Identification
173
174Relationships may be classified as either _identifying_ or _non-identifying_ and these are rendered with either solid or dashed lines respectively. This is relevant when one of the entities in question cannot have independent existence without the other. For example a firm that insures people to drive cars might need to store data on `NAMED-DRIVER`s. In modelling this we might start out by observing that a `CAR` can be driven by many `PERSON` instances, and a `PERSON` can drive many `CAR`s - both entities can exist without the other, so this is a non-identifying relationship that we might specify in Mermaid as: `PERSON }|..|{ CAR : "driver"`. Note the two dots in the middle of the relationship that will result in a dashed line being drawn between the two entities. But when this many-to-many relationship is resolved into two one-to-many relationships, we observe that a `NAMED-DRIVER` cannot exist without both a `PERSON` and a `CAR` - the relationships become identifying and would be specified using hyphens, which translate to a solid line:
175
176| Value | Alias for |
177| :---: | :---------------: |
178| -- | _identifying_ |
179| .. | _non-identifying_ |
180
181**Aliases**
182
183| Value | Alias for |
184| :-----------: | :---------------: |
185| to | _identifying_ |
186| optionally to | _non-identifying_ |
187
188```mermaid-example
189erDiagram
190 CAR ||--o{ NAMED-DRIVER : allows
191 PERSON }o..o{ NAMED-DRIVER : is
192```
193
194```mermaid
195erDiagram
196 CAR ||--o{ NAMED-DRIVER : allows
197 PERSON }o..o{ NAMED-DRIVER : is
198```
199
200```mermaid-example
201erDiagram
202 CAR 1 to zero or more NAMED-DRIVER : allows
203 PERSON many(0) optionally to 0+ NAMED-DRIVER : is
204```
205
206```mermaid
207erDiagram
208 CAR 1 to zero or more NAMED-DRIVER : allows
209 PERSON many(0) optionally to 0+ NAMED-DRIVER : is
210```
211
212### Attributes
213
214Attributes can be defined for entities by specifying the entity name followed by a block containing multiple `type name` pairs, where a block is delimited by an opening `{` and a closing `}`. The attributes are rendered inside the entity boxes. For example:
215
216```mermaid-example
217erDiagram
218 CAR ||--o{ NAMED-DRIVER : allows
219 CAR {
220 string registrationNumber
221 string make
222 string model
223 }
224 PERSON ||--o{ NAMED-DRIVER : is
225 PERSON {
226 string firstName
227 string lastName
228 int age
229 }
230```
231
232```mermaid
233erDiagram
234 CAR ||--o{ NAMED-DRIVER : allows
235 CAR {
236 string registrationNumber
237 string make
238 string model
239 }
240 PERSON ||--o{ NAMED-DRIVER : is
241 PERSON {
242 string firstName
243 string lastName
244 int age
245 }
246```
247
248The `type` values must begin with an alphabetic character and may contain digits, hyphens, underscores, parentheses and square brackets. The `name` values follow a similar format to `type`, but may start with an asterisk as another option to indicate an attribute is a primary key. Other than that, there are no restrictions, and there is no implicit set of valid data types.
249
250### Entity Name Aliases
251
252An alias can be added to an entity using square brackets. If provided, the alias will be showed in the diagram instead of the entity name. Alias names follow all of the same rules as entity names.
253
254```mermaid-example
255erDiagram
256 p[Person] {
257 string firstName
258 string lastName
259 }
260 a["Customer Account"] {
261 string email
262 }
263 p ||--o| a : has
264```
265
266```mermaid
267erDiagram
268 p[Person] {
269 string firstName
270 string lastName
271 }
272 a["Customer Account"] {
273 string email
274 }
275 p ||--o| a : has
276```
277
278#### Attribute Keys and Comments
279
280Attributes may also have a `key` or comment defined. Keys can be `PK`, `FK` or `UK`, for Primary Key, Foreign Key or Unique Key (markdown formatting and unicode is not supported for keys). To specify multiple key constraints on a single attribute, separate them with a comma (e.g., `PK, FK`). A `comment` is defined by double quotes at the end of an attribute. Comments themselves cannot have double-quote characters in them.
281
282```mermaid-example
283erDiagram
284 CAR ||--o{ NAMED-DRIVER : allows
285 CAR {
286 string registrationNumber PK
287 string make
288 string model
289 string[] parts
290 }
291 PERSON ||--o{ NAMED-DRIVER : is
292 PERSON {
293 string driversLicense PK "The license #"
294 string(99) firstName "Only 99 characters are allowed"
295 string lastName
296 string phone UK
297 int age
298 }
299 NAMED-DRIVER {
300 string carRegistrationNumber PK, FK
301 string driverLicence PK, FK
302 }
303 MANUFACTURER only one to zero or more CAR : makes
304```
305
306```mermaid
307erDiagram
308 CAR ||--o{ NAMED-DRIVER : allows
309 CAR {
310 string registrationNumber PK
311 string make
312 string model
313 string[] parts
314 }
315 PERSON ||--o{ NAMED-DRIVER : is
316 PERSON {
317 string driversLicense PK "The license #"
318 string(99) firstName "Only 99 characters are allowed"
319 string lastName
320 string phone UK
321 int age
322 }
323 NAMED-DRIVER {
324 string carRegistrationNumber PK, FK
325 string driverLicence PK, FK
326 }
327 MANUFACTURER only one to zero or more CAR : makes
328```
329
330### Direction
331
332The direction statement declares the direction of the diagram.
333
334This declares that the diagram is oriented from top to bottom (`TB`). This can be reversed to be oriented from bottom to top (`BT`).
335
336```mermaid-example
337erDiagram
338 direction TB
339 CUSTOMER ||--o{ ORDER : places
340 CUSTOMER {
341 string name
342 string custNumber
343 string sector
344 }
345 ORDER ||--|{ LINE-ITEM : contains
346 ORDER {
347 int orderNumber
348 string deliveryAddress
349 }
350 LINE-ITEM {
351 string productCode
352 int quantity
353 float pricePerUnit
354 }
355```
356
357```mermaid
358erDiagram
359 direction TB
360 CUSTOMER ||--o{ ORDER : places
361 CUSTOMER {
362 string name
363 string custNumber
364 string sector
365 }
366 ORDER ||--|{ LINE-ITEM : contains
367 ORDER {
368 int orderNumber
369 string deliveryAddress
370 }
371 LINE-ITEM {
372 string productCode
373 int quantity
374 float pricePerUnit
375 }
376```
377
378This declares that the diagram is oriented from left to right (`LR`). This can be reversed to be oriented from right to left (`RL`).
379
380```mermaid-example
381erDiagram
382 direction LR
383 CUSTOMER ||--o{ ORDER : places
384 CUSTOMER {
385 string name
386 string custNumber
387 string sector
388 }
389 ORDER ||--|{ LINE-ITEM : contains
390 ORDER {
391 int orderNumber
392 string deliveryAddress
393 }
394 LINE-ITEM {
395 string productCode
396 int quantity
397 float pricePerUnit
398 }
399```
400
401```mermaid
402erDiagram
403 direction LR
404 CUSTOMER ||--o{ ORDER : places
405 CUSTOMER {
406 string name
407 string custNumber
408 string sector
409 }
410 ORDER ||--|{ LINE-ITEM : contains
411 ORDER {
412 int orderNumber
413 string deliveryAddress
414 }
415 LINE-ITEM {
416 string productCode
417 int quantity
418 float pricePerUnit
419 }
420```
421
422Possible diagram orientations are:
423
424- TB - Top to bottom
425- BT - Bottom to top
426- RL - Right to left
427- LR - Left to right
428
429### Styling a node
430
431It is possible to apply specific styles such as a thicker border or a different background color to a node.
432
433```mermaid-example
434erDiagram
435 id1||--||id2 : label
436 style id1 fill:#f9f,stroke:#333,stroke-width:4px
437 style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
438```
439
440```mermaid
441erDiagram
442 id1||--||id2 : label
443 style id1 fill:#f9f,stroke:#333,stroke-width:4px
444 style id2 fill:#bbf,stroke:#f66,stroke-width:2px,color:#fff,stroke-dasharray: 5 5
445```
446
447It is also possible to attach styles to a list of nodes in one statement:
448
449```
450 style nodeId1,nodeId2 styleList
451```
452
453#### Classes
454
455More convenient than defining the style every time is to define a class of styles and attach this class to the nodes that
456should have a different look.
457
458A class definition looks like the example below:
459
460```
461 classDef className fill:#f9f,stroke:#333,stroke-width:4px
462```
463
464It is also possible to define multiple classes in one statement:
465
466```
467 classDef firstClassName,secondClassName font-size:12pt
468```
469
470Attachment of a class to a node is done as per below:
471
472```
473 class nodeId1 className
474```
475
476It is also possible to attach a class to a list of nodes in one statement:
477
478```
479 class nodeId1,nodeId2 className
480```
481
482Multiple classes can be attached at the same time as well:
483
484```
485 class nodeId1,nodeId2 className1,className2
486```
487
488A shorter form of adding a class is to attach the classname to the node using the `:::`operator as per below:
489
490```mermaid-example
491erDiagram
492 direction TB
493 CAR:::someclass {
494 string registrationNumber
495 string make
496 string model
497 }
498 PERSON:::someclass {
499 string firstName
500 string lastName
501 int age
502 }
503 HOUSE:::someclass
504
505 classDef someclass fill:#f96
506```
507
508```mermaid
509erDiagram
510 direction TB
511 CAR:::someclass {
512 string registrationNumber
513 string make
514 string model
515 }
516 PERSON:::someclass {
517 string firstName
518 string lastName
519 int age
520 }
521 HOUSE:::someclass
522
523 classDef someclass fill:#f96
524```
525
526This form can be used when declaring relationships between entities:
527
528```mermaid-example
529erDiagram
530 CAR {
531 string registrationNumber
532 string make
533 string model
534 }
535 PERSON {
536 string firstName
537 string lastName
538 int age
539 }
540 PERSON:::foo ||--|| CAR : owns
541 PERSON o{--|| HOUSE:::bar : has
542
543 classDef foo stroke:#f00
544 classDef bar stroke:#0f0
545 classDef foobar stroke:#00f
546```
547
548```mermaid
549erDiagram
550 CAR {
551 string registrationNumber
552 string make
553 string model
554 }
555 PERSON {
556 string firstName
557 string lastName
558 int age
559 }
560 PERSON:::foo ||--|| CAR : owns
561 PERSON o{--|| HOUSE:::bar : has
562
563 classDef foo stroke:#f00
564 classDef bar stroke:#0f0
565 classDef foobar stroke:#00f
566```
567
568Similar to the class statement, the shorthand syntax can also apply multiple classes at once:
569
570```
571 nodeId:::className1,className2
572```
573
574### Default class
575
576If a class is named default it will be assigned to all classes without specific class definitions.
577
578```
579 classDef default fill:#f9f,stroke:#333,stroke-width:4px;
580```
581
582> **Note:** Custom styles from style or other class statements take priority and will overwrite the default styles. (e.g. The `default` class gives nodes a background color of pink but the `blue` class will give that node a background color of blue if applied.)
583
584```mermaid-example
585erDiagram
586 CAR {
587 string registrationNumber
588 string make
589 string model
590 }
591 PERSON {
592 string firstName
593 string lastName
594 int age
595 }
596 PERSON:::foo ||--|| CAR : owns
597 PERSON o{--|| HOUSE:::bar : has
598
599 classDef default fill:#f9f,stroke-width:4px
600 classDef foo stroke:#f00
601 classDef bar stroke:#0f0
602 classDef foobar stroke:#00f
603```
604
605```mermaid
606erDiagram
607 CAR {
608 string registrationNumber
609 string make
610 string model
611 }
612 PERSON {
613 string firstName
614 string lastName
615 int age
616 }
617 PERSON:::foo ||--|| CAR : owns
618 PERSON o{--|| HOUSE:::bar : has
619
620 classDef default fill:#f9f,stroke-width:4px
621 classDef foo stroke:#f00
622 classDef bar stroke:#0f0
623 classDef foobar stroke:#00f
624```
625
626## Configuration
627
628### Layout
629
630The layout of the diagram is handled by [`render()`](../config/setup/mermaid/interfaces/Mermaid.md#render). The default layout is dagre.
631
632For larger or more-complex diagrams, you can alternatively apply the ELK (Eclipse Layout Kernel) layout using your YAML frontmatter's `config`. For more information, see [Customizing ELK Layout](../intro/syntax-reference.md#customizing-elk-layout).
633
634```yaml
635---
636config:
637 layout: elk
638---
639```
640
641Your Mermaid code should be similar to the following:
642
643```mermaid-example
644---
645title: Order example
646config:
647 layout: elk
648---
649erDiagram
650 CUSTOMER ||--o{ ORDER : places
651 ORDER ||--|{ LINE-ITEM : contains
652 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
653```
654
655```mermaid
656---
657title: Order example
658config:
659 layout: elk
660---
661erDiagram
662 CUSTOMER ||--o{ ORDER : places
663 ORDER ||--|{ LINE-ITEM : contains
664 CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
665```
666
667> **Note**
668> Note that the site needs to use mermaid version 9.4+ for this to work and have this featured enabled in the lazy-loading configuration.
669
670<!--- cspell:locale en,en-gb --->
671