3.6.1　CREATE FOREIGN TABLE文の指定形式および規則

(1)　指定形式

CREATE FOREIGN TABLE文：：＝
  CREATE FOREIGN TABLE 表名 〔(列定義〔,列定義〕…)〕
                      〔パーティションキー列指定〕
                      〔SERVER 外部サーバ名〕
                       OPTIONS (外部表オプション〔,外部表オプション〕…)
 
  列定義：：＝列名 データ型
　
  パーティションキー列指定：：＝PARTITIONED BY (列名 データ型〔,列名 データ型〕…)
 
  外部表オプション：：＝｛外部データのデータ形式指定
                         ｜外部データのディレクトリパス指定
                         ｜外部データのフォーマットオプション指定
                         ｜パーティションキー列のオプション指定
                         ｜Icebergオプション指定｝
 
    外部データのデータ形式指定：：＝FORMAT ｛CSV｜PARQUET｜JSON｜ICEBERG｝
 
    外部データのディレクトリパス指定：：＝LOCATION 外部データのディレクトリパス文字列
      外部データのディレクトリパス文字列：：＝文字列定数
 
    外部データのフォーマットオプション指定：：＝フォーマットオプション
                                              〔,フォーマットオプション〕…
      フォーマットオプション：：＝｛区切り文字指定｜囲み文字指定｜ヘッダー指定｝
          区切り文字指定：：＝DELIMITER_CHAR 区切り文字
          囲み文字指定：：＝ENCLOSING_CHAR ｛囲み文字｜NONE｝
          ヘッダー指定：：＝HEADER_SPEC ｛YES｜NO｝
             区切り文字：：＝文字列定数
             囲み文字　：：＝文字列定数
 
    パーティションキー列のオプション指定：：＝
                        パーティションキー列オプション〔,パーティションキー列オプション〕…
      パーティションキー列オプション：：＝｛属性プロパティ｜テンプレートディレクトリパス｝
        属性プロパティ：：＝｛列名.TYPE ｛ENUM｜INTEGER｜DATE｜TIME｜TIMESTAMP｝
                             ｜列名.VALUE 列挙文字列
                             ｜列名.RANGE_MIN ｛最小値整数｜最小値文字列｝
                             ｜列名.RANGE_MAX ｛最大値整数｜最大値文字列｝
                             ｜列名.FORMAT 日時書式文字列
                             ｜列名.INTERVAL 間隔値
                             ｜列名.DIGITS 桁数
                             ｜列名.INTERVAL．UNIT 時間単位｝
            列挙文字列：：＝文字列定数
            最小値整数：：＝整数定数
            最小値文字列：：＝文字列定数
            最大値整数：：＝整数定数
            最大値文字列：：＝文字列定数
            日時書式文字列：：＝文字列定数
            間隔値：：＝符号なし整数定数
            桁数：：＝符号なし整数定数
            時間単位：：＝｛YEAR｜MONTH｜WEEK｜DAY｜HOUR｜MINUTE｜SECOND｝
        テンプレートディレクトリパス：：＝
                              LOCATION.TEMPLATE テンプレートディレクトリパス文字列
            テンプレートディレクトリパス文字列：：＝文字列定数
 
    Icebergオプション指定：：＝Icebergオプション〔,Icebergオプション〕…
      Icebergオプション：：＝｛カタログ種別指定
                              ｜カタログ名前空間指定
                              ｜カタログURI指定
                              ｜カタログリージョン指定
                              ｜カタログID指定
                              ｜ウェアハウス名指定
                              ｜トークンURI指定
                              ｜クライアントID指定
                              ｜クライアントシークレット指定
                              ｜許可スコープ指定｝
        カタログ種別指定：：＝CATALOG_TYPE ｛REST｜GLUE｝
        カタログ名前空間指定：：＝CATALOG_NAMESPACE カタログ名前空間
            カタログ名前空間：：＝文字列定数
        カタログURI指定：：＝CATALOG_URI カタログエンドポイント文字列
            カタログエンドポイント文字列：：＝文字列定数
        カタログリージョン指定：：＝CATALOG_REGION カタログリージョン名
            カタログリージョン名：：＝文字列定数
        カタログID指定：：＝CATALOG_ID カタログID
            カタログID：：＝文字列定数
        ウェアハウス名指定：：＝WAREHOUSE_NAME ウェアハウス名
            ウェアハウス名：：＝文字列定数
        トークンURI指定：：＝AUTH_TOKEN_URI トークンURI
            トークンURI：：＝文字列定数
        クライアントID指定：：＝AUTH_CLIENT_ID クライアントID
            クライアントID：：＝文字列定数
        クライアントシークレット指定：：＝AUTH_CLIENT_SECRET クライアントシークレット
            クライアントシークレット：：＝文字列定数
        許可スコープ指定：：＝AUTH_ALLOWED_SCOPES 許可スコープ文字列
             許可スコープ文字列：：＝文字列定数

ページの先頭へ

(2)　指定形式の説明

列定義：：＝列名 データ型

パーティションキー列指定：：＝PARTITIONED BY (列名 データ型〔,列名 データ型〕…)

SERVER 外部サーバ名

OPTIONS (外部表オプション〔,外部表オプション〕…)
 
  外部表オプション：：＝｛外部データのデータ形式指定
                         ｜外部データのディレクトリパス指定
                         ｜外部データのフォーマットオプション指定
                         ｜パーティションキー列のオプション指定
                         ｜Icebergオプション指定｝

ページの先頭へ

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

CREATE FOREIGN TABLE文を実行する場合，CONNECT権限およびスキーマ定義権限が必要になります。

ページの先頭へ

(4)　規則

1. 外部表を定義する前にスキーマを定義しておいてください。

2. 自分（HADBサーバに接続中の認可識別子のHADBユーザ）が所有するスキーマに対してだけ外部表を定義できます。ほかのHADBユーザが所有するスキーマに対しては外部表を定義できません。

