/ /

ドキュメントの置換

Overview

このガイドでは、 .NET/ C#ドライバーを使用してMongoDBコレクション内のドキュメントを置き換える方法を学習できます。

.NET/ C#ドライバーは ReplaceOne() メソッドと ReplaceOneAsync() メソッドを提供します。これらのメソッドは、検索条件に一致する最初のドキュメントからすべてのフィールド（ _idフィールドを除く）を削除し、指定したフィールドと値をドキュメントに挿入します。

注意

メソッドのオーバーロード

このページのメソッドの多くには、複数のオーバーロードがあります。このガイドの例では、各メソッドの 1 つの定義のみを示します。利用可能なオーバーロードの詳細については、APIドキュメントを参照してください。

サンプルデータ

このガイドの例では、 sample_restaurantsデータベースのrestaurantsコレクションを使用します。このコレクションのドキュメントでは、次のRestaurant 、 Address 、 GradeEntryクラスをモデルとして使用します。

public class Restaurant
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    [BsonElement("restaurant_id")]
    public string RestaurantId { get; set; }
    public string Cuisine { get; set; }
    public Address Address { get; set; }
    public string Borough { get; set; }
    public List<GradeEntry> Grades { get; set; }
}

public class Address
{
    public string Building { get; set; }
    [BsonElement("coord")]
    public double[] Coordinates { get; set; }
    public string Street { get; set; }
    [BsonElement("zipcode")]
    public string ZipCode { get; set; }
}

public class GradeEntry
{
    public DateTime Date { get; set; }
    public string Grade { get; set; }
    public float? Score { get; set; }
}

注意

restaurantsコレクションのドキュメントは、スニペットケースの命名規則を使用します。このガイドの例では、ConventionPack を使用してコレクション内のフィールドをパスカルケースに逆シリアル化し、Restaurantクラスのプロパティにマップします。

カスタム直列化について詳しくは、「カスタム直列化」を参照してください。

このコレクションは、Atlas が提供するサンプルデータセットから構成されています。無料のMongoDBクラスターを作成し、このサンプルデータをロードする方法については、 .NET/ C#ドライバーを使い始めるを参照してください。

1 つのドキュメントの置換

コレクション内のドキュメントを置き換えるには、ReplaceOne() メソッドまたは ReplaceOneAsync() メソッドを呼び出します。これらのメソッドは次のパラメーターを受け入れます。

Parameter	説明
`filter`	置き換えドキュメントを指定するクエリフィルター。`Builders`クラスを使用してクエリフィルターを作成できます。クエリフィルターの詳細については、 MongoDB Serverマニュアルを参照してください。データ型： FilterDefinition<TDocument>
`replacement`	置換ドキュメント。新しいドキュメントに挿入するフィールドと値を指定します。コレクション内のドキュメントがC#クラスにマップされている場合、置換ドキュメントはこのクラスのインスタンスになることができます。データ型： `TDocument`
`options`	任意。置換操作の構成を指定する `ReplaceOptions`クラスのインスタンス。デフォルト値は `null` です。データ型： ReplaceOptions
`cancellationToken`	任意。操作をキャンセルするために使用できるトークン。データ型 : CancelToken

次のコード例は、置換操作を実行する方法を示しています。このコードでは、次の手順が実行されます。

Buildersクラスを使用してクエリフィルターを作成します。フィルターは、cuisineフィールドの値が "Pizza" であるすべてのドキュメントと一致します。
新しい Restaurantオブジェクトを作成します。
restaurantsコレクションで ReplaceOne() メソッドを呼び出します。この操作は、コレクション内で最初に一致するドキュメントを検索し、それを新しく作成されたドキュメントに置き換えます。

