AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

$out ステージ(Atlas Data Federation)

$outは、集計パイプラインによって返されたドキュメントを受け取り、指定されたコレクションに書き込みます。演算子は、 $out集計パイプライン の最後の ステージ である必要があります。Atlas Data Federation では、 を使用して、 フェデレーティッドクエリ を使用している場合、 サポートされている フェデレーティッドデータベースインスタンス保存 (する)のいずれかの$out 1 つまたは複数の サポートされている フェデレーティッドデータベースインスタンス保存 (する)から、次のいずれかの 1 つにデータを書き込む (write)ことができます。

  • Atlas クラスター名前空間

  • Amazon Web Services S3 読み取りおよび書き込み (write)権限が付与されたバケット

  • 読み取りおよび書込み権限を持つAzure Blog ストレージ コンテナ

  • Google Cloud Platform Storage(GCS)

を使用するには、フェデレーティッドデータベースインスタンスに$out 接続 する必要があります。

次のものが必要です。

  • A federated database instance configured for an S3 bucket with read and write permissions or s3:PutObject permissions.

  • atlasAdminロールを持つ MongoDB ユーザー、またはoutToS3権限を持つカスタムロール。

{ "$out": { "s3": { "bucket": "<bucket-name>", "region": "<aws-region>", "filename": "<file-name>", "format": { "name": "<file-format>", "maxFileSize": "<file-size>", "maxRowGroupSize": "<row-group-size>", "columnCompression": "<compression-type>" }, "errorMode": "stop"|"continue" } }}
フィールド
タイプ
説明
必要性

s3

オブジェクト

集約パイプラインからドキュメントを書き込むロケーション。

必須

s3.bucket

string

集計パイプラインからドキュメントを S3 bucket に書き込み (write)する名前。

S3 への生成された呼び出しでは、s3.bucket と s3.filename の間に / が挿入されます。s3.bucket string に / を追加しないでください。

たとえば、 s3.bucketをmyBucketに、 s3.filenameをmyPath/myDataに設定すると、Atlas Data Federation は出力場所を次のように書込みます。

s3://myBucket/myPath/myData.[n].json

必須

s3.region

string

バケットがホストされている AWS リージョンの名前。省略した場合、フェデレーティッドデータベースインスタンスの構成を使用して、指定された s3.bucket がホストされているリージョンを決定します。

任意

s3.filename

string

集計パイプラインからドキュメントを書き込み (write)ファイルの名前。ファイル名は、定数とするか、または ステージに達するドキュメント内のフィールドから 動的に作成する $outこともできます。指定するファイル名の式は、string データ型に評価される必要があります。新しく生成されたファイルと同じ名前とパスを持つファイルが S3 上にある場合、$out は既存のファイルを新しく生成されたファイルで上書きします。

S3 への生成された呼び出しでは、s3.bucket と s3.filename の間に / が挿入されます。s3.filename 文字列の前に / を付けないでください。

たとえば、 s3.filenameをmyPath/myDataに、 s3.bucketをmyBucketに設定すると、Atlas Data Federation は出力場所を次のように書込みます。

s3://myBucket/myPath/myData.[n].json

必須

s3.format

オブジェクト

S3 におけるファイルの詳細。

必須

s3
.format
.name

列挙

S3 におけるファイルの形式。値は次のいずれかになります。

  • bson

  • bson.gz

  • csv

  • csv.gz

  • json 1

  • json.gz 1

  • parquet

  • tsv

  • tsv.gz

1 この形式の場合、$out はMongoDB拡張JSON形式にデータの書き込み (write)を行います。

詳細については、「制限 」を参照してください。

必須

s3
.format
.maxFileSize

バイト

S3 内の非圧縮 BSON ファイルの最大サイズ。BSON をお好みの形式に変換する際、生成される出力ファイルは小さくなることもあります (例、Parquet に変換する場合)、または大きくなることもあります (例、CSV に変換する場合)。