3. 実表と外部表を合計30,000個まで定義できます（ディクショナリ表（実表）およびシステム表（実表）は除く）。

4. 1つの外部表に対して4,000個まで列を定義できます。パーティションキー列を定義する場合，1つのパーティションキー列を1列と数えてください。

5. 外部表の検索時，検索対象となる外部データがない場合，外部表の検索結果の行数は0行になります。

6. 外部表の定義時には外部データへのアクセスは実行されません。外部表の検索時に外部データへのアクセスが実行されます。そのため，外部表を定義したあとに外部データを変更した場合，外部表の検索結果が変わることがあります。

7. 外部データのデータ形式指定にPARQUETまたはICEBERGを指定した場合，PARQUET形式の外部データにアクセスします。PARQUET形式の外部データの各列のデータ型とHADBのデータ型の対応を次の表に示します。

   表3‒6　PARQUET形式の外部データの各列のデータ型とHADBのデータ型の対応（その1）

   PARQUET形式の外部データの列のデータ型	対応するHADBのデータ型
   	SMALLINT※1	INTEGER※2	BIGINT	DECIMAL，NUMERIC	REAL	DOUBLE PRECISION，FLOAT
   NULL	○	○	○	○	○	○
   INT(bitWidth=8, isSigned=false)	○	○	○	×	×	×
   INT(bitWidth=8, isSigned=true)	○	○	○	×	×	×
   INT(bitWidth=16, isSigned=false)	△	○	○	×	×	×
   INT(bitWidth=16, isSigned=true)	○	○	○	×	×	×
   INT(bitWidth=32, isSigned=false)	△	△	○	×	×	×
   INT(bitWidth=32, isSigned=true)	△	○	○	×	×	×
   INT(bitWidth=64, isSigned=false)	△	△	△	×	×	×
   INT(bitWidth=64, isSigned=true)	△	△	○	×	×	×
   DECIMAL(precision=m, scale=n)	×	×	×	△	×	×
   FLOAT16	×	×	×	×	○	○
   FLOAT	×	×	×	×	○	○
   DOUBLE	×	×	×	×	×	○
   STRING	×	×	×	×	×	×
   BYTE_ARRAY	×	×	×	×	×	×
   FIXED_LEN_BYTE_ARRAY	×	×	×	×	×	×
   DATE	×	×	×	×	×	×
   TIME(timeUnit=milliseconds)	×	×	×	×	×	×
   TIME(timeUnit=microseconds)	×	×	×	×	×	×
   TIME(timeUnit=nanoseconds)	×	×	×	×	×	×
   TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=false)	×	×	×	×	×	×
   TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=false)	×	×	×	×	×	×
   TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=false)	×	×	×	×	×	×
   TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=true)	×	×	×	×	×	×
   TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=true)	×	×	×	×	×	×
   TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=true)	×	×	×	×	×	×
   BOOLEAN	×	×	×	×	×	×
   UUID	×	×	×	×	×	×
   LIST	×	×	×	×	×	×
   STRUCT	×	×	×	×	×	×
   MAP	×	×	×	×	×	×
   上記以外	×	×	×	×	×	×

   （凡例）

   ○：対応しています。

   △：対応しています。ただし，桁あふれなどでHADBのデータ型に変換できない場合は，SQL文がエラーになります。STRUCT型の各フィールドのフィールドデータ型，および配列型の各配列要素の要素データ型についても，HADBのデータ型に変換できない場合は，SQL文がエラーになります。

   ×：対応していません。

   注※1

   整数データ型のデータ形式がレガシー形式の場合は，INTEGER型と同じ対応になります。

   注※2

   整数データ型のデータ形式がレガシー形式の場合は，BIGINT型と同じ対応になります。

   表3‒7　PARQUET形式の外部データの各列のデータ型とHADBのデータ型の対応（その2）

   PARQUET形式の外部データの列のデータ型	対応するHADBのデータ型
   	文字データ	DATE	TIME	TIMESTAMP WITHOUT TIME ZONE	TIMESTAMP WITH TIME ZONE	バイナリデータ	ARRAY
   NULL	○	○	○	○	○	○	△※1
   INT(bitWidth=8, isSigned=false)	×	×	×	×	×	×	×
   INT(bitWidth=8, isSigned=true)	×	×	×	×	×	×	×
   INT(bitWidth=16, isSigned=false)	×	×	×	×	×	×	×
   INT(bitWidth=16, isSigned=true)	×	×	×	×	×	×	×
   INT(bitWidth=32, isSigned=false)	×	×	×	×	×	×	×
   INT(bitWidth=32, isSigned=true)	×	×	×	×	×	×	×
   INT(bitWidth=64, isSigned=false)	×	×	×	×	×	×	×
   INT(bitWidth=64, isSigned=true)	×	×	×	×	×	×	×
   DECIMAL(precision=m, scale=n)	×	×	×	×	×	×	×
   FLOAT16	×	×	×	×	×	×	×
   FLOAT	×	×	×	×	×	×	×
   DOUBLE	×	×	×	×	×	×	×
   STRING	△	×	×	×	×	×	×
   BYTE_ARRAY	×	×	×	×	×	△	×
   FIXED_LEN_BYTE_ARRAY	×	×	×	×	×	△	×
   DATE	×	○	×	×	×	×	×
   TIME(timeUnit=milliseconds)	×	×	△	×	×	×	×
   TIME(timeUnit=microseconds)	×	×	△	×	×	×	×
   TIME(timeUnit=nanoseconds)	×	×	△	×	×	×	×
   TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=false)	×	×	×	△	×	×	×
   TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=false)	×	×	×	△	×	×	×
   TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=false)	×	×	×	△	×	×	×
   TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=true)	×	×	×	×	△	×	×
   TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=true)	×	×	×	×	△	×	×
   TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=true)	×	×	×	×	△	×	×
   BOOLEAN	×	×	×	×	×	×	×
   UUID	×	×	×	×	×	×	×
   LIST	×	×	×	×	×	×	△
   STRUCT	×	×	×	×	×	×	×
   MAP	×	×	×	×	×	×	△※2
   上記以外	×	×	×	×	×	×	×

   （凡例）

   ○：対応しています。

   △：対応しています。ただし，桁あふれなどでHADBのデータ型に変換できない場合は，SQL文がエラーになります。STRUCT型の各フィールドのフィールドデータ型，および配列型の各配列要素の要素データ型についても，HADBのデータ型に変換できない場合は，SQL文がエラーになります。

   ×：対応していません。

   文字データ：CHARACTER，VARCHAR，STRING

   バイナリデータ：BINARY，VARBINARY

   注※1

   要素データ型にSTRUCT型を指定したARRAY型の列は，対応していません。

   注※2

   外部表の列定義を省略した場合，MAP型に対応する外部表の列のデータ型には次の配列型が定義されます。この配列型だけが対応しています。

   STRUCT{"key"   MAPのkeyのデータ型,
          "value" MAPのvalueのデータ型} ARRAY[30000]

   表3‒8　PARQUET形式の外部データの各列のデータ型とHADBのデータ型の対応（その3）

   PARQUET形式の外部データの列のデータ型	対応するHADBのデータ型
   	STRUCT	BOOLEAN	UUID
   NULL	×	○	○
   INT(bitWidth=8, isSigned=false)	×	×	×
   INT(bitWidth=8, isSigned=true)	×	×	×
   INT(bitWidth=16, isSigned=false)	×	×	×
   INT(bitWidth=16, isSigned=true)	×	×	×
   INT(bitWidth=32, isSigned=false)	×	×	×
   INT(bitWidth=32, isSigned=true)	×	×	×
   INT(bitWidth=64, isSigned=false)	×	×	×
   INT(bitWidth=64, isSigned=true)	×	×	×
   DECIMAL(precision=m, scale=n)	×	×	×
   FLOAT16	×	×	×
   FLOAT	×	×	×
   DOUBLE	×	×	×
   STRING	×	×	×
   BYTE_ARRAY	×	×	×
   FIXED_LEN_BYTE_ARRAY	×	×	×
   DATE	×	×	×
   TIME(timeUnit=milliseconds)	×	×	×
   TIME(timeUnit=microseconds)	×	×	×
   TIME(timeUnit=nanoseconds)	×	×	×
   TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=false)	×	×	×
   TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=false)	×	×	×
   TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=false)	×	×	×
   TIMESTAMP(timeUnit=milliseconds, isAdjustedToUTC=true)	×	×	×
   TIMESTAMP(timeUnit=microseconds, isAdjustedToUTC=true)	×	×	×
   TIMESTAMP(timeUnit=nanoseconds, isAdjustedToUTC=true)	×	×	×
   BOOLEAN	×	○	×
   UUID	×	×	○
   LIST	×	×	×
   STRUCT	△	×	×
   MAP	×	×	×
   上記以外	×	×	×

   （凡例）

   ○：対応しています。

   △：対応しています。ただし，桁あふれなどでHADBのデータ型に変換できない場合は，SQL文がエラーになります。STRUCT型の各フィールドのフィールドデータ型，および配列型の各配列要素の要素データ型についても，HADBのデータ型に変換できない場合は，SQL文がエラーになります。

   ×：対応していません。

