Collection Data Store

A collection data store is simply a collection of items. Data stored in collection data stores is indexed to make it easy to work with.

API

The data storage API is available in WebApps and RESTApps.

// retrieve an instance of the storage API
const storage = require('storage');
// get a collection store
// if no collection store exists with the provided name, one will be created
// (note: the name must also be explicitly registered in the app's manifest.json)
const collectionDataStore = storage.getCollectionDataStore('myCollectionStore');

add(data, callback)

Adds an item to a collection

Argument

Description

data

JSON data to store

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain the stored data.

const person = {
   name: 'Foo',
   age: 33
};

collectionDataStore.add(person, (err, data) => {
   if (err) {
   // handle error
   }
   // data --> 
   {
      dsid: '00e40be0-59c7-11e9-9d84-7a4f433f610f', 
      name: 'Foo', 
      dstimestamp: 1554704685982, 
      age: 33
   }
});

addAll(data, callback)

Adds an array of items to a collection

Argument

Description

data

An array of objects to store

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise.

const people = [
   {
      name: 'Foo',
      age: 33
   },
   {
      name: 'Bar',
      age: 34
   }
];

collectionDataStore.addAll(people, err => {
   if (err) {
   // handle error
   }
});

get(dsid, callback)

Gets a specific item in a collection

Argument

Description

dsid

The dsid to identify the item to retrieve data from

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain the stored data.

collectionDataStore.get(dsid, (err, data) => {
   if (err) {
   // handle error
   }
   // ...
});

set(dsid, data, callback)

Updates a specific item in a collection (partial update)

Argument

Description

dsid

The dsid to identify the item to update

data

JSON data to update the item

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain the stored data.

collectionDataStore.set(dsid, data, (err, data) => {
   if (err) {
   // handle error
   }
   // ...
});

If a property is set to null, the property will be removed

remove(dsid, callback)

Removes a specific item in a collection

Argument

Description

dsid

The dsid to identify the item to remove

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain the removed data.

collectionDataStore.remove(dsid, (err, data) => {
   if (err) {
   // handle error
   }
   // ...
});

removeAll(callback)

Removes all items in a collection

Argument

Description

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise.

collectionDataStore.removeAll(err => {
   if (err) {
   // handle error
   }
});

First level data is asynchronously indexed in a new DataStorage Solr index. Queries are performed using regular Solr-syntax.

Index fields (object keys) are prefixed with 'ds'. Numerical values will also get a numerical field:

  • ds.analyzed.<key> - "analyzed" and "stored" data (solr.TextField)
  • ds.double.<key> - "numerical" and "stored" data (solr.TrieDoubleField)

find(query, count, skip)

Returns a search result

Argument

Description

Default

query

The search query (Solr query syntax)


count

Maximum number of hits to return

10

skip

Number of leading hits to be skipped

0

const result = store.find('cheese');
store.find('ds.analyzed.name:jane');
store.find('ds.double.age:[30 TO 40]');
store.find('*'); // Iterates the data store without querying the index

"Find all" queries ('*', '*:*') bypasses the index and iterates the data store directly.

Search result

The find method returns a search result wrapper which exposes helpful methods to operate on the data.

toArray(callback)

Gets an array of items from the search result

Argument

Description

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain an array of items matching the query.

result.toArray((err, data) => {
   if (err) {
   // handle error  
   }
   // data -->
   [
      {
         name: 'Bar',
         dstimestamp: 1554719693812,
         dsid: 'f2412b40-59e9-11e9-ae61-7a4f433f610f',
         age: 30
      },
      {
         name: "Foo",
         dstimestamp: 1554719663367,
         dsid: 'e01ba170-59e9-11e9-ae61-7a4f433f610f',
         age: 33
      }
   ]
});

each(callback)

Calls the supplied callback for every item in the result

Argument

Description

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain an item from the result

result.each((err, data) => {
   if (err) {
   // handle error  
   }
   handleItem(data);
});

hasNext()

Returns a boolean indicating whether there are available items in the search result iterator

 if (result.hasNext()) {
   // ...
}

next(callback)

Reads one item at a time from the result iterator using a callback

Argument

Description

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain an item from the result

 if (result.hasNext()) {
   result.next((err, data) => {
      if (err) {
      // handle error  
      }
      res.json(data);
   });
}

length(callback)

Get the number of items in the search result

Argument

Description

callback

Called after execution. The first parameter of the callback will contain an error object if an error occurred, undefined otherwise. The second parameter will contain the number of hits in the search result

result.length((err, length) => {
   if (err) {
   // handle error  
   }
   // ...
});