SynchronousAsynchronous対応するコードを表示するには、タブまたはタブを選択します。

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new Address()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
// Replaces the existing restaurant document with the new document
return _restaurantsCollection.ReplaceOne(filter, newPizzaRestaurant);

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{   
    Id = oldId,
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new Address()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
// Asynchronously replaces the existing restaurant document with the new document
return await _restaurantsCollection.ReplaceOneAsync(filter, newPizzaRestaurant);

重要

_idフィールドの値は不変です。置き換えドキュメントで_idフィールドに値が指定される場合は、既存のドキュメントの_id値と一致する必要があります。

置き換えドキュメントで_idフィールドの値が指定されていない場合は、Plain Old CLR/Class Object（POCO）の _idフィールドに [BsonIgnoreIfDefault] 属性を追加できます。 POCO の _idフィールドが ObjectId タイプである場合は、[BsonIgnoreIfDefault] を使用します。

次の例は、この属性を追加する方法を示しています。

public class Restaurant
{
    [BsonIgnoreIfDefault]
    public ObjectId Id { get; set; }
    // Other properties
}

置換操作をカスタマイズする

ReplaceOne() メソッドと ReplaceOneAsync() メソッドはオプションで、置換操作を構成するために使用できるオプションを表す ReplaceOptionsオブジェクトをパラメーターとして受け入れます。

ReplaceOptionsクラスには、次のプロパティが含まれています。

プロパティ

説明

BypassDocumentValidation

置換操作がドキュメントの検証をバイパスするかどうかを指定します。これにより、スキーマ検証要件を満たさないドキュメントを存在する場合に置き換えることができます。スキーマ検証の詳細については、 MongoDB Serverマニュアルを参照してください。

データ型： bool?

Collation

結果をソートするときに使用する言語照合の種類を指定します。詳細については、このページの「照合」セクションを参照してください。

データ型： 照合

Comment

操作のユーザー指定のコメントを取得または設定します。詳細については、 MongoDB Server のマニュアルを参照してください。

データ型： BsonValue

Hint

ドキュメントをスキャンするために使用するインデックスを取得または設定します。詳細については、 MongoDB Server のマニュアルを参照してください。

データ型： BsonValue

IsUpsert

クエリフィルターに一致するドキュメントがない場合に、置換操作でアップサート操作を実行するかどうかを指定します。詳細については、 MongoDB Server のマニュアルを参照してください。

データ型： bool

Sort

クエリで複数のドキュメントが選択された場合に、その操作で置き換えるドキュメントを決定します。これは、置き換え操作が指定されたソート順の最初のドキュメントを置き換えるためです。このオプションを設定するには、次のコードに示すように、データをモデル化するジェネリック型を使用する ReplaceOptions<T>インスタンスをインスタンス化する必要があります。

var options = new ReplaceOptions<Restaurant>
{
  Sort = Builders<Restaurant>.Sort.Ascending(r => r.Name)
};

データ型： SortDefinition<T>

Let

letドキュメントを取得または設定します。詳細については、 MongoDB Server のマニュアルを参照してください。

データ型： BsonDocument

次の例では、前の例と同じ手順を実行しますが、スキーマ検証要件をバイパスするために BypassDocumentValidation オプションも使用されています。対応するコードを表示するには、Synchronous タブまたは Asynchronousタブを選択します。

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new Address()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
var options = new ReplaceOptions
{
    BypassDocumentValidation = true
};
// Replaces the existing restaurant document with the new document
return _restaurantsCollection.ReplaceOne(filter, newPizzaRestaurant, options);

// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza"
var filter = Builders<Restaurant>.Filter
    .Eq(r => r.Cuisine, "Pizza");
// Finds the ID of the first restaurant document that matches the filter
var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First();
var oldId = oldPizzaRestaurant.Id;
// Generates a new restaurant document
Restaurant newPizzaRestaurant = new()
{
    Id = oldId,
    Name = "Mongo's Pizza",
    Cuisine = "Pizza",
    Address = new Address()
    {
        Street = "Pizza St",
        ZipCode = "10003"
    },
    Borough = "Manhattan",
};
var options = new ReplaceOptions
{
    BypassDocumentValidation = true
};
// Asynchronously replaces the existing restaurant document with the new document
return await _restaurantsCollection.ReplaceOneAsync(filter, newPizzaRestaurant, options);

照合

操作の照合を構成するには、照合クラスのインスタンスを作成します。

次の表では、Collation コンストラクターが受け入れるパラメーターを説明しています。また、各設定の値を読み取るために使用できる対応するクラスプロパティも一覧表示されます。

Parameter	説明	クラスプロパティ
`locale`	国際化コンポーネント for Unicode (ICU) ロケールを指定します。サポートされているロケールの一覧については、MongoDB Server マニュアルの「照合ロケールとデフォルトパラメータ」を参照してください。単純なバイナリ比較を使用する場合は、`Collation.Simple` 静的プロパティを使用して、`locale` が `"simple"` に設定された `Collation` オブジェクトを返します。データ型: `string`	`Locale`
`caseLevel`	(任意) 大文字と小文字の比較を含めるかどうかを指定します。この引数が `true` の場合、ドライバーの動作は `strength` 引数の値によって異なります。 - `strength` が `CollationStrength.Primary` の場合、ドライバーは基本文字と大文字と小文字を比較します。 - `strength` が `CollationStrength.Secondary` の場合、ドライバーは基本文字、分音符号、その他の二次的な違い、および大文字と小文字を比較します。 - `strength` がその他の値の場合、この引数は無視されます。この引数が `false` の場合、ドライバーは強度レベル `Primary` または `Secondary` での大文字と小文字の比較を含みません。データ型: `boolean` デフォルト: `false`	`CaseLevel`
`caseFirst`	(任意) 三次レベルの比較中の大文字と小文字の相違のソート順序を指定します。データ型: CollationCaseFirst デフォルト: `CollationCaseFirst.Off`	`CaseFirst`
`strength`	(任意) ICU ドキュメントで定義されている、実行する比較のレベルを指定します。データ型: CollationStrength デフォルト: `CollationStrength.Tertiary`	`Strength`
`numericOrdering`	(任意) ドライバーが数字の文字列を数値として比較するかどうかを指定します。この引数が `true` の場合、ドライバーは数値型文字列を数値として比較します。例えば、文字列 "10" と "2" を比較する場合、ドライバーは値を 10 と 2 として取り扱い、10 が大きいことを確認します。この引数が `false` の場合、または除外される場合、ドライバーは数値型文字列を文字列として比較します。例えば、文字列 "10" と "2" を比較する場合、ドライバーは 1 文字ずつ比較します。"1" は "2" より小さいため、ドライバーは "10" が "2" より小さいことを確認します。詳細については、MongoDB Server マニュアルの「照合制限」を参照してください。データ型: `boolean` デフォルト: `false`	`NumericOrdering`
`alternate`	(任意) ドライバーが比較の基準文字として空白と句読点を考慮するかどうかを指定します。データ型: CollationAlternate デフォルト: `CollationAlternate.NonIgnorable` (空白と句読点は基準文字と見なされます)	`Alternate`
`maxVariable`	（任意） `alternateCollationAlternate.Shifted`引数がの場合にドライバーが無視可能と見なす文字を指定します。データ型: CollectionMaxVvariable デフォルト:`CollationMaxVariable.Punctuation` （ドライバーは句読点とスペースを無視します）	`MaxVariable`
`normalization`	（任意）ドライバーが必要に応じてテキストを正規化するかどうかを指定します。ほとんどのテキストは正規化を必要としません。正規化の詳細については、 ICU のドキュメントを参照してください。データ型:`boolean` デフォルト:`false`	`Normalization`
`backwards`	(任意) 発音区別符号を含む string を、string の後ろから前にソートするかどうかを指定します。データ型: `boolean` デフォルト: `false`	`Backwards`

照合の詳細については、 MongoDB Serverマニュアルの照合ページを参照してください。

戻り値

ReplaceOne() メソッドは ReplaceOneResultオブジェクトを返し、ReplaceOneAsync() メソッドは Task<ReplaceOneResult>オブジェクトを返します。 ReplaceOneResultクラスには次のプロパティが含まれています。

プロパティ	説明
`IsAcknowledged`	置き換え操作が MongoDB によって確認されたかどうかを示します。データ型： `bool`
`IsModifiedCountAvailable`	`ReplaceOneResult`で置換されたレコードの数を読み取れるかどうかを示します。データ型： `bool`
`MatchedCount`	置き換えられたかどうかにかかわらず、クエリフィルターに一致したドキュメントの数。データ型： `long`
`ModifiedCount`	置換操作によって置き換えられたドキュメントの数。データ型： `long`
`UpsertedId`	ドライバーがアップサートを実行した場合、データベースでアップサートされたドキュメントのID。データ型： BsonValue

詳細情報

置換操作の実行可能な例については、次の使用例を参照してください。

API ドキュメント

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

戻る

配列

Delete Documents