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

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
+constraints (SQL).
+Using this relation with NoSQL databases will result in unexpected behavior,
+such as the ability to create a relation with a model that does not exist. We are [working on a solution](https://github.com/strongloop/loopback-next/issues/2341) 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 is 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

docs/site/HasMany-relation.md

@@ -8,6 +8,13 @@ permalink: /doc/en/lb4/HasMany-relation.html
 
 ## Overview
 
+{% include note.html content="
+This relation best works with databases that support foreign key
+constraints (SQL).
+Using this relation with NoSQL databases will result in unexpected behavior,
+such as the ability to create a relation with a model that does not exist. We are [working on a solution](https://github.com/strongloop/loopback-next/issues/2341) 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 is 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

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](https://github.com/strongloop/loopback-next/issues/2341).
+" %}
+
 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.

docs/site/hasOne-relation.md

@@ -8,6 +8,13 @@ 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 relation with a model that does not exist. We are [working on a solution](https://github.com/strongloop/loopback-next/issues/2341) 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 is 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