对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

$out 阶段 (Atlas Data Federation)

$out 获取聚合管道返回的文档并将其写入指定集合。$out操作符必须是 聚合管道 中的最后一个 阶段 。在 Atlas Data Federation 中,当使用 联合查询 时,您可以使用$out 将数据从任何一个 支持的 联合数据库实例存储或多个 支持的 联合数据库实例存储写入以下任何一个:

  • Atlas 集群 namespace

  • AWS S3 存储桶(具有读写入权限)

  • 具有读写权限的 Azure Blob Storage 容器

  • 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 角色或具有 outToS3 权限的自定义角色的 MongoDB 用户。

{ "$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

字符串

从聚合管道向其写入文档的 S3 存储桶的名称。

生成的调用 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

字符串

托管存储桶的 AWS 区域的名称。如果省略,则使用联合数据库实例配置来确定托管指定 s3.bucket 的区域。

Optional

s3.filename

字符串

将聚合管道中的文档写入到的文件的名称。文件名可以是常量,也可以根据达到 阶段的文档中的字段 动态创建 $out。您提供的任何文件名表达式的值必须为 string 数据类型。如果 S3 上有与新生成文件具有相同名称和路径的文件,则 $out 会用新生成的文件覆盖现有文件。

生成的调用 S3 会在 s3.bucket 和 s3.filename 之间插入 /。不要在 s3.filename string 前添加 /。

例如,如果将 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 格式写入数据。

要了解更多信息,请参阅限制。

必需

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>。

Optional

s3
.format
.maxRowGroupSize

字符串

仅支持 Parquet 文件格式。

写入 Parquet 文件时使用的最大行组大小。如果省略,则默认为 128 MiB 或 s3.format.maxFileSize 的值,以较小者为准。最大允许值为 1 GB。

Optional

s3
.format
.columnCompression

字符串

仅支持 Parquet 文件格式。

对 Parquet 文件进行格式化时用于压缩 Parquet 文件内数据的压缩类型。有效值为:

  • gzip

  • snappy

  • uncompressed

如果省略,则默认值为 snappy。

要了解更多信息,请参阅支持的数据格式。

Optional

errorMode

枚举

指定在处理文档出现错误时 Atlas Data Federation 应如何继续。例如,如果 Atlas Data Federation 在写入 CSV 文件时遇到某文档中的数组,它将使用此值来确定是否跳过该文档并继续处理其他文档。有效值为:

  • continue 跳过该文档并继续处理剩余文档。Atlas Data Federation 还会将导致错误的文档写入错误文件。

    要了解更多信息,请参阅错误。

  • stop 以在该点停止并且不处理剩余的文档。

如果省略,则默认值为 continue。

Optional

选项
类型
说明
必要性

background

布尔

标记在后台运行聚合操作。如果省略,则默认值为 false。当设置为 true 时,Atlas Data Federation 会在后台运行查询。

{ "background" : true }

如果您想要提交其他新查询,而无需等待当前运行的查询完成或断开与联合数据库实例的连接,同时查询继续在后台运行,请使用此选项。

Optional

创建文件名

以下示例显示 $out 语法,用于从常量字符串或到达 $out 阶段的文档中相同或不同数据类型的字段动态创建文件名。

您想要将 1 GiB 数据以压缩的 BSON 文件的形式写入名为 my-s3-bucket 的 S3 存储桶中。

使用以下 $out 语法:

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

已省略 s3.region,因此 Atlas Data Federation 会从存储配置中确定托管名为 my-s3-bucket 的存储桶的区域。$out 会写入五个压缩的 BSON 文件:

  1. 将前 200 MiB 数据写入 $out 命名为 big_box_store/1.bson.gz 的文件。

    • 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. 将第二个 200 MiB 数据写入 $out 命名为 big_box_store/2.bson.gz 的新文件。

  3. $out将另外三个文件命名为big_box_store/3.bson.gz到big_box_store/5.bson.gz。

您想要将 90 MiB 的数据写入 JSON 文件,并存储到名为 my-s3-bucket 的 S3 存储桶。

使用以下 $out 语法:

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

$out 将 90 MiB 的数据写入存储桶根目录中的 JSON 文件。每个 JSON 文件包含所有具有相同 saleDate 值的文档。$out 使用转换为 string 的文档的 saleDate 值来为每个文件命名。

您想要将 176 MiB 的数据写入 BSON 文件并存储到名为 my-s3-bucket 的 S3 存储桶。

使用以下 $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 文件。要为每个文件命名,$out 会连接以下内容:

  • 常量字符串 persons/ 和文档中的:

    • name 字段的字符串值,

    • 正斜杠(/),

    • uniqueId 字段的字符串值,以及

    • 正斜线(/)。

每个 BSON 文件包含具有相同 name 和 uniqueId 值的所有文档。$out 使用文档的 name 和 uniqueId 值命名每个文件。

您想要将 154 MiB 数据以压缩的 JSON 文件的形式写入名为 my-s3-bucket 的 S3 存储桶中。

考虑以下 $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 文件,其中每个文件包含具有相同 storeNumber、saleDate 和 partId 值的所有文档。要为每个文件命名,$out 会连接以下内容:

  • 常量字符串值 big-box-store/,

  • storeNumber 字段中唯一商店编号的字符串值,

  • 正斜杠(/),

  • saleDate 字段中日期的字符串值,

  • 正斜杠(/),

  • 来自 partId 字段的部件 ID 的字符串值,以及

  • 正斜线(/)。

以下示例显示了在背景中运行以 $out 阶段结尾的聚合管道的 $out 语法。

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

$out 在后台写入存储桶根目录中的 JSON 文件。每个 JSON 文件包含所有具有相同 saleDate 值的文档。$out 使用转换为 string 的文档 saleDate 值来为每个文件命名。

解析文件名时,Atlas Data Federation 会将空字符串 ("") 解释为 null 值。如果您想让 Atlas Data Federation 生成可解析的文件名,请使用 $convert 和空 string onNull 值来包装可能具有 null 值的字段引用。

此示例演示了在从字段值创建文件名时如何处理 year 字段中的空值。

{ "$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 或 Parquet 文件格式时,Atlas Data Federation 不支持超过 32000 个唯一字段。

当写入 CSV 或 TSV 格式时,Atlas Data Federation 不支持文档中的以下数据类型:

  • 数组

  • DB 指针

  • JavaScript

  • 带作用域的 JavaScript 代码

  • 最小或最大密钥数据类型

在 CSV 文件中,Atlas Data Federation 使用点 (.) 符号表示嵌套文档。例如,Atlas Data Federation 以如下形式将 { x: { a: 1, b: 2 } } 写入 CSV 文件:

x.a,x.b1,2

Atlas Data Federation 会将所有其他数据类型表示为字符串。因此,从 CSV 文件读回的 MongoDB 中的数据类型可能与写入数据类型的原始 BSON 文档中的数据类型不同。

Atlas Data Federation 在读取 Parquet 文件时会将包含空值或未定义值的字段视为缺失,因为 Parquet 并不区分空值或未定义值与缺失值。尽管 Atlas Data Federation 支持所有数据类型,但对于在 Parquet 中没有直接等效项的 BSON 数据类型(例如 JavaScript、正则表达式等),它会:

  • 选择一种允许使用非 MongoDB 工具读回生成的 Parquet 的表示形式。

  • 将 MongoDB 模式存储在 Parquet 文件的键/值元数据中,以便在读回 Parquet 文件时,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" }}

如果您使用 $out to S3 将前面的 BSON 文档写入 Parquet 格式,则您的 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 会将所有级别的文档映射到一个 Parquet 群组。

  • Atlas Data Federation使用 LIST 逻辑类型和强制的三级列表或元素结构对数组进行编码。要学习;了解更多信息,请参阅列表。

  • 由于 Parquet 不支持多态列,Atlas Data Federation 将多态 BSON 字段映射到包含多列的一组单一类型列。Atlas Data Federation 以 BSON 字段命名该群组。在前面的示例中,Atlas Data Federation 为名为 clientId 的多态字段创建一个名为 clientId 的 Parquet 组,其中有两个以其 BSON 类型命名的子项:int 和 string。

Atlas Data Federation 对进入$out阶段且由于以下原因之一而无法写入的文档使用下述错误处理机制:

  • s3.filename 的计算结果不是字符串值。

  • 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>/中的以下三个特殊错误文件:

错误文件名
说明

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 会将错误消息写入此文件。每条错误消息都包含错误描述和索引值 n,该索引值以 0 开头,并且在每多写入一条错误消息时递增。i 从 1 开始,并在写入的文件达到 maxFileSize 时递增。然后,任何进一步的错误信息都将写入新文件 out-error-docs/<i+1>.json。

out-error-summary.json

Atlas Data Federation 会将聚合操作期间遇到的每种错误类型的单个摘要文档写入此文件。每个摘要文档都包含错误类型的描述以及遇到该类型错误的文档计数。

此示例演示如何在联合数据库实例中使用$out生成错误文件。

以下聚合管道按客户出生日期降序对 analytics.customers 示例数据集合中的文档进行排序,并尝试将年龄最小的三个客户的 _id、name 和 accounts 字段写入到名为 customer-data 的 S3 存储桶中名为 youngest-customers.csv 的文件中。

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时会遇到错误。 为了处理这些错误,Atlas Data Federation 会写入以下三个错误文件:

  • 以下输出显示了写入 out-error-docs/1.json 文件的三个文档中的第一个:

    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 文件的三条错误消息中的第一条。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"} }