Document Database

Additional details can be found on the OrientDB wiki page.

##Server

When accessing the server, all methods must be run within the callback of the server connect method. Once a connection has been made, server methods can be called.

###Connect to Server This is the first operation requested by the client when it needs to work with the server instance. It returns the session id of the client.

db.connect(function (error, results) {});

• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • results - (numeric) Session id.

Example

var orientdb = require("orientdb-binary"),
var Db       = orientdb.Db;

var dbConfig = {
    username:"admin",
    password:"admin",
    database:"test",
    host: "localhost",
    port: 2424,
    database_type: "document", //Optional. Default: document.
    storage_type: "local" //Optional. Default: local.
};

var db = new Db(dbConfig);

db.connect(function(error, results) {
    if(error) {
        console.log(error);
        return;
    }

    console.log('Session ID: ', results);

    //List databases
    db.list(function(error, results){
        db.close();
        
        if(error) {
            console.log(error);
            return;
        }

        console.log(results);
    });
});

---

###Shutdown Server Shut down the server. Requires shutdown permission to be set in orientdb-server-config.xml file.

db.shutdown(username, password, function (error) {});

• username - (string) Admin username.
• password - (object) Password for user.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.

---

###Get Config List Get list of parameters set in the configuration

db.configList(function (error, results) {});

• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • results - (object)
    • config - (array) List of key/value sets in the configuration.
      • param - (object) Parameter in the configuration.
        • key - (string) Parameter key.
        • value - (string) Parameter value.
    • count - (numeric) Number of parameters set in the configuration.

---

###Get Config Parameter Get configuration parameters from

db.configGet(key, function (error, results) {});

• key - (string) Configuration parameter to get.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • results - (object)
    • value - (string) Value for the configuration key.

---

###Set Config Parameter Set a configuration parameter

db.configSet(key, value, function (error) {});

• key - (string) Configuration parameter to get.
• value - (string) Value for the configuration key.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.

---

###List Databases

db.list(function(error, result){});

• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (array) An array of databases on the server.
    • obj - (object) Database object.
      • name - (string) Database name.
      • path - (string) Path to database.

---

###Check if Database Exist

Check whether a database exists

db.exist(databaseName, storageType, function(error, result){});

• databaseName - (string) Name of the database to check. Required.
• storageType - (string) Database storage type. May be local, plocal, or memory. Optional. Default: local.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • results - (boolean) True if database exists, otherwise false.

###Get Server Protocol

The server protocol version.

db.serverProtocolVersion

---

###Get Client Protocol

This NodeJS client protocol version.

db.currentProtocolVersion

---

##Database

When calling methods in the database, a connection must be opened using the open method first. All other methods must be included in the callback.

###Create a New Database Creates a database in the remote OrientDB server instance.

db.create(databaseData, function(error){});

• databaseData - (object) Data to create a new database.
  • databaseName - (string) Database name. Required.
  • databaseType - (string) Database type. Valid values are: document or graph. Optional. Default: "document".
  • storageType - (string) Storage type. Valid values are: local or memory. Optional. Default: "local".
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.

---

###Copy a Database Copy the database to a remote server.

db.copy(databaseData, function(error){});

• databaseData - (object) Data to create a new database.
  • url - (string) Database url. Required.
  • username - (string) Database username. Required.
  • password - (object) Database password for user. Required.
  • remoteServerName - (string) The remote server name.
  • remoteServerEngine - (string) The remote server engine.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.

---

###Drop/Delete a Database Removes a database from the OrientDB Server instance. It returns nothing if the database has been deleted or throws a OStorageException if the database doesn't exists.

db.drop(databaseName, storageType, function(error){});

• databaseName - (string) Database name. Required.
• storageType - (string) Storage type. Optional. Default: "local".
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.

---

###Open a Database

This is the first operation the client should call. It opens the default database specified in the node-orientdb configuration or you can specify another database to access. Returns the session ID to be reused for all the next calls and the list of configured clusters.

db.open(function(error){});
db.open(databaseName, databaseType, function(error){});

• databaseName - (string) Name of the database. Optional.
• databaseType - (string) Type of database. Either document or graph. Optional.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (array) An array of databases on the server.
    • obj - (object) Database object.
      • sessionId - (string) Database name.
      • clusters - (array) Path to database.
        • id - (numeric) Id.
        • name - (string) Name of cluster.
        • type - (string) Cluster type.
        • dataSegmentId - (numeric) Data segment id.
      • config - (string) Is always null unless you're running in a server clustered configuration.
      • release - (string) Version of OrientDB release deployed on server and optionally build number. Example: "1.4.0-SNAPSHOT (build 13)"

Example

var orientdb = require("orientdb-binary"),
var Db       = orientdb.Db;

var dbConfig = {
    username:"admin",
    password:"admin",
    database:"test",
    host: "localhost",
    port: 2424,
    database_type: "document", //Optional. Default: document.
    storage_type: "local" //Optional. Default: local.
};

var db = new Db(dbConfig);

