ビルダを用いた操作

Overview

このガイドでは、操作で使用する型を作成するために .NET/C# ドライバーが提供するヘルパー クラス、つまり ビルダ について学習できます。ビルダを使用すると、コンパイル時にエラーを識別し、実行時にエラーを回避することができます。このガイドでは、次のタスクに使用できるビルダ クラスに関する情報を提供します。

• フィルター定義の作成

• プロジェクションの作成

• ソート順序の定義

• アップデート操作の定義

• インデックス キーの選択

ビルダを使用して定義を構築し、構文をビルドする方法について詳しはは、こちらのガイドをお読みください。

サンプル クラス

このガイドのコード例は、ビルダを使用してサンプルコレクション plants.flowers内のドキュメントを操作するための型を作成する方法を示しています。このコレクション内のドキュメントは、以下の Flower クラスによってモデル化されます。

public class Flower
{
    public ObjectId Id { get; set; }
    public string Name { get; set; }
    public string Category { get; set; }
    public double Price { get; set; }
    public List<string> Season { get; set; }
    public double Stock { get; set; }
    public string Description { get; set; }
}

各ビルダ クラスには、操作するドキュメントのタイプを表すジェネリック型パラメーター TDocument があります。このガイドでは、 Flower クラスは各ビルダ クラスの例で使用されるドキュメント タイプです。

フィルターを構築する

FilterDefinitionBuilder クラスは、クエリをビルドするための型セーフなインターフェースを提供します。次の条件に一致するドキュメントをコレクション内で照会するとします。

• Price フィールド値は 20 未満

• Category フィールド値は「Perennial」

ビルダを使用して、型指定されたバリアントを持つフィルター定義を作成します。

var builder = Builders<Flower>.Filter;
var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial");

型指定されたバリアント形式を使用すると、コンパイル時の安全性が確保されます。さらに、IDE はリファクタリングのサポートを提供できます。

あるいは、文字列ベースのフィールド名を使用してフィルターを構築することもできます。

var builder = Builders<Flower>.Filter;
var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial");

var builder = Builders<Flower>.Filter;
var filter = builder.AnyEq(f => f.Season, "winter");

プロジェクションを作成する

ProjectionDefinitionBuilder クラスは、プロジェクションを定義するための型セーフなインターフェースを提供します。Name フィールドと Price フィールドにプロジェクションを作成し、Id フィールドを除外するとします。

ビルダを使用して、型指定されたバリアントを持つプロジェクション定義を作成します。

var builder = Builders<Flower>.Projection;
var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id);

文字列ベースのフィールド名を使用してプロジェクションを定義することもできます。

var builder = Builders<Flower>.Projection;
var projection = builder.Include("Name").Include("Price").Exclude("Id");

最後に、Expression() メソッドを使用してプロジェクションを定義します。

var builder = Builders<Flower>.Projection;
var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price });

この定義の戻り値の型は ProjectionDefinition<TDocument, TProjection> ですが、他の定義は ProjectionDefinition<TDocument> を返します。

var builder = Builders<Flower>.Projection;
var projection = builder.Expression(f => new { Profit = f.Price * f.Stock });

ソートを定義する

SortDefinitionBuilder クラスは、ソート構文を構築するための型セーフなインターフェースを提供します。次の順序でソートを定義するとします。

• 昇順基準: Price

• 降順基準: Category

ビルダを使用して、型指定されたバリアントでソート定義を作成します。

var builder = Builders<Flower>.Sort;
var sort = builder.Ascending(f => f.Price).Descending(f => f.Category);

あるいは、文字列ベースのフィールド名を使用してソートを定義することもできます。

var builder = Builders<Flower>.Sort;
var sort = builder.Ascending("Price").Descending("Category");

アップデートを定義する

UpdateDefinitionBuilder クラスは、アップデート仕様を構築するための型セーフなインターフェースを提供します。次の基準でアップデート仕様を作成するとします。

• 新しいフィールドを作成する SunRequirement

• Price　フィールド値を 0.9 倍します

ビルダを使用して、型指定されたバリアントを含むアップデート仕様を作成します。

var builder = Builders<Flower>.Update;
var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9);

あるいは、文字列ベースのフィールド名を使用して更新を定義することもできます。

var builder = Builders<Flower>.Update;
var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9);

インデックス キーを定義する

IndexKeysDefinitionBuilder クラスは、インデックス キーを定義するための型セーフなインターフェースを提供します。昇順のインデックス キーとして Category を選択するとします。

ビルダを使用して、型指定されたバリアントを持つインデックス キーを選択します。

var builder = Builders<Flower>.IndexKeys;
var keys = builder.Ascending(f => f.Category);

あるいは、文字列ベースのフィールド名を使用してインデックス キーを選択することもできます。

var builder = Builders<BsonDocument>.IndexKeys;
var keys = builder.Ascending("Category");

IndexKeysDefinitionBuilder クラスには、ワイルドカード インデックスを構築するメソッドも用意されています。All field paths または A single field path を使用してワイルドカード インデックスを作成できます（この場合は Category を使用します）。

var builder = Builders<Flower>.IndexKeys;
var keys = builder.Wildcard();

var builder = Builders<Flower>.IndexKeys;
// Using the typed variant
var keys = builder.Wildcard(f => f.Category);
// Using string-based field names
var keys = builder.Wildcard("Category");

ワイルドカード インデックスの使用方法の詳細については、「ワイルドカード インデックス 」を参照してください。

Aggregation Pipeline をビルドする

PipelineDefinitionBuilder クラスでは、集計パイプラインを定義するためのタイプセーフ インターフェースが提供されます。集計パイプラインは、ドキュメントを変換するために使用される一連のステージです。次の操作を実行するパイプラインを作成するとします。

• Season フィールドに「spring」が含まれるすべてのドキュメントに一致します

• 結果を Category フィールドでソートします

• ドキュメントをカテゴリ別にグループ化し、そのカテゴリ内のすべてのドキュメントの平均価格と合計を表示します

パイプラインを構築するには、PipelineDefinitionBuilder クラスを使用します。

var sortBuilder = Builders<Flower>.Sort.Ascending(f => f.Category);
var matchFilter = Builders<Flower>.Filter.AnyEq(f => f.Season, "spring");
var pipeline = new EmptyPipelineDefinition<Flower>()
    .Match(matchFilter)
    .Sort(sortBuilder)
    .Group(f => f.Category,
           g => new
              {
                 name = g.Key,
                 avgPrice = g.Average(f => f.Price),
                 totalAvailable = g.Sum(f => f.Stock)
               }
          );

上記の例では、次のパイプラインが作成されます。

[{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }]

クエリを BsonDocument として AppendStage() メソッドに提供することで、PipelineDefinitionBuilder インターフェースに対応するタイプセーフ メソッドがないステージをパイプラインに追加できます。

var pipeline = new EmptyPipelineDefinition<BsonDocument>().AppendStage<BsonDocument, BsonDocument, BsonDocument>("{ $set: { field1: '$field2' } }");

Aggregation Pipeline の詳細については、 マニュアルの「Aggregation Pipeline サーバー」ページを参照してください。

Atlas 検索クエリをビルドする

Search クラスは、$search パイプライン ステージを作成するための型セーフなインターフェースを提供します。

Searchクラスを使用して検索クエリを構築する方法については、「Atlas Search」を参照してください。

詳細情報

さまざまな操作でビルダを使用して実行可能な例については、「使用例」を参照してください。