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

In the following subsections we will discuss the basic NoSQL-style methods which include the following operations:
Create, read, update, and delete operations
Iteration
Other operations
Note:
Data used in Basic NoSQL examples
In this chapter the examples will be based on the following simple Caché data set:
   ^Customer(1)="Jane K. White"
   ^Customer(1, "address")="Banstead"
   ^Customer(2)="John P.Jackson"
   ^Customer(3)="Jane Smith"
Save a Global Node: set()
Synchronous:
   var result = mydata.set(node);
Asynchronous:
   mydata.set(node, function(error, result){});
Example:
   mydata.set(
      {global: "Customer", subscripts: [1], data: "Jane K. White"},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   Operation successful if no error reported.
Retrieve a Global Node: get()
Synchronous:
   var result = mydata.get(node);
Asynchronous:
   mydata.get(node, function(error, result){});
Example 1 (Synchronous)
   result = mydata.get({global: "Customer", subscripts: [9]});
result:
   {global: "Customer", subscripts: [9], data: "", defined: 0}
Example 2 (Asynchronous)
   mydata.get(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   {global: "Customer", subscripts: [1], data: "Jane K. White", defined: 1}
Note that the defined property is set to 1 if the global node is actually defined and set to 0 if it is not.
Delete a Global Node: kill()
Synchronous:
   var result = mydata.kill(node);
Asynchronous:
   mydata.kill(node, function(error, result){});
Example:
   mydata.kill(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
Operation successful if no error reported.
Test for the Existence of a Global Node: data()
This method will return one of the following numeric values:
This method will return one of the following numeric values:
Synchronous:
   var result = mydata.data(node);
Asynchronous:
   mydata.data(node, function(error, result){});
Example:
   mydata.data(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   {defined: 11}
Get the Next Global Subscript: next()
Get the next value in the collating sequence for a particular level of subscript.
Synchronous:
   var result = mydata.order(node);
Asynchronous:
   mydata.order(node, function(error, result){});
Example 1 (Synchronous)
   result = mydata.order({global: "Customer", subscripts: [""]},
result:
   {global: "Customer", subscripts: [1], result: "1"}}
Example 2 (Synchronous)
   result = mydata.next({global: "Customer", subscripts: [3]},
result:
   {global: "Customer", subscripts: [""], result: ""}}
Example 3 (Asynchronous)
   mydata.next(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   {global: "Customer", subscripts: [2], result: "2"}}
Example 4 (Parse at the first level)
   key = {global: "Customer", subscripts: [""]};
   while ((key = user.next(key)).result != "") {
      console.log(JSON.stringify(key, null, '\t'))
   }
result:
   {global: "Customer", subscripts: [1], result: "1"}}
   {global: "Customer", subscripts: [2], result: "2"}}
   {global: "Customer", subscripts: [3], result: "3"}}
If there is no further subscript defined in the sequence then the result property will be returned as empty string ("").
Get the Previous Global Subscript: previous()
Get the previous value in the collating sequence for a particular level of subscript.
Synchronous:
   var result = mydata.previous(node);
Asynchronous:
   mydata.previous(node, function(error, result){});
Example 1 (Synchronous)
   result = mydata.previous({global: "Customer", subscripts: [""]},
result:
   {global: "Customer", subscripts: [3], result: "3"}}
Example 2 (Synchronous)
   result = mydata.previous({global: "Customer", subscripts: [2]},
result:
   {global: "Customer", subscripts: ["1"], result: "1"}}
Example 3 (Asynchronous)
   mydata.previous(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   {global: "Customer", subscripts: [""], result: ""}}
Example 4 (Parse at the first level)
   key = {global: "Customer", subscripts: [""]};
   while ((key = user.previous(key)).result != "") {
      console.log(JSON.stringify(key, null, '\t'))
   }
result:
   {global: "Customer", subscripts: [3], result: "3"}}
   {global: "Customer", subscripts: [2], result: "2"}}
   {global: "Customer", subscripts: [1], result: "1"}}
If there is no further subscript defined in the sequence then the result property will be returned as empty string ("").
Get the Next Global Node: next_node()
Get the next whole global node in the collating sequence regardless of the level of subscript.
Synchronous:
   var result = mydata.next_node(node);
Asynchronous:
   mydata.next_node(node, function(error, result){});
