ドキュメントの置き換え

MongoCollectionオブジェクトで replaceOne()メソッドを使用して単一のドキュメントを置き換えることができます。このメソッドは、ドキュメントから既存のすべてのフィールドと値（ _idフィールドを除く）を削除し、それを置換ドキュメントに置き換えます。

replaceOne()メソッドは、置き換えるドキュメントに一致するクエリフィルターと、一致したドキュメントの代わりに保存するデータを含む置換ドキュメントを受け入れます。 replaceOne()メソッドは、フィルターに一致する最初のドキュメントのみを置換します。

メソッドの動作を指定するために、オプションでReplaceOptionsのインスタンスをreplaceOne()メソッドに渡すことができます。たとえば、 ReplaceOptionsオブジェクトのupsertフィールドをtrueに設定すると、クエリフィルターに一致するドキュメントがない場合、この操作によって置換ドキュメントのフィールドから新しいドキュメントが挿入されます。詳しくは、このページの下部にあるReplaceOptions API ドキュメントへのリンクを参照してください。

正常に実行されると、 replaceOne()メソッドはUpdateResultのインスタンスを返します。 getModifiedCount()メソッドを呼び出すと、変更されたドキュメントの数などの情報を取得できます。また、 ReplaceOptionsインスタンスでupsert(true)を設定し、その操作によって新しいドキュメントが挿入された場合は、 getUpsertedId()メソッドを呼び出してドキュメントの_idフィールドの値を取得することもできます。

置き換え操作に失敗した場合、ドライバーは例外を発生させます。たとえば、置き換えドキュメント内の不変フィールド_idに元のドキュメントとは異なる値を指定しようとすると、メソッドは次のメッセージとともにMongoWriteExceptionを返します。

After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)

置き換えドキュメントに一意なインデックスのルールに違反する変更が含まれている場合、メソッドは次のようなエラーメッセージを含むMongoWriteExceptionをスローします。

E11000 duplicate key error collection: ...

特定の条件下で発生する例外の種類の詳細については、このページの下部にリンクしているreplaceOne()の API ドキュメントを参照してください。

例

この例では、 sample_mflixデータベースのmoviesコレクション内のクエリフィルターの最初の一致を置換ドキュメントに置き換えます。 _idフィールドを除くすべてのフィールドは元のドキュメントから削除され、置き換えドキュメントによって置き換えられます。

replaceOne()操作が実行される前に、元のドキュメントには映画を説明する複数のフィールドが含まれています。操作の実行後、結果のドキュメントには、置換ドキュメントによって指定されたフィールド（ titleとfullplot ）と_idフィールドのみが含まれます。

次のスニペットでは、次のオブジェクトとメソッドを使用します。

replaceOne() メソッドに渡されるクエリフィルター。eq フィルターは、タイトルが 'Music of the Heart' テキストと完全に一致する映画のみに一致します。
一致するドキュメントが存在する場合は、それを置き換えるドキュメントを含む置換ドキュメント。
upsertオプションがtrueに設定されているReplaceOptionsオブジェクト。このオプションは、クエリフィルターがどのドキュメントにも一致しない場合に、メソッドが置換ドキュメントに含まれるデータを挿入することを指定します。

注意

この例では、接続 URI を使用して MongoDB のインスタンスに接続します。 MongoDB インスタンスへの接続の詳細については、「接続ガイド」を参照してください。

// Replaces the first document that matches a filter by using the Java driver
package usage.examples;
import static com.mongodb.client.model.Filters.eq;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.MongoException;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.ReplaceOptions;
import com.mongodb.client.result.UpdateResult;
public class ReplaceOne {
    public static void main(String[] args) {
        // Replace the uri string with your MongoDB deployment's connection string
        String uri = "<connection string uri>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
            MongoCollection<Document> collection = database.getCollection("movies");
            Bson query = eq("title", "Music of the Heart");
            // Creates a new document containing "title" and "fullplot" fields
            Document replaceDocument = new Document().
                    append("title", "50 Violins").
                    append("fullplot", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music");
            // Instructs the driver to insert a new document if none match the query
            ReplaceOptions opts = new ReplaceOptions().upsert(true);
            // Replaces the first document that matches the filter with a new document
            UpdateResult result = collection.replaceOne(query, replaceDocument, opts);
            // Prints the number of modified documents and the upserted document ID, if an upsert was performed
            System.out.println("Modified document count: " + result.getModifiedCount());
            System.out.println("Upserted id: " + result.getUpsertedId());
        // Prints a message if any exceptions occur during the operation
        } catch (MongoException me) {
            System.err.println("Unable to replace due to an error: " + me);
        }
    }
}

例を実行すると、次のような出力が表示されます。

Modified document count: 1
Upserted id: null

または、例でアップサートが発生した場合は、次のようになります。

Modified document count: 0
Upserted id: BsonObjectId{value=...}

置換されたドキュメントをクエリすると、出力は次のようになります。

Document {
  { _id=...,
    title=50 Violins,
    fullplot=A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music
  }
}

Tip

Legacy API

レガシー API を使用している場合は、 FAQ ページを参照して、このコード例に加える必要がある変更を確認してください。

このページで言及されているクラスとメソッドについて詳しくは、次の API ドキュメントを参照してください。

戻る

複数のドキュメントの更新

削除操作