データ形式パラメータ - Amazon Redshift

データ形式パラメータ

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

標準データ形式に加えて、COPY は、Amazon S3 から COPY の以下の列データ形式をサポートしています。

列形式の COPY は、特定の制限でサポートされています。詳細については、「列データ形式の COPY」を参照してください。

データ形式パラメータ
FORMAT [AS]

(オプション) データ形式キーワードを識別します。FORMAT 引数については以下で説明します。

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 の形式を次に示します。

'colLabel1:colWidth1,colLabel:colWidth2, ...'
SHAPEFILE [ SIMPLIFY [AUTO] ['tolerance'] ]

入力データで SHAPEFILE 形式の使用を有効にします。デフォルトでは、シェープファイルの最初の列は GEOMETRY 列または IDENTITY 列のいずれかです。後続のすべての列は、シェープファイルで指定された順序に従います。

SHAPEFILE を FIXEDWIDTH、EMOVEQUOTES、または ESCAPE と一緒に使用することはできません。

COPY FROM SHAPEFILEGEOGRAPHY オブジェクトを使用するには、まずオブジェクトを GEOMETRY 列に取り込んだ後に、そのオブジェクトを GEOGRAPHY オブジェクトにキャストします。

SIMPLIFY [tolerance]

(オプション) Ramer-Douglas-Peucker アルゴリズムと指定された許容値を使用して、取り込みプロセス中のすべてのジオメトリを簡略化します。

SIMPLIFY AUTO [tolerance]

(オプション) 最大ジオメトリのサイズより大きいジオメトリのみを簡略化します。この簡略化では、Ramer-Douglas-Peucker アルゴリズムと、指定した許容値を超えない場合に自動的に計算された許容値が使用されます。このアルゴリズムは、指定された許容値内でオブジェクトを保存するためのサイズを計算します。許容値は任意の値です。

シェープファイルのロードの例については、「シェープファイルを Amazon Redshift にロードする」を参照してください。

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'

  • 'auto ignorecase'

  • 's3://jsonpaths_file'

デフォルトは 'auto' です。

COPY は Avro ソースデータのデータ要素をターゲットテーブルの列に自動的にマッピングします。Avro スキーマのフィールド名をターゲットテーブルの列名に一致させることで、行われます。一致で、'auto'では大文字と小文字が区別され、'auto ignorecase'では大文字と小文字が区別されません。

Amazon Redshift テーブルの列名は常に小文字になるため、'auto' オプションを使用する場合、対応するフィールド名も小文字である必要があります。フィールド名がすべて小文字でない場合は、'auto ignorecase'オプションを使用できます。デフォルトの 'auto' 引数を使用すると、COPY は構造内の最初のレベルのフィールドまたは外部フィールドのみを認識します。

列名を Avro フィールド名に明示的にマップするには、JSONPaths ファイル を使用できます。

デフォルトでは、COPY はターゲットテーブルのすべての列が Avro のフィールド名に一致するように試みます。列のサブセットをロードするには、オプションで列リストを指定できます。ターゲットテーブルの列が列リストから削除された場合は、COPY はターゲット列の DEFAULT 式をロードします。ターゲット列にデフォルトがない場合は、COPY は NULL をロードしようとします。列が列リストに含まれており、COPY が Avro データで一致するフィールドを見つけることができなかった場合、COPY はその列に NULL をロードしようと試みます。

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

Avro スキーマ

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

{ "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 つの名前と値のペア "name""type"、および "fields" があります。

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

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

キーに関連付けられた値が 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'

  • 'auto ignorecase'

  • 's3://jsonpaths_file'

  • 'noshred'

デフォルトは 'auto' です。Amazon Redshift は、JSON ドキュメントのロード中に JSON 構造の属性を複数の列に細分化しません。

デフォルトでは、COPY はターゲットテーブルのすべての列を JSON のフィールド名キーに一致させるように試みます。列のサブセットをロードするには、オプションで列リストを指定できます。JSON フィールド名のキーがすべて小文字でない場合は、'auto ignorecase' オプションまたは JSONPaths ファイル を使用して、明示的に列名を JSON フィールド名のキーにマッピングすることができます。

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

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

COPY は、JSON ソースデータ内のデータ要素をターゲットテーブル内の列にマッピングします。これは、ソースの名前と値のペアのオブジェクトキーまたは名前を、ターゲットテーブルの列の名前と一致させることによって行われます。

json_option 値については、次の詳細を参照してください。

'auto'

このオプションでは、一致では大文字と小文字が区別されます。Amazon Redshift テーブルの列名は常に小文字になるため、'auto' オプションを使用する場合、対応する JSON フィールド名も小文字である必要があります。

'auto ignorecase'

このオプションでは、一致では大文字と小文字は区別されません。Amazon Redshift テーブルの列名は常に小文字であるため、'auto ignorecase' オプションを使用する場合、対応する JSON フィールド名は小文字、大文字、または大文字と小文字を混在させることができます。

's3://jsonpaths_file'

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

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

'noshred'

このオプションを使用すると、Amazon Redshift は JSON ドキュメントのロード中に JSON 構造の属性を複数の列に細分化しません。

JSON データファイル

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

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

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

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

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

["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 配列を検索します。使用可能な JSON 構造体を見つける前に、または有効な JSON オブジェクトまたは配列の間で COPY が空白以外の文字を検出した場合、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 はソースデータ内の第 1 レベルのデータ要素をターゲットテーブル内の列にマッピングします。これは、名前と値のペアの各名前またはオブジェクトキーを、ターゲットテーブルの列の名前と一致させることによって行われます。

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

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

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

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

s3://jsonpaths_file 値は、's3://mybucket/jsonpaths.txt'などの単一のファイルを明示的に参照する Amazon S3 オブジェクトキーである必要があります。キープレフィックスにすることはできません。

場合によっては、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 には適用されません。

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 式を示しています。

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

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

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

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

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

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

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

{ "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 ファイルを示します。

{ "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 つのフィールドを参照します。

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

列データ形式のパラメータ

標準データ形式に加えて、COPY は、Amazon S3 から COPY の以下の列データ形式をサポートしています。列形式の COPY は、特定の制限でサポートされています。詳細については、「列データ形式の COPY」を参照してください。

ORC

最適化された行列 (ORC) ファイル形式を使用するファイルからデータをロードします。

PARQUET

Parquet ファイル形式を使用するファイルからデータをロードします。