AWS S3 存储桶

Overview

Atlas Data Federation 支持 AWS S3 存储桶作为联合数据库实例存储。您必须在联合数据库实例中定义到 AWS S3 存储桶的映射，才能运行数据查询。

配置文件格式

要为 AWS S3 存储桶定义联合数据库实例存储，您可以在 JSON 中指定配置参数。该配置包含 AWS 数据存储，并将其映射到您可以查询的虚拟集合。

AWS S3 存储桶中数据的 JSON 配置使用以下字段：

1 {
2   "stores" : [
3     {
4       "name" : "<string>",
5       "provider": "<string>",
6       "region" : "<string>",
7       "bucket" : "<string>",
8       "additionalStorageClasses" : ["<string>"],
9       "prefix" : "<string>",
10       "includeTags": <boolean>,
11       "delimiter": "<string>",
12       "public": <boolean>
13     }
14   ],
15   "databases" : [
16     {
17       "name" : "<string>",
18       "collections" : [
19         {
20           "name" : "<string>",
21           "dataSources" : [
22             {
23               "storeName" : "<string>",
24               "path" : "<string>",
25               "defaultFormat" : "<string>",
26               "provenanceFieldName": "<string>",
27               "omitAttributes": true | false
28             }
29           ]
30         }
31       ],
32       "maxWildcardCollections" : <integer>,
33       "views" : [ 
34         {
35           "name" : "<string>", 
36           "source" : "<string>", 
37           "pipeline" : "<string>" 
38         }
39       ] 
40     }
41   ]
42 }

Amazon Web Services S3 数据存储的JSON配置包含两个顶级对象：stores 和databases 。

`stores`

stores 对象定义与该联合数据库实例关联的每个数据存储。此存储可在 AWS S3 存储桶中捕获文件。Data Federation 只能访问 stores 对象中定义的数据存储。

stores对象包含以下字段：

1    "stores" : [
2      {
3        "name" : "<string>",
4        "provider" : "<string>",
5        "region" : "<string>",
6        "bucket" : "<string>",
7        "additionalStorageClasses" : ["<string>"],
8        "prefix" : "<string>",
9        "delimiter" : "<string>",
10        "includeTags": <boolean>,
11        "public": <boolean>
12      }
13    ]

下表描述了 stores 对象中的字段：

