Documentation Home
X DevAPI User Guide for MySQL Shell in Python Mode
Download this Manual
PDF (US Ltr) - 1.2Mb
PDF (A4) - 1.2Mb


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

    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.

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

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.