Amazon S3 へのアクセスを Aurora に許可するデータをロードするための権限の付与 Amazon S3 バケットへのパスの指定 LOAD DATA FROM S3 LOAD XML FROM S3 関連トピック

Amazon S3 バケットのテキストファイルから Amazon Aurora MySQL DB クラスターへのデータのロード

LOAD DATA FROM S3 または LOAD XML FROM S3 ステートメントを使用して、Amazon S3 バケットに保存されているファイルからデータをロードできます。

注記

Amazon S3 バケットのテキストファイルからテーブルへのデータのロードは、Amazon Aurora MySQL バージョン 1.8 以降で可能です。Aurora MySQL のバージョンの詳細については、「Amazon Aurora MySQL のデータベースエンジンの更新」を参照してください。

この機能は現在、Aurora Serverless クラスターでは使用できません。

Amazon S3 へのアクセスを Aurora に許可する

Amazon S3 バケットからデータをロードする前に、まず Amazon S3 へのアクセス権限を Aurora MySQL DB クラスターに付与する必要があります。

Amazon S3 へのアクセス権限を Aurora MySQL に付与するには

バケットおよびオブジェクトのアクセス許可を付与し、Aurora MySQL DB クラスターから Amazon S3 へのアクセスを許可する AWS Identity and Access Management (IAM) ポリシーを作成します。手順については、「Amazon S3 リソースにアクセスするための IAM ポリシーの作成」を参照してください。
IAM ロールを作成して、「Amazon S3 リソースにアクセスするための IAM ポリシーの作成」で作成した IAM ポリシーを新しい IAM ロールにアタッチします。手順については、「Amazon Aurora が AWS のサービスにアクセスすることを許可する IAM ロールの作成」を参照してください。
DB クラスターがカスタム DB クラスターパラメータグループを使用していることを確認します。

カスタム DB クラスターパラメータグループの作成の詳細については、「DB クラスターのパラメータグループの作成」を参照してください。
DB クラスターの aurora_load_from_s3_role パラメータまたは aws_default_s3_role パラメータを、新しい IAM ロールの Amazon リソースネーム (ARN) に設定します。IAM ロールが aurora_load_from_s3_role に指定されていない場合、Aurora は aws_default_s3_role に指定されている IAM ロールを使用します。

クラスターが Aurora グローバルデータベースの一部である場合は、このパラメータをグローバルデータベース内の Aurora クラスターごとに設定します。Aurora グローバルデータベース内のプライマリクラスターのみがデータをロードできますが、フェイルオーバー機構によって別のクラスターが昇格されてプライマリクラスターになる場合があります。

DB クラスターのパラメータの詳細については、「Amazon Aurora の DB クラスターパラメータと DB インスタンスパラメータ」を参照してください。
Aurora MySQL DB クラスター内のデータベースユーザーが Amazon S3 にアクセスできるように、「Amazon Aurora が AWS のサービスにアクセスすることを許可する IAM ロールの作成」で作成したロールをその DB クラスターに関連付けます。Aurora グローバルデータベースの場合は、グローバルデータベース内の Aurora クラスターごとにロールを関連付けます。DB クラスターへの IAM ロールの関連付けの詳細については、「IAM ロールと Amazon Aurora MySQL DB クラスターの関連付け」を参照してください。
Amazon S3 へのアウトバウンド接続を許可するように Aurora MySQL DB クラスターを設定します。手順については、「Amazon Aurora MySQL から他の AWS のサービスへのネットワーク通信の有効化」を参照してください。

Aurora グローバルデータベースの場合は、グローバルデータベース内の Aurora クラスターごとにアウトバウンド接続を有効にします。

Amazon Aurora MySQL でデータをロードするための権限の付与

LOAD DATA FROM S3 ステートメントまたは LOAD XML FROM S3 ステートメントを発行するデータベースユーザーに対しては、このいずれかのステートメントを発行するための LOAD FROM S3 権限を付与する必要があります。DB クラスターのマスターユーザー名にはデフォルトで LOAD FROM S3 権限が付与されます。他のユーザーに権限を付与するには、次のコマンドを使用できます。


GRANT LOAD FROM S3 ON *.* TO 'user'@'domain-or-ip-address'

