Hitachi

Hitachi Advanced Database SQLリファレンス

4.1.1　COPY文の指定形式および規則

表の検索結果をPARQUET形式またはCSV形式のデータで次の外部ストレージに出力します。

〈この項の構成〉

(1)　指定形式

COPY文：：＝COPY (問合せ式本体 〔ORDER BY句〕 〔LIMIT句〕)
               TO 出力先位置文字列
              〔SERVER 外部サーバ名〕
              〔OPTIONS (COPYオプション〔,COPYオプション〕…)〕
 
  出力先位置文字列：：＝文字列定数
 
  COPYオプション：：＝｛出力データ形式指定
                      ｜出力データのフォーマットオプション指定
                      ｜出力データ圧縮形式指定｝
    出力データ形式指定：：＝FORMAT ｛PARQUET｜CSV｝
 
    出力データのフォーマットオプション指定：：＝｛区切り文字指定｜ヘッダー指定｝
      区切り文字指定：：＝DELIMITER_CHAR 区切り文字
      ヘッダー指定：：＝HEADER_SPEC ｛YES｜NO｝
        区切り文字：：＝文字列定数
 
    出力データ圧縮形式指定：：＝COMPRESSION ｛ZSTD｜SNAPPY｜GZIP｜LZ4｜BROTLI｜NONE｝

ページの先頭へ

(2)　指定形式の説明

●問合せ式本体 〔ORDER BY句〕 〔LIMIT句〕
問合せ式本体：

ファイルに出力するデータを取り出す問合せ式本体を指定します。問合せ式本体については，「7.1.1　問合せ式の指定形式および規則」の「(2)　指定形式の説明」の「(b)　問合せ式本体」を参照してください。

ORDER BY句：

問合せ式本体の検索結果を昇順または降順に並べ替える場合に指定します。ORDER BY句を省略した場合，問合せ式本体の検索結果の並び順は保証されません。ORDER BY句については，「4.5.1　SELECT文の指定形式および規則」の「(2)　指定形式の説明」を参照してください。

LIMIT句：

問合せ式本体の検索結果として取得する行数の最大値を指定します。LIMIT句については，「7.9　LIMIT句」を参照してください。

●TO 出力先位置文字列

表の検索結果のデータの出力先と，出力ファイル名のプレフィックスを文字列定数の形式で指定します。文字列定数については，「6.3　定数」を参照してください。指定例を次に示します。

  • オブジェクトストレージにデータを出力する場合

    表の検索結果のデータの出力先をS3 URI形式で指定します。

    （例1）出力先のディレクトリとファイル名のプレフィックスを指定する場合
    TO 's3://data-bucket/ftbl/T1/res_sql'

    この例では，ファイル名のプレフィックスとしてres_sqlを指定しています。この場合，s3://data-bucket/ftbl/T1/ディレクトリ下に，例えば次のファイルが出力されます。

    • res_sql-1234-1-1-1.parquet

    • res_sql-1234-1-1-2.parquet

    （例2）出力先のディレクトリだけを指定する場合
    TO 's3://data-bucket/ftbl/T1/'

    この例では，ファイル名のプレフィックスを指定していません。この場合，s3://data-bucket/ftbl/T1/ディレクトリ下に，例えば次のファイルが出力されます。

    • adb-1234-1-1-1.parquet

    • adb-1234-1-1-2.parquet

    このように，ファイル名のプレフィックスを指定しないと，ファイル名の先頭の文字列がadbになります。

  • ファイルストレージにデータを出力する場合

    表の検索結果のデータの出力先をFILE URI形式で指定します。

    （例1）出力先のディレクトリとファイル名のプレフィックスを指定する場合
    TO 'file:///data/ftbl/T1/res_sql'

    この例では，ファイル名のプレフィックスとしてres_sqlを指定しています。この場合，/data/ftbl/T1/ディレクトリ下に，例えば次のファイルが出力されます。

    • res_sql-1234-1-1-1.parquet

    • res_sql-1234-1-1-2.parquet

    （例2）出力先のディレクトリだけを指定する場合
    TO 'file:///data/ftbl/T1/'

    この例では，ファイル名のプレフィックスを指定していません。この場合，/data/ftbl/T1/ディレクトリ下に，例えば次のファイルが出力されます。

    • adb-1234-1-1-1.parquet

    • adb-1234-1-1-2.parquet

    このように，ファイル名のプレフィックスを指定しないと，ファイル名の先頭の文字列がadbになります。

