メニュー
Amazon Redshift
データベース開発者ガイド (API Version 2012-12-01)

データ形式パラメータ

デフォルトでは、COPY コマンドはソースデータを文字区切り形式 UTF-8 のテキストと見なします。デフォルトの区切り文字はパイプ文字です。ソースデータが別の形式である場合は、以下のパラメータを使用してデータ形式を指定します。

データ形式パラメータ

FORMAT [AS]

オプション。データ形式キーワードを識別します。

CSV [ QUOTE [AS] 'quote_character' ]

入力データで CSV 形式の使用を有効にします。区切り記号、改行文字、およびキャリッジリターンを自動的にエスケープするには、QUOTE パラメータで指定した文字でフィールドを囲みます。デフォルトの引用文字は二重引用符 (") です。フィールド内で引用文字が使用されている場合、引用文字を追加してその文字をエスケープします。たとえば、引用文字が二重引用符である場合、文字列 A "quoted" word を挿入するには、入力ファイルに文字列 "A ""quoted"" word" を含める必要があります。CSV パラメータを使用する場合、デフォルトの区切り記号はカンマ (,) です。DELIMITER パラメータを使用して、異なる区切り記号を指定できます。

フィールドを引用符で囲んだ場合、区切り記号と引用文字との間の空白は無視されます。区切り記号がタブなどの空白文字である場合、その区切り記号は空白として扱われません。

CSV は FIXEDWIDTH、REMOVEQUOTES、または ESCAPE と共に使用することはできません。

QUOTE [AS] 'quote_character'

オプション。CSV パラメータを使用する場合に引用文字として使用する文字を指定します。デフォルトは二重引用符 (") です。QUOTE パラメータを使用して二重引用符以外の引用文字を定義した場合、フィールド内で二重引用符をエスケープする必要はありません。QUOTE パラメータは CSV パラメータと共にしか使用できません。AS キーワードはオプションです。

DELIMITER [AS] ['delimiter_char']

パイプ文字 (|)、カンマ (,)、タブ (\t) など、入力ファイルのフィールドを区切るときに使用する単一の ASCII 文字を指定します。非表示の ASCII 文字がサポートされています。ASCII 文字は "\ddd" 形式を使用して 8 進数で表すこともできます。ここで "d" は 8 進数の数字 (0~7) です。デフォルトの区切り記号はパイプ文字 (|) です。ただし、CSV パラメータを使用する場合、デフォルトの区切り記号はカンマ (,) です。AS キーワードはオプションです。DELIMITER と FIXEDWIDTH は併用できません。

FIXEDWIDTH 'fixedwidth_spec'

列を区切り記号で区切らずに各列幅を固定長にしたファイルからデータをロードします。fixedwidth_spec はユーザー定義の列ラベルと列幅を指定する文字列です。列ラベルには、ユーザーの選択に従って、テキスト文字列または整数を指定できます。列ラベルは列名と関係ありません。ラベル/幅のペアの順序はテーブルの列の順序に正確に一致する必要があります。FIXEDWIDTH と CSV または DELIMITER を併用することはできません。Amazon Redshift では、CHAR 列および VARCHAR 列の長さがバイト単位で表されるため、ロードするファイルを準備する際には、指定する列幅がマルチバイト文字のバイナリ長に対応できることを確認してください。詳細については、「文字型」を参照してください。

fixedwidth_spec の形式を次に示します。

Copy
'colLabel1:colWidth1,colLabel:colWidth2, ...'
AVRO [AS] 'avro_option'

ソースデータが Avro 形式であることを指定します。

Avro 形式はここに挙げるサービスおよびプロトコルから実行する COPY でサポートされます。

  • Amazon S3

  • Amazon EMR

  • リモートホスト (SSH)

Avro は DynamoDB から実行する COPY ではサポートされません。

Avro はデータのシリアル化プロトコルです。Avro のソースファイルには、データ構造を定義するスキーマが含まれています。Avro のスキーマ型は record である必要があります。COPY はデフォルトの非圧縮コーデック、および deflatesnappy 圧縮コーデックを使用して、Avro ファイルのサポートを許可します。Avro に関する詳細については、「Apache Avro」を参照してください。

avro_option の有効な値は次のとおりです。

  • 'auto'

  • 's3://jsonpaths_file'

デフォルト: 'auto'

'auto'

COPY は Avro スキーマのフィールド名をターゲットテーブルの列名に一致させることで、Avro ソースデータのデータ要素をターゲットテーブルの列に自動的にマッピングします。一致には、大文字と小文字の区別があります。Amazon Redshift テーブルの列名は常に小文字になるため、「自動」オプションを使用する場合、対応するフィールド名も小文字である必要があります。フィールド名がすべて小文字でない場合は、JSONPaths file を使用して、Avro フィールド名に明示的に列名をマッピングできます。COPY はデフォルトの 'auto' 引数を使用して、構造のフィールドの最初のレベル、または外部フィールドのみを認識します。

デフォルトでは、COPY はターゲットテーブルのすべての列が Avro のフィールド名に一致するように試みます。列のサブセットをロードするには、オプションで列リストを指定できます。

ターゲットテーブルの列が列リストから削除されている場合は、COPY はターゲット列の DEFAULT 式をロードします。ターゲット列にデフォルトがない場合は、COPY は NULL をロードします。

列が列リストに含まれており、COPY が Avro データで一致するフィールドを見つけることができなかった場合、COPY はその列に NULL をロードしようと試みます。

COPY を実行し、NOT NULL として定義されている列に NULL を割り当てようとすると、COPY コマンドは失敗します。

's3://jsonpaths_file'

明示的に列に Avro のデータ要素をマッピングするには、JSONPaths ファイルを使用できます。JSONPaths ファイルの使用方法の詳細については、「JSONPaths file」を参照してください。

Avro スキーマ

Avro のソースデータファイルには、データ構造を定義するスキーマが含まれています。COPY は Avro のソースデータファイルの一部であるスキーマを読み込み、ターゲットテーブルの列にデータ要素をマッピングします。次の例で Avro のスキーマを示します。

Copy
{ "name": "person", "type": "record", "fields": [ {"name": "id", "type": "int"}, {"name": "guid", "type": "string"}, {"name": "name", "type": "string"}, {"name": "address", "type": "string"} }

Avro スキーマは JSON 形式を使用して定義されています。最上位の JSON オブジェクトには 3 つの名前と値のペアと名前、つまり keys"name""type"、および "fields" があります。

オブジェクトの配置を含む "fields" キーペアは、データ構造の各フィールド名とデータ型を定義します。デフォルトでは、COPY はフィールド名を列名に自動的に一致させます。列名は常に小文字であるため、一致させるフィールド名もまた小文字にする必要があります。列名と一致しないフィールド名はすべて無視されます。順序は関係ありません。前の例では、COPY は列名 idguidname および address にマッピングしています。

デフォルトの 'auto' 引数を使用すると、COPY は列の第 1 レベルのオブジェクトのみと一致します。スキーマのより深いレベルにマッピングする場合、またはフィールド名と列名が一致しない場合は、JSONPaths ファイルを使用してマッピングを定義します。詳細については、「JSONPaths file」を参照してください。

キーに関連付けられた値が Avro の複雑なデータ型 (バイト、配列、レコード、マップ、リンクなど) である場合、COPY は値を文字列としてロードします。文字列はデータの JSON 形式です。COPY は Avro ENUM データ型を文字列としてロードします。文字列の内容は型名です。例については、「JSON 形式からの COPY」を参照してください。

スキーマおよびファイルメタデータを含む Avro ファイルヘッダーの最大サイズは 1 MB です。 

単一の Avro データブロックの最大サイズは 4 MB です。これは、行の最大サイズとは異なります。単一の Avro データブロックの最大サイズを超えた場合は、最終的な行サイズが 4 MB 未満であっても COPY コマンドは失敗します。

行のサイズを計算する際、Amazon Redshift では、パイプ文字 ( | ) を 2 回内部的にカウントします。入力データに非常に多くのパイプ文字が含まれる場合、データブロックが 4 MB 未満であっても行サイズが 4 MB を超えることは可能です。

JSON [AS] 'json_option'

ソースデータは JSON 形式です。

JSON 形式は次のサービスおよびプロトコルからの COPY でサポートされています。

  • Amazon S3

  • Amazon EMR からの COPY

  • SSH からの COPY

JSON は DynamoDB からの COPY ではサポートされません。

json_option の有効な値は次のとおりです。

  • 'auto'

  • 's3://jsonpaths_file'

デフォルト: 'auto'

'auto'

COPY はソースの名前と値のペアに含まれるオブジェクトキー (名前) をターゲットテーブルの列名に一致させることによって、JSON ソースデータ内のデータ要素をターゲットテーブル内の列にマッピングします。一致には、大文字と小文字の区別があります。Amazon Redshift テーブルの列名は常に小文字になるため、「自動」オプションを使用する場合、対応する JSON フィールド名も小文字である必要があります。JSON フィールド名のキーがすべて小文字でない場合は、JSONPaths file を使用して、明示的に列名を JSON フィールド名のキーにマッピングすることができます。

デフォルトでは、COPY はターゲットテーブルのすべての列を JSON のフィールド名キーに一致させるように試みます。列のサブセットをロードするには、オプションで列リストを指定できます。

ターゲットテーブルの列が列リストから削除されている場合は、COPY はターゲット列の DEFAULT 式をロードします。ターゲット列にデフォルトがない場合は、COPY は NULL をロードします。

列が列リストに含まれており、COPY が JSON データで一致するフィールドを見つけることができなかった場合、COPY はその列に NULL をロードしようと試みます。

COPY を実行し、NOT NULL として定義されている列に NULL を割り当てようとすると、COPY コマンドは失敗します。

's3://jsonpaths_file'

COPY は指定された JSONPaths ファイルを使用して、JSON ソースデータ内のデータ要素をターゲットテーブル内の列にマッピングします。s3://jsonpaths_file 引数は、単一ファイルを明示的に参照する Amazon S3 オブジェクトキーでなければならず ('s3://mybucket/jsonpaths.txt など)、キープレフィックスにすることはできません。JSONPaths ファイルの使用方法の詳細については、「JSONPaths file」を参照してください。

注記

jsonpaths_file で指定されたファイルに、データファイルの copy_from_s3_objectpath で指定されたパスと同じプレフィックスがある場合、COPY は JSONPaths ファイルをデータファイルとして読み取り、エラーを返します。たとえば、データファイルで使用するオブジェクトパスが s3://mybucket/my_data.json であり、JSONPaths ファイルが s3://mybucket/my_data.jsonpaths である場合、COPY は my_data.jsonpaths をデータファイルとしてロードしようとします。

JSON データファイル

JSON データファイルには、一連のオブジェクトまたは配列が含まれます。COPY は、それぞれの JSON オブジェクトまたは JSON 配列をターゲットテーブルの 1 つの行にロードします。行に対応する各オブジェクトまたは配列は、スタンドアロンのルートレベル構造である必要があります。つまり、別の JSON 構造のメンバーではない必要があります。

JSON オブジェクトの先頭と末尾には中括弧 ({ }) が付き、順序が設定されていない一連の名前と値のペアが含まれます。ペアの名前と値はコロンで区切られ、各ペアはカンマで区切られます。デフォルトでは、名前と値のペアに含まれるオブジェクトキー (名前) は、テーブル内の対応する列の名前に一致する必要があります。Amazon Redshift テーブルの列名は常に小文字であるため、一致する JSON フィールド名のキーも小文字である必要があります。列名と JSON キーが一致しない場合、JSONPaths file を使用して明示的に列をキーにマッピングします。

JSON オブジェクト内の順序は問題ではありません。列名と一致しない名前はすべて無視されます。次に、簡単な JSON オブジェクトの構造を示します。

Copy
{ "column1": "value1", "column2": value2, "notacolumn" : "ignore this value" }

JSON 配列の先頭と末尾には角括弧 ([  ]) が付き、順序が設定された一連のカンマ区切りの値が含まれます。データファイルで配列を使用している場合は、JSONPaths ファイルを指定して、値を列に一致させる必要があります。次に、簡単な JSON 配列の構造を示します。

Copy
["value1", value2]

JSON は正しい形式になっている必要があります。たとえば、オブジェクトまたは配列をカンマまたは空白以外の他の文字で区切ることはできません。文字列は、二重引用文字で囲む必要があります。引用符は、傾きの付いた "高機能な" 引用符ではなくシンプルな引用符 (0x22) にする必要があります。

1 つの JSON オブジェクトまたは JSON 配列の最大サイズ (中括弧または角括弧を含む) は 4 MB です。これは、行の最大サイズとは異なります。単一の JSON オブジェクトまたは配列の最大サイズを超えた場合は、最終的な行サイズが 4 MB 未満であっても COPY コマンドは失敗します。

行のサイズを計算する際、Amazon Redshift では、パイプ文字 ( | ) を 2 回内部的にカウントします。入力データに非常に多くのパイプ文字が含まれる場合、オブジェクトサイズが 4 MB 未満であっても行サイズが 4 MB を超えることは可能です。

COPY は改行文字として \n を、タブ文字として \t をロードします。バックスラッシュをロードするには、バックスラッシュをバックスラッシュでエスケープします (\\)。

COPY は、指定した JSON ソースにおいて、正しい形式の有効な JSON オブジェクトまたは JSON 配列を検索します。COPY で、使用可能な JSON 構造を特定するまでに、または有効な JSON オブジェクトまたは配列の間に、空白以外の文字が検出された場合、COPY は各インスタンスについてエラーを返します。このエラーは、MAXERROR のエラー数としてカウントされます。エラー数が MAXERROR 以上に達すると、COPY は失敗します。

それぞれのエラーについて、Amazon Redshift は STL_LOAD_ERRORS システムテーブルの行を記録します。LINE_NUMBER 列には、エラーの原因となった JSON オブジェクトの最後の行が記録されます。

IGNOREHEADER を指定した場合、COPY は JSON データの指定数の行を無視します。JSON データに含まれる改行文字は、常に IGNOREHEADER の計算にカウントされます。

デフォルトでは、COPY は空の文字列を空のフィールドとしてロードします。EMPTYASNULL を指定した場合、COPY は CHAR および VARCHAR フィールドの空の文字列を NULL としてロードします。INT など、他のデータ型の空の文字列は常に NULL でロードされます。

次のオプションは JSON ではサポートされません。

  • CSV

  • DELIMITER

  • ESCAPE

  • FILLRECORD

  • FIXEDWIDTH

  • IGNOREBLANKLINES

  • NULL AS

  • READRATIO

  • REMOVEQUOTES

詳細については、「JSON 形式からの COPY」を参照してください。JSON データ構造の詳細については、www.json.org を参照してください。

JSONPaths ファイル

JSON 形式または Avro ソースのデータからロードする場合、デフォルトでは COPY は名前と値のペアに含まれる各名前 (オブジェクトキー) をターゲットテーブル内の列の名前と一致させることで、JSON ソースデータ内の第 1 レベルのデータ要素をターゲットテーブル内の列にマッピングします。

列名とオブジェクトキーが一致しない場合、またはデータ階層のより深いレベルまでマッピングする場合は、JSONPaths ファイルを使用して明示的に JSON または Avro のデータ要素を列にマッピングできます。JSONPaths ファイルは、ターゲットテーブルまたは列リストで列の順序を一致させることで、JSON データ要素を列にマッピングします。

JSONPaths には、単一の JSON オブジェクト (配列ではない) を格納しなければなりません。JSON オブジェクトは、名前と値のペアです。オブジェクトキー (名前と値のペアに含まれる名前) は、"jsonpaths" にする必要があります。名前の値のペアに含まれるは、JSONPath expressions の配列です。各 JSONPath 式は、JSON データ階層内または Avro スキーマの単一の要素を参照します。XPath 式が XML ドキュメント内の要素を参照する方法と似ています。詳細については、「JSONPath Expressions」を参照してください。

JSONPaths ファイルを使用するには、JSON または AVRO キーワードを COPY コマンドに追加し、次の形式を使用して JSONPaths ファイルの S3 バケット名とオブジェクトパスを指定します。

Copy
COPY tablename FROM 'data_source' CREDENTIALS 'credentials-args' FORMAT AS { AVRO | JSON } 's3://jsonpaths_file';

s3://jsonpaths_file 引数は、単一ファイルを明示的に参照する Amazon S3 オブジェクトキーでなければならず ('s3://mybucket/jsonpaths.txt' など)、キープレフィックスにすることはできません。

注記

Amazon S3 からロードする場合で、jsonpaths_file で指定されたファイルに、データファイルの copy_from_s3_objectpath で指定されたパスと同じプレフィックスがある場合、COPY は JSONPaths ファイルをデータファイルとして読み取り、エラーを返します。たとえば、データファイルで使用するオブジェクトパスが s3://mybucket/my_data.json であり、JSONPaths ファイルが s3://mybucket/my_data.jsonpaths である場合、COPY は my_data.jsonpaths をデータファイルとしてロードしようとします。

注記

キー名が "jsonpaths" 以外の文字列である場合、COPY コマンドはエラーを返しませんが、jsonpaths_file を無視して 'auto' 引数を代わりに使用します。

以下のいずれかの状況に当てはまる場合、COPY コマンドは失敗します。

  • JSON が正しい形式ではない.

  • 複数の JSON オブジェクトがある.

  • オブジェクトの外に空白以外の文字が存在する.

  • 配列エレメントが空の文字列であるか、文字列ではない.

MAXERROR は JSONPaths には適用されません。

COPY で ENCRYPTED パラメータが使用されている場合、JSONPaths ファイルは暗号化されません。

詳細については、「JSON 形式からの COPY」を参照してください。

JSONPath 式

JSONPaths ファイルは JSONPath 式を使用してターゲット列にデータフィールドをマッピングします。各 JSONPath 式は、Amazon Redshift のターゲットテーブル内の 1 列に対応しています。JSONPath 配列要素の順序は、ターゲットテーブル内の列の順序または列リストが使用される場合は列リスト内の列の順序と一致していなければなりません。

例に示すように、フィールド名と値のどちらにも二重引用符が必要です。 引用符は、傾きの付いた "高機能な" 引用符ではなくシンプルな引用符 (0x22) にする必要があります。

JSONPath 式によって参照されるオブジェクト要素が JSON データにない場合、COPY は NULL 値をロードしようとします。参照されるオブジェクトが正しい形式ではない場合、COPY はロードエラーを返します。

JSONPath 式により参照される配列要素が JSON データまたは Avro データに見つからない場合、COPY は次のエラーで失敗します。Invalid JSONPath format: Not an array or index out of range. ソースデータに存在しない配列要素を JSONPaths からすべて削除し、ソースデータの配列が正しい形式であることを確認してください。

JSONPath 式では、ブラケット表記またはドット表記のいずれかを使用できますが、両方の表記を混ぜて使用することはできません。次の例は、ブラケット表記を使用した JSONPath 式を示しています。

Copy
{ "jsonpaths": [ "$['venuename']", "$['venuecity']", "$['venuestate']", "$['venueseats']" ] }

次の例は、ドット表記を使用した JSONPath 式を示しています。

Copy
{ "jsonpaths": [ "$.venuename", "$.venuecity", "$.venuestate", "$.venueseats" ] }

Amazon Redshift の COPY 構文のコンテキストでは、JSONPath 式は、JSON または Avro の階層データ構造内の 1 つの名前要素に対する明示的なパスを指定する必要があります。Amazon Redshift では、あいまいなパスや複数の名前要素に解決される可能性がある、ワイルドカード文字やフィルタ式などの JSONPath 要素をサポートしていません。

詳細については、「JSON 形式からの COPY」を参照してください。

Avro データに対する JSONPaths の使用

次の例で、複数のレベルがある Avro スキーマを示します。

Copy
{ "name": "person", "type": "record", "fields": [ {"name": "id", "type": "int"}, {"name": "guid", "type": "string"}, {"name": "isActive", "type": "boolean"}, {"name": "age", "type": "int"}, {"name": "name", "type": "string"}, {"name": "address", "type": "string"}, {"name": "latitude", "type": "double"}, {"name": "longitude", "type": "double"}, { "name": "tags", "type": { "type" : "array", "name" : "inner_tags", "items" : "string" } }, { "name": "friends", "type": { "type" : "array", "name" : "inner_friends", "items" : { "name" : "friends_record", "type" : "record", "fields" : [ {"name" : "id", "type" : "int"}, {"name" : "name", "type" : "string"} ] } } }, {"name": "randomArrayItem", "type": "string"} ] }

次の例で、AvroPath 式を使用して前のスキーマを参照する JSONPaths ファイルを示します。

Copy
{ "jsonpaths": [ "$.id", "$.guid", "$.address", "$.friends[0].id" ] }

JSONPaths の例には、以下の要素が含まれています。

jsonpaths

AvroPath 式を含む JSON オブジェクトの名前です。

[ … ]

かっこ内にパス要素を含む JSON 配列を囲みます。

$

ドル記号は、"fields" 配列である Avro スキーマのルート要素を表します。

"$.id",

AvroPath 式のターゲットです。このインスタンスでは、ターゲットは "fields" 配列の "id" という名前の要素です。式はコンマで区切ります。

"$.friends[0].id"

かっこは配列インデックスを示します。JSONPath 式はゼロベースのインデックスを使用します。従って、この式は "friends" 配列の第 1 要素を "id" と言う名前で参照します。

Avro スキーマの構文では、内部フィールドを使用してレコード構造および配列データ型を定義する必要があります。内部フィールドは AvroPath 式には無視されます。たとえば、フィールド "friends""inner_friends" という名前の配列を定義し、は "friends_record" という名前のレコードを定義します。フィールド "id" を参照する AvroPath 式は、追加のフィールドを無視してターゲットフィールドを直接参照できます。次の AvroPath 式は、"friends" 配列内に属する 2 つのフィールドを参照します。

Copy
"$.friends[0].id" "$.friends[0].name"
BZIP2

入力ファイルが圧縮された bzip2 形式 (.bz2 ファイル) であることを指定する値です。COPY 操作では、圧縮されたそれぞれのファイルを読み取り、ロード時にデータを解凍します。

GZIP

入力ファイルが圧縮された gzip 形式 (.gz 形式) であることを指定する値です。COPY 操作では、圧縮されたそれぞれのファイルを読み取り、ロード時にデータを解凍します。

LZOP

入力ファイルが圧縮された lzop 形式 (lzo ファイル) であることを指定する値です。COPY 操作では、圧縮されたそれぞれのファイルを読み取り、ロード時にデータを解凍します。

注記

COPY は、lzop --filter オプションを使用して圧縮されたファイルをサポートしていません。