The CRUD commands described at Section 4.3, “Collection CRUD Function Overview” all act on a group of documents in a collection that match a filter. X DevAPI also provides the following operations, which work on single documents that are identified by their document IDs:
Collection.getOne(string id)
returns the document with the givenid
. This is a shortcut forCollection.find("_id = :id").bind("id", id).execute().fetchOne()
.Collection.replaceOne(string id, Document doc)
updates or replaces the document identified byid
, if it exists, with the provided document.Collection.addOrReplaceOne(string id, Document doc)
adds the given document; however, if theid
or any other field that has a unique index on it already exists in the collection, the operation updates the matching document instead.Collection.removeOne(string id)
removes the document with the givenid
. This is a shortcut forCollection.remove("_id = :id").bind("id", id).execute()
.
Using these operations you can reference a document by its ID (see Section 5.2, “Working with Document IDs”), making operations on single documents simpler by following a "load, modify, and save" pattern such as the following:
doc = collection.getOne(id); // Load document of the specified id into a temporary document called doc
doc["address"] = "123 Long Street"; //Modify the "address" field of doc
collection.replaceOne(id, doc); // Save doc into the document with the specified id
The syntax of the single document operations is as follows:
Document getOne(string
, whereid
)id
is the document ID of the document to be retrieved. This operation returns the document, orNULL
if no match is found. Searches for the document that has the givenid
and returns it.Result replaceOne(string
, whereid
, Documentdoc
)id
is the document ID of the document to be replaced, anddoc
, which can contain expressions, is the new document for replacing the document identified byid
. Ifdoc
itself contains an_id
value and it is different fromid
, the operation fails. The operation also fails if the new document contains a unique key value that conflicts with any other document in the collection. The operation returns aResult
object, which indicates the number of affected documents (1 or 0). If no matches are found forid
, the function returns normally with no changes being made.Result addOrReplaceOne(string id, Document doc)
, whereid
is the document ID of the document to be replaced or added (if no match can be found for theid
), anddoc
, which can contain expressions, is the new document used for replacement or addition. Ifdoc
itself contains an_id
value and it is different fromid
, the operation fails. The operation also fails if the new document contains a unique key value that conflicts with any other document in the collection. This operation returns aResult
object, which indicates the number of affected documents (1 or 0).Result removeOne(string
, whereid
)id
is the document ID of the document to be removed. This operation returns aResult
object, which indicates the number of removed documents (1 or 0, if none).