字段	类型	必要性	说明
`stores`	阵列	必需	对象数组，其中每个对象代表一个与联合数据库实例关联的数据存储。存储可在 AWS S3 存储桶中捕获文件。Atlas Data Federation 只能访问 `stores` 对象中定义的数据存储。
`stores.[n].name`	字符串	必需	联合数据库实例存储的名称。 `databases.[n].collections.[n].dataSources.[n].storeName`字段引用此值作为映射配置的一部分。
`stores.[n].provider`	字符串	必需	定义数据的存储位置。AWS S3 存储桶的值必须为 `s3`。
`stores.[n].region`	字符串	必需	托管 AWS S3 存储桶的 AWS 区域的名称。有关有效区域名称的列表，请参阅 Amazon Web Services (AWS)。
`stores.[n].bucket`	字符串	必需	AWS S3 存储桶的名称。必须与 Atlas Data Federation 可使用配置的 AWS IAM 凭证来访问的 AWS S3 存储桶的名称完全匹配。
`stores.[n].additionalStorageClasses`	阵列	可选	Amazon Web Services S3 存储类的数组。Atlas Data Federation将在查询结果中包含这些存储类中的文件。有效值为： `INTELLIGENT_TIERING` 以包含智能分层存储类中的文件 `STANDARD_IA` 将文件包含在标准-不频繁访问中存储类重要提示：默认支持标准存储类中的文件。
`stores.[n].prefix`	字符串	可选	为 AWS S3 存储桶中的文件搜索路径添加前缀。Atlas Data Federation 会将 `prefix` 的值置于 `databases.[n].collections.[n].dataSources.[n].path` 之前，以创建要摄取的文件的完整路径。如果省略，Atlas Data Federation 会从 AWS S3 存储桶的根目录搜索所有文件。
`stores.[n].delimiter`	字符串	可选	设置用于分隔联合数据库实例存储中的路径段的分隔符。Data Federation使用分隔符有效地遍历具有分层目录结构的Amazon Web Services S3 存储桶。您可以将Amazon Web Services S3 对象键支持的任何字符指定为分隔符。示例，您可以指定下划线 (`_`) 或加号 (`+`) 或多个字符（例如双下划线 (`__`)）作为分隔符。如果省略，则默认值为 `"/"`。
`stores.[n].includeTags`	布尔	可选	决定是否在给定路径中的文件上使用 AWS S3 标签作为附加分区属性。有效值为 `true` 和 `false`。如果省略，则默认值为 `false`。如果设为 `true`，Atlas Data Federation 则会执行以下操作：添加 AWS S3 标签作为附加分区属性。为标记的文件添加新的顶层 BSON 元素，将每个标记与每个文档关联起来。警告：如果设置为 `true`，Atlas Data Federation 会额外调用 AWS S3 来获取标签，从而针对其他分区属性处理文件。这种行为可能会影响性能。
`stores.[n].public`	布尔	可选	指定存储桶是否公开。如果设置为 `true`，Atlas Data Federation 将不会使用配置的 AWS IAM 角色来访问 AWS S3 存储桶。如果设置为 `false`，则配置的 AWS IAM 必须包含访问 AWS S3 存储桶的权限，即使该存储桶是公共的。如果省略，则默认值为 `false`。

`databases`

databases 对象定义 stores 中定义的每个联合数据库实例存储与数据库中的 MongoDB 集合之间的映射。

database对象包含以下字段：

1 "databases" : [
2   {
3     "name" : "<string>",
4     "collections" : [
5       {
6         "name" : "<string>",
7         "dataSources" : [
8           {
9             "storeName" : "<string>",
10             "defaultFormat" : "<string>",
11             "path" : "<string>",
12             "provenanceFieldName": "<string>",
13             "omitAttributes": <boolean>
14           }
15         ]
16       }
17     ], 
18     "maxWildcardCollections" : <integer>,
19     "views" : [
20       {
21         "name" : "<string>",
22         "source" : "<string>",
23         "pipeline" : "<string>"
24       }
25     ]
26   }
27 ]

下表描述了 database 对象中的字段：

字段

类型

必要性

说明

databases

阵列

必需

对象数组，其中每个对象均代表一个数据库、其集合以及（可选）这些集合的所有视图。每个数据库均可有多个 collections 和 views 对象。

databases.[n].name

字符串

必需

Atlas Data Federation 将数据存储中包含的数据映射到数据库的数据库名称。

databases.[n].collections

阵列

必需

对象数组，其中每个对象代表一个集合和映射到 stores 联合数据库实例存储的数据源。

databases.[n].collections.[n].name

字符串

必需

Atlas Data Federation将每个databases.[n].collections.[n].dataSources.[n].storeName中包含的数据映射到的集合名称。大量中的每个对象代表集合与stores 大量中对象之间的映射。

通过为集合名称指定 *，并在 path 字段中指定 collectionName() 函数，可以从文件路径动态生成集合名称。有关示例，请参阅从文件路径生成动态集合名称。

databases.[n].collections.[n].dataSources

阵列

必需

对象数组，其中每个对象代表要与集合的stores联合数据库实例存储。

databases.[n].collections.[n].dataSources.[n].storeName

字符串

必需

要映射到 <collection>的联合数据库实例存储的名称。必须匹配name 大量中对象的stores。

databases.[n].collections.[n].dataSources.[n].path

字符串

必需

