4.5 Single Document Operations

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 given id. This is a shortcut for Collection.find("_id = :id").bind("id", id).execute().fetchOne().

• Collection.replaceOne(string id, Document doc) updates or replaces the document identified by id, if it exists, with the provided document.

• Collection.addOrReplaceOne(string id, Document doc) adds the given document; however, if the id 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 given id. This is a shortcut for Collection.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

Syntax of Single Document Operations

The syntax of the single document operations is as follows:

• Document getOne(string id), where id is the document ID of the document to be retrieved. This operation returns the document, or NULL if no match is found. Searches for the document that has the given id and returns it.

• Result replaceOne(string id, Document doc), where id is the document ID of the document to be replaced, and doc, which can contain expressions, is the new document for replacing the document identified by id. If doc itself contains an _id value and it is different from id, 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 a Result object, which indicates the number of affected documents (1 or 0). If no matches are found for id, the function returns normally with no changes being made.

• Result addOrReplaceOne(string id, Document doc), where id is the document ID of the document to be replaced or added (if no match can be found for the id), and doc, which can contain expressions, is the new document used for replacement or addition. If doc itself contains an _id value and it is different from id, 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 a Result object, which indicates the number of affected documents (1 or 0).

• Result removeOne(string id), where id is the document ID of the document to be removed. This operation returns a Result object, which indicates the number of removed documents (1 or 0, if none).