SparkMongoCollectionReadWrite

Provides read write access to a mongo collection.

All methods defined in SparkMongoCollectionReadOnly are available in this object along with those listed below.

e.g.

var myRuntimeCollection = Spark.runtimeCollection('runtimetest');

Note: To make sure your game performs and scales well, see GameSparks Best Practices before using these APIs.

count

signature count()

returns number

Returns the number of documents in this collection

returns

the number of documents

example

var count = myMetaCollection.count();

signature count(JSON query)

returns number

Returns the number of documents that match the supplied query

returns

the number of documents

example

var count = Spark.metaCollection('metatest').count({"metafield" : "metavalue"});

distinct

signature distinct(string key)

returns JSON

Returns a list of distinct values for the given key in the collection

params

key - the key to use in the query

returns

an object array

example

var keys = Spark.metaCollection('metatest').distinct("metafield");

signature distinct(string key, JSON query)

returns JSON

Returns a list of distinct values for the given key in the collection that match the supplied query

params

key - the key to use in the query

query - the Mongo query

returns

an object array

example

var keys = Spark.metaCollection('metatest').distinct("metafield", {"metafield1":{"$gte" : 5}});

dropIndex

signature dropIndex(JSON keys)

returns void

Drops or removes the specified index from a collection.

params

keys - the index definition used in ensureIndex.

example

Spark.metaCollection('metatest').dropIndex({"metafield" : 1});

dropIndexByName

signature dropIndexByName(string name)

returns void

Drops or removes the specified index from a collection.

params

name - the name of the index to drop.

example

Spark.metaCollection('metatest').dropIndexByName("myIndex");

ensureIndex

signature ensureIndex(JSON keys)

returns void

Creates an index on the specified fields if the index does not already exist.

params

keys - the index definition used in ensureIndex.

example

Spark.metaCollection('metatest').ensureIndex({"metafield" : 1, "metafield1" : 1});

signature ensureIndex(JSON keys, JSON optionsIN)

returns void

Creates an index on the specified fields if the index does not already exist.

params

keys - the index definition used in ensureIndex.

optionsIN - index options

example

Spark.metaCollection('metatest').ensureIndex({"metafield" : 1, "metafield1" : 1}, {"name":"myIndex"});

find

signature find()

returns SparkMongoCursor

Returns a SparkMongoCursor of all documents in this collection

params

example

var results = Spark.metaCollection('metatest').find();

signature find(JSON query)

returns SparkMongoCursor

Returns a SparkMongoCursor of all documents in this collection that match the supplied query

params

query - a Mongo query

example

var results = Spark.metaCollection('metatest').find({"metatest1" : {"$gt" : 1}});

signature find(JSON query, JSON fields)

returns SparkMongoCursor

Returns a SparkMongoCursor of all documents in this collection that match the supplied query.

The returned documents only contain the fields supplied in the fieldsToReturn parameter. This reduces the document size when being returned.

params

query - a Mongo query

fields - the fields to return

example

var results = Spark.metaCollection('metatest').find({"metatest1" : {"$gt" : 1}}, {"metatest" : 1});

findOne

signature findOne()

returns JSON

Returns the first document from the collection according to natural order (which reflects the order of documents on the disk)

returns

A JSON object

example

var results = Spark.metaCollection('metatest').findOne();

signature findOne(JSON query)

returns JSON

Returns one document that satisfies the specified query criteria.

If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk.

params

query - a Mongo query

example

