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，如果沒有移除任何文件)。