Skip to content

Commit b15b263

Browse files
jeff-allen-mongojeff-allen-mongo
authored
(DOCSP-30631): Migrate Diagrams section to snooty (#16)
* (DOCSP-30631): Migrate Diagrams section to snooty * add Understand Diagrams page * fixes * wording
1 parent 8385101 commit b15b263

File tree

5 files changed

+271
-5
lines changed

5 files changed

+271
-5
lines changed

‎source/diagrams/diagrams.txt

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,48 @@
1+
.. _rm-diagrams:
2+
13
========
24
Diagrams
35
========
46

5-
TBD.
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Diagrams function as an Entity Relationship Diagram (ERD) tool to
14+
visualize tables, foreign key relationships, and data types. Diagrams
15+
help you understand the relational database's schema, and show you how
16+
to best represent relational data in MongoDB. Diagrams also show how
17+
your mapping rules shape the target MongoDB schema.
18+
19+
When you finish :ref:`creating a migration project
20+
<rm-create-project-live>`, Relational Migrator creates a new diagram
21+
based on your project's mapping rules. The diagram is comprised of two
22+
views:
23+
24+
- A Relational view, representing the tables in your relational
25+
database
26+
27+
- A MongoDB view, representing the collections in your target MongoDB
28+
database
29+
30+
When you :ref:`edit mapping rules <mapping-rules-edit>` for your
31+
project, the MongoDB view automatically updates to reflect the new
32+
rules.
33+
34+
The relational view is unaffected by mapping rules, and only changes
35+
when you update your project's data model.
36+
37+
Learn More
38+
----------
39+
40+
- :ref:`understand-diagrams`
41+
42+
- :ref:`navigate-diagrams-and-entities`
43+
44+
- :ref:`rm-apply-layout`
45+
646

747
.. toctree::
848
:hidden:

‎source/diagrams/navigate-diagrams/navigate-diagrams.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _navigate-diagrams-and-entities:
2+
13
==============================
24
Navigate Diagrams and Entities
35
==============================
@@ -73,4 +75,4 @@ Learn More
7375
:hidden:
7476
:titlesonly:
7577

76-
/diagrams/navigate-diagrams/apply-layout
78+
/diagrams/navigate-diagrams/apply-layout

‎source/diagrams/understand-diagrams.txt

Lines changed: 221 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,223 @@
1+
.. _understand-diagrams:
2+
13
===================
24
Understand Diagrams
3-
===================
5+
===================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
This page explains how to interpret diagrams created in the Relational
14+
Migrator. Each diagram is comprised of two views, one for your
15+
relational database and one for your MongoDB database. The views show
16+
the relationships between entities in your databases.
17+
18+
Relational View
19+
---------------
20+
21+
In the relational view, each box represents a table in your
22+
relational database. The box title indicates the table name.
23+
24+
Each box lists the columns in the corresponding table. For each column,
25+
the box indicates the column name and its data type.
26+
27+
Some columns have icons to indicate their role within the table:
28+
29+
- A key icon indicates the table's primary key.
30+
31+
- A link icon indicates a foreign key.
32+
33+
MongoDB View
34+
------------
35+
36+
In the MongoDB view, each box represents a collection in your
37+
MongoDB database. The box title indicates the collection name.
38+
39+
Each box lists the fields in the corresponding collection. For each
40+
field, the box indicates the field name and its data type.
41+
42+
If a collection contains embedded documents or arrays, those fields are
43+
shown in-line in the same collection.
44+
45+
Some fields have icons to indicate their role within the table:
46+
47+
- A key icon indicates the collection's ``_id`` field. When you use the
48+
``wrapped`` key handling strategy, the ``_id`` field contains
49+
sub-fields. In this case, the box contains multiple key icons which
50+
apply to a single field.
51+
52+
- A link icon indicates that the field maps to a relational column used
53+
in a foreign key.
54+
55+
Choose View Mode
56+
----------------
57+
58+
The Relational Migrator provides different view modes for your diagrams:
59+
Horizontal Split, Vertical Split, Relational view, and MongoDB view.
60+
61+
.. list-table::
62+
:header-rows: 1
63+
:widths: 10 20
64+
65+
* - View Mode
66+
- Description
67+
68+
* - Horizontal Split
69+
- Displays the relational view on top and the MongoDB view is on
70+
the bottom. When you create a new project, Horizontal Split is
71+
the default view mode.
72+
73+
* - Vertical Split
74+
- Displays the relational view on the left and the MongoDB view on
75+
the right.
76+
77+
* - Relational View
78+
- Displays only your relational database diagram.
79+
80+
* - MongoDB View
81+
- Displays only your MongoDB database diagram.
82+
83+
To switch view modes, click a view mode option in the left navigation
84+
bar:
85+
86+
.. image:: /img/diagrams/viewing-mode.png
87+
:alt: View Modes
88+
89+
Color Coding
90+
------------
91+
92+
Entities in the diagram are color-coded based on whether they represent
93+
the relational or MongoDB database:
94+
95+
- Entities with pink highlights are relational tables.
96+
97+
- Entities with green highlights are MongoDB collections.
98+
99+
Entity Links
100+
------------
101+
102+
The lines between boxes represent the relationships that connect
103+
database entities. If two boxes are connected, the corresponding
104+
entities are linked with a foreign key. The lines may show the following
105+
features of relationships:
106+
107+
- A small bar across a relationship link indicates a one-to-one
108+
relationship between entities.
109+
110+
- A prong (or "crow's feet") indicates "many" in the relationship.
111+
112+
Relational and MongoDB View Links
113+
---------------------------------
114+
115+
When you click a box in either the relational or MongoDB view, the
116+
Relational Migrator highlights the corresponding entity in the opposite
117+
view. This allows you to see how your relational tables and MongoDB
118+
collections are mapped to one another.
119+
120+
Example
121+
-------
122+
123+
The following example shows a sample diagram for a database that
124+
tracks orders at a store.
125+
126+
Relational View
127+
~~~~~~~~~~~~~~~
128+
129+
This relational view shows the relationship of several tables within a
130+
relational database:
131+
132+
.. image:: /img/diagrams/relational-diagram.png
133+
:alt: Relational Diagram Example
134+
135+
136+
The view shows the following relationships:
137+
138+
139+
- In the ``Order`` table, ``OrderID`` is the primary key. ``CustomerID`` and
140+
``OrderStatusID`` are foreign keys. The ``Customer`` and ``OrderStatus``
141+
tables contain the references for these foreign keys, respectively.
142+
143+
144+
- ``Order`` to ``Customer`` and ``Order`` to ``OrderStatus`` are both
145+
many-to-one relationships:
146+
147+
148+
- A customer can have multiple orders, and each order only applies
149+
to a single customer. In this example, Order is the parent and
150+
Customer is the child.
151+
152+
- An order status can apply to multiple orders, and each order only
153+
has a single order status. In this example, Order is the parent
154+
and OrderStatus is the child.
155+
156+
- In the ``OrderLine`` table, ``OrderLineID`` is the primary key. ``OrderID``
157+
and ``ProductID`` are foreign keys. The ``Order`` and ``Product`` tables
158+
contain the references for these foreign keys, respectively.
159+
160+
161+
- ``OrderLine`` to ``Order`` and ``OrderLine`` to ``Product`` are both
162+
many-to-one relationships:
163+
164+
165+
- An order line is an individual transaction within an order. An
166+
order can have multiple order lines, and each order line applies
167+
to a single order. In this example, OrderLine is the parent and
168+
Order is the child.
169+
170+
- A product can apply to multiple order lines, and each order line
171+
contains a single product. In this example, OrderLine is the parent
172+
and Product is the child.
173+
174+
MongoDB View
175+
~~~~~~~~~~~~
176+
177+
This MongoDB view corresponds to the previous Relational view:
178+
179+
180+
.. image:: /img/diagrams/mongodb-diagram-2.png
181+
:alt: MongoDB Diagram Example
182+
183+
184+
The collections and data types presented in the view reflect the
185+
mapping rules specified for the project.
186+
187+
The link icons indicate fields which map to a relational column used in a
188+
foreign key. For example, in the ``Order`` collection, the ``OrderStatusID``
189+
field represents a foreign key that links the ``Order`` and ``OrderStatus``
190+
tables.
191+
192+
New Mapping Rules
193+
~~~~~~~~~~~~~~~~~
194+
195+
The following new mapping rules have been created to better utilize
196+
MongoDB's embedded data model:
197+
198+
199+
- The ``Order`` collection contains a rule that maps ``OrderLines`` as
200+
an :ref:`Embedded array <mapping-rule-embedded-array>`. The
201+
``OrderLine`` table from the relational schema is mapped as an array
202+
of objects inside the ``Order`` documents, using the foreign key
203+
relationship from the relational schema.
204+
205+
206+
.. image:: /img/diagrams/order-mapping-example.png
207+
:alt: Order Mapping Rule Example
208+
209+
210+
- The ``Customer`` collection contains a rule which maps ``Orders`` as
211+
an :ref:`Embedded array <mapping-rule-embedded-array>`. The ``Order``
212+
table from the relational schema is mapped as an array of objects
213+
inside the ``Customer`` documents, using the foreign key relationship
214+
from the relational schema.
215+
216+
217+
.. image:: /img/diagrams/customer-mapping-example.png
218+
:alt: Customer Mapping Rule Example
219+
220+
Both of the preceding mapping rules remove the ID fields from the
221+
mapping. Since the ``OrderLines`` and ``Orders`` fields are embedded in
222+
their parent fields rather than being referenced with a foreign key, the
223+
ID fields are not required to link the fields together.

‎source/mapping-rules/edit-rules.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _mapping-rules-edit:
2+
13
==========
24
Edit Rules
3-
==========
5+
==========

‎source/mapping-rules/mapping-rule-options/embedded-array.txt

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _mapping-rule-embedded-array:
2+
13
==============
24
Embedded Array
3-
==============
5+
==============

0 commit comments

Comments
 (0)