MySQL :: X DevAPI 用户指南 :: 4.5 单文档操作

4.5 单文档操作

在第 4.3 节“集合 CRUD 函数概述” 中描述的 CRUD 命令都作用于集合中与过滤器匹配的一组文档。X DevAPI 还提供以下操作，它们作用于通过其文档 ID 标识的单个文档

Collection.getOne(string id) 返回具有给定 id 的文档。这是 Collection.find("_id = :id").bind("id", id).execute().fetchOne() 的快捷方式。
Collection.replaceOne(string id, Document doc) 更新或替换由 id 标识的文档（如果存在），使用提供的文档。
Collection.addOrReplaceOne(string id, Document doc) 添加给定的文档；但是，如果 id 或任何其他具有唯一索引的字段已存在于集合中，则操作将改为更新匹配的文档。
Collection.removeOne(string id) 删除具有给定 id 的文档。这是 Collection.remove("_id = :id").bind("id", id).execute() 的快捷方式。

使用这些操作，您可以通过其 ID（参见第 5.2 节“使用文档 ID”）引用文档，通过遵循以下“加载、修改和保存”模式使单个文档的操作更简单

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

单文档操作的语法

单文档操作的语法如下

Document getOne(string id)，其中 id 是要检索的文档的文档 ID。此操作返回文档，如果未找到匹配项，则返回 NULL。搜索具有给定 id 的文档并返回它。
Result replaceOne(string id, Document doc)，其中 id 是要替换的文档的文档 ID，doc（可以包含表达式）是用于替换由 id 标识的文档的新文档。如果 doc 本身包含一个 _id 值，并且它与 id 不同，则操作失败。如果新文档包含与集合中的任何其他文档冲突的唯一键值，则操作也会失败。该操作返回一个 Result 对象，该对象指示受影响的文档数量（1 或 0）。如果未找到 id 的匹配项，则该函数将正常返回，而不会进行任何更改。
Result addOrReplaceOne(string id, Document doc)，其中 id 是要替换或添加的文档的文档 ID（如果无法找到 id 的匹配项），doc（可以包含表达式）是用于替换或添加的新文档。如果 doc 本身包含一个 _id 值，并且它与 id 不同，则操作失败。如果新文档包含与集合中的任何其他文档冲突的唯一键值，则操作也会失败。此操作返回一个 Result 对象，该对象指示受影响的文档数量（1 或 0）。
Result removeOne(string id)，其中 id 是要删除的文档的文档 ID。此操作返回一个 Result 对象，该对象指示删除的文档数量（1 或 0，如果无）。