var result = Spark.metaCollection('metatest').findOne({"metatest1" : {"$gt" : 1}}

signature findOne(JSON query, JSON fields)

returns JSON

Returns one document that satisfies the specified query criteria.

If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk.

The returned documents only contain the fields supplied in the fieldsToReturn parameter. This reduces the document size when being returned.

params

query - a Mongo query

fields - the fields to return

example

var result = Spark.metaCollection('metatest').findOne({"metatest1" : {"$gt" : 1}}, {"metatest" : 1});

signature findOne(JSON query, JSON fields, JSON orderBy)

returns JSON

Returns one document that satisfies the specified query criteria.

If multiple documents satisfy the query, this method returns the first document according to the natural order which reflects the order of documents on the disk.

The returned documents only contain the fields supplied in the fieldsToReturn parameter. This reduces the document size when being returned.

params

query - a Mongo query

fields - the fields to return

orderBy - the order clause

example

var result = Spark.metaCollection('metatest').findOne({"metatest1" : {"$gt" : 1}}, {"metatest" : 1});

findAndModify

signature findAndModify(JSON query, JSON update)

returns JSON

Calls findAndModify(query, fields, sort, remove, update, returnNew, upsert) with fields=null, remove=false, returnNew=false, upsert=false, sort=null

params

query - Specifies the selection criteria for the modification. The query field employs the same query selectors as used in the find() method. Although the query may match multiple documents, findAndModify will only select one document to modify.

update - Must specify either the remove or the update field in the findAndModify command. The update field employs the same update operators or field: value specifications to modify the selected document.

returns

a JSON object

example

var doc = myRuntimeCollection.findAndModify({"field" : "value"}, {"field" : 1}, {"field" : "value1"});

signature findAndModify(JSON query, JSON sort, JSON update)

returns JSON

Calls findAndModify(query, fields, sort, remove, update, returnNew, upsert) with fields=null, remove=false, returnNew=false, upsert=false

params

sort - Determines which document the operation will modify if the query selects multiple documents. findAndModify will modify the first document in the sort order specified by this argument.

returns

a JSON object

example

var doc = myRuntimeCollection.findAndModify({"field" : "value"},{"field" : 1}, {"field" : "value1"});

signature findAndModify(JSON query, JSON fields, JSON sort, boolean remove, JSON update, boolean returnNew, boolean upsert)

returns JSON

Atomically modifies and returns a single document. By default, the returned document does not include the modifications made on the update. To return the document with the modifications made on the update, use the returnNew option.

params

query - specifies the selection criteria for the modification. The query field employs the same query selectors as used in the find() method. Although the query may match multiple documents, findAndModify will only select one document to modify.

fields - the fields to return

sort - determines which document the operation will modify if the query selects multiple documents. findAndModify will modify the first document in the sort order specified by this argument.

remove - must specify either the remove or the update field in the findAndModify command. When true, removes the selected document. The default is false.

update - must specify either the remove or the update field in the findAndModify command. The update field employs the same update operators or field: value specifications to modify the selected document.

returnNew - when true, returns the modified document rather than the original. The findAndModify method ignores the new option for remove operations. The default is false.

upsert - used in conjunction with the update field. When true, the findAndModify command creates a new document if the query returns no documents. The default is false.

returns

a JSON object

example

var doc = myRuntimeCollection.findAndModify({"field" : "value"},{"field" : 1},false,{"field" : "value1"},true, {"field" : 1},false);

findAndRemove

signature findAndRemove(JSON query)

returns JSON

Calls findAndModify(query, fields, sort, remove, update, returnNew, upsert) with fields=null, sort=null, remove=true, returnNew=false, upsert=false

params

query - a Mongo query

returns

a JSON object

example

var doc = myRuntimeCollection.findAndRemove({"field" : "value"});

insert

signature insert(JSON[] documents)

returns boolean

Inserts a document or documents into a collection.

params

documents - A document or array of documents to insert into the collection.

returns

true if the operation was successful

example

var success = myRuntimeCollection.insert({"field" : "value"}, {"field" : "value1"}, {"field" : "value2"});

aggregate

signature aggregate(JSON firstOp, JSON[] additionalOps)

returns JSON

applyChanges

signature applyChanges(JSON existingDocument, JSON newDocument)

returns boolean

Generates the correct mongo update command to set and unset fields so the mongo record matches the newDocument.

This can greatly increase performance in documents where only a small amount of change has been made as only the required fields are modified.

If the existing document is null, the new document is inserted directly into the collection

params

existingDocument - A document perviously retrieved from the database. The _id field of this document will be used to determine which document to update. If the document passed has no _id the call will fail.

newDocument - The new state to persist in the database, and _id field in this document will be ignored.

returns

true if the operation was successful

getIndexInfo

signature getIndexInfo()

returns JSON

Return a list of the indexes for this collection. Each object in the list is the "info document" from MongoDB

returns

list of index documents

example

var indexes = Spark.metaCollection('metatest').getIndexInfo();

getLastError

signature getLastError()

returns JSON

Gets the error (if there is one) from the previous operation on this connection.

returns

a JSON object with error and status information

example

var errors = Spark.metaCollection('metatest').getLastError();

save

signature save(JSON document)

returns boolean

Updates an existing document or inserts a new document, depending on its document parameter.

If the document does not contain an _id field, then the save() method performs an insert. During the operation, mongo will add to the document the _id field and assign it a unique ObjectId.

If the document contains an _id field, then the save() method performs an upsert, querying the collection on the _id field. If a document does not exist with the specified _id value, the save() method performs an insert. If a document exists with the specified _id value, the save() method performs an update that replaces all fields in the existing document with the fields from the document.

params

document - the document to save

example

var success = myRuntimeCollection.save({"field" : "value"});

remove

signature remove(JSON query)

returns boolean

Removes any document from the collection that matches the supplied query.

Return a boolean indicating whether the remove was successful.

params

query - the query

returns

true if the operation was successful

example

var success = myRuntimeCollection.remove({"field" : "value"});

update

signature update(JSON query, JSON update)

returns boolean

Calls update(query, update, upsert, multi) with upsert=false and multi=false

params

query - query (document) The selection criteria for the update. Use the same query selectors as used in the find() method

update - update (document) The modifications to apply. For details see Update Parameter

returns

true if the operation was successful

example

var success = myRuntimeCollection.update({"field" : "value"}, {"field" : "value1"});

signature update(JSON query, JSON update, boolean upsert, boolean multi)

returns boolean

Modifies an existing document or documents in a collection. The method can modify specific fields of existing document or documents or replace an existing document entirely, depending on the update parameter.

By default, the update() method updates a single document. If the multi option is set to true, the method updates all documents that match the query criteria.

params

query - query (document) The selection criteria for the update. Use the same query selectors as used in the find() method

update - update (document) The modifications to apply. For details see Update Parameter

upsert - if set to true, creates a new document when no document matches the query criteria. The default value is false, which does not insert a new document when no match is found

multi - multi (boolean) Optional. If set to true, updates multiple documents that meet the query criteria. If set to false, updates one document. The default value is false. For additional information, see Multi Parameter

returns

true if the operation was successful

example

var success = myRuntimeCollection.update({"field" : "value"}, {"field" : "value1"}, false, false);

updateMulti

signature updateMulti(JSON query, JSON update)

returns boolean

Calls update(query, update, upsert, multi) with upsert=false and multi=true

params

query - query (document) The selection criteria for the update. Use the same query selectors as used in the find() method

update - update (document) The modifications to apply. For details see Update Parameter

returns

true if the operation was successful

example

var success = myRuntimeCollection.updateMulti({"field" : "value"}, {"field" : "value1"});