$out（集計ステージ）

定義

$out

集計パイプラインによって返されたドキュメントを受け取り、指定されたコレクションに書き込みます。出力データベースを指定できます。

$out ステージはパイプラインの最後のステージである必要があります。$out 演算子を使用すると、集計フレームワークは任意のサイズの結果セットを返すことができます。

警告

$out 操作で指定されたコレクションがすでに存在する場合、$out ステージは集計の完了時に既存のコレクションを新しい結果のコレクションにアトミックに置き換えます。詳細については、 「既存のコレクションの置き換え」を参照してください。

構文

$out ステージの構文は次のとおりです。

• $out 出力コレクションのみを指定する文字列を採用できます（つまり、同じデータベース内のコレクションに出力します）。

  { $out: "<output-collection>" } // Output collection is in the same database

• $out 出力データベースと出力コレクションを指定するためのドキュメントを受け取れます。

  { $out: { db: "<output-db>", coll: "<output-collection>" } }

• MongoDB 7.0.3と7.1以降では、 $outはドキュメントを取得し、 時系列コレクションに出力できます。

  { $out:
    { db: "<output-db>", coll: "<output-collection>",
      timeseries: {
        timeField: "<field-name>",
        metaField: "<field-name>",
        granularity:  "seconds" || "minutes" || "hours" ,
      }
    }
  }

  重要

  時系列の粒度の変更

  時系列コレクションを作成したら、collMod メソッドを使用してその粒度を変更できます。ただし、各バケットの対象期間は増やすことしかできず、減らすことはできません。

  フィールド	説明
  db	出力データベース名。 レプリカセットまたはスタンドアロンでは、出力データベースが存在しない場合、$out によってデータベースも作成されます。
  coll	出力コレクション名。
  timeseries	時系列コレクションへの書き込みで使用する構成を指定するドキュメント。timeField は必須です。その他のフィールドはすべてオプションです。
  timeField	時系列コレクションへの書き込みで必要です。各時系列ドキュメントの日付を含むフィールドの名前。 時系列コレクション内のドキュメントには、 timeFieldの値として有効な BSON 日付が必要です。
  metaField	任意。各時系列ドキュメントのメタデータを含むフィールドの名前。指定されたフィールドのメタデータは、一意の時系列ドキュメントにラベルを付けるために使用されるデータでなければなりません。メタデータを変更する必要はめったにありません。指定されたフィールドの名前を _id または timeseries.timeField と同じ名前にはできません。フィールドは任意のデータ型に指定できます。 metaFieldフィールドは任意ですが、メタデータを使用するとクエリの最適化が向上します。 たとえば、MongoDB metaFieldtimeFieldは新しいコレクションの フィールドと フィールドに 複合インデックス を自動的に作成します 。このフィールドに値を指定しない場合、データは時間のみに基づいてバケット化されます。
  granularity	オプション。bucketRoundingSecondsとbucketMaxSpanSecondsを設定する場合は使用しないでください。 可能な値はseconds （デフォルト）、minutes 、およびhoursです。 granularityを、連続する受信タイムスタンプ間の時間に最も近い値に設定します。これにより、MongoDB によるコレクションへのデータ保存方法が最適化され、パフォーマンスが向上します。 粒度とバケット間隔の詳細については、「時系列データの粒度の設定」を参照してください。
  bucketMaxSpanSeconds	オプション。granularityの代替としてbucketRoundingSecondsと一緒に使用します。同じバケツ内のタイムスタンプ間の最大時間を設定する。 設定可能な値は 1～31536000 です。 バージョン 6.3 で追加。
  bucketRoundingSeconds	オプション。granularityの代替としてbucketMaxSpanSecondsと一緒に使用します。bucketMaxSpanSecondsと等しくなければなりません。 ドキュメントに新しいバケットが必要な場合、MongoDB ではドキュメントのタイムスタンプ値がこの間隔で切り捨てられ、バケットの最小時間が設定されます。 バージョン 6.3 で追加。

動作

例

db.movies.aggregate( [
    { $match : { runtime : { $gt : 1000 } } },
    { $group : { _id : "$year", movies: { $push: "$title" } } },
    { $out : "movies_by_year" }
] )

db.movies_by_year.find().sort( { _id: 1 } )

[
  { _id: 1978, movies: [ 'Centennial' ] },
  { _id: 1994, movies: [ 'Baseball' ] }
]

db.movies.aggregate( [
    { $match : { runtime : { $gt : 1000 } } },
    { $group : { _id : "$year", movies: { $push: "$title" } } },
    { $out : { db: "reporting", coll: "movies_by_year" } }
] )

db.movies_by_year.find().sort( { _id: 1 } )

[
  { _id: 1978, movies: [ 'Centennial' ] },
  { _id: 1994, movies: [ 'Baseball' ] }
]

[BsonIgnoreExtraElements]
public class Movie
{
    [BsonId]
    public ObjectId Id { get; set; }
    [BsonElement("title")]
    public string Title { get; set; } = null!;
    [BsonElement("year")]
    public int? Year { get; set; }
    [BsonElement("runtime")]
    public int? Runtime { get; set; }
    [BsonElement("rated")]
    public string? Rated { get; set; }
    [BsonElement("metacritic")]
    public int Metacritic { get; set; }
    [BsonElement("plot")]
    public string? Plot { get; set; }
    [BsonElement("type")]
    public string? Type { get; set; }
    [BsonElement("cast")]
    public string[]? Cast { get; set; }
    [BsonElement("directors")]
    public string[]? Directors { get; set; }
    [BsonElement("writers")]
    public string[]? Writers { get; set; }
    [BsonElement("imdb")]
    public ImdbData? Imdb { get; set; }
}

var outCollection = _client
    .GetDatabase("sample_mflix")
    .GetCollection<Movie>("top_movies");
var pipeline = new EmptyPipelineDefinition<Movie>()
    .Match(Builders<Movie>.Filter.Eq(m => m.Metacritic, 100))
    .Sort(Builders<Movie>.Sort.Ascending(m => m.Title))
    .Out(outCollection);

{"_id": "...", "title": "Best Kept Secret", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "Boyhood", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "Fanny and Alexander", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "Lawrence of Arabia", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Conformist", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Godfather", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Leopard", "runtime": "...", "metacritic": 100, "imdb": "..."}
{"_id": "...", "title": "The Wizard of Oz", "runtime": "...", "metacritic": 100, "imdb": "..."}

const pipeline = [{ $out: { db: "sample_mflix", coll: "movies" } }];
const cursor = collection.aggregate(pipeline);
return cursor;