Using Node.js with Caché
NoSQL Methods for Structured JSON Objects
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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.
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]