8. CSV形式またはJSON形式の外部データを外部表に読み込む際，外部データアクセス用ライブラリを使用します。外部表の列定義に指定したHADBのデータ型に対応するApache Arrowのデータ型に変換したデータを外部表に読み込みます。HADBのデータ型とApache Arrowのデータ型の対応を次の表に示します。

   表3‒9　HADBのデータ型とApache Arrowのデータ型の対応

   外部表の列定義に指定したHADBのデータ型	対応するApache Arrowのデータ型
   SMALLINT※1	INT16
   INTEGER※2	INT32
   BIGINT	INT64
   DECIMAL(m,n)	DECIMAL128(m,n)
   NUMERIC(m,n)
   REAL	FLOAT32
   FLOAT	FLOAT64
   DOUBLE PRECISION
   CHAR	STRING
   VARCHAR
   STRING
   DATE	DATE32
   TIME(0)	TIME32(TimeUnit:SECOND)
   TIME(3)	TIME32(TimeUnit:MILLI)
   TIME(6)	TIME64(TimeUnit:MICRO)
   TIME(9)	TIME64(TimeUnit:NANO)
   TIMESTAMP(0) WITHOUT TIME ZONE	TIMESTAMP(TimeUnit:SECOND, isAdjustedToUTC=false)
   TIMESTAMP(3) WITHOUT TIME ZONE	TIMESTAMP(TimeUnit:MILLI, isAdjustedToUTC=false)
   TIMESTAMP(6) WITHOUT TIME ZONE	TIMESTAMP(TimeUnit:MICRO, isAdjustedToUTC=false)
   TIMESTAMP(9) WITHOUT TIME ZONE	TIMESTAMP(TimeUnit:NANO, isAdjustedToUTC=false)
   TIMESTAMP(0) WITH TIME ZONE	TIMESTAMP(TimeUnit:SECOND, isAdjustedToUTC=true)
   TIMESTAMP(3) WITH TIME ZONE	TIMESTAMP(TimeUnit:MILLI, isAdjustedToUTC=true)
   TIMESTAMP(6) WITH TIME ZONE	TIMESTAMP(TimeUnit:MICRO, isAdjustedToUTC=true)
   TIMESTAMP(9) WITH TIME ZONE	TIMESTAMP(TimeUnit:NANO, isAdjustedToUTC=true)
   BINARY	BINARY
   VARBINARY
   BOOLEAN	BOOL
   ARRAY	LIST※3
   STRUCT	STRUCT※4

   注

   Apache Arrowのデータ型については，Apache ArrowのドキュメントのData Typesを参照してください。

   注※1

   整数データ型のデータ形式がレガシー形式の場合，対応するApache Arrowのデータ型はINT32になります。

   注※2

   整数データ型のデータ形式がレガシー形式の場合，対応するApache Arrowのデータ型はINT64になります。

   注※3

   配列要素の要素データ型に対しても，上記の表の規則が適用されます。

   注※4

   フィールドのフィールドデータ型に対しても，上記の表の規則が適用されます。

   メモ

   外部データを読み込む際，Apache Arrowのデータ型に変換できないデータが含まれていると，SQL文がエラーになります。例えば，次のような場合にエラーになります。

   • Apache Arrowのデータ型の範囲（外部表の列定義で指定したHADBのデータ型の範囲）を超えるデータが外部データに含まれている場合

   • 外部表の列定義で指定したHADBのデータ型に対応するApache Arrowのデータ型に対して，互換性のないデータが外部データに含まれている場合（外部表の列定義のデータ型が数データの場合に，外部データ中に文字データが含まれているなど）