出力先位置文字列の指定規則

  • 表の検索結果のデータの出力先がオブジェクトストレージの場合は，出力先位置文字列の先頭にs3://を指定してください。表の検索結果のデータの出力先がファイルストレージの場合は，file://を指定してください。

  • 出力先位置文字列の末尾に/を指定した場合，ファイル名のプレフィックスが指定されていないと見なされます。その場合，ファイル名のプレフィックスとして「adb」が仮定されます。

  • 出力先位置文字列は，1,024バイト以下にしてください。

  • オブジェクトストレージにデータを出力する場合，出力先位置文字列に指定したバケット名がないと，COPY文がエラーになります。

データを出力するファイルの名称規則

データを出力するファイルの名称は次の規則に従って決定されます。

  • PARQUET形式のデータを出力する場合

    プレフィックス‐通番1‐通番2‐通番3‐通番4.parquet

  • CSV形式のデータを出力する場合

    プレフィックス‐通番1‐通番2‐通番3‐通番4.csv

［説明］

  • プレフィックス

    出力先位置文字列に指定したファイル名のプレフィックスです。出力先位置文字列にプレフィックスを指定していない場合は，プレフィックスには「adb」が仮定されます。

  • 通番1

    COPY文を実行したトランザクションのトランザクションID（最大20桁のゼロサプレスした数字）

  • 通番2

    COPY文を実行したコネクションでのSQL文通番（最大20桁のゼロサプレスした数字）

  • 通番3

    ファイルを出力したリアルスレッドのリアルスレッド番号（SQL文ごとに割り振られる1から始まる通番で，最大4桁のゼロサプレスした数字）

  • 通番4

    リアルスレッド内で出力したファイルの出力順番号（1から始まる通番で，最大11桁のゼロサプレスした数字）

●SERVER 外部サーバ名

オブジェクトストレージにデータを出力する場合にこのオプションを指定します。ファイルストレージにデータを出力する場合，このオプションは指定しないでください。

ファイルの出力先となる外部サーバ名を指定します。存在しない外部サーバ名は指定できません。

外部サーバの定義時に指定した認証情報で外部サーバにアクセスできない場合，COPY文がエラーになります。

●OPTIONS (COPYオプション〔,COPYオプション〕…)
COPYオプション：：＝｛出力データ形式指定
                    ｜出力データのフォーマットオプション指定
                    ｜出力データ圧縮形式指定｝

COPYオプションには，出力するデータの形式などを指定します。

出力データ形式指定を2回指定するなど，同じ種類のCOPYオプションは指定できません。

出力データ形式指定：
出力データ形式指定：：＝FORMAT ｛PARQUET｜CSV｝

データをPARQUET形式で出力するか，またはCSV形式で出力するかを指定します。

  • PARQUET

    PARQUET形式のデータを出力します。

    出力データ形式指定を省略した場合，PARQUET形式のデータを出力します。

  • CSV

    CSV形式のデータを出力します。

出力データのフォーマットオプション指定：
出力データのフォーマットオプション指定：：＝｛区切り文字指定｜ヘッダー指定｝
    区切り文字指定：：＝DELIMITER_CHAR 区切り文字
    ヘッダー指定：：＝HEADER_SPEC ｛YES｜NO｝

出力データのフォーマットオプション指定には，出力データの区切り文字や，ヘッダーを出力するかどうかを指定します。

