Enhancements and minor bug fixes, WMS 11912

json-to-duality-migrator/0-intro/introduction.md

@@ -4,6 +4,11 @@
 
 This workshop focuses on migrating from JSON Collections to Duality Views using the JSON to Duality Migrator in Oracle Database 23ai. You will learn how to migrate apps from a document to relational model automatically without any application changes.
 
+Watch this quick video to know why JSON Relational Duality is awesome.
+
+[](youtube:Eb_ytQBw2i8)
+
+
 ### **JSON Relational Duality**
 
 JSON Relational Duality is a landmark capability in Oracle Database 23ai providing game-changing flexibility and simplicity for Oracle Database developers. This breakthrough innovation overcomes the historical challenges developers have faced when building applications, using relational or document models.
@@ -12,11 +17,11 @@ JSON Relational Duality helps to converge the benefits of both document and rela
 
 Key benefits of JSON Relational Duality:
 
-* Experience extreme flexibility in building apps using Duality Views. Developers can access the same data relationally or as hierarchical documents based on their use case and are not forced into making compromises because of the limitations of the underlying database. Build document-centric apps on relational data or create SQL apps on documents.
-* Experience simplicity by retrieving and storing all the data needed for an app in a single database operation. Duality Views provide fully updatable JSON views over data. Apps can read a document, make necessary changes, and write the document back without worrying about underlying data structure, mapping, consistency, or performance tuning.
-* Enable flexibility and simplicity in building multiple apps on same data. Developers can define multiple Duality Views across overlapping groups of tables. This flexible data modeling makes building multiple apps against the same data easy and efficient.
-* Duality Views eliminate the inherent problem of data duplication and data inconsistency in document databases. Duality Views are fully ACID (atomicity, consistency, isolation, durability) transactions across multiple documents and tables. It eliminates data duplication across documents data, whereas consistency is maintained automatically.
-* Build apps that support high concurrency access and updates. Traditional locks don’t work well for modern apps. A new value-based concurrency control protocol provided with Duality Views supports high concurrency updates. The new protocol also works efficiently for interactive applications since the data is not locked during human thinking time.
+* **Experience extreme flexibility** in building apps using Duality Views. Developers can access the same data relationally or as hierarchical documents based on their use case and are not forced into making compromises because of the limitations of the underlying database. Build document-centric apps on relational data or create SQL apps on documents.
+* **Experience simplicity** by retrieving and storing all the data needed for an app in a single database operation. Duality Views provide fully updatable JSON views over data. Apps can read a document, make necessary changes, and write the document back without worrying about underlying data structure, mapping, consistency, or performance tuning.
+* **Enable flexibility and simplicity** in building multiple apps on same data. Developers can define multiple Duality Views across overlapping groups of tables. This flexible data modeling makes building multiple apps against the same data easy and efficient.
+* **Eliminate the inherent problem of data duplication and data inconsistency** in document databases. Duality Views are fully ACID (atomicity, consistency, isolation, durability) transactions across multiple documents and tables. It eliminates data duplication across documents data, whereas consistency is maintained automatically.
+* **Support high concurrency access and updates**. Traditional locks don’t work well for modern apps. A new value-based concurrency control protocol provided with Duality Views supports high concurrency updates. The new protocol also works efficiently for interactive applications since the data is not locked during human thinking time.
 
 ### **JSON to Duality Migrator**
 
@@ -42,11 +47,6 @@ How does the JSON to Duality Migrator work?
 3. Eliminates duplication by identifying shared data across collections
 4. Uses functional dependency analysis to automatically identify primary keys for each entity and foreign keys between the identified entities
 
-Watch this quick video to know why JSON Relational Duality is awesome.
-
-[](youtube:Eb_ytQBw2i8)
-
-Estimated Time: 50 minutes
 
 ### Objectives
 
@@ -57,6 +57,8 @@ In this lab, you will:
 * Migrate from JSON Collections to Duality Views using the JSON to Duality Migrator
 * Use the JSON to Duality Migrator's hint infrastructure to guide relational schema design
 
+Estimated Time: 50 minutes
+
 ### Prerequisites
 
 * Oracle Autonomous Database 23ai provisioned or one running in a LiveLabs environment

json-to-duality-migrator/1-json-collections/json-collections.md

@@ -27,157 +27,180 @@ In this lab, you will:
 
 In this task, we will create a JSON collection table called `attendee` that represents a collection of attendees for a database conference.
 
