X DevAPI 用户指南  / 第 4 章使用集合  /  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)。