JSON Data Modeling Guide: updates (#63)

* JSON Data Modeling Guide: updates, improvements, tweaks, fixes, corrections

* Update tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/02-using-json-documents.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/04-phases-of-data-modeling.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/05-json-design-choices.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: mgroves

tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/01-comparing-document-oriented-relational-data.md

@@ -8,7 +8,7 @@ description:
   - Learn the different characteristics of each and explore the flexibility of Couchbase
   - See an example dataset get mapped from relational to document-based
 content_type: tutorial
-filter: n1ql
+filter: sql++
 technology:
   - kv
   - capella

tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/02-using-json-documents.md

@@ -7,7 +7,7 @@ description:
   - A brief introduction to the JSON data format that illustrates the readability and ease of use
   - Learn about the basic data types supported in JSON and view a few example documents
 content_type: tutorial
-filter: n1ql
+filter: sql++
 technology:
   - kv
   - capella
@@ -31,7 +31,9 @@ The following are basic data types supported in JSON:
 
 For more information about creating valid JSON documents, please refer to [http://www.json.org](http://www.json.org).
 
-When you use JSON documents to represent your application data, you should think about the document as a logical container for information. This involves thinking about how data from your application fits into natural groups. It also requires thinking about the information you want to manage in your application. Doing data modeling for Couchbase Server is a similar process that you would do for traditional relational databases; there is however much more flexibility and you can change your mind later on your data structures. As a best practice, during your data/document design phase, you want to evaluate:
+When you use JSON documents to represent your application data, you should think about the document as a logical container for information. In Couchbase, JSON documents are organized into collections within scopes, which are similar in concept to tables and schemas in relational databases. Collections help isolate types of documents (e.g., `beers`, `breweries`, `users`) within a bucket, improving data organization, access control, and query performance. You should plan your document modeling with collections in mind.
+
+This involves thinking about how data from your application fits into natural groups. It also requires thinking about the information you want to manage in your application. Data modeling for Couchbase is a similar process that you would do for traditional relational databases; there is however much more flexibility and you can change your mind later on your data structures. During your data/document design phase, you should evaluate:
 
 - What are the _**things**_ you want to manage in your applications, for instance, _users_, _breweries_, _beers_ and so forth.
 - What do you want to store about the _**things**_. For example, this could be _alcohol percentage_, _aroma_, _location_, etc.
@@ -48,7 +50,7 @@ For instance, if you are creating a beer application, you might want a particula
 }
 ```
 
-For each of the keys in this JSON document you would provide unique values to represent individual beers. If you want to provide more detailed information in your beer application about the actual breweries, you could create a JSON structure to represent a brewery:
+For each of the keys in this JSON document, you would provide unique values to represent individual beers. If you want to provide more detailed information in your beer application about the breweries, you could create a JSON structure to represent a brewery:
 
 ```json
 {
@@ -61,7 +63,9 @@ For each of the keys in this JSON document you would provide unique values to re
 }
 ```
 
-Performing data modeling for a document-based application is no different than the work you would need to do for a relational database. For the most part it can be much more flexible, it can provide a more realistic representation or your application data, and it also enables you to change your mind later about data structure. For more complex items in your application, one option is to use nested pairs to represent the information:
+Performing data modeling for a document-based application is no different than the work you would need to do for a relational database. However, it can be much more flexible, it can provide a more realistic representation or your application data, and it also enables you to more easily change your mind later about data structure.
+
+For more complex items in your application, one option is to use nested objects to represent the information:
 
 ```json
 {
@@ -85,6 +89,6 @@ Performing data modeling for a document-based application is no different than t
 }
 ```
 
-In this case we added a nested attribute for the geolocation of the brewery and for beers. Within the location, we provide an exact longitude and latitude, as well as level of accuracy for plotting it on a map. The level of nesting you provide is your decision; as long as a document is under the maximum storage size for Couchbase Server, you can provide any level of nesting that you can handle in your application.
+In this case we added a nested attribute for the geolocation of the brewery and a nested attribute of its beers. The level of nesting you provide is your decision; as long as a document is under the maximum storage size (20MB per document), you can provide any level of nesting that you can handle in your application.
 
 In traditional relational database modeling, you would create tables that contain a subset of information for an item. For instance a _brewery_ may contain types of beers which are stored in a separate table and referenced by the _beer ID_. In the case of JSON documents, you use key-values pairs, or even nested key-value pairs.

tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/03-schemaless-data-modeling.md

@@ -8,7 +8,7 @@ description:
   - Explore important design considerations to keep in mind when designing JSON documents
   - See how you can use Couchbase's built-in Compare and Swap (CAS) functionality to maintain data consistency
 content_type: tutorial
-filter: n1ql
+filter: sql++
 technology:
   - kv
   - capella
@@ -34,42 +34,38 @@ While you can choose any structure for your documents, the JSON model in particu
 
 There are several considerations to have in mind when you design your JSON document:
 
-- Whether you want to use a type field at the highest level of your JSON document in order to group and filter object types.
 - What particular keys, ids, prefixes or conventions you want to use for items, for instance **beer\_My\_Brew**.
 - When you want a document to expire, if at all, and what expiration would be best.
 - If want to use a document to access other documents. In other words, you can store keys that refer other documents in a JSON document and get the keys through this document. In the NoSQL database jargon, this is often known as using _composite keys_.
 
-You can use a _type_ field to group together sets of records. For example, the following JSON document contains a _type_ field with the value _beer_ to indicate that the document represents a beer. A document that represents another kind of beverage would use a different value in the type field, such as _ale_ or _cider_.
+You can group together sets of records into collections. For example, the following JSON document could be in the "beers" collection. A document that represents another kind of entity would be in a different collection, such as _brewery_ or _user_.
 
 ```json
 {
   "beer_id": "beer_Hoptimus_Prime",
-  "type": "beer",
   "abv": 10,
   "category": "North American Ale",
   "name": "Hoptimus Prime",
   "style": "Double India Pale Ale"
 }
 ```
 
-Here is another _type_ of document in our application which we use to represent breweries. As in the case of beers, we have a type field we can use now or later to group and categorize our beer producers:
+Here is another document in the _breweries_ collection:
 
 ```json
 {
   "brewery_id": "brewery_Legacy_Brewing_Co",
-  "type": "brewery",
   "name": "Legacy Brewing Co.",
   "address": "525 Canal Street, Reading, Pennsylvania, 19601 United States",
   "updated": "2010-07-22 20:00:20"
 }
 ```
 
-What happens if we want to change the fields we store for a brewery? In this case we just add the fields to brewery documents. In this case we decide later that we want to include GPS location of the brewery:
+What happens if we want to change the fields we store for a brewery? Add the fields to brewery documents. In this case we decide later that we want to include GPS location of the brewery:
 
 ```json
 {
   "brewery_id": "brewery_Legacy_Brewing_Co",
-  "type": "brewery",
   "name": "Legacy Brewing Co.",
   "address": "525 Canal Street, Reading, Pennsylvania, 19601 United States",
   "updated": "2010-07-22 20:00:20",
@@ -78,7 +74,7 @@ What happens if we want to change the fields we store for a brewery? In this cas
 }
 ```
 
-So in the case of document-based data, we extend the record by just adding the two new fields for _latitude_ and _longitude_. When we add other breweries after this one, we would include these two new fields. For older breweries we can update them with the new fields or provide programming logic that shows a default for older breweries. The best approach for adding new fields to a document is to perform a compare and swap operation on the document to change it; with this type of operation, Couchbase Server will send you a message that the data has already changed if someone has already changed the record. For more information about compare and swap methods with Couchbase, see [Compare and Swap (CAS)](https://developer.couchbase.com/documentation/server/3.x/developer/dev-guide-3.0/update-info.html#concept29631__cas).
+In the case of document-based data, we extend the record by just adding the two new fields for _latitude_ and _longitude_. When we add other breweries after this one, we would include these two new fields. For older breweries we can update them with the new fields or provide programming logic that shows a default for older breweries. The best approach for adding new fields to a document is to perform a compare and swap operation on the document to change it; with this type of operation, Couchbase will send you a message that the data has already changed if someone has already changed the record. For more information about compare and swap methods with Couchbase, see [Compare and Swap (CAS)](https://docs.couchbase.com/java-sdk/current/howtos/concurrent-document-mutations.html).
 
 To create relationships between items, we again use fields. In this example we create a logical connection between beers and breweries using the _brewery_ field in our beer document which relates to the _ID_ field in the brewery document. This is analogous to the idea of using a foreign key in traditional relational database design.
 
@@ -87,7 +83,6 @@ This first document represents a beer, Hoptimus Prime:
 ```json
 {
   "beer_id": "beer_Hoptimus_Prime",
-  "type": "beer",
   "abv": 10,
   "brewery": "brewery_Legacy_Brewing_Co",
   "category": "North American Ale",
@@ -101,7 +96,6 @@ This second document represents the brewery which brews Hoptimus Prime:
 ```json
 {
   "brewery_id": "brewery_Legacy_Brewing_Co",
-  "type": "brewery",
   "name": "Legacy Brewing Co.",
   "address": "525 Canal Street Reading, Pennsylvania, 19601 United States",
   "updated": "2010-07-22 20:00:20",

tutorial/markdown/couchbase-server/best-practices/json-data-modeling-guide/04-phases-of-data-modeling.md

@@ -8,7 +8,7 @@ description:
   - Compare embedded documents to referenced documents and learn when to use each method
   - See best practices for building your data model
 content_type: tutorial
-filter: n1ql
+filter: sql++
 technology:
   - kv
   - capella
@@ -189,7 +189,6 @@ Referring to canonical instances of documents is a good default when modeling wi
 - You want to ensure your cache is used efficiently.
 - The embedded version would be unwieldy.
 
-
 That last point is particularly important where your documents have an unbound potential for growth.
 
 Imagine we were storing activity logs related to each user of our system. Embedding those logs in the user profile could lead to a rather large document.
@@ -211,17 +210,18 @@ It's unlikely we'd breach Couchbase's 20 MB upper limit for an individual docume
 
 The physical data model takes the logical data model and maps the entities and relationships to physical containers.
 
-In Couchbase Server, items are used to store associated values that can be accessed with a unique key. Couchbase Server also provides buckets to group items. Based on the access patterns, performance requirements, and atomicity and consistency requirements, you can choose the type of container(s) to use to represent your logical data model.
+In Couchbase, items are used to store associated values that can be accessed with a unique key. Couchbase also provides buckets to group items. Based on the access patterns, performance requirements, and atomicity and consistency requirements, you can choose the type of container(s) to use to represent your logical data model.
 
-The data representation and containment in Couchbase Server is drastically different from relational databases. The following table provides a high level comparison to help you get familiar with Couchbase Server containers.
+The data representation and containment in Couchbase is drastically different from relational databases. The following table provides a high level comparison to help you get familiar with Couchbase containers.
 
-**Data representation and containment in Couchbase Server versus relational databases:**
+**Data representation and containment in Couchbase versus relational databases:**
 
-| Couchbase Server  | Relational databases  |
+| Couchbase  | Relational databases  |
 |:------------------------------------  |:--------------------- |
-| Buckets | Databases |        
-| Buckets or Items (with type designator attribute)  | Tables |
-| Items (key-value or document) | Rows |
+| Buckets | Databases |
+| Scopes | Schema/namespace |
+| Collections | Tables |
+| Documents/Items | Rows |
 | Index | Index |
 
 ### Items
@@ -230,8 +230,8 @@ Items consist of a key and a value. A key is a unique identifier within the buck
 
 - **Keys**: Each value (binary or JSON) is identified by a unique key. The key is typically a surrogate key generated using a counter or a UUID generator. Keys are immutable. Thus, if you use composite or compound keys, ensure that you use attributes that don't change over time.
 - **Values**
-  - **Binary values**: Binary values can be used for high performance access to compact data through keys. Encrypted secrets, IoT instrument measurements, session states, or other non-human-readable data are typical cases for binary data. _Binary_ data may not necessarily be binary, but could be non-JSON formatted text like XML, String, etc. However, using binary values limits the functionality your application can take advantage of, ruling out indexing and querying in Couchbase Server as binary values have a proprietary representation.
-  - **JSON values**: JSON provides rich representation for entities. Couchbase Server can parse, index and query JSON values. JSON provide a name and a value for each attribute. You can find the JSON definition at [RFC 7159](https://tools.ietf.org/html/rfc7159) or at [ECMA 404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf).
+  - **Binary values**: Binary values can be used for high performance access to compact data through keys. Encrypted secrets, IoT instrument measurements, session states, or other non-human-readable data are typical cases for binary data. _Binary_ data may not necessarily be binary, but could be non-JSON formatted text like XML, String, etc. However, using binary values limits the functionality your application can take advantage of, ruling out indexing and querying in Couchbase as binary values have a proprietary representation.
+  - **JSON values**: JSON provides rich representation for entities. Couchbase can parse, index and query JSON values. JSON provide a name and a value for each attribute. You can find the JSON definition at [RFC 7159](https://tools.ietf.org/html/rfc7159) or at [ECMA 404](http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf). These type of items are typically called "documents".
 
 The JSON document attributes can represent both basic types such as number, string, Boolean, and complex types including embedded documents and arrays. In the examples below, a1 and a2 represent attributes that have a numeric and string value respectively, a3 represents an embedded document, and a4 represents an array of embedded documents.