9. 外部データがCSV形式の場合，次の規則に対応している外部データを準備してください。

   • 外部データの1行のデータが，外部表の1行のデータになります。

   • 外部データのフィールドデータとフィールドデータの間を区切り文字で区切ってください。

   • 外部データのフィールドデータの両端に囲み文字を指定できます。

   • 空行の場合，外部表の全列にナル値が設定されます。

   • 外部データの1行の長さは，64メガバイト以下としてください。

   • 外部データの各フィールドデータの先頭と末尾に限り空白とタブを指定できます（先頭と末尾以外は指定できません）。ただし，文字列やバイナリデータの一部としての空白や，時刻印の表記法としての空白は問題ありません。

   • 外部データの各フィールドデータの形式は，外部表の列定義に指定するHADBのデータ型と対応させることを推奨します。対応を次の表に示します。

   表3‒10　外部表で定義するHADBのデータ型に対応するフィールドデータの指定形式

   外部表の列定義に指定するHADBのデータ型	推奨するフィールドデータの指定形式	指定例	説明および注意事項
   SMALLINT	整数	123 -123	正符号（+）は指定できません。例えば，+123とは指定できません。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。
   INTEGER
   BIGINT
   DECIMAL(m,n)	10進数	123.45 -123.45 +123 .12	ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。
   NUMERIC(m,n)
   REAL	浮動小数点数	1.234E5 1.234E+5 1.234E-5	指数部を表示する場合，指数部は省略できません。例えば，123Eとは指定できません。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。
   FLOAT
   DOUBLE PRECISION
   CHAR	文字列	ABC	ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。 フィールドデータ中に囲み文字と同じ文字がある場合は，囲み文字と同じ文字を2つ連続して指定してください。 列のデータ型がVARCHAR型またはSTRING型の場合に空文字を指定するときは，フィールドデータを空文字とし，囲み文字を指定してください。
   VARCHAR
   STRING
   DATE	日付	2025-03-01	日付は，YYYY-MM-DDの形式で指定してください。YYYYは年，MMは月，DDは日を意味しています。 年月日の区切りに，/は使用できません。例えば，2025/03/01とは指定できません。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。
   TIME(0)	時刻	11:22:33 11:22:33.123 11:22:33.123456 11:22:33.123456789	時刻は，hh:mm:ss.nn...nの形式で指定してください。hhは時，mmは分，ssは秒を意味しています。小数秒精度が1以上の場合は，.nn...nnと指定します。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。
   TIME(3)
   TIME(6)
   TIME(9)
   TIMESTAMP(0) WITHOUT TIME ZONE	時刻印（時刻帯なし）	2020-06-01 11:22:33 2020-06-01 11:22:33.123 2020-06-01 11:22:33.123456 2020-06-01 11:22:33.123456789	時刻帯なしの時刻印は，YYYY-MM-DD hh:mm:ss.nn...nの形式で指定してください。YYYYは年，MMは月，DDは日，hhは時，mmは分，ssは秒を意味しています。小数秒精度が1以上の場合は，.nn...nnと指定します。 また，DDの後には半角空白を入れてください。 年月日の区切りに，/は使用できません。例えば，2025/03/01 12:34:56とは指定できません。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。 外部表の列定義でTIMESTAMP(9) WITHOUT TIME ZONEを指定する場合，1677-09-21 00:12:43.145224192～2262-04-11 23:47:16.854775807の範囲の値を指定してください。範囲外の値を指定した場合，不正な値が返却されます。
   TIMESTAMP(3) WITHOUT TIME ZONE
   TIMESTAMP(6) WITHOUT TIME ZONE
   TIMESTAMP(9) WITHOUT TIME ZONE
   TIMESTAMP(0) WITH TIME ZONE	時刻印（時刻帯付き）	2025-06-01 11:22:33+00:00 2025-06-01 20:22:33+09:00 2025-06-01 11:22:33Z 2025-06-01 11:22:33.123+00:00 2025-06-01 11:22:33.123456+00:00 2025-06-01 11:22:33.123456789+00:00	時刻帯付きの時刻印は，YYYY-MM-DD hh:mm:ss.nn...n±hh:mmの形式で指定してください。YYYYは年，MMは月，DDは日，hhは時，mmは分，ssは秒を意味しています。小数秒精度が1以上の場合は，.nn...nnと指定します。 また，DDの後には半角空白を入れてください。 時刻帯は，±hh:mmの形式で指定してください。時（hh），分（mm）の桁数が足りない場合は，左側に0を記述してください。また，+00:00の代わりにZを指定できます。 年月日の区切りに，/は使用できません。例えば，2025/03/01 12:34:56+00:00とは指定できません。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。 外部表の列定義でTIMESTAMP(9) WITH TIME ZONEを指定する場合，1677-09-21 00:12:43.145224192+00:00～2262-04-11 23:47:16.854775807+00:00の範囲の値を指定してください。範囲外の値を指定した場合，不正な値が返却されます。
   TIMESTAMP(3) WITH TIME ZONE
   TIMESTAMP(6) WITH TIME ZONE
   TIMESTAMP(9) WITH TIME ZONE
   BINARY	文字列	ABCD	指定されているデータをそのままバイナリデータとして外部表に読み込みます。例えば，文字列にABCDと指定した場合，外部表には0x41424344で読み込まれます。 16進文字列と2進文字列によるデータの表現はできません。 ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。 フィールドデータ中に囲み文字と同じ文字がある場合は，囲み文字と同じ文字を2つ連続して指定してください。 列のデータ型がVARBINARY型の場合に空文字を指定するときは，フィールドデータを空文字とし，囲み文字を指定してください。
   VARBINARY
   BOOLEAN	真偽値	True False true false TRUE FALSE	ナル値を設定したい場合は，フィールドデータを空文字とし，囲み文字を指定しないでください。 指定例以外の形式は，BOOLEAN型として認識しません。