LOAD FROM S3 権限は Amazon Aurora に固有であり、MySQL データベースまたは RDS for MySQL DB インスタンスでは使用できません。Aurora DB クラスターをレプリケーションマスターとし、MySQL データベースをレプリケーションクライアントとして両者間にレプリケーションを設定すると、GRANT LOAD FROM S3 ステートメントはエラーとなり、レプリケーションが停止します。エラーをスキップして、レプリケートを再開できます。RDS for MySQL DB インスタンスでエラーをスキップするには、 mysql_rds_skip_repl_error プロシージャを使用します。外部 MySQL データベースでエラーをスキップするには、SET GLOBAL sql_slave_skip_counter ステートメントを使用します。

Amazon S3 バケットへのパスの指定

Amazon S3 バケットに保存されているファイルへのパスを指定する構文は次のとおりです。


s3-region://bucket-name/file-name-or-prefix

パスに指定する値は以下のとおりです。

region (オプション) – ロード元の Amazon S3 バケットがある AWS リージョン。この値はオプションです。region 値を指定しないと、Aurora は DB クラスターと同じリージョンの Amazon S3 からファイルをロードします。
bucket-name – ロードするデータが含まれている Amazon S3 バケットの名前。仮想フォルダのパスを識別するオブジェクトプレフィックスがサポートされています。
file-name-or-prefix – Amazon S3 テキストファイルまたは XML ファイルの名前、あるいはロードする 1 つ以上のテキストファイルまたは XML ファイルを識別するプレフィックス。ロードするテキストファイルを識別するマニフェストファイルを指定することもできます。マニフェストファイルを使用して Amazon S3 からテキストファイルをロードする方法の詳細については、「マニフェストを使用して、ロードするデータファイルを指定する」を参照してください。

LOAD DATA FROM S3

LOAD DATA FROM S3 ステートメントを使用して MySQL LOAD DATA INFILE ステートメントでサポートされている任意のテキストファイル形式 (カンマ区切りのテキストデータなど) からデータをロードできます。圧縮ファイルはサポートされていません。

Syntax


LOAD DATA FROM S3 [FILE | PREFIX | MANIFEST] 'S3-URI'
    [REPLACE | IGNORE]
    INTO TABLE tbl_name
    [PARTITION (partition_name,...)]
    [CHARACTER SET charset_name]
    [{FIELDS | COLUMNS}
        [TERMINATED BY 'string']
        [[OPTIONALLY] ENCLOSED BY 'char']
        [ESCAPED BY 'char']
    ]
    [LINES
        [STARTING BY 'string']
        [TERMINATED BY 'string']
    ]
    [IGNORE number {LINES | ROWS}]
    [(col_name_or_user_var,...)]
    [SET col_name = expr,...]

Parameters

以下に、LOAD DATA FROM S3 ステートメントで使用される必須およびオプションのパラメータのリストを示します。以下のパラメータの一部については、MySQL ドキュメントの「LOAD DATA INFILE 構文」に詳しい説明があります。

FILE | PREFIX | MANIFEST – データを読み取るのが、1 つのファイルからか、特定のプレフィックスに一致するすべてのファイルからか、特定のマニフェスト内のすべてのファイルからかを指定します。デフォルトは FILE です。
S3-URI – ロードするテキストファイルまたはマニフェストファイルの URI か、使用する Amazon S3 プレフィックスを指定します。「Amazon S3 バケットへのパスの指定」で説明されている構文を使用して URI を指定します。
REPLACE | IGNORE – 入力行とデータベーステーブルの既存の行で一意のキー値が同じである場合、どのアクションを実行するかを決定します。
- テーブル内の既存の行を入力行で置き換える場合は、REPLACE を指定します。
- 入力行を破棄する場合は、IGNORE を指定します。
INTO TABLE – 入力行をロードする先のデータベーステーブルの名前を指定します。
PARTITION – すべての入力行を、指定されたカンマ区切りのパーティション名のリストに記載されているパーティション内に挿入することを要求します。指定されたパーティションのいずれかに入力行を挿入できない場合、ステートメントは失敗し、エラーが返されます。
CHARACTER SET – 入力ファイルのデータの文字セットを指定します。
FIELDS | COLUMNS – 入力ファイルのフィールドまたは列を区切る方法を指定します。デフォルトでは、フィールドはタブで区切られます。
LINES – 入力ファイルの行を区切る方法を指定します。デフォルトでは、行は改行文字 ('\n') で区切られます。
IGNORE number LINES | ROWS – 入力ファイルの先頭で特定の行数を無視することを指定します。例えば、IGNORE 1 LINES では列名を含む最初のヘッダー行がスキップされます。IGNORE 2 ROWS では、入力ファイルの先頭から 2 行のデータがスキップされます。また、PREFIX を使用すると、IGNORE は最初の入力ファイルの先頭にある特定の行数または行をスキップします。
col_name_or_user_var, ... – 1 つ以上の列名またはユーザー変数のカンマ区切りのリストにより、ロードする列を名前で指定します。この目的で使用されるユーザー変数の名前は、プレフィックスを @ とするテキストファイルの要素名と一致する必要があります。フィールド値を対応するユーザー変数に保存して後で再利用できます。

