Show JSON examples with 12.2's easier dot notation

Author: cjbj

doc/api.md

@@ -5570,17 +5570,17 @@ As an example, the following table has a `PO_DOCUMENT` column that is
 enforced to be JSON:
 
 ```sql
-CREATE TABLE po (po_document VARCHAR2(4000) CHECK (po_document IS JSON));
+CREATE TABLE j_purchaseorder (po_document VARCHAR2(4000) CHECK (po_document IS JSON));
 ```
 
 To insert data using node-oracledb:
 
 ```javascript
-var data = { customerId: 100, item: 1234, quantity: 2 };
+var data = { "userId": 1, "userName": "Chris", "location": "Australia" };
 var s = JSON.stringify(data);  // change JavaScript value to a JSON string
 
 connection.execute(
-  "INSERT INTO po (po_document) VALUES (:bv)",
+  "INSERT INTO j_purchaseorder (po_document) VALUES (:bv)",
   [s]  // bind the JSON string
   function (err) {
   . . .
@@ -5594,17 +5594,24 @@ and array ranges.  An example is `$.friends` which is the value of
 JSON field `friends`.
 
 Oracle provides SQL functions and conditions to create, query, and
-operate on JSON data stored in the database.  An example is the Oracle
-SQL Function `JSON_TABLE` which projects JSON data to a relational
-format effectively making it usable like an inline relational view.
-Another example is `JSON_EXISTS` which tests for the existence of a
-particular value within some JSON data:
+operate on JSON data stored in the database.
 
-This example looks for JSON entries that have a `quantity` field:
+For example, `j_purchaseorder` can be queried with:
+
+```
+"SELECT po.po_document.location FROM j_purchaseorder po"
+```
+
+With the earlier JSON inserted into the table, the queried value would
+be `Australia`.
+
+The `JSON_EXISTS` tests for the existence of a particular value within
+some JSON data.  To look for JSON entries that have a `quantity`
+field:
 
 ```JavaScript
 conn.execute(
-  "SELECT po_document FROM po WHERE JSON_EXISTS (po_document, '$.quantity')",
+  "SELECT po_document FROM j_purchaseorder WHERE JSON_EXISTS (po_document, '$.location')",
   function(err, result) {
     if (err) {
       . . .
@@ -5615,10 +5622,10 @@ conn.execute(
   });
 ```
 
-After the previous `INSERT` example, this query would display:
+This query would display:
 
 ```
-{ customerId: 100, item: 1234, quantity: 2 }
+{ userId: 1, userName: 'Chris', location: 'Australia' }
 ```
 
 In Oracle Database 12.2 the [`JSON_OBJECT` ][54] function is a great

examples/selectjson.js

@@ -88,9 +88,24 @@ var dojsonquery = function (conn, cb) {
     });
 };
 
-// 2. Using JSON_VALUE to extract a value from a JSON column
+// 2. Extract a value from a JSON column.  This syntax requires Oracle Database 12.2
+var dorelationalquerydot = function (conn, cb) {
+  console.log('2. Using dot-notation to extract a value from a JSON column');
+  conn.execute(
+    "SELECT po.po_document.location FROM j_purchaseorder po",
+    function(err, result) {
+      if (err) {
+        return cb(err, conn);
+      } else {
+        console.log('Query results: ', result.rows[0][0]);  // just show first record
+        return cb(null, conn);
+      }
+    });
+};
+
+// 3. Using JSON_VALUE to extract a value from a JSON column
 var dorelationalquery = function (conn, cb) {
-  console.log('2. Using JSON_VALUE to extract a value from a JSON column');
+  console.log('3. Using JSON_VALUE to extract a value from a JSON column');
   conn.execute(
     "SELECT JSON_VALUE(po_document, '$.location') FROM j_purchaseorder",
     function(err, result) {
@@ -103,9 +118,9 @@ var dorelationalquery = function (conn, cb) {
     });
 };
 
-// 3. Using JSON_OBJECT to extract relational data as JSON
+// 4. Using JSON_OBJECT to extract relational data as JSON
 var dojsonfromrelational = function (conn, cb) {
-  console.log('3. Using JSON_OBJECT to extract relational data as JSON');
+  console.log('4. Using JSON_OBJECT to extract relational data as JSON');
   if (conn.oracleServerVersion < 1202000000) { // JSON_OBJECT is new in Oracle Database 12.2
     console.log('The JSON_OBJECT example only works with Oracle Database 12.2 or greater');
     return cb(null, conn);
@@ -133,6 +148,7 @@ async.waterfall(
     checkver,
     doinsert,
     dojsonquery,
+    dorelationalquerydot,
     dorelationalquery,
     dojsonfromrelational
   ],

examples/selectjsonblob.js

@@ -19,7 +19,7 @@
  *   selectjsonblob.js
  *
  * DESCRIPTION
- *   Executes sample insert and query using a JSON column with BLOB storage.
+ *   Executes sample insert and query statements using a JSON column with BLOB storage.
  *   Requires Oracle Database 12.1.0.2, which has extensive JSON datatype support.
  *   See https://docs.oracle.com/database/122/ADJSN/toc.htm
  *
@@ -70,10 +70,10 @@ var doinsert = function (conn, cb) {
     });
 };
 
-// Select JSON stored in a BLOB column
+// Select JSON with JSON_EXISTS
 
 var dojsonquery = function (conn, cb) {
-  console.log('Selecting JSON stored in a BLOB column');
+  console.log('Selecting JSON stored in a BLOB column:');
   conn.execute(
     "SELECT po_document FROM j_purchaseorder_b WHERE JSON_EXISTS (po_document, '$.location')",
     [],
@@ -84,18 +84,35 @@ var dojsonquery = function (conn, cb) {
       if (result.rows.length === 0)
         return cb(new Error('No results'), conn);
 
-      console.log('Query results:');
       console.log(result.rows[0][0].toString('utf8'));
       return cb(null, conn);
     });
 };
 
+// Select a JSON value using dot-notation.  This syntax requires Oracle Database 12.2
+
+var dojsonquerydot = function (conn, cb) {
+  console.log('Selecting a JSON value:');
+  conn.execute(
+    "SELECT pob.po_document.location FROM j_purchaseorder_b pob",
+    function(err, result) {
+      if (err)
+        return cb(err, conn);
+      if (result.rows.length === 0)
+        return cb(new Error('No results'), conn);
+
+      console.log(result.rows[0][0]);
+      return cb(null, conn);
+    });
+};
+
 async.waterfall(
   [
     doconnect,
     checkver,
     doinsert,
-    dojsonquery
+    dojsonquery,
+    dojsonquerydot
   ],
   function (err, conn) {
     if (err) { console.error("In waterfall error cb: ==>", err, "<=="); }