控制 Atlas Data Federation 在将文件映射到 <collection> 之前，如何在 storeName 中搜索和解析文件。联合数据库实例会将 stores.[n].prefix 置于 path 之前，以构建内部搜索的完整路径。指定 / 以捕获 prefix 路径中的所有文件和文件夹。

例如，某一 S3 存储桶的 metrics 采用以下结构：

 metrics
 |--hardware
  |--software
   |--computed

/的path指示 Atlas Data Federation 搜索metrics存储桶中的所有文件和文件夹。

/hardware 的 path 指示 Atlas Data Federation 仅搜索该路径下的文件进行摄取。

如果 prefix 为 software，则 Atlas Data Federation 仅搜索路径 /software/computed 中的文件。

将 * 通配符附加到此路径会指示 Atlas Data Federation 包含此路径中从该时间点起的所有文件和文件夹。例如，/software/computed* 将匹配 /software/computed-detailed、/software/computedArchive 和 /software/computed/errors 等文件。

path 支持用于解析文件名的其他语法，包括：

从文件名生成文档字段
使用正则表达式控制字段生成。
设置按时间戳分桶文件名的界线。

请参阅为 S3 数据定义路径以了解更多信息。

指定 path 时：

指定分区属性的数据类型。
确保分区属性类型与要解析的数据类型相匹配。
使用 delimiter 中指定的分隔符。

在指定相同类型的属性时，请执行以下任一操作：

在属性之间添加常量分隔符。
使用正则表达式来描述搜索模式。要了解更多信息，请参阅不支持的解析函数。

databases.[n].collections.[n].dataSources.[n].defaultFormat

Data Federation在搜索 databases.[n].collections.[n].dataSources.[n].storeName 时遇到不带扩展名的文件时采用的默认格式。

以下值对 defaultFormat 字段有效：

.json, .json.gz, .bson, .bson.gz, .avro, .avro.gz, .orc, .tsv, .tsv.gz, .csv, .csv.gz, .parquet

重要：如果您的文件格式为 CSV 或 TSV，则必须在数据中包含标题行。有关详细信息，请参阅 CSV 和 TSV。

如果省略，Data Federation 将尝试处理文件的几个字节来检测文件类型。

提示

支持的数据格式

databases.[n].collections.[n].dataSources.[n].provenanceFieldName

字符串

可选

包含结果中文档来源的字段的名称。如果在存储配置中指定了此设置，Atlas Data Federation 则会为结果中的每个文档返回以下字段：

字段名称	说明
`provider`	联合数据库实例存储配置中的提供商 ()`stores.[n].provider`
`region`	Amazon Web Services地区()`stores.[n].region`
`bucket`	Amazon Web Services S3 存储桶 () 的名称`stores.[n].bucket`
`key`	文档的路径`databases.[n].collections.[n].dataSources.[n].path` ()
`lastModified`	文档最后修改的日期和时间。

您无法使用 Atlas 用户界面中的可视化编辑器来配置此设置。

databases.[n].collections.[n].dataSources.[n].omitAttributes

布尔

可选

指定是否省略 Atlas Data Federation 添加到集合中的文档的属性（键和值对）的标志。您可以指定以下值之一：

false - 要添加属性
true - 省略这些属性

如果省略，则默认为 false，Atlas Data Federation 会添加属性。

例如：

考虑一个名为 /employees/949-555-0195.json 的文件，为其配置 path /employees/{phone string}。如果 omitAttributes 为false，Atlas Data Federation 会将属性 phone: 949-555-0195 添加到此文件中的文档，无论文档中是否已存在键值对。如果将 omitAttributes 设置为 true，则 Atlas Data Federation 不会将属性添加到虚拟集合中的文档。

databases.[n].maxWildcardCollections

整型

可选

可选。数据库中通配符 * 集合的最大数量。每个通配符集合只能有一个数据源。值可以在 1 到 1000 之间（含）。如果省略，默认为 100。

databases.[n].views

阵列

可选

对象数组，其中的每个对象代表一个集合上的一个聚合管道。要了解有关视图的更多信息，请参阅视图。