例えば、次のステートメントでは、入力ファイルの最初の列を table1 の最初の列内にロードし、さらに table_column2 の table1 列の値として、2 列目の入力値を 100 で割った値を設定します。
```
LOAD DATA FROM S3 's3://mybucket/data.txt'
    INTO TABLE table1
    (column1, @var1)
    SET table_column2 = @var1/100;
```
SET – 割り当てオペレーションのカンマ区切りのリストにより、テーブル内の列の値を入力ファイルに含まれていない値に設定します。

例えば、次のステートメントは table1 の最初の 2 列を入力ファイルの最初の 2 列の値に設定し、さらに column3 の table1 の値を現在のタイムスタンプに設定します。
```
LOAD DATA FROM S3  's3://mybucket/data.txt'
    INTO TABLE table1
    (column1, column2)
    SET column3 = CURRENT_TIMESTAMP;
```
SET 割り当ての右側のサブクエリを使用できます。列に割り当てる値を返すサブクエリとしては、スカラーサブクエリのみ使用できます。また、サブクエリを使用してロード中のテーブルから選択することはできません。

Amazon S3 バケットからデータをロードしている場合、LOCAL ステートメントの LOAD DATA FROM S3 キーワードは使用できません。

マニフェストを使用して、ロードするデータファイルを指定する

LOAD DATA FROM S3 ステートメントの MANIFEST キーワードで、JSON 形式のマニフェストファイルを指定して、DB クラスターのテーブルにロードするテキストファイルをリストできます。MANIFEST ステートメントで LOAD DATA FROM S3 キーワードを使用するには、Aurora 1.11 以上を使用している必要があります。

次の JSON スキーマはマニフェストファイルの形式と内容を示しています。


{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "additionalProperties": false,
    "definitions": {},
    "id": "Aurora_LoadFromS3_Manifest",
    "properties": {
        "entries": {
            "additionalItems": false,
            "id": "/properties/entries",
            "items": {
                "additionalProperties": false,
                "id": "/properties/entries/items",
                "properties": {
                    "mandatory": {
                        "default": "false"
                        "id": "/properties/entries/items/properties/mandatory",
                        "type": "boolean"
                    },
                    "url": {
                        "id": "/properties/entries/items/properties/url",
                        "maxLength": 1024,
                        "minLength": 1,
                        "type": "string"
                    }
                },
                "required": [
                    "url"
                ],
                "type": "object"
            },
            "type": "array",
            "uniqueItems": true
        }
    },
    "required": [
        "entries"
    ],
    "type": "object"
}

マニフェスト内の各 url では、プレフィックスだけでなく、バケットの名前とファイルの完全なオブジェクトパスを使用して URL を指定する必要があります。マニフェストを使用し、異なるバケットやリージョンからファイルをロードしたり、同じプレフィックスを共有しないファイルをロードしたりできます。URL にリージョンを指定していない場合は、ターゲットの Aurora DB クラスターのリージョンが使用されます。以下の例では、異なるバケットから 4 つのファイルをロードするマニフェストファイルを示しています。


{
  "entries": [
    {
      "url":"s3://aurora-bucket/2013-10-04-customerdata", 
      "mandatory":true
    },
    {
      "url":"s3-us-west-2://aurora-bucket-usw2/2013-10-05-customerdata",
      "mandatory":true
    },
    {
      "url":"s3://aurora-bucket/2013-10-04-customerdata", 
      "mandatory":false
    },
    {
      "url":"s3://aurora-bucket/2013-10-05-customerdata"
    }
  ]
}