db.open(function(error) {
    if(error) {
        console.log(error);
        return;
    }

    //Details
    console.log("Database '" + db.databaseName + "' has " + db.clusters.length + " clusters");

    //Queries
    db.query("SELECT FROM Users", options, function(error, results){
        db.close();
        
        if(error) {
            console.log(error);
            return;
        }

        console.log(results);
    });
});

---

###Close Database Connection

Closes the database and the network connection to the OrientDB Server instance. No return is expected. The socket is also closed.

db.close();

---

###Count Records Get the number of records in a database.

db.countRecords(function(error, results){});

• callback - (function) Callback
  • result - (numeric) Number of records in database.

---

###Get Database Size Get the size of a database.

db.size(function(error, results){});

• callback - (function) Callback
  • result - (numeric) Size in bytes

---

###Reload Database Reloads database information.

db.reload(function(error, results){});

• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (array) An array of databases on the server.
    • obj - (object) Database object.
      • clusters - (array) Path to database.
        • id - (numeric) Id.
        • name - (string) Name of cluster.
        • type - (string) Cluster type.
        • dataSegmentId - (numeric) Data segment id.

---

##Records

###Load a Record

Load a record by RecordID, according to a fetch plan.

db.recordLoad(record, function(error, results){});

• record - (object) Data to create a record.

  • @rid - (string|array) A record ID or a list of record IDs. Each record ID can be a formatted string (ie. "#9:5") or an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) Specific cluster to add new record.
    • clusterPosition - (numeric) Cluster position.
  • @options (object)
    • fetchPlan - (string) The fetch plan to use. Optional. Default: "".
    • ignoreCache - (numeric) Tells if the cache must be ignored: 1 = ignore the cache, 0 = not ignore. Default: 0.
    • loadTombstones - (numeric) The flag which indicates whether information about deleted record should be loaded. The flag is applied only to autosharded storage and ignored otherwise.

• callback - (function) Callback

  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object | array) Record object or array of multiple record objects.
    • @class - (string)
    • @type - (string)
    • @version - (numeric)
    • @rid - (object)
      • recordId - (string) - Formatted Record ID.
      • clusterId - (numeric) Cluster ID
      • clusterPosition - (numeric) Cluster position
    • [custom] - (*) custom fields within record.

Examples:

//Example of loading a single record using a formatted record id
var record = {
    '@rid':'#9:5',
    '@options':{
        fetchPlan:'',
        ignoreCache:0
    }
};

db.recordLoad(record, function(error, results){
    console.log(results);
});

//Example of loading multiple records using cluster id and position
var record = {
    '@rid':[{clusterID:9, clusterPosition:0}, {clusterID:9, clusterPosition:1}],
    '@options':{
        fetchPlan:'',
        ignoreCache:0
    }
};

db.recordLoad(record, function(error, results){
    console.log(results);
});

---

###Create a New Record Create a new record. Returns the position in the cluster of the new record. New records can have version > 0 (since v1.0) in case the RID has been recycled.

db.recordCreate(record, function(error, results){});

• record - (object) Data to create a record.
  • @rid - (string | array) A record ID or a list of record IDs. Each record ID can be a formatted string (ie. "#9") or an object with the cluster ID. Required (unless class is specified).
    • clusterId - (numeric) Specific cluster to add new record.
  • @class - (string) Class to create new record. Required (unless clusterId is specified).
  • @options (object)
    • dataSegmentId - (string) The segment id to store the data. Optional. Default: -1;
    • mode - (numeric) Whether or not to wait for an answer. Valid values are : 0 (synchronous) and 1 (asynchronous). Optional. Default: 0.
  • [custom] - (*) custom fields within record.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Record object.
    • @class - (string) Class record belongs to.
    • @type - (string) Type of record.

Example

//Example of creating a record
var record = {
    '@class':'Users',
    'id':'123',
    'name':'Giraldo'
};

db.recordCreate(record, function(error, results){
    console.log(results);
});

---

###Update a Record Update a record. Returns the new record's version. The updated document will replace the previous. This means that any variables not included in the content will not be included in the updated document.

db.recordUpdate(record, function(error, result){});

• record - (object) Data to create a record.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
  • @options (object)
    • version - (numeric) Record version policy. (-1) Document update , version increment, no version control. (-2) Document update, no version control nor increment. (-3) Used internal in transaction rollback (version decrement). (>-1) Standard document update (version control).
    • mode - (numeric) Whether or not to wait for an answer. Valid values are : 0 (synchronous) and 1 (asynchronous). Optional. Default: 0.
  • [custom] - (*) custom fields within record.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Record object.
    • version - (numeric) The version of the updated document.

Examples

//Example of updating a record
var record = {
    '@rid':'#9:5',
    'name':'Tester Updated'
};

db.recordCreate(record, function(error, results){
    console.log(results);
});

//Example of updating a record with version control
var record = {
    '@rid':'#9:5',
    '@options':{
        'version':5
    },
    'name':'Tester Updated'
};

db.recordCreate(record, function(error, results){
    console.log(results);
});

---

