X DevAPI User Guide for MySQL Shell in Python Mode
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
The syntax of the single document operations is as follows:
Document getOne(string
, where
id
)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
, where
id
, Document
doc
)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
, where
id
)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).