ファイルが見つからない場合に、オプションの mandatory フラグによってコマンドがエラーを返すかどうかを指定します。LOAD DATA FROM S3mandatory フラグはデフォルトで false に設定されています。mandatory の設定方法にかかわらず、ファイルが見つからない場合、LOAD DATA FROM S3 は終了します。

マニフェストファイルには、任意の拡張子を付けることができます。次の例では、前の例にあった「LOAD DATA FROM S3」という名前のマニフェストで customer.manifest ステートメントを実行しています。


LOAD DATA FROM S3 MANIFEST 's3-us-west-2://aurora-bucket/customer.manifest'
    INTO TABLE CUSTOMER
    FIELDS TERMINATED BY ','
    LINES TERMINATED BY '\n'
    (ID, FIRSTNAME, LASTNAME, EMAIL);

ステートメントが完了すると、正常にロードされた各ファイルのエントリが aurora_s3_load_history テーブルに書き込まれます。

aurora_s3_load_history テーブルを使用してロード済みのファイルを確認する

LOAD DATA FROM S3 ステートメントが成功するたびに、aurora_s3_load_history スキーマの mysql テーブルが、ロードされた各ファイルのエントリで更新されます。

LOAD DATA FROM S3 ステートメントの実行後、aurora_s3_load_history テーブルをクエリすることで、どのファイルがロードされたかを確認できます。ステートメントの 1 回のイテレーションからロードされたファイルを確認するには、WHERE 句を使用して Amazon S3 URI のレコードをフィルタリングし、ステートメントで使用されたマニフェストファイルを見つけます。以前に同じマニフェストファイルを使用した場合は、timestamp フィールドを使用して結果をフィルタリングします。


select * from mysql.aurora_s3_load_history where load_prefix = 'S3_URI';

以下の表では、aurora_s3_load_history テーブルのフィールドについて説明しています。

フィールド	説明
`load_prefix`	load ステートメントで指定した URI。この URI は、次のいずれかにマッピングできます。 `LOAD DATA FROM S3 FILE` ステートメントの単一のデータファイル `LOAD DATA FROM S3 PREFIX` ステートメントの複数のデータファイルにマッピングする Amazon S3 プレフィックス `LOAD DATA FROM S3 MANIFEST` ステートメントにロードされるファイルの名前を含む単一のマニフェストファイル
`file_name`	`load_prefix` フィールドで指定した URI を使用して Amazon S3 から Aurora にロードされたファイルの名前。
`version_number`	Amazon S3 バケットにバージョン番号がある場合、ロードされた `file_name` フィールドで識別されるファイルのバージョン番号。
`bytes_loaded`	ロードされたファイルのサイズ (バイト単位)。
`load_timestamp`	`LOAD DATA FROM S3` ステートメントが完了したときのタイムスタンプ。

Examples

次のステートメントでは、Aurora DB クラスターと同じリージョンにある Amazon S3 バケットからデータをロードします。customerdata.txt Amazon S3 バケットにある dbbucket ファイルのカンマ区切りデータを読み取り、そのデータを store-schema.customer-table テーブル内にロードします。


LOAD DATA FROM S3 's3://dbbucket/customerdata.csv' 
    INTO TABLE store-schema.customer-table
    FIELDS TERMINATED BY ','
    LINES TERMINATED BY '\n'
    (ID, FIRSTNAME, LASTNAME, ADDRESS, EMAIL, PHONE);

次のステートメントでは、Aurora DB クラスターとは別のリージョンにある Amazon S3 バケットからデータをロードします。employee-data リージョンの my-data Amazon S3 バケットで us-west-2 オブジェクトプレフィックスと一致するすべてのファイルからカンマ区切りのデータを読み取り、そのデータを employees テーブル内にロードします。


LOAD DATA FROM S3 PREFIX 's3-us-west-2://my-data/employee_data'
    INTO TABLE employees
    FIELDS TERMINATED BY ','
    LINES TERMINATED BY '\n'
    (ID, FIRSTNAME, LASTNAME, EMAIL, SALARY);

次のステートメントでは、q1_sales.json という名前の JSON マニフェストファイルに指定されているファイルから sales テーブルにデータをロードします。


LOAD DATA FROM S3 MANIFEST 's3-us-west-2://aurora-bucket/q1_sales.json'
    INTO TABLE sales
    FIELDS TERMINATED BY ','
    LINES TERMINATED BY '\n'
    (MONTH, STORE, GROSS, NET);

