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構成には、とのstoresdatabases 2 つの最上位オブジェクトが含まれています。

`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`	string	必須	フェデレーティッドデータベースインスタンスストアの名前。`databases.[n].collections.[n].dataSources.[n].storeName`フィールドは、マッピング構成の一部としてこの値を参照します。
`stores.[n].provider`	string	必須	データを保存する場所を定義します。AWS S3 バケットの場合、値は`s3` である必要があります。
`stores.[n].region`	string	必須	AWS S3 バケットがホストされているAWSリージョンの名前。有効なリージョン名のリストについては、「 Amazon Web Services （AWS）」を参照してください。
`stores.[n].bucket`	string	必須	AWS S3 バケットの名前。構成されたAWS IAM 認証情報を使用して Atlas Data Federation がアクセスできるAWS S バケットの名前と完全に一致する必要があります。3
`stores.[n].additionalStorageClasses`	配列	任意	Amazon Web Services S3 ストレージクラスの配列。Atlas Data Federation は、これらのストレージクラスのファイルをクエリ結果に含めます。有効な値は以下のとおりです。 `INTELLIGENT_TIERING` : インテリジェント階層化ストレージクラスにファイルを含めます。 `STANDARD_IA` : 標準～低頻度のアクセスストレージクラスのファイルを含めます。重要: 標準ストレージクラス内のファイルはデフォルトでサポートされています。
`stores.[n].prefix`	string	任意	AWS S3 バケット内のファイルのパスを検索するためにプレフィックスを追加します。 Atlas Data Federation は、の値を`prefix` `databases.[n].collections.[n].dataSources.[n].path`の先頭に追加して、取り込むファイルの完全なパスを作成します。省略した場合、Atlas Data Federation はAWS S3 バケットのルートからすべてのファイルを検索します。
`stores.[n].delimiter`	string	任意	フェデレーティッドデータベースインスタンスインスタンス内のパスセグメントを区切る区切り文字を設定します。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 S3 バケットにアクセスするために、設定されたAWS IAM ロールを使用しません。`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

string

必須

Atlas Data Federation がデータストアに含まれるデータをマッピングするデータベースの名前。

databases.[n].collections

配列

必須

各オブジェクトが stores フェデレーティッドデータベースインスタンスストアにマッピングするコレクションとデータソースを表すオブジェクトの配列。

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

string

必須

Atlas Data Federation が各 databases.[n].collections.[n].dataSources.[n].storeName に含まれるデータをマッピングするコレクションの名前。配列内の各オブジェクトは、コレクションと stores 配列内のオブジェクトとの間のマッピングを表します。

コレクション名に* を指定し、フィールドにcollectionName() path関数を指定することで、ファイルパスからコレクション名を動的に生成できます。例については、「ファイルパスからの動的コレクション名の生成」を参照してください。

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

配列

必須

各オブジェクトがコレクションでマッピングするstoresフェデレーティッドデータベースインスタンスストアを表すオブジェクトの配列。

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

string

必須

<collection> にマッピングするフェデレーティッドデータベースインスタンスストアの名前。namestores配列内のオブジェクトのと一致する必要があります。

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

string

必須

Atlas Data FederationstoreName <collection>stores.[n].prefixpathが/ 内のファイルを検索して解析し、その後にファイルをにマッピングする方法を制御します。フェデレーティッドデータベースインスタンスは、の先頭にを付加して、検索するための完全パスを構築します。パスからすべてのファイルとフォルダーを取得するには、prefix を指定します。

以下の構造を持つ S3 バケット metrics を例に考えてみましょう。

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

path が / の場合、Atlas Data Federation は metrics バケット内のすべてのファイルとフォルダーを検索します。

path が/hardware の場合、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

databases.[n].collections.[n].dataSources.[n].storeName を検索中に拡張子のないファイルを検出した場合に Atlas Data Federation が想定するデフォルトの形式。

defaultFormat フィールドでは、次の値が有効です。

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

重要:ファイル形式が CSVまたはTSV の場合、データにヘッダー行を含める必要があります。詳細については、「 CSV およびTSV 」を参照してください。

省略した場合、Atlas Data Federation はファイルの数バイトを処理することでファイルタイプの検出を試みます。

Tip

サポートされているデータ形式

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

string

任意

結果にドキュメントの出所が含まれるフィールドの名前。ストレージ構成でこの設定を指定すると、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 UI のビジュアルエディターを使用してこの設定を構成することはできません。

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} という名前のファイルを考えてみましょう。 Atlas Data Federationphone: 949-555-0195 omitAttributesは、がfalse の場合、キーと値のペアがドキュメントに既に存在するかどうかにかかわらず、このファイル内のドキュメントに属性を追加します。をomitAttributes trueに設定すると、Atlas Data Federation は仮想コレクション内のドキュメントにこの属性を追加しません。

databases.[n].maxWildcardCollections

integer

任意

任意。データベース内のワイルドカード * コレクションの最大数。各ワイルドカードコレクションには、データソースを 1 つだけ含めることができます。値は、両端を含む 1 から 1000 までです。省略した場合、デフォルトは 100 になります。

databases.[n].views

配列

任意

各オブジェクトがコレクション上の集計パイプラインを表すオブジェクトの配列。ビューの詳細については、「ビュー」を参照してください。

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

string

必須

ビューの名前。

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

string

必須

ビューのソースコレクションの名前。$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クエリ言語とサポートされている集計を使用し、コレクションを通じてAWS S3 datacenter-alpha-metrics.hardwareバケット内のデータを分析できます。

Tip

S3 でのデータのクエリ

Tip

チュートリアル: フェデレーティッドクエリと 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	]