Documentation Home
X DevAPI User Guide
Download this Manual

X DevAPI User Guide  /  Working with Collections  /  Single Document Operations

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:

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

  • Collection.addOrReplaceOne(string id, Document doc) add the given document. 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.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.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 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).


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.