LOAD XML FROM S3

LOAD XML FROM S3 ステートメントを使用して、Amazon S3 バケットに保存されている XML ファイルのデータを以下の 3 種類の XML フォーマットのいずれかでロードできます。

<row> 要素の属性としての列名。属性値はテーブルフィールドの内容を指定します。
```
<row column1="value1" column2="value2" .../>
```
<row> 要素の子要素としての列名。子要素の値は、テーブルフィールドの内容を指定します。
```
<row>
  <column1>value1</column1>
  <column2>value2</column2>
</row>
```
name 要素で <field> 要素の <row> 属性の列名。<field> 要素の値は、テーブルフィールドの内容を指定します。
```
<row>
  <field name='column1'>value1</field>
  <field name='column2'>value2</field>
</row>
```

Syntax


LOAD XML FROM S3 'S3-URI'
    [REPLACE | IGNORE]
    INTO TABLE tbl_name
    [PARTITION (partition_name,...)]
    [CHARACTER SET charset_name]
    [ROWS IDENTIFIED BY '<element-name>']
    [IGNORE number {LINES | ROWS}]
    [(field_name_or_user_var,...)]
    [SET col_name = expr,...]

Parameters

以下に、LOAD DATA FROM S3 ステートメントで使用される必須およびオプションのパラメータのリストを示します。以下のパラメータの一部については、MySQL ドキュメントの「LOAD XML 構文」に詳しい説明があります。

FILE | PREFIX – 単一のファイルまたは特定のプレフィックスに一致するすべてのファイルからデータをロードするかどうかを指定します。デフォルトは FILE です。
REPLACE | IGNORE – 入力行とデータベーステーブルの既存の行で一意のキー値が同じである場合、どのアクションを実行するかを決定します。
- テーブル内の既存の行を入力行で置き換える場合は、REPLACE を指定します。
- 入力行を破棄する場合は、IGNORE を指定します。デフォルトは IGNORE です。
INTO TABLE – 入力行をロードする先のデータベーステーブルの名前を指定します。
PARTITION – すべての入力行を、指定されたカンマ区切りのパーティション名のリストに記載されているパーティション内に挿入することを要求します。指定されたパーティションのいずれかに入力行を挿入できない場合、ステートメントは失敗し、エラーが返されます。
CHARACTER SET – 入力ファイルのデータの文字セットを指定します。
ROWS IDENTIFIED BY – 入力ファイルの行を識別する要素名を指定します。デフォルト: <row>。
IGNORE number LINES | ROWS – 入力ファイルの先頭で特定の行数を無視することを指定します。例えば、IGNORE 1 LINES ではテキストファイルの最初の行がスキップされます。IGNORE 2 ROWS では、入力 XML の最初の 2 行のデータがスキップされます。
field_name_or_user_var, ... – 1 つ以上の XML 要素名またはユーザー変数のカンマ区切りのリストにより、ロードする要素を名前で指定します。この目的で使用されるユーザー変数の名前は、プレフィックスを @ とする XML ファイルの要素名と一致する必要があります。フィールド値を対応するユーザー変数に保存して後で再利用できます。

例えば、次のステートメントでは、入力ファイルの最初の列を table1 の最初の列内にロードし、さらに table_column2 の table1 列の値として、2 列目の入力値を 100 で割った値を設定します。
```
LOAD XML FROM S3 's3://mybucket/data.xml'
   INTO TABLE table1
   (column1, @var1)
   SET table_column2 = @var1/100;
```
SET – 割り当てオペレーションのカンマ区切りのリストにより、テーブル内の列の値を入力ファイルに含まれていない値に設定します。

例えば、次のステートメントは table1 の最初の 2 列を入力ファイルの最初の 2 列の値に設定し、さらに column3 の table1 の値を現在のタイムスタンプに設定します。
```
LOAD XML FROM S3 's3://mybucket/data.xml'
   INTO TABLE table1
   (column1, column2)
   SET column3 = CURRENT_TIMESTAMP;
```
SET 割り当ての右側のサブクエリを使用できます。列に割り当てる値を返すサブクエリとしては、スカラーサブクエリのみ使用できます。また、サブクエリを使用してロード中のテーブルから選択することはできません。