-1. Create the `attendee` collection.
-
-   ```sql
-   <copy>
-   DROP TABLE IF EXISTS attendee;
-   CREATE JSON COLLECTION TABLE IF NOT EXISTS attendee;
-   </copy>
-   ```
-
-   This creates a table with a single JSON-type object column named `DATA`. Because it's ultimately "just a table", you can use a JSON collection table in most of the ways that you use a regular table. In particular, you can use GoldenGate to replicate a collection table between databases, including between Oracle Database and JSON document databases, such as MongoDB.
-
-2. Insert data into the `attendee` collection.
-
-   ```sql
-   <copy>
-   INSERT INTO attendee VALUES
-     ('{"_id"          : 1,
-        "firstName"    : "Beda",
-        "lastName"     : "Hammerschmidt",
-        "nickName"     : "Dr. JSON",
-        "age"          : 20,
-        "phoneNumber"  : "222-111-021",
-        "coffeeItem"   : "Espresso",
-        "lectures" : [ {"id" : 10, "lectureName" : "JSON and SQL", "credits" : 3},
-                       {"id" : 20, "lectureName" : "PL/SQL or Javascript", "credits" : 4},
-                       {"id" : 30, "lectureName" : "MongoDB API Internals", "credits" : 5},
-                       {"id" : 40, "lectureName" : "Oracle ADB on iPhone", "credits" : 3},
-                       {"id" : 50, "lectureName" : "JSON Duality Views", "credits" : 3} ]}');
-   INSERT INTO attendee VALUES
-     ('{"_id"          : 2,
-        "firstName"    : "Hermann",
-        "lastName"     : "Baer",
-        "age"          : 22,
-        "phoneNumber"  : "222-112-023",
-        "coffeeItem"   : "Cappuccino",
-        "lectures" : [ {"id" : 10, "lectureName" : "JSON and SQL", "credits" : 3},
-                       {"id" : 30, "lectureName" : "MongoDB API Internals", "credits" : 5},
-                       {"id" : 40, "lectureName" : "JSON Duality Views", "credits" : 3} ]}');
-   INSERT INTO attendee VALUES
-     ('{"_id"           : 3,
-        "firstName"     : "Shashank",
-        "lastName"      : "Gugnani",
-        "nickName"      : "SG",
-        "age"           : 23,
-        "phoneNumber"   : "222-112-024",
-        "coffeeItem"    : "Americano",
-        "lectures" : [ {"id" : 10, "lectureName" : "JSON and SQL", "credits" : 3},
-                       {"id" : 30, "lectureName" : "MongoDB API Internals", "credits" : 5} ]}');
-   INSERT INTO attendee VALUES
-     ('{"_id"          : 4,
-        "firstName"    : "Julian",
-        "lastName"     : "Dontcheff",
-        "nickName"     : "Jul",
-        "age"          : 24,
-        "phoneNumber"  : "222-113-025",
-        "coffeeItem"   : "Decaf",
-        "lectures" : [ {"id" : 40, "lectureName" : "JSON Duality Views", "credits" : 3} ]}');
-
-   COMMIT;
-   </copy>
-   ```
+1. Click in the *Database Actions* dropdown list and select **View all database actions**
+
+   ![DB Actions](images/dbaction1.png)
+
+
+2. Below you can find the Database Actions homepage. Click the SQL tile under development to open the SQL worksheet.
+
+   ![Homepage Development SQL](./images/development-sql.png)
+
+3. In the SQL worksheet, create the `attendee` collection. 
+
+      Copy the SQL below and press the 'run script' button.
+
+      ```sql
+      <copy>
+      DROP TABLE IF EXISTS attendee;
+      CREATE JSON COLLECTION TABLE IF NOT EXISTS attendee;
+      </copy>
+      ```
+
+      ![SQL worksheet - run script](./images/sql-run-script.png)
+
+      This creates a table with a single JSON-type object column named `DATA`. Because it's ultimately "just a table", you can use a JSON collection table in most of the ways that you use a regular table. In particular, you can use GoldenGate to replicate a collection table between databases, including between Oracle Database and JSON document databases, such as MongoDB.
+
+4. Insert data into the `attendee` collection.
+
+      Copy the SQL below and press the 'run script' button.
+
+      ```sql
+      <copy>
+      INSERT INTO attendee VALUES
+      ('{"_id"          : 1,
+         "firstName"    : "Beda",
+         "lastName"     : "Hammerschmidt",
+         "nickName"     : "Dr. JSON",
+         "age"          : 20,
+         "phoneNumber"  : "222-111-021",
+         "coffeeItem"   : "Espresso",
+         "lectures" : [ {"id" : 10, "lectureName" : "JSON and SQL", "credits" : 3},
+                        {"id" : 20, "lectureName" : "PL/SQL or Javascript", "credits" : 4},
+                        {"id" : 30, "lectureName" : "MongoDB API Internals", "credits" : 5},
+                        {"id" : 50, "lectureName" : "Oracle ADB on iPhone", "credits" : 3},
+                        {"id" : 40, "lectureName" : "JSON Duality Views", "credits" : 3} ]}');
+      INSERT INTO attendee VALUES
+      ('{"_id"          : 2,
+         "firstName"    : "Hermann",
+         "lastName"     : "Baer",
+         "age"          : 22,
+         "phoneNumber"  : "222-112-023",
+         "coffeeItem"   : "Cappuccino",
+         "lectures" : [ {"id" : 10, "lectureName" : "JSON and SQL", "credits" : 3},
+                        {"id" : 30, "lectureName" : "MongoDB API Internals", "credits" : 5},
+                        {"id" : 40, "lectureName" : "JSON Duality Views", "credits" : 3} ]}');
+      INSERT INTO attendee VALUES
+      ('{"_id"           : 3,
+         "firstName"     : "Shashank",
+         "lastName"      : "Gugnani",
+         "nickName"      : "SG",
+         "age"           : 23,
+         "phoneNumber"   : "222-112-024",
+         "coffeeItem"    : "Americano",
+         "lectures" : [ {"id" : 10, "lectureName" : "JSON and SQL", "credits" : 3},
+                        {"id" : 30, "lectureName" : "MongoDB API Internals", "credits" : 5} ]}');
+      INSERT INTO attendee VALUES
+      ('{"_id"          : 4,
+         "firstName"    : "Julian",
+         "lastName"     : "Dontcheff",
+         "nickName"     : "Jul",
+         "age"          : 24,
+         "phoneNumber"  : "222-113-025",
+         "coffeeItem"   : "Decaf",
+         "lectures" : [ {"id" : 40, "lectureName" : "JSON Duality Views", "credits" : 3} ]}');
+
+      COMMIT;
+      </copy>
+      ```
 
    As you see, it looks like a normal SQL `INSERT` statement. The only difference is that we specified a proper JSON document as input for our DATA column. Copy the SQL statement and execute it in the SQL worksheet.
 
 ## Task 2: Access a JSON Collection
 
 1. Find a document in the `attendee` collection
 