###Delete a Record Delete a record by its RecordID. During the optimistic transaction the record will be deleted only if the versions match. Returns true if has been deleted otherwise false.

db.recordDelete(record, function(error, result){});

• record - (object) Data of record to delete.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
  • @options (object)
    • version - (numeric) A specific version to delete. Optional. Default: -1.
    • mode - (numeric) Whether or not to wait for an answer. Valid values are : 0 (synchronous) and 1 (asynchronous). Optional. Default: 0.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Record object.
    • status - (boolean) True if record was deleted successfully.

---

###Clean Out Record Clean out record.

db.recordCleanOut(record, function(error, result){});

• record - (object) Data of record to clean out.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
  • @options (object)
    • version - (numeric) A specific version to clean out. Optional. Default: -1.
    • mode - (numeric) Whether or not to wait for an answer. Valid values are : 0 (synchronous) and 1 (asynchronous). Optional. Default: 0.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Record object.
    • status - (boolean) True if record was cleaned successfully.

---

###Get Record Metadata

db.recordMetadata(recordData, function(error, result){});

• record - (object) Data of record to clean out.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Record object.
    • rid - (string) Record ID.
    • version - (boolean) Current record version.

---

###Get Higher Positions Get higher positioned records

db.positionsHigher(record, function(error, result){});

• record - (object) Data of record to start.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Position object.
    • clusterPosition - (numeric)
    • dataSegmentId - (numeric)
    • dataSegmentPos - (numeric)
    • recordSize - (numeric)
    • recordVersion - (numeric)

---

###Get Lower Positions Get lower positioned records

db.positionsLower(record, function(error, result){});

• record - (object) Data of record to start.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Position object.
    • clusterPosition - (numeric)
    • dataSegmentId - (numeric)
    • dataSegmentPos - (numeric)
    • recordSize - (numeric)
    • recordVersion - (numeric)

---

###Get Ceiling Positions

db.positionsCeiling(record, function(error, result){});

• record - (object) Data of record to start.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Position object.
    • clusterPosition - (numeric)
    • dataSegmentId - (numeric)
    • dataSegmentPos - (numeric)
    • recordSize - (numeric)
    • recordVersion - (numeric)

---

###Get Floor Positions

db.positionsFloor(record, function(error, result){});

• record - (object) Data of record to start.
  • @rid - (string | object) The Record ID to update. May pass the record ID as a string ("#9:5") or as an object with the cluster ID and cluster position. Required.
    • clusterId - (numeric) The cluster the record belongs to.
    • clusterPosition - (numeric) Cluster position.depending on record type.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object) Position object.
    • clusterPosition - (numeric)
    • dataSegmentId - (numeric)
    • dataSegmentPos - (numeric)
    • recordSize - (numeric)
    • recordVersion - (numeric)

##Data Cluster

###Add a New Data Cluster Add a new data cluster.

db.dataClusterAdd(clusterData, function(error, result){});

• clusterData - (object) Cluster object
  • name - (string) Cluster name.
  • clusterId - (numeric) Cluster ID. Set to -1 to create a new cluster. Optional. Default: -1.
  • type - (string) Type of cluster. Valid types are: physical or memory. Optional. Default: "physical".
  • location - (string) Location of physical cluster. Optional.
  • dataSegmentName - (string) Data segment name if using physical. Optional.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object)
    • clusterId - (numeric)

---

###Drop/Delete a Data Cluster Remove a cluster.

db.dataClusterDrop(clusterId, function(error, result){});

• clusterId - (numeric) Cluster ID
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object)
    • status - (numeric) 1 if the cluster has been successfully removed and the client has to remove too, otherwise 0.

---

###Get Data Cluster Count Returns the number of records in one or more clusters.

db.dataClusterCount(clusterIds, tombstones, function(error, result){});

• clusterIds - (numeric | array) Cluster ID of each single cluster. May use a numeric value for a single cluster or an array of numeric values for multiple clusters.
• tombstones - (boolean) Flag which indicates whether deleted records should be taken in account. It is applicable for autosharded storage only, otherwise it is ignored. Optional. Default: 0.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object)
    • count - (numeric) Total number of records found in the requested clusters.

---

###Get Data Cluster Data Range Returns the range of record ids for a cluster.

db.dataClusterDataRange(clusterId, function(error, result){});

• clusterId - (numeric) Cluster ID.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object)
    • begin - (numeric) The beginning of the cluster range.
    • end - (numeric) The end of the cluster range.

---

Data Segments

###Add a New Data Segment Add a new data segment.

db.dataSegmentAdd(segmentName, location, function(error, result){});

• segmentName - (string) Segment name
• location - (string) Location of segment.
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object)
    • segmentId - (numeric) New segment ID.

---

###Drop/Delete a Data Segment Drop a data segment.

db.dataSegmentDrop(segmentName, function(error, result){});

• segmentName - (string) Segment name
• callback - (function) Callback
  • error - (string) Any errors that may be returned. Null if no errors.
  • result - (object)
    • status - (boolean) 1 if the segment has been successfully removed, otherwise 0.