10. 外部データがJSON形式の場合，次の規則に対応している外部データを準備してください。

    • JSONファイルの記述形式は，各JSONオブジェクトを改行で区切って記述する形式であるLine-separated JSON（JSONL）を推奨します。

    • 改行で区切られた1つのJSONオブジェクトに，表の1行のデータを記述してください。

    • 各JSONオブジェクトは改行で区切って記述してください。コンマ（ , ）で区切って記述しないでください。

    • 各JSONオブジェクトは，波括弧（｛ ｝）で囲んでください。

    • JSONオブジェクトの値の中に，JSONの仕様に従っていない空白を含むことはできません。

    • JSONオブジェクトの値としてナル値を設定したい場合，値にnullと記述してください。nullは二重引用符（"）で囲まないでください。

    • JSONファイル中の1行の長さは，64メガバイト以下としてください。

    • JSONオブジェクトは，キーと値のペアで構成され，次の記述形式で表現されます。

      〔キー：値〔,キー：値〕…〕

      1つのキーと値のペアが，表の1列分のデータに対応します。また，キーには対応する列名を，値には列のデータ型に対応する値を指定します。

      なお，JSONファイルの一部またはすべての行で，外部表の列定義に対応するキーと値のペアが存在しない場合でも，SQL文はエラーになりません。行中に存在しないキーの値としてナル値が設定されます。

      キーと値の推奨する指定形式を次の表に示します。

      表3‒11　キーと値の推奨する指定形式

      外部表の列定義に指定するHADBのデータ型	キーと値の推奨する指定形式	指定例	説明および注意事項
      SMALLINT	"列名"：整数	"C1":123 "C1":-123	整数には，二重引用符の囲み文字を指定できません。例えば，"C1":"123"とは指定できません。 正符号（+）は指定できません。例えば，"C1":+123とは指定できません。 整数の先頭に不要な0を付けることはできません。例えば，"C1":0123とは指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。
      INTEGER
      BIGINT
      DECIMAL(m,n)	"列名"：10進数	"C1":123.45 "C1":-123.45	10進数には，二重引用符の囲み文字を指定できません。例えば，"C1":"123.45"とは指定できません。 正符号（+）は指定できません。例えば，"C1":+123.45とは指定できません。 10進数の先頭に不要な0を付けることはできません。例えば，"C1":0123.45とは指定できません。 10進数の整数部は省略できません。例えば，"C1":.12とは指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。
      NUMERIC(m,n)
      REAL	"列名"：浮動小数点数	"C1":1.234E5 "C1":1.234E+5 "C1":1.234E-5	浮動小数点数には，二重引用符の囲み文字を指定できません。例えば，"C1":"1234E5"とは指定できません。 正符号（+）は指定できません。例えば，"C1":+1234E5とは指定できません。 浮動小数点数の先頭に不要な0を付けることはできません。例えば，"C1":01234E5とは指定できません。 浮動小数点数の整数部は省略できません。例えば，"C1":E5とは指定できません。 指数部を表示する場合，指数部は省略できません。例えば，"C1":123Eとは指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。
      FLOAT
      DOUBLE PRECISION
      CHAR	"列名"："文字列"	"C1":"ABC"	二重引用符の囲み文字で囲まれていない文字列は読み込めません。 改行（\n），タブ（\t），バックスラッシュ（\\）などの制御文字は，エスケープする必要があります。例えば，"C1":"A\nB"と指定すると，\nは改行を意味します。 ナル値を設定したい場合は，"列名":nullと指定してください。
      VARCHAR
      STRING
      DATE	"列名"：整数	"C1":18414	整数には，二重引用符の囲み文字を指定できません。例えば，"C1":"123"とは指定できません。 正符号（+）は指定できません。例えば，"C1":+123とは指定できません。 整数の先頭に不要な0を付けることはできません。例えば，"C1":0123とは指定できません。 整数には，UNIX epoch（1970/01/01）を0とした通算日を指定します。例えば，"C1":18414と指定した場合は，"2020-06-01"となります。 "C1":"2025-03-01"などの文字列表現は指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。
      TIME(0)	"列名"：整数	"C1":45296789	整数には，二重引用符の囲み文字を指定できません。例えば，"C1":"123"とは指定できません。 正符号（+）は指定できません。例えば，"C1":+123とは指定できません。 整数の先頭に不要な0を付けることはできません。例えば，"C1":0123とは指定できません。 整数には，00:00:00を0とし，通算した秒，ミリ秒，マイクロ秒，ナノ秒を指定します。例えば，HADBのデータ型がTIME(3)で，"C1":45296789を指定した場合は，"12:34:56.789"となります。 "C1":"12:34:56.789"などの文字列表現は指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。
      TIME(3)
      TIME(6)
      TIME(9)
      TIMESTAMP(0) WITHOUT TIME ZONE	"列名"："時刻帯なしの時刻印"	"C1":"2020-06-01 11:22:33" "C1":"2020-06-01 11:22:33.123" "C1":"2020-06-01 11:22:33.123456" "C1":"2020-06-01 11:22:33.123456789"	時刻帯なしの時刻印は，YYYY-MM-DD hh:mm:ss.nn...nの形式で指定してください。YYYYは年，MMは月，DDは日，hhは時，mmは分，ssは秒を意味しています。小数秒精度が1以上の場合は，.nn...nnと指定します。 また，DDの後には半角空白を入れてください。 二重引用符の囲み文字で囲まれていない時刻印の値は読み込めません。 年月日の区切りに，/は使用できません。例えば，2025/03/01 12:34:56とは指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。 外部表の列定義でTIMESTAMP(9) WITHOUT TIME ZONEを指定する場合，1677-09-21 00:12:43.145224192～2262-04-11 23:47:16.854775807の範囲の値を指定してください。範囲外の値を指定した場合，不正な値が返却されます。
      TIMESTAMP(3) WITHOUT TIME ZONE
      TIMESTAMP(6) WITHOUT TIME ZONE
      TIMESTAMP(9) WITHOUT TIME ZONE
      TIMESTAMP(0) WITH TIME ZONE	"列名"："時刻帯付きの時刻印"	"C1":"2025-06-01 11:22:33+00:00" "C1":"2025-06-01 20:22:33+09:00" "C1":"2025-06-01 11:22:33Z" "C1":"2025-06-01 11:22:33.123+00:00" "C1":"2025-06-01 11:22:33.123456+00:00" "C1":"2025-06-01 11:22:33.123456789+00:00"	時刻帯付きの時刻印は，YYYY-MM-DD hh:mm:ss.nn...n±hh:mmの形式で指定してください。YYYYは年，MMは月，DDは日，hhは時，mmは分，ssは秒を意味しています。小数秒精度が1以上の場合は，.nn...nnと指定します。 また，DDの後には半角空白を入れてください。 時刻帯は，±hh:mmの形式で指定してください。時（hh），分（mm）の桁数が足りない場合は，左側に0を記述してください。また，+00:00の代わりにZを指定できます。 二重引用符の囲み文字で囲まれていない時刻印の値は読み込めません。 年月日の区切りに，/は使用できません。例えば，2025/03/01 12:34:56+00:00とは指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。 外部表の列定義でTIMESTAMP(9) WITH TIME ZONEを指定する場合，1677-09-21 00:12:43.145224192+00:00～2262-04-11 23:47:16.854775807+00:00の範囲の値を指定してください。範囲外の値を指定した場合，不正な値が返却されます。
      TIMESTAMP(3) WITH TIME ZONE
      TIMESTAMP(6) WITH TIME ZONE
      TIMESTAMP(9) WITH TIME ZONE
      BINARY	"列名"："文字列"	"C1":"ABCD"	二重引用符の囲み文字で囲まれていない文字列は読み込めません。 指定されているデータをそのままバイナリデータとして外部表に読み込みます。例えば，文字列にABCDと指定した場合，外部表には0x41424344で読み込まれます。 16進文字列と2進文字列によるデータの表現はできません。 改行（\n），タブ（\t），バックスラッシュ（\\）などの制御文字は，エスケープする必要があります。例えば，"C1":"A\nB"と指定すると，\nは改行を意味します。 ナル値を設定したい場合は，"列名":nullと指定してください。
      VARBINARY
      BOOLEAN	"列名"：真偽値	"C1":true "C1":false	真偽値には，二重引用符の囲み文字を指定できません。例えば，"C1":"true"とは指定できません。 真偽値には，大文字を指定できません。例えば，"C1":Trueとは指定できません。 ナル値を設定したい場合は，"列名":nullと指定してください。
      ARRAY	"列名"：[配列要素値〔,配列要素値〕…]	"C1":["A","B","C"]	配列要素値には，要素データ型に対応した値を，この表で説明しているデータ型の指定形式に従って指定してください。 ナル値を設定したい場合は，"列名":nullと指定してください。 配列要素値にナル値を設定したい場合は，配列要素値にnullを指定してください。
      STRUCT	"列名"：{フィールド名：フィールド値〔,フィールド名：フィールド値〕…}	"C1":{"F1":"X", "F2":"Y", "F3":"Z"}	フィールド名には，構造データのフィールド名を指定します。 フィールド値には，フィールドデータ型に対応した値を，この表で説明しているデータ型の指定形式に従って指定してください。 ナル値を設定したい場合は，"列名":nullと指定してください。 フィールド値にナル値を設定したい場合は，フィールド値にnullを指定してください。

