/ /

/ /

定义 S3 数据的路径

Overview

当您查询 S 3存储桶中的文档时， Atlas Data Federation path值允许Data Federation将文档内的数据映射到文档的文档名。

path支持将S 3存储桶中的文件名解析为计算字段。 Data Federation可以将计算字段添加到从已解析文件生成的每个文档中。 Data Federation可以将对这些计算字段值的查询仅定位到具有匹配文件名的文件。有关更多信息，请参阅支持的解析函数和示例。

path 还支持使用文件路径中的分区属性创建分区。 Data Federation可以将针对分区属性中定义的参数的查询定位到仅在文件名或分区前缀中包含查询的文件。

例子

考虑S3存储桶中的以下文件：

/users/26/1234.json
/users/26/5678.json

JSON文档1234.json包含以下内容：

{
  "name": "jane doe",
  "age": 26,
  "userID": "1234"
}

S3存储桶中文件的联合数据库实例配置定义了以下path ：

"path": "/users/{age int}/{userID string}"

下面显示了Data Federation如何将查询映射到根据path定义创建的分区：

db.users.findOne(                /users
  {                                /40
    "age": 26 ----------------->   /26
    "userID": "1234" ---------->     /1234.json
  }                                  /5678.json
)

如果分区属性的计算字段已存在于文档中，Data Federation 会将您的查询映射到相应的文件。如果计算字段不存在，Data Federation 会将计算字段添加到文档中。例如，如果1234.json中不存在age字段，Data Federation 会将age字段和值添加到1234.json中。

支持的解析函数

您可以对文件名指定单个解析函数。

/path/to/files/{<fieldA> <data-type>}

您可以对文件名指定多个解析函数。

/path/to/files/{<fieldA> <data-type>}-{<fieldB> <data-type>}

您可以在文件名中指定静态字符串的同时指定解析函数：

/path/to/files/prefix-{<fieldA> <data-type>}-suffix

您可以指定点（即 . ）沿路径添加到文件名。

/path/to/files/{<fieldA>.<fieldB> <data-type>}

您可以在创建分区的文件路径中指定ObjectIds 。

/path/to/files/{objid objectid}

您可以在文件路径中指定ObjectIds范围以创建分区。

/path/to/files/{min(obj) objectid}-{max(obj) objectid}

您可以沿文件名的路径指定解析函数。