ドキュメントがmaxFileSizeより大きい場合、Atlas Data Federation はドキュメントを独自の ファイルに書込みます。 次のサフィックスがサポートされています。

  • ベース 10、1000 の倍数で拡大: B, KB, MB, GB, TB, PB

  • ベース 2、1024 の倍数での拡大: KiB、MiB、GiB、TiB、PiB

省略した場合、デフォルトは 200MiB になります。

現在のファイルのサイズ制限に達すると、Atlas Data Federation は S3 に新しいファイルを作成します。最初のファイルの拡張子の前に 1 が追加されます。Atlas Data Federation は、後続のファイルごとに付加される番号を 1 ずつ増やします。

たとえば、 <filename>.1.<fileformat>や<filename>.2.<fileformat>などです。

任意

s3
.format
.maxRowGroupSize

string

Perquet ファイル形式のみでサポートされています。

Farquet ファイルへの書き込み時に使用する最大行グループ サイズ。 省略した場合、デフォルトは128 MiBまたはs3.format.maxFileSizeの値のいずれか小さい方になります。 許可される最大値は1 GBです。

任意

s3
.format
.columnCompression

string

Perquet ファイル形式のみでサポートされています。

Perquet ファイルをフォーマットするときに、Parquet ファイル内のデータを圧縮するために適用する圧縮タイプ。 有効な値は以下のとおりです。

  • gzip

  • snappy

  • uncompressed

省略した場合、デフォルトは snappy になります。

詳細については、 「サポートされているデータ形式」 を参照してください。

任意

errorMode

列挙

ドキュメントの処理時にエラーが発生した場合に Atlas Data Federation が続行する方法を指定します。 たとえば、 Atlas Data Federation Atlas Data FederationがCSVファイルに書き込みを行っているときにドキュメント内の配列を検出した場合、 Atlas Data Federationはこの値を使用して、ドキュメントをスキップして他のドキュメントを処理するかどうかを決定します。 有効な値は以下のとおりです。

  • continue ドキュメントをスキップし、残りのドキュメントの処理を続行します。 Atlas Data Federation は、エラーの原因となったドキュメントもエラー ファイルに書込みます。

    詳しくは、 「 エラー 」を参照してください。

  • stop その時点で停止し、残りのドキュメントを処理しない場合。

省略した場合、デフォルトは continue になります。

任意

オプション
タイプ
説明
必要性

background

ブール値

バックグラウンドで集計操作を実行するためのフラグ。 省略した場合、デフォルトはfalseになります。 trueに設定すると、Atlas Data Federation はバックグラウンドでクエリを実行します。

{ "background" : true }

現在実行中のクエリがフェデレーティッドデータベースインスタンスへの接続を完了または切断するのを待たずに、他の新しいクエリを送信すると同時に、クエリがバックグラウンドで実行され続ける場合は、このオプションを使用します。

任意

ファイル名を作成

次の例は、定数$out string から、または ステージに到達するドキュメント内の同じまたは異なるデータ型のフィールドからファイル名を動的に作成するための$out 構文を示します。

1 GiB のデータを圧縮 BSON ファイルとして、my-s3-bucket という名前の S3 バケットに書き込み (write)するとします。

次の $out 構文を使用します。

{ "$out": { "s3": { "bucket": "my-s3-bucket", "filename": "big_box_store/", "format": { "name": "bson.gz" } } }}

s3.regionは省略されているため、Atlas Data Federation は、 my-s3-bucketという名前のバケットがホストされているリージョンをストレージ構成から決定します。$out は 5 つの圧縮された BSON ファイルを書き込みます:

  1. $outがbig_box_store/1.bson.gzと名前を付けるファイルへの最初の200 MiB のデータ。

    • s3.filenameの値は、各ファイル名で定数として機能します。 この値は、ドキュメント フィールドまたは値に依存しません。

    • s3.filenameは区切り文字で終わるため、Atlas Data Federation は 定数の後にカウンターを追加します。

    • 区切り文字で終了しない場合、Atlas Data Federation はbig_box_store.1.bson.gzのように 定数と カウンターの間に.を追加します。

    • s3.format.maxFileSizeを使用して最大ファイルサイズを変更しなかったため、Atlas Data Federation はデフォルト値の 200 MiB を使用します。

  2. $out が big_box_store/2.bson.gz と名付ける新しいファイルへの 2 番目の 200 MiB のデータ。

  3. $out が big_box_store/3.bson.gz から big_box_store/5.bson.gz までの名前を付けるさらに 3 つのファイル。