ページの先頭へ

(5)　列定義の指定を省略した場合の規則

列定義の指定を省略した場合，ここで説明する規則に従って列定義が生成されます。

ページの先頭へ

(6)　留意事項

外部データのデータ形式指定にICEBERGを指定したときの留意事項を説明します。

1. 検索対象となる外部データは，すべてPARQUET形式のファイルに格納されている必要があります。

2. 行レベルの更新によって削除ファイルが生成されたIcebergテーブルは検索できません。

3. 外部表の検索時，Icebergテーブルのメタデータを基に，外部表の列定義（列名，列のデータ型など）が生成されます。このとき，「(5)　列定義の指定を省略した場合の規則」の「(a)　外部データのデータ形式指定にICEBERGを指定する場合」で説明している規則に従って外部表の列定義が生成されます。

   また，外部表の検索時にタイムトラベル指定を指定している場合（過去のメタデータを参照している場合），タイムトラベル指定で指定したスナップショットのメタデータを基に，外部表の列定義（列名，列のデータ型など）が生成されます。

4. ディクショナリ表（SQL_TABLES表，SQL_COLUMNS表，SQL_DATATYPE_DESCRIPTORS表）に格納されている外部表の列定義に関する情報は，外部表の定義時点のものです。外部表の検索時点のものではありません。そのため，メタデータに含まれている列定義に関する情報を変更した場合，ディクショナリ表に格納されている外部表の列定義に関する情報と，外部表の検索時に使用される外部表の列定義に関する情報が不一致になります。一致させたい場合は，いったん外部表を削除したあとに，外部表を定義し直してください。

   ただし，外部表の検索時にタイムトラベル指定を指定した場合は，外部表を定義し直しても，ディクショナリ表に格納されている情報と一致しません。