/path/{<fieldA> <data-type>}/{<fieldB> <data-type>}/{<fieldC> <data-type>}/*

您可以沿文件名的路径指定ISODate的正则表达式。

/path/to/files/{<field-name> isodate("<date-format>"):\\<regex>}

注意

指定 path 时：

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

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

在属性之间添加常量分隔符。
使用正则表达式描述搜索模式。要学习；了解详情，请参阅不支持的解析函数。

从文件名中解析空值

对于除string之外的所有 Atlas Data Federation 属性类型，Data Federation 会自动将文件路径中属性的空字符串 ( "" ) 解析为 BSON null 值。使用string时，空字符串可以表示 BSON null 值或 BSON 空字符串值。 Atlas Data Federation 不会解析string属性类型的任何 BSON 值。这样可以避免向从S3读取的文档添加类型冲突的 BSON 值。

例子

请考虑以下S3联合数据库实例存储：

/records/january/1.json
/records/february/1.json
/records//1.json
For the path ``/records/{month string}/*``, Data Federation does not add any
computed fields for the ``month`` attribute to documents generated
from the third record in the above store.

注意

将文件写入S3时，将所有 Atlas Data Federation 属性类型的BSON null 值作为空字符串写入文件名中。

从文件名中解析填充的数字

文件路径可以包含用前导零填充的数值。为了使 Data Federation 正确解析int 、 epoch_millis和epoch_secs等属性类型的填充数值，请使用正则表达式指定值中的位数。

例子

考虑包含以下文件的S3存储：

|--users
   |--001.json
   |--002.json
   ...

以下path语法使用正则表达式来指定文件名中的位数。 Data Federation标识路径中与分区属性对应的部分，然后将该分区属性映射到类型int ：

/users/{user_id int:\\d{3}}

不支持的解析函数

对同一文件名指定连续的解析函数而无法区分它们可能会导致结果不一致。

例子

考虑包含以下文件的S3存储：

|--food
   |--icecream
   |--peanutbutter

现在考虑food目录中文件的以下路径：

/food/{first string}{second string}/

无法确定文件名子字符串的哪一部分应与 first 与 second string属性匹配。因此， Atlas Data Federation将所有内容都与first进行匹配。

请考虑改用带有正则表达式的属性，类似于以下内容：

```
/food/{first string:\\D{3}}{second string:\\D{5}}
```
前面的路径指定first匹配3个非数字字符， second匹配接下来的5非数字字符。
```
/food/{first string:[A-Z]{3}}{second string:[a-z]{5}}
```
前面的路径匹配first到3个大写字母和second到5个小写字母。

示例

以下示例演示了如何将文件名解析为计算字段：

从文件名中解析单个字段
从文件名中解析多个字段
使用正则表达式解析文件名中的字段
从文件名中识别可查询数据的范围
从文件名中识别嵌套字段
从 ObjectId 创建分区
从文件路径创建分区
从ISODate创建分区
从文件路径生成动态集合名称

从文件名中解析单个字段

考虑一个联合数据库实例存储accountingArchive ，其中包含文件名描述发票日期的文件。例如，文件名/invoices/1564671291998.json包含 UNIX 时间戳1564671291998的发票。

以下databases对象通过将文件名解析为 UNIX 时间戳来生成字段invoiceDate ：

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceDate epoch_millis}"
          }
        ]
      }
    ]
  }
]

Data Federation将计算字段和值添加到从文件名生成的每个文档中。从示例文件生成的文档包含字段invoiceDate: ISODate("2019-08-01T14:54:51Z") 。对invoiceDate字段的查询只能定位到与指定值匹配的文件。

从文件名中解析多个字段

考虑一个联合数据库实例存储accountingArchive ，其中包含文件名描述发票号码和发票日期的文件。例如，文件名/invoices/MONGO12345-1564671291998.json 包含MONGODB12345 UNIX 时间戳的发票1564671291998 。

以下databases对象会生成：

字段invoiceNumber，将文件名的第一段解析为string 。
字段invoiceDate ，将文件名的第二段解析为 UNIX 时间戳。

"databases" : [
  {
    "name": "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceNumber string}-{invoiceDate epoch_millis}"
          }
        ]
      }
    ]
  }
]

Data Federation将计算字段和值添加到从文件名生成的每个文档中。从示例文件名生成的文档包括以下字段：

invoiceNumber : "MONGODB12345"
invoiceDate : ISODate("2019-08-01T14:54:51Z")

同时包含invoiceNumber和invoiceDate字段的查询只能定位到与指定值匹配的文件。

使用正则表达式解析文件名中的字段

考虑一个联合数据库实例存储accountingArchive ，其中包含文件名描述发票号码和发票日期的文件。 /invoices/MONGODB12345-20190102.json示例，文件名MONGODB12345 包含日期的发票20190102 。

以下databases对象会生成：

字段invoiceNumber，将文件名的第一段解析为string
字段year ，使用正则表达式仅将文件名第二段的前4位解析为整数。
字段month ，使用正则表达式仅将文件名第二段的接下来的2位解析为整数。
字段day ，使用正则表达式仅将文件名第二段的接下来的2位解析为整数。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceNumber string}-{year int:\\d{4}}{month int:\\d{2}}{day int:\\d{2}}"
          }
        ]
      }
    ]
  }
]

Data Federation将计算字段和值添加到从文件名生成的每个文档中。从示例文件名生成的文档包括以下字段：

invoiceNumber : "MONGODB12345"
year : 2019
month: 01
day: 02

重要

您必须对 path 中指定的正则表达式字符串进行转义。示例，如果正则表达式字符串包含双引号，则必须对这些值进行转义。 Data Federation支持存储配置中正则表达式的包事务语法。

包含所有生成字段的查询只能定位到与指定值匹配的文件。

提示

从文件名中解析填充的数字

从文件名中识别可查询数据的范围

考虑一个联合数据库实例存储accountingArchive ，其中包含一些文件，这些文件的文件名描述了文件中包含的数据范围。例如，文件名/invoices/1546367712000-1549046112000.json包含 2019 年 1 月 1 日到 2019 年 1 月 2 日期间的发票，日期范围表示为自 UNIX 纪元以来经过的毫秒数。

以下databases对象将最小时间范围标识为文件名的第一段，并将最大时间范围标识为文件名的第二段：

"databases" : [
  {
    "name: "accounting",
    "collections" : [
      {
        "name: "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{min(invoiceDate) epoch_millis}-{max(invoiceDate) epoch_millis}"
          }
        ]
      }
    ]
  }
]

当Data Federation收到对"invoiceDate"字段的查询时，它会使用指定的路径来识别哪些文件包含与查询匹配的数据。

对invoiceDate字段的查询只能定位到范围捕获指定值的文件，包括min和max日期。

重要

为最小和最大范围指定的字段必须存在于文件中包含的每个文档中，以避免意外或不需要的行为。 Data Federation不会验证根本的数据是否符合此约束。

提示

从文件名中解析填充的数字

从文件名中识别嵌套字段

当嵌套数据值也是文件名时， Data Federation支持查询嵌套数据。您可以使用点操作符（即 . ）在path中将存储配置中的分区属性映射到文档中的嵌套字段。

以联合数据库实例存储accountingArchive为例。联合数据库实例存储包含名称与文档中的嵌套字段值匹配的文件。示例：

accountingArchive
|--invoices
   |--January.json
   |--February.json
   ...

假设January.json文件包含一个具有以下字段的文档：

{
  "invoice": {
     "invoiceNumber" : "MONGODB12345",
     "year" : 2019,
     "month": "January", //value matches filename
     "date": 02
  },
  "vendor": "MONGODB",
  ...
}

以下databases对象将month标识为文档内的嵌套字段。 databases对象还将month的值标识为包含该文档的文件的名称。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoice.month string}"
          }
        ]
      }
    ]
  }
]

当 Atlas Data Federation 收到针对特定月份的查询（例如January时，它会使用指定的路径来识别哪个文件包含与查询匹配的数据。

从 ObjectId 创建分区

您可以在文件路径中指定ObjectId 。对于文件名中包含ObjectId的文件， Atlas Data Federation会为每个ObjectId创建分区。

请考虑以下联合数据库实例存储accountingArchive 。此数据存储包含文件名中包含ObjectId的文件：

accountingArchive
|--invoices
   |--507f1f77bcf86cd799439011.json
   |--507f1f77bcf86cd799439012.json
   |--507f1f77bcf86cd799439013.json
   |--507f1f77bcf86cd799439014.json
   |--507f1f77bcf86cd799439015.json

以下databases对象为ObjectIds创建分区。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{objid objectid}"
          }
        ]
      }
    ]
  }
]

或者，假设联合数据库实例存储accountingArchive包含文件名中包含ObjectIds范围的文件。示例：

accountingArchive
|--invoices
   |--507f1f77bcf86cd799439011-507f1f77bcf86cd799439020.json
   |--507f1f77bcf86cd799439021-507f1f77bcf86cd799439030.json
   |--507f1f77bcf86cd799439031-507f1f77bcf86cd799439040.json

以下databases对象为给定范围的ObjectIds创建分区。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{min(obj) objectid}-{max(obj) objectid}"
          }
        ]
      }
    ]
  }
]

当Data Federation收到对ObjectId的查询时，它会使用指定的路径来识别哪个文件包含与查询匹配的数据。

从文件路径创建分区

您可以在通向该文件名的任何路径上指定解析函数。每个计算字段都基于路径上的解析函数。查询数据时，Atlas Data Federation 会将每个计算字段转换为分区。然后，使用与子目录同义的分区以越来越高的精度筛选文件。

考虑具有以下目录结构的联合数据库实例存储 accountingArchive：

invoices
|--MONGO12345
   |--2019
      |--01
         |--02

以下databases对象使用一小组已筛选文件创建invoiceNumber 、 year 、 month和day分区：

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{invoiceNumber string}/{year int}/{month int:\\d{2}}/{day int:\\d{2}}/*"
          }
        ]
      }
    ]
  }
}

提示

从文件名中解析填充的数字

从ISODate创建分区

您可以在文件路径中指定ISODate 。对于文件名中包含ISODate的文件， Atlas Data Federation会为每个ISODate创建分区。

请考虑以下联合数据库实例存储accountingArchive 。此数据存储包含文件名中包含ISODate的文件：

accountingArchive
|--invoices
   |--01_02_2022_2301.json
   |--02_02_2022_2301.json
   |--03_02_2022_2301.json
   |--04_02_2022_2301.json
   |--05_02_2022_2301.json

以下databases对象为 ISODate 创建分区。path 演示了如果日期不是 RFC 3339 格式，如何使用正则表达式设置日期格式。

"databases" : [
  {
    "name" : "accounting",
    "collections" : [
      {
        "name" : "invoices",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/creationDate isodate('01_02_2006_1504'):\\d{2}_\\d{2}_\\d{4}_\\d{4}.json"
          }
        ]
      }
    ]
  }
]

要学习；了解有关其他支持格式的更多信息，请参阅使用分区属性类型。

从文件路径生成动态集合名称

考虑具有以下目录结构的联合数据库实例存储 accountingArchive：

invoices
|--SuperSoftware
|--UltraSoftware
|--MegaSoftware

以下databases对象根据文件路径生成动态集合名称：

"databases" : [
  {
    "name" : "invoices",
    "collections" : [
      {
        "name" : "*",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/invoices/{collectionName()}/"
          }
        ]
      }
    ]
  }
]

当应用于示例目录结构时，该路径会产生以下集合：

SuperSoftware
UltraSoftware
兆软件

或者，考虑具有以下文件的联合数据库实例存储accountingArchive ：

/orders/MONGODB/invoices/January.json
/orders/MONGODB/purchaseOrders/January.json
/orders/MONGODB/invoices/February.json
...

以下databases对象根据文件路径生成动态集合名称：

"databases" : [
  {
    "name" : "invoices",
    "collections" : [
      {
        "name" : "*",
        "dataSources" : [
          {
            "storeName" : "accountingArchive",
            "path" : "/orders/MONGODB/{collectionName()}/{invoiceMonth string}.json/"
          }
        ]
      }
    ]
  }
]

当应用于示例文件名时，该路径将产生以下集合：

invoices
purchaseOrders

注意

当您从文件名动态生成集合时， Data Federation视图不会准确报告集合的数量。

后退

生成集合

来年

优化查询