Example 1 (Synchronous)
   result = mydata.next_node({global: "Customer"},
result:
   {global: "Customer", subscripts: [1], data: "Jane K. White, defined: 1}}
Example 2 (Synchronous)
   result = mydata.next_node({global: "Customer", subscripts: [3]},
result:
   {global: "Customer", defined: 0}}
Example 3 (Asynchronous)
   mydata.next_node(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
Example 4 (Parse global)
   key = {global: "Customer"};
   while ((key = user.next_node(key)).defined) {
      console.log(JSON.stringify(key, null, '\t'));
   }
key:
   {
      global: "Customer",
      subscripts: [1],
      data: "Jane K. White",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [2],
      data: "John P.Jackson",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [3],
      data: "Jane Smith",
      defined: 1
   }
If there is no further node defined in the sequence then the defined property will be set to zero.
Get the Previous Global Node: previous_node()
Get the previous whole global node in the collating sequence regardless of the level of subscript.
Synchronous:
   var result = mydata.previous_node(node);
Asynchronous:
   mydata.previous_node(node, function(error, result){});
Example 1 (Synchronous)
   result = mydata.previous_node({global: "Customer", subscripts: ["z"]},
result:
   {global: "Customer", subscripts: [3], data: "Jane Smith", defined: 1}}
Example 2 (Synchronous)
   result = mydata.previous_node({global: "Customer", subscripts: [2]},
result:
   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
Example 3 (Asynchronous)
   mydata.previous_node(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
   {global: "Customer", defined: 0}}
Example 4 (Parse global)
   key = {global: "Customer", subscripts: ["z"]};
   while ((key = user.previous_node(key)).defined) {
      console.log(JSON.stringify(key, null, '\t'));
   }
result:
   {
      global: "Customer",
      subscripts: [3],
      data: "Jane Smith",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [2],
      data: "John P.Jackson",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [1, "address"],
      data: "Banstead",
      defined: 1
   }
   {
      global: "Customer",
      subscripts: [1],
      data: "Jane K. White",
      defined: 1
   }
If there is no further node defined in the sequence then the defined property will be set to zero.
Get the Next Value for an Integer Held in a Global Node: increment()
This method provides an efficient way of uniquely assigning an (incremented) integer to a process without using locking. When called, the integer value held in the global is incremented and the new value returned to the calling program. Caché will guarantee that a unique number is assigned to multiple processes that may be accessing this function simultaneously.
Synchronous:
   var result = mydata.increment(node);
Asynchronous:
   mydata.increment(node, function(error, result){});
Example 1 (Increment ^Counter by one)
   mydata.increment(
      {global: "Counter"},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
If successful the integer value held in global ^Counter will be incremented and the new value returned as the result.
Example 2 (Increment ^Counter by one – JSON based argument)
   result = mydata.increment({global: "Counter", increment: 1})
Example 3 (Increment ^Counter(1) by two)
   result = mydata.increment({global: "Counter", subscripts: [1], increment: 2})
Copy a Global: merge()
The merge() method copies either a whole global or a section of a global to another global.
Synchronous:
   var result = mydata.merge(
      {to: {destination_node},
       from: {source_node}};
   );
Asynchronous:
   mydata.merge(
      {{ to: {destination_node},
         from: {source_node}},
      function(error, result){}
   );
Example 1: Copy a whole global
   mydata.merge(
      {to: {global: "CopyOfCustomer"},
       from: {global: "Customer"}},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
If successful, the whole of global ^Customer will be copied to ^CopyOfCustomer.
Example 2: Copy a section of global
   mydata.merge(
      {to: {global: "Customer", subscripts: [7, "address"]},
       from: {global: "Customer", subscripts: [1, "address"]}},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
If successful, the subsection of global contained under "Customer(1,'address')" will be copied to "Customer(7,'address')".
Get a List of Globals in the Directory: global_directory()
This method will obtain a list of globals held in the directory. The number of names returned can be controlled using the range limiting properties lo, hi and max.
Synchronous:
   var result = mydata.global_directory(range);
Asynchronous:
   mydata.global_directory (range, function(error, result){});
Example 1: Obtain a list of all globals in the directory
   mydata.global_directory({},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
If successful, an array containing all global names found will be returned.
Example 2: Obtain a list of all globals whose name begins with "Cust"
   mydata.global_directory(
      {lo: "Cust", hi: "Cust~"},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
If successful, an array containing all global names beginning with Cust will be returned.
Lock and Unlock Global Nodes: lock() and unlock()
The Caché database contains the facility to lock either whole (for example, ^Customer) or sub-sections of a global (for example, ^Customer(1)) for exclusive use.
Synchronous:
   var result = mydata.lock(node);
   var result = mydata.unlock(node);
Asynchronous:
   mydata.lock(node, function(error, result){});
   mydata.unlock(node, function(error, result){});
Example:
   mydata.lock(
      {global: "Customer", subscripts: [1]},
      function(error, result) {
         if (error) { // error (see result.ErrorMessage and result.ErrorCode) 
         }
         else { // success 
         }
      }
   );
result:
Operation successful if no error reported.
Remember to, at some point, unlock all global nodes that your code previously locked in order to avoid deadlock situations.
Finally, to release all locks held by your program call the unlock() method with no node argument.
   var result = mydata.unlock();
   mydata.unlock(function(error, result){});
All locks held by a Node.js process will be released if and when the process terminates.