-   ```sql
-   <copy>SELECT a.data FROM attendee a WHERE a.data."_id" = 1;</copy>
-   ```
+      ```sql
+      <copy>SELECT a.data FROM attendee a WHERE a.data."_id" = 1;</copy>
+      ```
 
-   ![Task 2 Step 1a Output](../1-json-collections/images/task2-step1a.png " ")
+      ![Task 2 Step 1a Output](../1-json-collections/images/task2-step1a.png " ")
 
-   We can also select specific fields within the JSON document by using the dot notation to peek inside the document.
+      **Tip:** If you get to the end of a long JSON column, you will see an eye. If you click on that eye, you will see your JSON document in a separate window in pretty format.
+
+      ![Task 2 Step 1a Output pretty](../1-json-collections/images/task2-step1a-pretty.png " ")
 
-   ```sql
-   <copy>
-   SELECT a.data.lastName || ', ' || a.data.firstName as name,
-          a.data.nickName as nick_name
-   FROM attendee a
-   WHERE a.data."_id" = 1;
-   </copy>
-   ```
+
+      We can also select specific fields within the JSON document by using the dot notation to peek inside the document.
+
+      ```sql
+      <copy>
+      SELECT a.data.lastName || ', ' || a.data.firstName as name,
+            a.data.nickName as nick_name
+      FROM attendee a
+      WHERE a.data."_id" = 1;
+      </copy>
+      ```
 
-   ![Task 2 Step 1b Output](../1-json-collections/images/task2-step1b.png " ")
+      ![Task 2 Step 1b Output](../1-json-collections/images/task2-step1b.png " ")
 
 2. Add a field to an existing document. We will add a `country` field to Julian's attendee document to specify his country of origin.
 
-   ```sql
-   <copy>
-   UPDATE attendee a
-   SET a.data = JSON_TRANSFORM(a.data, SET '$.country' = 'Finland')
-   WHERE a.data."_id" = 4;
+      Copy the SQL below in the SQL worksheet and run it.
 
-   COMMIT;
-   </copy>
-   ```
+      ```sql
+      <copy>
+      UPDATE attendee a
+      SET a.data = JSON_TRANSFORM(a.data, SET '$.country' = 'Finland')
+      WHERE a.data."_id" = 4;
+
+      COMMIT;
+      </copy>
+      ```
 
 3. Query the updated document. It should now contain the `country` field, which can also be queried using dot notation.
 