PARQUET形式のデータを出力する場合は，このオプションは指定できません。

  • 区切り文字指定

    区切り文字指定：：＝DELIMITER_CHAR 区切り文字

    CSV形式の各データを区切る区切り文字を文字列定数の形式で指定します。文字列定数については，「6.3　定数」を参照してください。区切り文字として「:」を指定する場合の指定例を次に示します。

    DELIMITER_CHAR ':'

    指定規則を次に示します。

    • 区切り文字には，1バイトの文字列を指定します。

    • 区切り文字指定を省略した場合，区切り文字としてコンマ（,）が仮定されます。

    • 区切り文字にアポストロフィ（'）を指定する場合，区切り文字としてアポストロフィを2個続けて指定してください。

  • ヘッダー指定

    ヘッダー指定：：＝HEADER_SPEC ｛YES｜NO｝

    CSV形式の出力データの先頭1行目にヘッダーを出力するかどうかを指定します。

    YES：ヘッダーを出力します。ヘッダー指定を省略した場合，YESが仮定されます。

    NO：ヘッダーを出力しません。

    ヘッダーには，問合せ式本体の結果から導出される各列の検索項目列名が，区切り文字で区切られて出力されます。検索項目列名については，「4.5.1　SELECT文の指定形式および規則」の「(4)　規則」を参照してください。

出力データ圧縮形式指定：
出力データ圧縮形式指定：：＝COMPRESSION ｛ZSTD｜SNAPPY｜GZIP｜LZ4｜BROTLI｜NONE｝

データを出力するファイルの圧縮形式を指定します。

CSV形式のデータを出力する場合は，このオプションは指定できません。

  • ZSTD

    ZSTD形式でファイルを圧縮します。出力データ圧縮形式指定を省略した場合，ZSTD形式でファイルを圧縮します。

  • SNAPPY

    SNAPPY形式でファイルを圧縮します。

  • GZIP

    GZIP形式でファイルを圧縮します。

  • LZ4

    LZ4形式でファイルを圧縮します。

  • BROTLI

    BROTLI形式でファイルを圧縮します。

  • NONE

    ファイルを圧縮しません。

ページの先頭へ

(3)　実行時に必要な権限

COPY文を実行する場合，次に示すすべての権限が必要になります。

ページの先頭へ

