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
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.
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.
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 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"});