という名前の` S3 90` バケットに、 MiB のデータを` JSON ` ファイルに書き込み my-s3-bucket (write)とします。

次の $out 構文を使用します。

{ "$out": { "s3": { "bucket": "my-s3-bucket", "region": "us-east-1", "filename": {"$toString": "$saleDate"}, "format": { "name": "json", "maxFileSize": "100MiB" } } }}

$out は、バケットのルートにある JSON ファイルに 90 MiB のデータを書き込み (write)ます。各 JSON ファイルには、同じsaleDate値を持つすべてのドキュメントが含まれています。$out は、ドキュメントの saleDate 値を string に変換して、各ファイルに名前を付けます。

という名前の 176S3 バケットに、 MiBのデータを BSON ファイルとして書き込み my-s3-bucket (write)するとします。

次の $out 構文を使用します。

{ "$out": { "s3": { "bucket": "my-s3-bucket", "region": "us-east-1", "filename": { "$concat": [ "persons/", "$name", "/", "$uniqueId", "/" ] }, "format": { "name": "bson", "maxFileSize": "200MiB" } } }}

$out は 176 MiB のデータを BSON ファイルに書き込み (write)。各ファイルに名前を付けるには、$out が連結します。

  • 次のドキュメントからの 定数string persons/ と

    • nameフィールドの string 値、

    • フォワードスラッシュ( / )、

    • uniqueIdフィールドの string 値、および

    • フォワードスラッシュ( / )。

各BSONファイルには、同じnameとuniqueIdの値を持つすべてのドキュメントが含まれています。$out は、ドキュメントの name と uniqueId の値を使用して、各ファイルに名前を付けます。

という名前の154 S3 バケットに、 MiB のデータを圧縮 JSON ファイルとして書き込み my-s3-bucket (write)ます。

次の$out構文を考えてみましょう。

{ "$out": { "s3": { "bucket": "my-s3-bucket", "region": "us-east-1", "filename": { "$concat": [ "big-box-store/", { "$toString": "$storeNumber" }, "/", { "$toString": "$saleDate" }, "/", "$partId", "/" ] }, "format": { "name": "json.gz", "maxFileSize": "200MiB" } } }}

$out は、154 MiB のデータを圧縮された JSON ファイルに書き込み (write)ます。各ファイルには、同じ storeNumber、saleDate、partId の値を持つドキュメントが全て含まれています。各ファイルに名前を付けるには、$out が連結します。

  • big-box-store/ の定数string値、

  • storeNumberフィールドの一意の店舗番号の string 値、

  • フォワードスラッシュ( / )、

  • saleDateフィールドからの日付の string 値、

  • フォワードスラッシュ( / )、

  • partIdフィールドからの 部分 ID の string 値、および

  • フォワードスラッシュ( / )。

次の例は、バックグラウンドで$out $outステージで終了する集計パイプラインを実行するための 構文を示しています。

db.runCommand({ "aggregate": "my-collection", "pipeline": [ { "$out": { "s3": { "bucket": "my-s3-bucket", "filename": { "$toString": "$saleDate" }, "format": { "name": "json" } } } } ], "background": true})

$out は、バケットのルートにある JSON ファイルに経歴で書き込み (write) を行います。各 JSON ファイルは、同じ saleDate 値を持つすべてのドキュメントを含んでいます。$out は、ドキュメントの saleDate 値を string に変換したものを使用して、各ファイルに名前を付けます。

Atlas Data Federation は、ファイル名を解析するときに空のstring( "" )を null 値として解釈します。Atlas Data Federation で解析可能なファイル名を生成する場合は、 $convert を使用して null 値を持つ可能性のあるフィールド参照を空のstring onNull 値とラップします。

この例では、 フィールド値からファイル名を作成するときに、 yearフィールドの null 値を処理する方法を示しています。