(4)　規則

  1. 問合せ式本体の結果から導出される列が，次のどれかのデータ型になる場合，COPY文がエラーになります。

    • PARQUET形式のデータを出力するとき

      TIME(0)，TIME(12)，TIMESTAMP(0) WITHOUT TIME ZONE，TIMESTAMP(12) WITHOUT TIME ZONE，TIMESTAMP(0) WITH TIME ZONE，TIMESTAMP(12) WITH TIME ZONE

      なお，問合せ式本体の結果から導出される列のデータ型がARRAY型の場合，要素データ型が上記のどれかのデータ型になるとCOPY文がエラーになります。

      また，問合せ式本体の結果から導出される列のデータ型がSTRUCT型の場合，フィールドデータ型が上記のどれかのデータ型になるとCOPY文がエラーになります。

    • CSV形式のデータを出力するとき

      TIME(12)，TIMESTAMP(12) WITHOUT TIME ZONE，TIMESTAMP(12) WITH TIME ZONE，UUID，ARRAY，STRUCT

  2. 次の条件をすべて満たす場合，COPY文がエラーになります。

    • 問合せ式本体の結果から導出される列にCHARACTER型，VARCHAR型，STRING型，ARRAY型※，またはSTRUCT型※の列がある

    • 上記の列のデータに，UTF8で表現できない文字が含まれている

    注※

    要素データ型がCHARACTER型，VARCHAR型，またはSTRING型で，その要素データ型のデータにUTF8で表現できない文字が含まれている場合に，COPY文がエラーになります。

    また，フィールドデータ型がCHARACTER型，VARCHAR型，またはSTRING型で，そのフィールドデータ型のデータにUTF8で表現できない文字が含まれている場合に，COPY文がエラーになります。

  3. CSV形式のデータを出力する場合，次の条件をすべて満たすとCOPY文がエラーになります。

    • 問合せ式本体の結果から導出される列に，BINARY型，VARBINARY型，ARRAY型※，またはSTRUCT型※の列がある

    • 上記の列のデータに，文字としてUTF8で表現できないバイナリ値が含まれている

    注※

    要素データ型がBINARY型またはVARBINARY型で，その要素データ型のデータに文字としてUTF8で表現できないバイナリ値が含まれている場合に，COPY文がエラーになります。

    また，フィールドデータ型がBINARY型またはVARBINARY型で，そのフィールドデータ型のデータに文字としてUTF8で表現できないバイナリ値が含まれている場合に，COPY文がエラーになります。

  4. 次の条件をすべて満たす場合，COPY文がエラーになります。

    • 問合せ式本体の結果から導出される列に，TIMESTAMP(9) WITHOUT TIME ZONE，TIMESTAMP(9) WITH TIME ZONE，ARRAY型※，またはSTRUCT型※の列がある

    • 上記の列に，1677-09-21 00:12:43.145224192～2262-04-11 23:47:16.854775807の範囲外のデータが含まれている

    注※

    要素データ型がTIMESTAMP(9) WITHOUT TIME ZONEまたはTIMESTAMP(9) WITH TIME ZONEで，その要素データ型のデータに1677-09-21 00:12:43.145224192～2262-04-11 23:47:16.854775807の範囲外のデータが含まれている場合に，COPY文がエラーになります。

    また，フィールドデータ型がTIMESTAMP(9) WITHOUT TIME ZONEまたはTIMESTAMP(9) WITH TIME ZONEで，そのフィールドデータ型のデータに1677-09-21 00:12:43.145224192～2262-04-11 23:47:16.854775807の範囲外のデータが含まれている場合に，COPY文がエラーになります。

  5. COPY文中に指定できる表，導出表，表関数導出表，および集まり導出表の延べ数は，最大2,048個になります。詳細については，「4.5.1　SELECT文の指定形式および規則」の「(4)　規則」を参照してください。

  6. COPY文中に指定している集合演算がすべてUNIONの場合，指定できる集合演算の数は最大1,023個になります。ただし，指定した集合演算にEXCEPTまたはINTERSECTがある場合は，指定できる集合演算の数は最大63個になります。

  7. COPY文中に指定できるFULL OUTER JOIN（またはFULL JOIN）の数は，最大63個になります。

  8. COPY文で出力されるデータの各列の名前は，問合せ式本体の導出列名と同じになります。導出列に列名が設定されていない場合，列の名前はEXPnnnn_NO_NAME（nnnnは0001～4000の符号なし整数）になります。導出列名については，「6.9　導出列名」を参照してください。

    なお，問合せ式本体の結果から導出される列がSTRUCT型の場合，COPY文で出力されるデータの各フィールドの名前は，STRUCT型の列に定義されているフィールド名と同じになります。

  9. PARQUET形式でデータを出力する場合，出力データの各列のデータ型は，COPY文の問合せ式本体の結果から導出される各列のHADBのデータ型を基に決定されます。HADBのデータ型とPARQUET形式のデータのデータ型の対応を次の表に示します。

    表4‒1　HADBのデータ型とPARQUET形式のデータのデータ型の対応

    HADBのデータ型

    PARQUET形式のデータのデータ型

    SMALLINT※1

    INT(bitWidth=16, isSigned=true)

    INTEGER※2

    INT(bitWidth=32, isSigned=true)

    BIGINT

    INT(bitWidth=64, isSigned=true)

    DECIMAL(m,n)※3

    DECIMAL(precision=m,scale=n)

    NUMERIC(m,n)※3

    REAL

    FLOAT

    DOUBLE PRECISION

    DOUBLE

    FLOAT

    CHARACTER

    STRING

    VARCHAR

    STRING

    BINARY

    BYTE_ARRAY

    VARBINARY

    DATE

    DATE

    TIME(3)

    TIME(timeUnit=milliseconds)

    TIME(6)

    TIME(timeUnit=microseconds)

    TIME(9)

    TIME(timeUnit=nanoseconds)

    TIMESTAMP(3) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=false)

    TIMESTAMP(6) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=false)

    TIMESTAMP(9) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=false)

    TIMESTAMP(3) WITH TIME ZONE

    TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=true)

    TIMESTAMP(6) WITH TIME ZONE

    TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=true)

    TIMESTAMP(9) WITH TIME ZONE

    TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=true)

    BOOLEAN

    BOOLEAN

    UUID

    UUID

    ARRAY

    LIST

    STRUCT

    STRUCT
    注※1

    整数データ型のデータ形式がレガシー形式の場合は，SMALLINTはINT(bitWidth=32, isSigned=true)に対応します。

    注※2

    整数データ型のデータ形式がレガシー形式の場合は，INTEGERはINT(bitWidth=64, isSigned=true)に対応します。

    注※3

    精度がm，位取りがnです。

  10. CSV形式でデータを出力する場合，出力データの各列のデータ型は次のように決定されます。

    • COPY文の問合せ式本体の結果から導出される各列のHADBのデータ型をApache Arrowのデータ型に変換し，それを基にデータ型が決定されます。

    HADBのデータ型とApache Arrowのデータ型の対応を次の表に示します。

    表4‒2　HADBのデータ型とApache Arrowのデータ型の対応

    HADBのデータ型

    Apache Arrowのデータ型

    SMALLINT※1

    INT16

    INTEGER※2

    INT32

    BIGINT

    INT64

    DECIMAL(m,n)※3

    DECIMAL128(m,n)

    NUMERIC(m,n)※3

    REAL

    FLOAT64

    DOUBLE PRECISION

    FLOAT

    CHARACTER

    STRING

    VARCHAR

    STRING

    DATE

    DATE32

    TIME(0)

    TIME32(timeUnit=seconds)

    TIME(3)

    TIME32(timeUnit=milliseconds)

    TIME(6)

    TIME64(timeUnit=microseconds)

    TIME(9)

    TIME64(timeUnit=nanoseconds)

    TIMESTAMP(0) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=seconds, isAdjustedToUTC=false)

    TIMESTAMP(3) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=false)

    TIMESTAMP(6) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=false)

    TIMESTAMP(9) WITHOUT TIME ZONE

    TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=false)

    TIMESTAMP(0) WITH TIME ZONE

    TIMESTAMP(timeUnit=seconds, isAdjustedToUTC=true)

    TIMESTAMP(3) WITH TIME ZONE

    TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=true)

    TIMESTAMP(6) WITH TIME ZONE

    TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=true)

    TIMESTAMP(9) WITH TIME ZONE

    TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=true)

    BINARY

    BINARY

    VARBINARY

    BOOLEAN

    BOOL
    注※1

    整数データ型のデータ形式がレガシー形式の場合は，SMALLINTはINT32に対応します。

    注※2

    整数データ型のデータ形式がレガシー形式の場合は，INTEGERはINT64に対応します。

    注※3

    精度がm，位取りがnです。