databases.[n].views.[n].name

字符串

必需

视图名称。

databases.[n].views.[n].source

字符串

必需

视图源集合的名称。如果要创建带有$sql阶段的视图，则必须省略此字段，因为SQL声明将指定源集合。

databases.[n].views.[n].pipeline

阵列

可选

应用于 source 集合的聚合管道阶段数组。您还可以使用 $sql 阶段来创建视图。

S3 数据存储配置示例

例子

假设某个 S3 存储桶 datacenter-alpha 包含从数据中心收集的数据：

|--metrics
|--hardware

/metrics/hardware 路径存储 JSON 文件，其中包含源自数据中心硬件的指标，每个文件名是该文件所涵盖的 24 小时周期的 UNIX 时间戳（毫秒）：

/hardware/1564671291998.json

配置如下：

对 us-east-1 AWS 地区的 datacenter-alpha S3 存储桶定义一个联合数据库实例存储。该联合数据库实例存储被明确限制为仅包含 metrics 文件夹路径中的数据文件。
将 hardware 文件夹中的文件映射到 MongoDB 数据库 datacenter-alpha-metrics 和集合 hardware。配置映射包括用于收集文件名中隐含的时间戳的解析逻辑。

{
  "stores" : [
    {
      "name" : "datacenter-alpha",
      "provider" : "s3",
      "region" : "us-east-1",
      "bucket" : "datacenter-alpha",
      "additionalStorageClasses" : [
        "STANDARD_IA"
      ],
      "prefix" : "/metrics",
      "delimiter" : "/"
    }
  ],
  "databases" : [
    {
      "name" : "datacenter-alpha-metrics",
      "collections" : [
        {
          "name" : "hardware",
          "dataSources" : [
            {
              "storeName" : "datacenter-alpha",
              "path" : "/hardware/{date date}"
            }
          ]
        }
      ]
    }
  ]
}

Atlas Data Federation 解析 S3 存储桶 datacenter-alpha，并处理 /metrics/hardware/ 下的所有文件。collections 使用路径解析语法将文件名映射到每个文档中的 date 字段，即 ISO-8601 日期。如果文档中不存在匹配的 date 字段，则会添加该字段。

连接到联合数据库实例的用户可以使用 MongoDB 查询语言和支持的聚合通过 datacenter-alpha-metrics.hardware 集合分析 AWS S3 存储桶中的数据。

提示

查询 S3 上的数据

提示

教程：联合查询和 S3 的 $out

后退

定义数据存储

来年

部署

1	{
2	"stores" : [
3	{
4	"name" : "<string>",
5	"provider": "<string>",
6	"region" : "<string>",
7	"bucket" : "<string>",
8	"additionalStorageClasses" : ["<string>"],
9	"prefix" : "<string>",
10	"includeTags": <boolean>,
11	"delimiter": "<string>",
12	"public": <boolean>
13	}
14	],
15	"databases" : [
16	{
17	"name" : "<string>",
18	"collections" : [
19	{
20	"name" : "<string>",
21	"dataSources" : [
22	{
23	"storeName" : "<string>",
24	"path" : "<string>",
25	"defaultFormat" : "<string>",
26	"provenanceFieldName": "<string>",
27	"omitAttributes": true \| false
28	}
29	]
30	}
31	],
32	"maxWildcardCollections" : <integer>,
33	"views" : [
34	{
35	"name" : "<string>",
36	"source" : "<string>",
37	"pipeline" : "<string>"
38	}
39	]
40	}
41	]
42	}

1	"stores" : [
2	{
3	"name" : "<string>",
4	"provider" : "<string>",
5	"region" : "<string>",
6	"bucket" : "<string>",
7	"additionalStorageClasses" : ["<string>"],
8	"prefix" : "<string>",
9	"delimiter" : "<string>",
10	"includeTags": <boolean>,
11	"public": <boolean>
12	}
13	]