{ "$out": { "s3": { "bucket": "my-s3-bucket", "region": "us-east-1", "filename": { "$concat": [ "big-box-store/", { "$convert": { "input": "$year", "to": "string", "onNull": "" } }, "/" ] }, "format": { "name": "json.gz", "maxFileSize": "200MiB" } } }}

CSV 、 TSV 、またはPerquetファイル形式に書き込む場合、Atlas Data Federation は 32000 を超える一意のフィールドをサポートしません。

CSV または TSV 形式に書き込む場合、Atlas Data Federation はドキュメント内の次のデータ型をサポートしません。

  • 配列

  • DBポインタ

  • JavaScript

  • JavaScript コード(スコープ付き)

  • 最小または最大のキー データ型

CSV ファイルでは、Atlas Data Federation はドット( . )表記を使用してネストされたドキュメントを表します。 たとえば、Atlas Data Federation は CSV ファイルに{ x: { a: 1, b: 2 } }を次のように書込みます。

x.a,x.b1,2

Atlas Data Federation は、他のすべてのデータ型を string として表現します。 そのため、CSV ファイルから読み取られた MongoDB のデータ型は、データ型が書き込まれた元のBSONドキュメントのデータ型と異なる場合があります。

Perquet の場合、Atlas Data Federation は null または未定義の値が欠落しているフィールドを読み取ります。これは、Parquet が null または未定義の値と欠落値を区別しないためです。 Atlas Data Federation はすべてのデータ型をサポートしていますが、JavaScript、正規表現など、Parquet に直接同等ではないBSONデータ型の場合は、次のようになります。

  • 非 MongoDB ツールを使用して結果の一部のファイルを読み取れる表現を選択します。

  • MongoDB スキーマを Perquet ファイルのキーと値のメタデータに保存し、Parquet ファイルが Atlas Data Federation によって読み取られた場合に、Atlas Data Federation が正しいデータ型で元のBSONドキュメントを再構築できるようにします。

次のBSONドキュメントを検討します。

{ "clientId": 102, "phoneNumbers": ["123-4567", "234-5678"], "clientInfo": { "name": "Taylor", "occupation": "teacher" }}{ "clientId": "237", "phoneNumbers": ["345-6789"], "clientInfo": { "name": "Jordan" }}

上記の BSON ドキュメントを $out to S3 を使用して Parquet 形式で書き込み (write) すると、BSON ドキュメントの Parquet ファイル スキーマは以下のようになります。

message root { optional group clientId { optional int32 int; optional binary string (STRING); } optional group phoneNumbers (LIST) { repeated group list { optional binary element (STRING); } } optional group clientInfo { optional binary name (STRING); optional binary occupation (STRING); }}

S3 上のあなたの Parquet データは次のようになります。

clientId:.int = 102phoneNumbers:.list:..element = "123-4567".list:..element = "234-5678"clientInfo:.name = "Taylor".occupation = "teacher" clientId:.string = "237"phoneNumbers:.list:..element = "345-6789"clientInfo:.name = "Jordan"

上記の例は、Atlas Data Federation が複雑なデータ型を処理する方法を示しています。

  • Atlas Data Federation は、すべてのレベルのドキュメントを Compass グループにマッピングします。

  • Atlas Data Federation は、LIST 論理型と必須の 3 レベルのリストまたは要素構造を使用して配列をエンコードします。詳細については、「 リスト 」を参照してください。

  • Atlas Data Federation は、Parquet がポリモーフィックな列をサポートしていないため、ポリモーフィックな BSON フィールドを複数の単一型列のグループにマッピングします。Atlas Data Federation は、BSON フィールドにちなんでグループに名前を付けます。前の例では、Atlas Data Federation は、clientId という名前のポリモーフィックフィールドに対して、その BSON 型にちなんで名付けられた 2 つの子(int と string)を持つ clientId という名前の Parquet グループを作成します。

