4.5 Single Document Operations — MySQL Connectors 1.0

4.5 Операции с отдельными документами

Команды CRUD, описанные в разделе 4.3 «Обзор функций CRUD для коллекций», работают со всей группой документов в коллекции, соответствующих фильтру. X DevAPI также предоставляет следующие операции, которые работают с отдельными документами, идентифицируемыми по их идентификаторам документов:

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

Используя эти операции, вы можете ссылаться на документ по его идентификатору (см. раздел 5.2 «Работа с идентификаторами документов»), упрощая операции с отдельными документами, следуя шаблону «загрузка, изменение и сохранение», например:

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 — идентификатор документа, который необходимо получить. Эта операция возвращает документ или NULL, если совпадений не найдено. Ищет документ с заданным id и возвращает его.
Result replaceOne(string id, Document doc), где id — идентификатор документа, который необходимо заменить, и doc, который может содержать выражения, — новый документ для замены документа, идентифицированного по id. Если doc содержит значение _id и оно отличается от id, операция завершается ошибкой. Операция также завершается ошибкой, если новый документ содержит значение уникального ключа, конфликтующее с любым другим документом в коллекции. Операция возвращает объект Result, который указывает количество затронутых документов (1 или 0). Если для id не найдено совпадений, функция возвращается без изменений.
Result addOrReplaceOne(string id, Document doc), где id — идентификатор документа, который необходимо заменить или добавить (если для id не найдено совпадений), и doc, который может содержать выражения, — новый документ, используемый для замены или добавления. Если doc содержит значение _id, и оно отличается от id, операция завершается ошибкой. Операция также завершается ошибкой, если новый документ содержит значение уникального ключа, конфликтующее с любым другим документом в коллекции. Эта операция возвращает объект Result, который указывает количество затронутых документов (1 или 0).
Result removeOne(string id), где id — идентификатор документа, который необходимо удалить. Эта операция возвращает объект Result, который указывает количество удаленных документов (1 или 0, если нет).