ページの先頭へ

(5)　例題

例題1

表T1のC1列およびC2列のデータを，外部サーバSERVER1上のオブジェクトストレージのs3://data/ディレクトリ下に出力します。PARQUET形式のデータを出力します。

COPY (SELECT "C1","C2" FROM "T1")
    TO 's3://data/'
    SERVER "SERVER1"
    OPTIONS (FORMAT PARQUET)

＜出力されるファイルの名称の例＞

  • adb-1234-1-1-1.parquet

  • adb-1234-1-1-2.parquet

  • adb-1234-1-2-1.parquet

  • adb-1234-1-3-1.parquet

例題2

表T1のC1列およびC2列のデータを，ファイルストレージの/data/ディレクトリ下に出力します。PARQUET形式のデータを出力します。また，ファイルのプレフィックスとしてres_sqlを指定します。

COPY (SELECT "C1","C2" FROM "T1")
    TO 'file:///data/res_sql'
    OPTIONS (FORMAT PARQUET)

＜出力されるファイルの名称の例＞

  • res_sql-1234-1-1-1.parquet

  • res_sql-1234-1-1-2.parquet

  • res_sql-1234-1-2-1.parquet

  • res_sql-1234-1-3-1.parquet

ページの先頭へ

(6)　留意事項

ページの先頭へ

All Rights Reserved. Copyright (C) 2012, 2026, Hitachi, Ltd.