X DevAPI User Guide

4.4 Single Document Operations

The CRUD commands described at Section 4.3, “Collection CRUD Function Overview” all work on a group of documents in a collection which match a filter. X DevAPI also provides the following operations which work on single documents that are identified by their document ID:

Using these operations you can reference documents by ID, making operations on single documents simpler by following a load, modify and save pattern such as:

doc = collection.getOne(id);
doc["address"] = "123 Long Street";
collection.replaceOne(id, doc);

For more information on document IDs see Section 5.1, “Working with Document IDs”.

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 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).

  • Result replaceOne(string id, Document doc), where id is the document ID of the document to be replaced and doc is the new document, which can contain expressions. If doc contains an _id value, it is ignored. The operation returns a Result object, which indicates the number of affected documents (1 or 0, if none). Takes in a document object which replaces the matching document. If no matches are found, 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 and doc is the new document, which can contain expressions. If doc contains an _id value, it is ignored. This operation returns a Result object, which indicates the number of affected documents (1 or 0, if none). Adds the document to the collection.

Important

These operations accept an explicit id to ensure that any changes being made by the operation are applied to the intended document. In many scenarios the document doc could come from an untrusted user, who could potentially change the id in the document and thus replace other documents than the application expects. To mitigate this risk, you should transfer the explicit document id through a secure channel.

If doc has a value for _id and it does not match the given id then an error is generated. If the collection has a document with the given document ID then the collection is checked for any document that conflicts with unique keys from doc and where the document ID of conflicting documents is not id then an error is generated. Otherwise the existing document in the collection is replaced by doc. If the collection has any document that conflicts with unique keys from doc then an error is generated. Otherwise doc is added to collection.

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 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).