Atlas Data Federation は、 $outステージに入り、次のいずれかの理由で書き込みができないドキュメントに対して、以下で説明するエラー処理メカニズムを使用します。

  • s3.filenameは string 値として評価されません。

  • s3.filenameは書き込み不可のファイルと評価します。

  • s3.format.nameはcsv 、 tsv 、 csv.gz 、またはtsv.gzに設定されており、 $outに渡されるドキュメントには、指定されたファイル形式ではサポートされていないデータ型が含まれています。 サポートされていないデータ型の完全なリストについては、「 CSV および TSV ファイル形式 」を参照してください。

ドキュメントの処理中に$outで上記のエラーのいずれかが発生した場合、Atlas Data Federation はパスs3://<bucket-name>/atlas-data-lake-<correlation-id>/にある次の 3 つの特別なエラー ファイルに書込みます。

エラーファイル名
説明

out-error-docs/<i>.json

Atlas Data Federation は、エラーが発生したドキュメントをこのファイルに書込みます。 はi 1から始まり、書き込まれるファイルが に達するたびに増加します。maxFileSizeその後、それ以降のドキュメントは新しいファイルout-error-docs/<i+1>.jsonに書き込まれます。

out-error-index/<i>.json

Atlas Data Federation は、このファイルにエラー メッセージを書込みます。 各エラー メッセージには、エラーの説明と、 0から始まり、ファイルに書き込まれる追加のエラー メッセージごとに増加するインデックス値nが含まれています。 iは1から始まり、書き込まれるファイルがmaxFileSizeに達するたびに増加します。 その後、それ以降のエラー メッセージは新しいファイルout-error-docs/<i+1>.jsonに書き込まれます。

out-error- Summary.json

Atlas Data Federation は、集計操作中に発生したエラーの種類ごとに 1 つのサマリー ドキュメントをこのファイルに書込みます。 各サマリードキュメントには、エラーのタイプの説明と、そのタイプのエラーが発生したドキュメントの数が含まれています。

この例では、フェデレーティッドデータベースインスタンスで$outを使用してエラーファイルを生成する方法を示します。

次の集計パイプラインは、analytics.customersサンプル データセット コレクション内のドキュメントをカスタマーの誕生日の降順でソートし、最も若い 3 人のカスタマーの _id、name、accounts フィールドを customer-data という名前の S3 バケット内の youngest-customers.csv という名前のファイルに書き込み (write)もうとします。

db.customers.aggregate([ { "$sort": { "birthdate": -1 } }, { "$unset": [ "username", "address", "email", "tier_and_details", "birthdate" ] }, { "$limit": 3 }, { "$out": { "s3": { "bucket": "customer-data", "region": "us-east-2", "filename": "youngest-customers", "format": { "name": "csv" } } } }])

accountsは配列フィールドであるため、 $outはs3.format.name csvにドキュメントを書込み (write) しようとするとエラーに遭遇します。 これらのエラーを処理するために、Atlas Data Federation は次の 3 つのエラーファイルに書込みます。

  • 次の出力は、 out-error-docs/1.jsonファイルに書き込まれた 3 つのドキュメントのうちの最初の を示しています。

    s3://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-docs/1.json

    { "_id" : {"$oid":"5ca4bbcea2dd94ee58162ba7"}, "name": "Marc Cain", "accounts": [{"$numberInt":"980440"}, {"$numberInt":"626807"}, {"$numberInt":"313907"}, {"$numberInt":"218101"}, {"$numberInt":"157495"}, {"$numberInt":"736396"}]}
  • 次の出力は、 out-error-index/1.jsonファイルに書き込まれた 3 つのエラー メッセージのうちの最初の を示しています。 nフィールドは 0 から始まり、ファイルに書き込まれるエラーごとに増加します。

    s3://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error-index/1.json

    { "n" : {"$numberInt": "0"}, "error" : "field accounts is of unsupported type array"}
  • 次の出力は、 out-error-summaryファイルに書き込まれたエラーの概要ドキュメントを示しています。 countフィールドは、 accounts配列フィールドが原因でエラーが発生した$outに渡されたドキュメントの数を表します。

    s3://customer-data/atlas-data-lake-1773b3d5e2a7f3858530daf5/out-error- Summary.json

    { "errorType": "field accounts is of unsupported type array", "count": {"$numberInt":"3"} }