5. 外部表を基表とするビュー表を検索する場合，ビュー表の検索時点のメタデータを基に外部表の列定義が生成されます。ビュー表の定義時とビュー表の検索時で，外部表の列定義が異なる場合（ビュー表を定義したあとに，メタデータに含まれている列定義に関する情報を変更した場合），ビュー表の検索時にSQL文がエラーになります。その場合は，ALTER VIEW文などでビュー表を再作成してください。

   なお，外部表に対してタイムトラベル指定を指定して定義したビュー表の場合は，ビュー表の定義時とビュー表の検索時で外部表の列定義が異なることがないため（同じスナップショットのメタデータを参照するため），ビュー表の検索時にSQL文がエラーになることはありません。

6. 外部データのデータ形式指定にICEBERGを指定して定義した外部表は，Icebergのスキーマ進化（Schema Evolution）に対応しています。ただし，Icebergテーブルのメタデータおよびデータファイルのメタデータから，データファイルごとの定義情報を一意に特定できるようにしておく必要があります。データファイルにメタデータを設定しない方法でIcebergテーブルにデータファイルの定義情報を登録した場合，スキーマ進化を実行するとデータファイルの定義情報をHADBサーバが特定できなくなります。その結果，外部表の検索時にSQL文がエラーになることがあります。エラーが発生した場合は，Icebergテーブルに対してデータファイルの再生成を実行してください。

7. 外部表の検索時，外部表の列定義（列名，列のデータ型など）がIcebergテーブルのメタデータから生成されます。そのため，外部表の検索時にIcebergのスキーマ進化（Schema Evolution）を実行すると，外部表の列定義の不一致が原因で外部表の検索がエラーになることがあります。

ページの先頭へ

(7)　例題

■パーティションキー列を指定しない場合

パーティションキー列を指定しない外部表の定義例を説明します。

外部データを格納している外部データファイルの構成は，次のようになっているとします。

例題1

外部表（FT1）を定義します。

CREATE FOREIGN TABLE "FT1" ("C1" INTEGER,"C2" INTEGER)   ...1
  SERVER "SERVER1"                                       ...2
  OPTIONS (                                              ...3
            FORMAT CSV                                   ...4
           ,LOCATION 's3://data/'                        ...5
          )

［説明］

1. 外部表の表名，および外部表の列定義を指定します。

2. 外部表が使用する外部サーバの名称を指定します。

3. OPTIONS以降には外部表オプションを指定します。

4. 外部データのデータ形式を指定します。外部データがCSV形式のため，CSVを指定します。

5. 外部データの検索対象ディレクトリのパスを指定します。

   外部表FT1の検索時，s3://data/ディレクトリ下のすべての外部データファイル中の外部データが検索対象になるため，「外部データファイルの構成」に示す［1］～［14］の外部データファイル中の外部データが検索対象になります。

例題2

外部表（FT2）を定義します。

CREATE FOREIGN TABLE "FT2" ("C1" INTEGER,"C2" INTEGER)   ...1
  SERVER "SERVER1"                                       ...2
  OPTIONS (                                              ...3
            FORMAT CSV                                   ...4
           ,LOCATION 's3://data/2025/'                   ...5
           ,DELIMITER_CHAR '.'                           ...6
           ,ENCLOSING_CHAR '@'                           ...7
           ,HEADER_SPEC YES                              ...8
          )

［説明］

1. 外部表の表名，および外部表の列定義を指定します。

2. 外部表が使用する外部サーバの名称を指定します。

3. OPTIONS以降には外部表オプションを指定します。

4. 外部データのデータ形式を指定します。外部データがCSV形式のため，CSVを指定します。

5. 外部データの検索対象ディレクトリのパスを指定します。

   外部表FT2の検索時，s3://data/2025/ディレクトリ下のすべての外部データファイル中の外部データが検索対象になるため，「外部データファイルの構成」に示す［11］～［14］の外部データファイル中の外部データが検索対象になります。

6. CSV形式の外部データの区切り文字（ . ）を指定します。

7. CSV形式の外部データの囲み文字（@）を指定します。

8. CSV形式の外部データの先頭1行目をヘッダー行として読み込む指定をします。

■パーティションキー列を指定する場合

パーティションキー列を指定する外部表の定義例を説明します。

外部データを格納している外部データファイルの構成は，次のようになっているとします。

例題

外部表（ACCESSLOG）を定義します。

CREATE FOREIGN TABLE "ACCESSLOG" ("ID" INTEGER,"USERID" CHAR(5))      ...1
  PARTITIONED BY ("YEAR" INTEGER,"MONTH" INTEGER,"DAY" INTEGER)       ...2
  SERVER "SERVER1"                                                    ...3
  OPTIONS (                                                           ...4
            FORMAT CSV                                                ...5
           ,LOCATION 's3://data/'                                     ...6
           ,"YEAR".TYPE ENUM                                          ...7
           ,"YEAR".VALUE '2024,2025'                                  ...7
           ,"MONTH".TYPE INTEGER                                      ...8
           ,"MONTH".RANGE_MIN 1                                       ...8
           ,"MONTH".RANGE_MAX 2                                       ...8
           ,"MONTH".INTERVAL 1                                        ...8
           ,"MONTH".DIGITS 2                                          ...8
           ,"DAY".TYPE INTEGER                                        ...9
           ,"DAY".RANGE_MIN 1                                         ...9
           ,"DAY".RANGE_MAX 2                                         ...9
           ,"DAY".INTERVAL 1                                          ...9
           ,"DAY".DIGITS 2                                            ...9
           ,LOCATION.TEMPLATE 's3://data/${YEAR}/${MONTH}/${DAY}/'    ...10
         )

