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"

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");

Asynchronous:

   mydata.retrieve(node, "list", function(error, result){});

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 
         }
      }
   );

result (three Customer records):

   [1, 2, 3]

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 
         }
      }
   );

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

   [1, 2]

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");

Asynchronous:

   mydata.retrieve(node, "array", function(error, result){});

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
         }
      }
   );

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"
      }
   ]

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");

Asynchronous:

   mydata.update(node, "array", function(error, result){});

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
         }
      }
   );

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");

Asynchronous:

   mydata.retrieve(node, "object", function(error, result){});

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"

In Node.js:

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

Result:

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

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");

Asynchronous:

   mydata.update(node, "object", function(error, result){});

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
            }
      }
   );

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"

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"

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 
         }
      }
   );

result (six Customer records):

   [2, 3, 4, 5, 6, 7]

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 
         }
      }
   );

result (six Customer Order records):

   [20100507, 20100509, 20100510, 20100520, 20100527, 20100906]

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 
         }
      }
   );

result (one Customer Order record):

   [
      {  global: "Customer",
         subscripts: [1, "Orders", 20100906, "Reference"]
         data: "Order008"
      }
   ]

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 
         }
      }
   );

Result (three Customer records):

   [1, 2, 3]