docs: document hasMany/belongsTo/hasOne limitations for NoSQL databases

Documented hasMany/belongsTo/hasOne limitations for NoSQL databases.
loopbackio · Apr 15, 2019 · 7cd5636 · 7cd5636
1 parent cb308ad
commit 7cd5636
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 0 deletions.
diff --git a/docs/site/BelongsTo-relation.md b/docs/site/BelongsTo-relation.md
@@ -8,6 +8,14 @@ permalink: /doc/en/lb4/BelongsTo-relation.html
 
 ## Overview
 
+{% include note.html content="
+This relation best works with databases that support foreign key
+constraint (SQL).
+Using this relation with NoSQL databases will result in unexpected behavior,
+such as the ability to create a model with a model that does not exist. We are working on a solution to better handle this. It is fine to use this relation with NoSQL databases for purposes such as navigating
+related models, where the referential integrity as not critical.
+" %}
+
 A `belongsTo` relation denotes a many-to-one connection of a model to another
 model through referential integrity. The referential integrity is enforced by a
 foreign key constraint on the source model which usually references a primary

diff --git a/docs/site/HasMany-relation.md b/docs/site/HasMany-relation.md
@@ -8,6 +8,14 @@ permalink: /doc/en/lb4/HasMany-relation.html
 
 ## Overview
 
+{% include note.html content="
+This relation best works with databases that support foreign key
+constraint (SQL).
+Using this relation with NoSQL databases will result in unexpected behavior,
+such as the ability to create a model with a model that does not exist. We are working on a solution to better handle this. It is fine to use this relation with NoSQL databases for purposes such as navigating
+related models, where the referential integrity as not critical.
+" %}
+
 A `hasMany` relation denotes a one-to-many connection of a model to another
 model through referential integrity. The referential integrity is enforced by a
 foreign key constraint on the target model which usually references a primary

diff --git a/docs/site/Relations.md b/docs/site/Relations.md
@@ -39,6 +39,14 @@ Here are the currently supported relations:
 - [BelongsTo](BelongsTo-relation.md)
 - [HasOne](hasOne-relation.md)
 
+{% include note.html content="
+The `hasMany` relation may alternatively be implemented using the
+`referencesMany` and `embedsMany` relations. These relations are similar, but
+not the same. Since each database paradigm comes with different trade-offs and
+thus different databases require the applications to use different relation
+types, use the relation best suited for your database.
+" %}
+
 The articles on each type of relation above will show you how to leverage the
 new relation engine to define and configure relations in your LoopBack
 application.
diff --git a/docs/site/hasOne-relation.md b/docs/site/hasOne-relation.md
@@ -8,6 +8,14 @@ permalink: /doc/en/lb4/hasOne-relation.html
 
 ## Overview
 
+{% include note.html content="
+This relation best works with databases that support foreign key and unique
+constraints (SQL).
+Using this relation with NoSQL databases will result in unexpected behavior,
+such as the ability to create a model with a model that does not exist. We are working on a solution to better handle this. It is fine to use this relation with NoSQL databases for purposes such as navigating
+related models, where the referential integrity as not critical.
+" %}
+
 A `hasOne` relation denotes a one-to-one connection of a model to another model
 through referential integrity. The referential integrity is enforced by a
 foreign key constraint on the target model which usually references a primary