/ /

AWS S3 バケット

Overview

Atlas Data Federation は、 AWS S3 バケットをフェデレーティッドデータベースインスタンスの保存としてサポートします。データに対してクエリを実行するには、フェデレーティッドデータベースインスタンスで AWS S3 バケットへのマッピングを定義する必要があります。

構成ファイル形式

AWS S3 バケット用のフェデレーティッドデータベースインスタンスストアを定義するには、JSON で構成パラメータを指定できます。構成には AWS データストアが含まれており、それをクエリ可能な仮想コレクションにマッピングします。

JSON 設定は、AWS S3 バケット内のデータに対して、以下のフィールドを使用します。

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	必須	AWSS3 バケットがホストされているAWS リージョンの名前。有効なリージョン名のリストについては、Amazon Web Services（AWS）を参照してください。
`stores.[n].bucket`	string	必須	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`	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 配列内のオブジェクトとの間のマッピングを表します。

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

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 Federation が storeName のファイルを <collection> にマッピングする前に、それらのファイルを検索して解析する方法を制御します。フェデレーティッドデータベースインスタンスは、path の先頭に stores.[n].prefix を追加して、検索するための完全パスを構築します。/ を指定して、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 は属性を追加します。

以下に例を挙げます。

path /employees/{phone string} を構成する /employees/949-555-0195.json という名前のファイルを考えてみます。Atlas Data Federation は、omitAttributes が false の場合、キーと値のペアがドキュメントにすでに存在するかどうかにかかわらず、このファイルのドキュメントに属性 phone: 949-555-0195 を追加します。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 クエリ言語とサポートされている集計を使用し、datacenter-alpha-metrics.hardware コレクションを通して AWS S3 バケット内のデータを分析できます。

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	]