-   ```sql
-   <copy>SELECT a.data FROM attendee a WHERE a.data."_id" = 4;</copy>
-   ```
+      ```sql
+      <copy>SELECT a.data FROM attendee a WHERE a.data."_id" = 4;</copy>
+      ```
 
-   ![Task 2 Step 3a Output](../1-json-collections/images/task2-step3a.png " ")
+      ![Task 2 Step 3a Output](../1-json-collections/images/task2-step3a.png " ")
 
-   ```sql
-   <copy>
-   SELECT a.data.lastName || ', ' || a.data.firstName as name,
-          a.data.nickName as nick_name,
-          a.data.country as country
-   FROM attendee a
-   WHERE a.data."_id" = 4;
-   </copy>
-   ```
+      ```sql
+      <copy>
+      SELECT a.data.lastName || ', ' || a.data.firstName as name,
+            a.data.nickName as nick_name,
+            a.data.country as country
+      FROM attendee a
+      WHERE a.data."_id" = 4;
+      </copy>
+      ```
 
-   ![Task 2 Step 3b Output](../1-json-collections/images/task2-step3b.png " ")
+      ![Task 2 Step 3b Output](../1-json-collections/images/task2-step3b.png " ")
 
 ## Task 3: Update Shared Information
 
 In this task, we will update lecture name for lecture id 40, from "JSON Duality Views" to "JSON Relational Duality Views". Since lecture information is duplicated across multiple attendee documents, we must update the lecture name in all documents containing that lecture.
 
 1. Find all document that contain lecture id 40. We will use a `JSON_EXISTS` predicate to find all such documents.
 
-   ```sql
-   <copy>
-   SELECT data
-   FROM attendee
-   WHERE JSON_EXISTS(data, '$.lectures[*]?(@.id == 40)');
-   </copy>
-   ```
+      ```sql
+      <copy>
+      SELECT data
+      FROM attendee
+      WHERE JSON_EXISTS(data, '$.lectures[*]?(@.id == 40)');
+      </copy>
+      ```
+      You will see three records returned. For legibility we expanded one of the three records to show the redundant information about lecture 40 in one JSON document.
 
-   ![Task 3 Step 1 Output](../1-json-collections/images/task3-step1.png " ")
+      ![Task 3 Step 1 Output](../1-json-collections/images/task3-step1.png " ")
 
 2. Update the lecture name in all documents containing lecture id 40. We will use a `JSON_EXISTS` predicate to find all such documents, then use `JSON_TRANSFORM` to update the lecture name only for the matching lecture id.
 
-   ```sql
-   <copy>
-   UPDATE attendee
-   SET data = JSON_TRANSFORM(
-      data,
-      SET '$.lectures[*]?(@.id == 40).lectureName' = 'JSON Relational Duality Views'
-   )
-   WHERE JSON_EXISTS(data, '$.lectures[*]?(@.id == 40)');
-
-   COMMIT;
-   </copy>
-   ```
+      ```sql
+      <copy>
+      UPDATE attendee
+      SET data = JSON_TRANSFORM(
+         data,
+         SET '$.lectures[*]?(@.id == 40).lectureName' = 'JSON Relational Duality Views'
+      )
+      WHERE JSON_EXISTS(data, '$.lectures[*]?(@.id == 40)');
 
-   This statement updates three documents, each of which references lecture id 40.
+      COMMIT;
+      </copy>
+      ```
+
+   This statement updates three documents, each of which references lecture id 40. **Note that we needed to update three documents to correct the lecture name for all our attendees.**
 
 3. Select all documents from the view to see the updated documents.
 
@@ -188,6 +211,8 @@ In this task, we will update lecture name for lecture id 40, from "JSON Duality
    </copy>
    ```
 
+   You can scroll through the documents or drill down into the detail of individual documents. For illustration purposes we highlight two of the changed entries in the screenshot below. (We actually updated three documents before, so you will find the third one when scrolling to the right.)
+
    ![Task 3 Step 3 Output](../1-json-collections/images/task3-step3.png " ")
 
    We can see that the lecture name for lecture id 40 has now been updated consistently everywhere. It is easy to see the problem with JSON collections containing duplicate data - Any update to duplicate data must be managed carefully and kept consistent manually. In the next lab, we will see how duality views effectively solves this problem.