-
Notifications
You must be signed in to change notification settings - Fork 24
Working With Collections
Collections in the context of SculeJS are groupings of JavaScript objects. Collections aren't exactly like tables in SQL based Database Management Systems - they don't enforce a schema on the data contained within them. Other than that you can think of them as being more or less analogous to RDBMS tables.
The objects contained in collections don't need to have the same sets of fields, typically though objects in a collection should be related in the context of the application.
Table of contents:
Instantiating collections in SculeJS is simple:
var scule = require('com.scule');
var collection = scule.factoryCollection('scule+dummy://test');You'll notice that when you factory a collection you need to provide a funny looking URL. The first segment of the URL tells SculeJS which collection implementation and storage engine to use. SculeJS includes a few storage engine implementations by default:
- titanium - a disk based storage engine for Titanium Appcelerator applications
- memory - a memory based storage engine used for unit testing - simulates disk based storage in memory
- dummy - a storage engine that doesn't actually store anything, great for when you need to temporarily persist data in memory
- local - a localStorage based storage engine for using inside web browsers
- nodejs - a disk based storage engine for NodeJS applications
SculeJS also includes a default collection class - other implementations can be injected into SculeJS using the registerCollectionPlugin function:
var scule = require('com.scule');
scule.registerCollectionPlugin('mypluginidentifier', MyCollectionFunction);
var collection = scule.factoryCollection('mypluginidentifier+dummy://test');You can also inject your own storage engine implementations into SculeJS using the registerStorageEngine function:
var scule = require('com.scule');
scule.registerStorageEngine('myengineidentifier', MyStorageEngineFunction);
var collection = scule.factoryCollection('scule+myengineidentifier://test');All storage engine implementations should extends the StorageEngine prototype and implement two functions:
- write = function (name, object, callback)
- read = function (name, callback)
Adding objects to a collection is done using the save function:
var scule = require('com.scule');
var collection = scule.factoryCollection('scule+dummy://test');
collection.save({foo:'bar'});If you want to commit your collection to storage all you need to do is call the commit function:
var scule = require('com.scule');
var collection = scule.factoryCollection('scule+dummy://test');
collection.save({foo:'bar'});
collection.commit();That's the basics! But what else can you do with collections? All functions on collection objects accept a callback function as the last parameter so they can be executed in an asynchronous fashion (since SculeJS doesn't do any I/O by default unless it's talking to the disk this is mostly for convenience).
var scule = require('com.scule');
var collection = scule.factoryCollection('scule+dummy://test');
var length = collection.getLength(); // count the number of objects in the collection
collection.findAll(function(documents) {
documents.forEach(function(document) {
// do something here
});
}); // return all objects in the collection
collection.findOne('identifier', function(document) {
// do something here
}); // returns a single object from the collection
collection.count({foo:'bar'}, {}, function(count) {
// do something here
}); // counts objects in the collection corresponding to the provided query parameters
collection.explain({foo:'bar'}, {$limit:100}, function() {
// do something here
}); // prints a human readable version of the scule virtual machine program for the query to the consoleGot the idea? Awesome. Below is an API reference for collections:
Sets the storage engine implementation for the collection
Ensures that a b+ plus tree index exists on the collection for the given definion. The value of definition is a comma separated list of object attributes names (e.g. a,b,c), if you want to index nested object attributes you can do this using dot notation (e.g. a,b,c.d)
The options argument for this function is an object - the only attribute being "order", the order value tells the index what the branching factor for the b+ tree should be.
Ensures that a b+ plus tree index exists on the collection for the given definion. The value of definition is a comma separated list of object attributes names (e.g. a,b,c), if you want to index nested object attributes you can do this using dot notation (e.g. a,b,c.d)
Tells the collection whether or not to auto-commit after each update, the semaphor value is a boolean
Returns the name of the collection as a string
Returns the length of the collection (number of objects) as an integer
Returns the ObjectId for the last object inserted into the collection
Commits the collection to storage (using the selected storage engine), the provided callback function is called once the commit operation is completed
Performs a query on the collection using the provided query expression object and conditions. The provided callback function is called once the query is complete with the result set from the query passed as the sole argument. If no callback is provided then the result set is returned to the caller.
Prints a human readable version of the byte code program generated by the query compiler using the provided query expression object and conditions. The provided callback function is called once the logging operation is complete. The callback receives no arguments.
Drops all objects from the collection. The provided callback function is called once the clear operation is complete with the collection as the sole argument.
Returns all objects in the collection in an array. The provided callback function is called once the query is complete with the result set from the query passed as the sole argument. If not callback is provided then the result set is returned to the caller. If no callback is provided then the result set is returned to the caller.
Finds a single object using it's ObjectId. The provided callback function is called once the query is complete with the result set from the query passed as the sole argument. If not callback is provided then the result set is returned to the caller. If no callback is provided then the result set is returned to the caller.
Saves a document to the collection. The provided callback function is called once the save operation is complete with the newly generated ObjectId as the sole argument. If no callback is provided then the result is returned to the caller.
Performs an update against the collection. The provided callback function is called once the query is complete with the result set from the query passed as the sole argument. If no callback is provided then the result set is returned to the caller.
Performs a query on the collection using the provided query expression object and conditions, returning the count of the number of objects in the result set. The provided callback function is called once the query is complete with the count passed as the sole argument. If no callback is provided then the result set is returned to the caller.
Performs a delete against the collection. The provided callback function is called once the query is complete with the result set from the query passed as the sole argument. If no callback is provided then the result set is returned to the caller.
Returns an object containing key, value pairs representing the distinct values for the provided key (and query if provided). The provided callback function is called once the query is complete with the result set from the query passed as the sole argument. If no callback is provided then the result set is returned to the caller.
Merges the current collection with the provided collection. The provided callback function is called once the merge is complete with a reference to the current collection. If no callback is provided a boolean value is returned to the caller indicating the success of the merge.
Performs a map/reduce operation against the collection. The map function has two arguments: a reference to the document to map and a reference to a function called "emit".
The reduce function should return the result of the reduce operation. The options object for the map/reduce operation can optionally contain:
- an "out" value containing a collection connection url as either a "merge" or "reduce" sub-argument. If provided as a merge the provided collection will be merged with the results of the map/reduce operation.
- a query expression object
- a limit/sort expression object
- a "finalize" value containing a reference to a function. Finalize functions should accept two arguments; a reference to the key being operated on and a reference to results of the reduce function. The finalize function should return a reference to the modified "reduced" value once it has completed execution.
An example options object might look like:
{
out:{
merge:'scule+dummy://map-reduce'
},
query:{a:10},
conditions:{$limit:100, $sort:{a:-1}},
finalize:function (key, reduced) {
reduced.finalized = key;
return reduced;
}
}The provided callback function is executed once the map/reduce operation is complete. The only argument for this function is the "out" collection.