Skip to main content
Previous section   Next section

NoSQL Methods for Structured JSON Objects

This section describes advanced methods that perform operations that could otherwise be achieved by combining several of the basic NoSQL-style methods.

The following Caché data will be used to illustrate these methods:

Data used in advanced NoSQL examples
   ^Customer(1)="Jane K. White"
   ^Customer(1, "Address", 1)="London"
   ^Customer(1, "Address", 2)="UK"
   ^Customer(1, "DateOfRegistration")="1 May 2010"
   ^Customer(2)="John P.Jackson"
   ^Customer(2, "Address", 1)="Reigate"
   ^Customer(2, "Address", 2)="UK"
   ^Customer(2, "DateOfRegistration")="7 May 2010"
   ^Customer(3)="Jane Smith"
   ^Customer(3, "Address", 1)="London"
   ^Customer(3, "Address", 2)="UK"
   ^Customer(3, "DateOfRegistration")="9 June 2010"
Copy code to clipboard

Retrieve a List of Global Nodes: retrieve("list")

This method will return a list of subscript values that are defined directly beneath a given level in the global.

Synchronous:

   var result = mydata.retrieve(node, "list");
Copy code to clipboard

Asynchronous:

   mydata.retrieve(node, "list", function(error, result){});
Copy code to clipboard
Example 1: Retrieve a list of customer numbers
   mydata.retrieve(
      {global: "Customer"},
      "list",
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result (three Customer records):

   [1, 2, 3]
Copy code to clipboard
Example 2: Retrieve a list of address lines for a specific customer
   mydata.retrieve(
      {global: "Customer", subscripts: [1, "address"]},
      "list"
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result (two lines in the address for customer number 1):

   [1, 2]
Copy code to clipboard

Retrieve a List of Global Nodes Recursively: retrieve("array")

This method will return a list of subscript values together with their associated data values that are defined beneath a given level in the global. The method is recursive and will retrieve all global nodes defined beneath a chosen level.

The result will be expressed as an array of global nodes: each global node expressed as a single JSON object.

Synchronous:

   var result = mydata.retrieve(node, "array");
Copy code to clipboard

Asynchronous:

   mydata.retrieve(node, "array", function(error, result){});
Copy code to clipboard
Example 1: Retrieve all data for a customer
   mydata.retrieve({global: "Customer", subscripts: [1]}, "array",
      function(error, result) {
         if (error) {
            // error   (see result.ErrorMessage
            //       and result.ErrorCode)
         }
         else {
            // success
         }
      }
   );
Copy code to clipboard

Result:

   [
      {   global: "Customer",
      subscripts: [1],
      data: "Jane K. White"
      }
      {   global: "Customer",
      subscripts: [1, "Address", 1],
      data: "London"
      }
      {   global: "Customer",
      subscripts: [1, "Address", 2],
      data: "UK"
      }
      {   global: "Customer",
      subscripts: [1, "DateOfRegistration],
      data: "1 May 2010"
      }
   ]
Copy code to clipboard

Save a List of Global Nodes: update("array")

This method performs the opposite task to that performed by the retrieve method. In other words the update method takes an array of global nodes, each expressed as a single JSON object and writes them back to the Caché database.

Synchronous:

   var result = mydata.update(node, "array");
Copy code to clipboard

Asynchronous:

   mydata.update(node, "array", function(error, result){});
Copy code to clipboard
Example 1: Create or update a record for a customer
   mydata.update([
      {   global: "Customer",
      subscripts: [1],
      data: "Jane K. White"
   }
      {   global: "Customer",
      subscripts: [1, "Address", 1],
      data: "London"
      }
      {   global: "Customer", subscripts: [1, "Address", 2],
      data: "UK"
      }
      {   global: "Customer",
      subscripts: [1, "DateOfRegistration],
      data: "1 May 2010"
      }
      ],
      "array",
      function(error, result) {
         if (error) {
            // error   (see result.ErrorMessage
            //       and result.ErrorCode)
         }
         else {
            // success
         }
      }
   );
Copy code to clipboard

Result:

Operation successful if no error reported.

Retrieve a Structured Data Object: retrieve("object")

This method will retrieve a structured data object defined beneath a given level in a global. This method provides a structured alternative to the array of global nodes described previously.

The result will be expressed as a single JSON object.

Synchronous:

   var result = mydata.retrieve(node, "object");
Copy code to clipboard

Asynchronous:

   mydata.retrieve(node, "object", function(error, result){});
Copy code to clipboard
Example: Retrieve all data for a customer

Consider the following structured Caché global:

   ^Customer(1, "Name")="Jane K. White"
   ^Customer(1, "Address", 1)="London"
   ^Customer(1, "Address", 2)="UK"
   ^Customer(1, "DateOfRegistration")="1 May 2010"
Copy code to clipboard

In Node.js:

   mydata.retrieve({global: "Customer", subscripts: [1]}, "object"
      function(error, result) {
         if (error) {
            // error    (see result.ErrorMessage
            //       and result.ErrorCode)
         }
         else {
            // success
         }
      }
   );
Copy code to clipboard

Result:

   {
      node: {   global: "Customer",
         subscripts: [1]
      }
      object: { Name: "Jane K. White",
         Address: {"1": "London", "2": "UK"}
         DateOfRegistration: "1 May 2010",
      }
   }
Copy code to clipboard

Save a Structured Data Object: update("object")

This method performs the opposite task to that performed by the retrieve method. In other words it writes the contents of a structured JSON object back to the Caché database.

Synchronous:

   var result = mydata.update(node, "object");
Copy code to clipboard

Asynchronous:

   mydata.update(node, "object", function(error, result){});
Copy code to clipboard
Example 1: Create or update a record for a customer
   mydata.update({   node: {global: "Customer",
                           subscripts: [1]
                  },
            Object: {Name: "Jane K. White",
                  DateOfRegistration: "1 May 2010",
                  Address: {"1": "London", "2": "UK"}
                  },
               "object",
            function(error, result) {
            if (error) {
               // error    (see result.ErrorMessage
               //       and result.ErrorCode)
            }
            else {
               // success
            }
      }
   );
Copy code to clipboard

Result:

Operation successful if no error reported. If successful, the following set of global nodes will be created for this example:

   ^Customer(1, "Address", 1)="London"
   ^Customer(1, "Address", 2)="UK"
   ^Customer(1, "DateOfRegistration")="1 May 2010"
   ^Customer(1, "Name")="Jane K. White"
Copy code to clipboard

Controlling the Amount of Data Returned by Retrieve Operations

Clearly the retrieve operations are capable, depending on the underlying global structure, of returning enormous volumes of data to the Node.js environment. The following properties can be added to the requesting JSON object (i.e. the object defining the root global node) to limit the amount of data returned.

  • max — The maximum number of global nodes to return.

  • lo — The lowest global subscript to return.

  • hi — The highest global subscript to return.

If all three properties are defined, the retrieve operation will terminate when the max number of global nodes have been returned, even if the global subscript defined in hi has not been reached.

Consider the following Caché global:

   ^Customer(1, "Address", 1)="London"
   ^Customer(1, "Address", 2)="UK"
   ^Customer(1, "DateOfRegistration")="1 May 2010"
   ^Customer(1, "Name")="Jane K. White"
   ^Customer(1, "Orders", 20100501, "Reference")="Order001"
   ^Customer(1, "Orders", 20100503, "Reference")="Order002"
   ^Customer(1, "Orders", 20100507, "Reference")="Order003"
   ^Customer(1, "Orders", 20100509, "Reference")="Order004"
   ^Customer(1, "Orders", 20100510, "Reference")="Order005"
   ^Customer(1, "Orders", 20100520, "Reference")="Order006"
   ^Customer(1, "Orders", 20100527, "Reference")="Order007"
   ^Customer(1, "Orders", 20100906, "Reference")="Order008"
   ^Customer(1, "Orders", 20110104, "Reference")="Order011"
   ^Customer(1, "Orders", 20110203, "Reference")="Order012"
   ^Customer(2, "Address", 1)="Reigate"
   ^Customer(2, "Address", 2)="UK"
   ^Customer(2, "DateOfRegistration")="7 May 2010"
   ^Customer(2, "Name")="John P.Jackson"
   ^Customer(2, "Orders", 20101204, "Reference")="Order009"
   ^Customer(2, "Orders", 20101206, "Reference")="Order010"
   ^Customer(3, "Address", 1)="London"
   ^Customer(3, "Address", 2)="UK"
   ^Customer(3, "DateOfRegistration")="9 June 2010"
   ^Customer(3, "Name")="Jane Smith"
   ^Customer(4, "Name")="Jim Cooper"
   ^Customer(5, "Name")="Eve Simpson"
   ^Customer(6, "Name")="John Cotton"
   ^Customer(7, "Name")="Alison Clarke"
   ^Customer(8, "Name")="Paul Francis"
   ^Customer(9, "Name")="Susan Reed"
   ^Customer(10, "Name")="Mary Dodds"
Copy code to clipboard
Note:

The third subscript in the Orders section is the date in YYYYMMDD format.

Example 1: List the registered Customer numbers between 2 and 7 (inclusive)
   mydata.retrieve(
      {global: "Customer", lo: 2, hi: 7},
      "list",
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result (six Customer records):

   [2, 3, 4, 5, 6, 7]
Copy code to clipboard
Example 2: List the Orders placed by Customer number 1 between 7 May 2010 and 24 December 2010 (inclusive)
   mydata.retrieve(
      {  global: "Customer",
         subscripts: [1, "Orders"],
         lo: 20100507, 
         hi: 20101224
      },
      "list",
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result (six Customer Order records):

   [20100507, 20100509, 20100510, 20100520, 20100527, 20100906]
Copy code to clipboard
Example 3: List the full details for Orders placed by Customer number 1 in September 2010
   mydata.retrieve(
      {  global: "Customer",
         subscripts: [1, "Orders"],
         lo: 20100901, 
         hi: 20100930
      },
      "array",
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

result (one Customer Order record):

   [
      {  global: "Customer",
         subscripts: [1, "Orders", 20100906, "Reference"]
         data: "Order008"
      }
   ]
Copy code to clipboard
Example 4: List first three Customers registered (by Customer number) in the database
   mydata.retrieve(
      {global: "Customer", max: 3},
      "list",
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
Copy code to clipboard

Result (three Customer records):

   [1, 2, 3]
Copy code to clipboard