［説明］

1. 外部表の表名，および外部表の列定義を指定します。

2. パーティションキー列を定義します。この例の場合，YEAR，MONTH，DAYをパーティションキー列として定義しています。

3. 外部表が使用する外部サーバの名称を指定します。

4. OPTIONS以降には外部表オプションを指定します。

5. 外部データのデータ形式を指定します。外部データがCSV形式のため，CSVを指定します。

6. 外部データの検索対象ディレクトリのパスを指定します。

7. パーティションキー列YEARの属性プロパティを指定します。パーティションキー列YEARの値が，2024および2025となるように定義しています。

8. パーティションキー列MONTHの属性プロパティを指定します。パーティションキー列MONTHの値が，1および2（テンプレートディレクトリパスの変数値として使用される値は01および02）となるように定義しています。

9. パーティションキー列DAYの属性プロパティを指定します。パーティションキー列DAYの値が，1および2（テンプレートディレクトリパスの変数値として使用される値は01および02）となるように定義しています。

10. テンプレートディレクトリパスを指定します。

    外部表ACCESSLOGの検索時，テンプレートディレクトリパスの指定を基に決定されたディレクトリが，外部データの検索対象ディレクトリとなり，このディレクトリ下の外部データファイル中の外部データが検索対象になります。「外部データファイルの構成」に示す［1］～［4］，［7］，［8］，［11］，［12］の外部データファイル中の外部データが検索対象になります。

パーティションキー列を指定したSELECT文の例を次に示します。

（例1）

SELECT "YEAR","MONTH","DAY","USERID" FROM "ACCESSLOG"
    ORDER BY "YEAR","MONTH","DAY","USERID"

下線部分がパーティションキー列の指定です。

この場合，CREATE FOREIGN TABLE文で定義したテンプレートディレクトリパスの指定に従って，「外部データファイルの構成」に示す［1］～［4］，［7］，［8］，［11］，［12］の外部データファイル中の外部データが検索対象になります。

＜SELECT文の実行結果の例＞

（例2）

SELECT "YEAR","MONTH","DAY","USERID" FROM "ACCESSLOG"
  WHERE "DAY" = 2
    ORDER BY "YEAR","MONTH","DAY","USERID"

下線部分がパーティションキー列の指定です。

WHERE句に指定した探索条件によって，パーティションキー列DAYの値が2（テンプレートディレクトリパスの変数値として使用される値は02）に絞り込まれるため，「外部データファイルの構成」に示す［3］，［4］，［8］の外部データファイル中の外部データが検索対象になります。

＜SELECT文の実行結果の例＞

（例3）

SELECT "YEAR","MONTH","DAY","USERID" FROM "ACCESSLOG"
  WHERE "DAY" = 2 AND "USERID" IN ('U0005','U0010')
    ORDER BY "YEAR","MONTH","DAY","USERID"

下線部分がパーティションキー列の指定です。

WHERE句に指定した探索条件（"DAY" = 2）によって，パーティションキー列DAYの値が2（テンプレートディレクトリパスの変数値として使用される値は02）になるため，「外部データファイルの構成」に示す［3］，［4］，［8］の外部データファイル中の外部データが検索対象になります。そして，もう1つの探索条件である"USERID" IN ('U005','U0010')の指定に従って実行結果が返されます。

＜SELECT文の実行結果の例＞

■Icebergテーブルで管理している外部データを読み込む外部表を定義する場合

例題1

外部表（REST_ACCESSLOG）を定義します。

Icebergテーブルを使用して外部データにアクセスします。カタログは，REST Catalogを使用します。

CREATE FOREIGN TABLE "REST_ACCESSLOG" ("ID" INT,"USERID" CHAR(5))
    SERVER "SERVER1"
    OPTIONS (
          FORMAT ICEBERG                            ...1
         ,CATALOG_TYPE REST                         ...2
         ,CATALOG_NAMESPACE 'analytics_sales'
         ,CATALOG_URI 'https://access-api/catalog/iceberg'
         ,WAREHOUSE_NAME 'accesslog_catalog'
         ,AUTH_TOKEN_URI 'https://auth-api/realms/rest/protocol/openid-connect/token'
         ,AUTH_CLIENT_ID 'rest-catalog-id'
         ,AUTH_CLIENT_SECRET 'secret1234567890'
         ,AUTH_ALLOWED_SCOPES 'catalog'
         )

［説明］

1. 外部データのデータ形式指定にはICEBERGを指定します。

2. Icebergで使用するカタログの種別を指定します。REST Catalogを使用する場合はRESTを指定します。

例題2

外部表（GLUE_ACCESSLOG）を定義します。

Icebergテーブルを使用して外部データにアクセスします。カタログは，Glue Catalogを使用します。

CREATE FOREIGN TABLE "GLUE_ACCESSLOG" ("ID" INT,"USERID" CHAR(5))
    SERVER "SERVER1"
    OPTIONS (
             FORMAT ICEBERG                            ...1
            ,CATALOG_TYPE GLUE                         ...2
            ,CATALOG_NAMESPACE 'analytics_sales'
            ,CATALOG_REGION 'ap-northeast-1'
            ,CATALOG_ID '123456789012'
           )

［説明］

1. 外部データのデータ形式指定にはICEBERGを指定します。

2. Icebergで使用するカタログの種別を指定します。Glue Catalogを使用する場合はGLUEを指定します。

ページの先頭へ