ORACLE_HDFSおよびORACLE_HIVEアクセス・ドライバ

17 ORACLE_HDFSおよびORACLE_HIVEアクセス・ドライバ

外部表を使用すると、Oracle Databaseの表に格納されたデータであるかのように、HadoopおよびHiveクライアント上のHDFSおよびHive表に格納されているデータにアクセスできます。

ORACLE_HDFSまたはORACLE_HIVEアクセス・ドライバを使用する外部表を作成するために使用するプロパティは、SQL文 CREATE TABLE ORGANIZATION EXTERNALでACCESS PARAMETERSのopaque_format_spec句の中に指定します。

プロパティを指定するための構文ルール
プロパティは、SQL CREATE TABLEのACCESS PARAMETERS句および構成ファイル内に、キーワード/値のペアを使用して設定します。
ORACLE_HDFSアクセス・パラメータ
ORACLE_HDFSアクセス・ドライバのアクセス・パラメータは、HDFS内のデータを特定し、それに基づいてHive表を作成するために必要なメタデータを提供します。
ORACLE_HIVEアクセス・パラメータ
ORACLE_HIVEは、Hiveカタログから外部データ・ソースに関するメタデータを取得します。
com.oracle.bigdataパラメータの説明
com.oracle.bigdataパラメータは、ORACLE_HIVE、ORACLE_HDFSおよびORACLE_BIGDATAアクセス・ドライバによって使用されます。

関連トピック

外部表の例

親トピック: 外部表

17.1 プロパティを指定するための構文ルール

プロパティは、SQL CREATE TABLEのACCESS PARAMETERS句および構成ファイル内に、キーワード/値のペアを使用して設定します。

構文は次のルールに従う必要があります。

各キーワード/値のペアの形式は、キーワード、コロンまたは等号と、値です。有効なキーワード/値のペアを次に示します。
```
keyword=value
keyword:value
```
値は、セパレータの後の最初の非空白文字から行末までのすべてになります。セパレータと値の間の空白は無視されます。値の後の空白は保持されます。
プロパティ定義は1行または複数行にできます。
行の終了文字は、LF、改行または改行とLFの組合せです。
1つのプロパティ定義が複数行にわたる場合は、最終行以外の行の終了文字の前にバックスラッシュ(エスケープ文字)を付けます。この例では、Keyword1プロパティの値はValue part 1 Value part 2 Value part 3です。
```
Keyword1=  Value part 1 \
           Value part 2 \
           Value part 3
```
先頭の空白の各物理行を削除して行を連結することで、論理行を作成できます。パーサーによって、プロパティ名および値が論理行から抽出されます。
文字の前に代入を示すバックスラッシュ(エスケープ文字)を付けることで、プロパティ名またはプロパティ値に特殊文字を埋め込むことができます。次の表で、特殊文字について説明します。

表17-1 プロパティの特殊文字

エスケープ・シーケンス	文字
`\b`	バックスペース(`\u0008`)
`\t`	水平タブ(`\u0009`)
`\n`	LF (`\u000a)`
`\f`	改ページ(`\u000c`)
`\r`	改行(`\u000d`)
`\"`	二重引用符(`\u0022`)
`\'`	一重引用符(`\u0027`)
`\\`	バックスラッシュ(`\u005c`) 複数のバックスラッシュが行末にある場合、パーサーは奇数のバックスラッシュに対してのみ値を次の行に継続します。
`\uxxxx`	2バイト、ビッグ・エンディアンのUnicodeコード・ポイント。 1文字に2コード・ポイント(4バイト)が必要な場合、パーサーは2番目のコード・ポイントに`\u`を要求します。

親トピック: ORACLE_HDFSおよびORACLE_HIVEアクセス・ドライバ

17.2 `ORACLE_HDFS`アクセス・パラメータ

ORACLE_HDFSアクセス・ドライバのアクセス・パラメータは、HDFS内のデータを特定し、それに基づいてHive表を作成するために必要なメタデータを提供します。

ORACLE_HDFSのデフォルトのパラメータ設定
ORACLE_HDFSのデフォルトのパラメータ設定について説明します。
ORACLE_HDFSのオプションのパラメータ設定
ORACLE_HDFSでは、オプションのcom.oracle.bigdataパラメータがサポートされており、opaque_format_spec句で指定できます。

親トピック: ORACLE_HDFSおよびORACLE_HIVEアクセス・ドライバ

17.2.1 `ORACLE_HDFS`のデフォルトのパラメータ設定

ORACLE_HDFSのデフォルトのパラメータ設定について説明します。

CREATE TABLE文からすべてのアクセス・パラメータを省略した場合、ORACLE_HDFSは次のデフォルト値を使用します。

com.oracle.bigdata.rowformat=DELIMITED
com.oracle.bigdata.fileformat=TEXTFILE
com.oracle.bigdata.overflow={"action":"error"}
com.oracle.bigdata.erroropt={"action":"setnull"}

親トピック: ORACLE_HDFSアクセス・パラメータ

17.2.2 ORACLE_HDFSのオプションのパラメータ設定

ORACLE_HDFSは、オプションのcom.oracle.bigdataパラメータをサポートしています。これらのパラメータは、opaque_format_spec句で指定できます。

具体的には次のとおりです。

com.oracle.bigdata.colmap
com.oracle.bigdata.erroropt
com.oracle.bigdata.fields
com.oracle.bigdata.fileformat
com.oracle.bigdata.log.exec
com.oracle.bigdata.log.qc
com.oracle.bigdata.overflow
com.oracle.bigdata.rowformat

次の例に、複数のアクセス・パラメータが設定されているCREATE TABLE文を示します。

例17-1 ORACLE_HDFSの複数のアクセス・パラメータの設定

CREATE TABLE ORDER (CUST_NUM VARCHAR2(10), 
                    ORDER_NUM VARCHAR2(20), 
                    ORDER_DATE DATE,
                    ITEM_CNT NUMBER,
                    DESCRIPTION VARCHAR2(100),
                    ORDER_TOTAL (NUMBER8,2)) ORGANIZATION EXTERNAL 
             (TYPE ORACLE_HDFS
 ACCESS PARAMETERS (
  com.oracle.bigdata.fields: (CUST_NUM,              \
                              ORDER_NUM,             \
                              ORDER_DATE,            \
                              ORDER_LINE_ITEM_COUNT, \
                              DESCRIPTION,           \
                              ORDER_TOTAL)
  com.oracle.bigdata.colMap:     {"col":"item_cnt", \
                                  "field":"order_line_item_count"}
  com.oracle.bigdata.overflow:   {"action":"TRUNCATE", \
                                  "col":"DESCRIPTION"}
  com.oracle.bigdata.errorOpt:  [{"action":"replace", \
                                  "value":"INVALID NUM", \
                                  "col":["CUST_NUM","ORDER_NUM"]} , \
                                 {"action":"reject", \
                                  "col":"ORDER_TOTAL}]
 )
 LOCATION ("hdfs:/usr/cust/summary/*"));

親トピック: ORACLE_HDFSアクセス・パラメータ

17.3 `ORACLE_HIVE`アクセス・パラメータ

ORACLE_HIVEは、Hiveカタログから外部データ・ソースに関するメタデータを取得します。

通常、外部データ表の列へのHiveデータのデフォルト・マッピングは適切です。ただし、状況によっては、特殊なパラメータ設定が必要になることや、独自の理由でデフォルト値を上書きすることがあります。

ORACLE_HIVEのデフォルトのパラメータ設定
ORACLE_HIVEのデフォルトのパラメータ設定について説明します。
ORACLE_HIVEのオプションのパラメータ設定
ORACLE_HIVEでは、オプションのcom.oracle.bigdataパラメータがサポートされており、opaque_format_spec句で指定できます。

親トピック: ORACLE_HDFSおよびORACLE_HIVEアクセス・ドライバ

17.3.1 `ORACLE_HIVE`のデフォルトのパラメータ設定

ORACLE_HIVEのデフォルトのパラメータ設定について説明します。

CREATE TABLE文からすべてのアクセス・パラメータを省略した場合、ORACLE_HIVEでは次のデフォルト値を使用します。

com.oracle.bigdata.tablename=name of external table
com.oracle.bigdata.overflow={"action":"error"}
com.oracle.bigdata.erroropt={"action":"setnull"}

親トピック: ORACLE_HIVEアクセス・パラメータ

17.3.2 ORACLE_HIVEのオプションのパラメータ設定

ORACLE_HIVEは、オプションのcom.oracle.bigdataパラメータをサポートしています。これらのパラメータは、opaque_format_spec句で指定できます。

具体的には次のとおりです。

com.oracle.bigdata.colmap
com.oracle.bigdata.erroropt
com.oracle.bigdata.log.exec
com.oracle.bigdata.log.qc
com.oracle.bigdata.overflow
com.oracle.bigdata.tablename

次の例に、複数のアクセス・パラメータが設定されているCREATE TABLE文を示します。

例17-2 ORACLE_HIVEの複数のアクセス・パラメータの設定

CREATE TABLE ORDER (cust_num VARCHAR2(10), 
                    order_num VARCHAR2(20), 
                    order_date DATE,
                    item_cnt NUMBER,
                    description VARCHAR2(100),
                    order_total (NUMBER8,2)) ORGANIZATION EXTERNAL 
(TYPE oracle_hive
 ACCESS PARAMETERS (
  com.oracle.bigdata.tableName:  order_db.order_summary
  com.oracle.bigdata.colMap:     {"col":"ITEM_CNT", \
                                  "field":"order_line_item_count"}
  com.oracle.bigdata.overflow:   {"action":"ERROR", \
                                  "col":"DESCRIPTION"}
  com.oracle.bigdata.errorOpt:   [{"action":"replace", \
                                   "value":"INV_NUM" , \
                                   "col":["CUST_NUM","ORDER_NUM"]} ,\
                                  {"action":"reject", \
                                   "col":"ORDER_TOTAL}]
));

親トピック: ORACLE_HIVEアクセス・パラメータ

17.4 com.oracle.bigdataパラメータの説明

com.oracle.bigdataパラメータは、ORACLE_HIVE、ORACLE_HDFSおよびORACLE_BIGDATAアクセス・ドライバによって使用されます。

com.oracle.bigdata.colmap
ソース・データの列をOracle外部表の列にマップします。
com.oracle.bigdata.erroropt
列の値の計算中に発生するエラーを処理する方法を示します。
com.oracle.bigdata.fields
データ・ソースのフィールド名およびデータ型をリストします。
com.oracle.bigdata.fileformat
ORACLE_HDFSによって生成されたHive表のROW FORMAT句に基づいて、データ・ソースの行形式を説明します。
com.oracle.bigdata.log.exec
アクセス・ドライバがCDH上のパラレル処理として実行されている場合、問合せのCコードによって生成されたログ・ファイルを生成する方法を指定します。
com.oracle.bigdata.log.qc
問合せのログ・ファイルをアクセス・ドライバで生成する方法を指定します。
com.oracle.bigdata.overflow
外部表の列に対して長すぎる文字列データの処理方法を示します。
com.oracle.bigdata.rowformat
アクセス・ドライバがファイル内のレコードからフィールドを抽出するために必要な情報を提供します。
com.oracle.bigdata.tablename
ソース・データを含む表の名前を識別します。

親トピック: ORACLE_HDFSおよびORACLE_HIVEアクセス・ドライバ

17.4.1 com.oracle.bigdata.colmap

ソース・データの列をOracle外部表の列にマップします。

1つまたは複数の列マッピングのペアを定義できます。ソース・フィールド名がOracle列名の最大長を超える場合、または外部表で別の列名を使用する場合、このプロパティを使用します。

デフォルト値

Hive列と同じ名前を持つ外部表の列

構文

キーワード/値のペアを持つJSONドキュメントを次の図に示します。

colmap ::=

図colmap.epsの説明

colmap_entry ::=

図colmap_entry.epsの説明

セマンティクス

"col":name

"col": キーワードは小文字にし、引用符で囲む必要があります。

name: Oracle外部表の列の名前。大/小文字が区別され、引用符で囲む必要があります。

"field":name

"field": キーワードは小文字にし、引用符で囲む必要があります。

name: データ・ソースのフィールドの名前。名前は大/小文字を区別しませんが、引用符で囲む必要があります。「プロパティを指定するための構文ルール」を参照してください。

例

この例では、ORDER_LINE_ITEM_COUNTという名前のHive列をITEM_CNTという名前のOracle列にマップします。

com.oracle.bigdata.colMap={"col":"ITEM_CNT", \
                           "field":"order_line_item_count"}

次の例は、複数の列のマッピングを示しています。

com.oracle.bigdata.colmap:[{"col":"KOL1", "field":"PROJECT_NAME"},{ "col":"KOL2","field":"wsdl_name"},{"col":"KOL3", "field":"method"}]

親トピック: com.oracle.bigdataパラメータの説明

17.4.2 com.oracle.bigdata.erroropt

列の値の計算中に発生するエラーを処理する方法を示します。

デフォルト値

{"action":"setnull"}

構文

キーワード/値のペアを持つJSONドキュメントを次の図に示します。

erroropt ::=

図erroropt.epsの説明

error_element ::=

図erroropt_element.epsの説明

セマンティクス

"action"、"reject"、"setnull"、"replace"、"value"および"col"キーワードは小文字を使用して、引用符で囲む必要があります。「プロパティを指定するための構文ルール」を参照してください。

"action":value

value: 次のキーワードのいずれかになります。

"reject": 行をロードしません。
"setnull": 列をNULLに設定します。
"replace": 列を指定された値に設定します。

"value":string

string: 外部表の不正な値を置換します。引用符で囲む必要があります。

"col":name

name: 外部表の列を識別します。列名は大/小文字が区別され、引用符で囲む必要があり、1回のみ指定できます。

例

この例では、Hive値によってエラーが発生した場合、CUST_NUMまたはORDER_NUM列の値をINVALIDに設定します。その他の列では、エラーによってHive値が拒否されます。

com.oracle.bigdata.errorOpt: {"action":"replace",\
                              "value":"INVALID", \
                              "col":["CUST_NUM","ORDER_NUM"]

親トピック: com.oracle.bigdataパラメータの説明

17.4.3 com.oracle.bigdata.fields

データ・ソースのフィールド名およびデータ型をリストします。

デフォルト値

未定義

構文

キーワード/値のペアを持つJSONドキュメントを次の図に示します。

fields ::=

図fields.epsの説明

data_type ::=

図data_type.epsの説明

primitive_type ::=

図primitive_type.epsの説明

セマンティクス

構文は、Hive表のフィールド・リストと同じです。フィールド・リストを複数行に分割する場合、バックスラッシュを使用して改行文字をエスケープする必要があります。

field_name

Hiveフィールドの名前。英数字およびアンダースコア(_)のみ使用します。最大の長さは、128文字です。フィールド名の大/小文字は区別されます。

data_type

(オプション) Hiveフィールドのデータ型。デフォルトはSTRINGです。文字セットはUTF8である必要があります。

データ型は複合またはプリミティブになります。

Hive複合データ型

ARRAY: 索引付け可能なリスト
MAP: キーと値のタプル
STRUCT: 要素のリスト
UNIONTYPE: 複数のデータ型

Hiveプリミティブ・データ型

INT: 4バイトの整数
BIGINT: 8バイトの整数
SMALLINT: 2バイトの整数
TINYINT: 1バイトの整数
BOOLEAN: TRUEまたはFALSE
FLOAT: 単精度
DOUBLE: 倍精度
STRING: 文字列

17.4.4 com.oracle.bigdata.fileformat

ORACLE_HDFSによって生成されたHive表のROW FORMAT句に基づいて、データ・ソースの行形式を説明します。

デフォルト値

TEXTFILE

構文

キーワード/値のペアを持つJSONドキュメントを次の図に示します。

fileformat::=

図fileformat.epsの説明

セマンティクス

ORC

最適化された行列ファイル形式

PARQUET

列指向、バイナリ・ファイル形式

RCFILE

レコード列ファイル形式

SEQUENCEFILE

圧縮ファイル形式

TEXTFILE

プレーン・テキスト・ファイル形式

INPUTFORMAT

データ・ファイルからレコードを抽出できるJavaクラスを識別します。

OUTPUTFORMAT

出力レコードを目的の形式に設定できるJavaクラスを識別します。

親トピック: com.oracle.bigdataパラメータの説明

17.4.5 com.oracle.bigdata.log.exec

アクセス・ドライバがCDH上のパラレル処理として実行されている場合、問合せのCコードによって生成されたログ・ファイルを生成する方法を指定します。

アクセス・ドライバは、Hadoopクラスタ・ノード上で実行されている場合、ログ・ファイルの作成または書込みを実行しません。書込みはパラレル問合せプロセスによって実行されます。Javaコードからのログ・ファイルはlog4jプロパティによって制御されます。このプロパティは、構成ファイルまたはアクセス・パラメータで指定されます。

17.4.6 com.oracle.bigdata.log.qc

アクセス・ドライバが問合せのログ・ファイルを生成する方法を指定します。

デフォルト値

未定義(ロギングなし)

構文

[directory_object:]file_name_template

セマンティクス

directory_object

ログ・ファイルが書き込まれるパスを指すOracleディレクトリ・オブジェクトの名前。この値を省略すると、ログは外部表のデフォルト・ディレクトリに書き込まれます。

file_name_template

ファイル名の生成に使用する文字列。表17-3に、文字列で使用できるオプションの変数を示します。

表17-3 com.oracle.bigdata.log.qcの変数

変数	値
`%p`	オペレーティング・システム・プロセス識別子(PID)
`%%`	パーセント記号(`%`)

例

この例では、PIDおよびパーセント記号を含むログ・ファイル名(xtlogp_hive213459_%など)を作成します。

com.oracle.bigdata.log.qc= xtlogp_hive21%p_%%

親トピック: com.oracle.bigdataパラメータの説明

17.4.7 com.oracle.bigdata.overflow

外部表の列に対して長すぎる文字列データの処理方法を示します。

データ・ソースは文字またはバイナリにできます。Hiveの場合、データ・ソースはSTRUCT、UNIONTYPES、MAPまたはARRAYにすることもできます。

デフォルト値

{"action":"error"}

構文

キーワード/値のペアを持つJSONドキュメントを次の図に示します。

overflow ::=

図overflow.epsの説明

overflow_element ::=

図overflow_element.epsの説明

セマンティクス

"action"、"truncate"、"error"および"col"タグは小文字にし、引用符で囲む必要があります。「プロパティを指定するための構文ルール」を参照してください。

"action":value

"action"の値は次のキーワードのいずれかになります。

truncate: 列に収まるようにデータを短くします。
error: エラーをスローします。プロパティcom.oracle.bigdata.erroroptは、エラーの結果を制御します。

"col":name

name: 外部表の列を識別します。名前は大/小文字が区別され、引用符で囲む必要があります。

例

この例では、DESCRIPTION列のソース・データが列幅を超える場合、ソース・データを切り捨てます。

com.oracle.bigdata.overflow={"action":"truncate", \
                             "col":"DESCRIPTION"}

親トピック: com.oracle.bigdataパラメータの説明

17.4.8 com.oracle.bigdata.rowformat

アクセス・ドライバがファイル内のレコードからフィールドを抽出するために必要な情報を提供します。

注意:

この属性値は使用しないでくださいcom.oracle.bigdata.rowformatは、"type ORACLE_LOADER"を使用する従来型の外部表のアクセス・パラメータ構文とは関連していません。FIELDS、TERMINATEDのようなキーワードなど、両方の句に出現するものもありますが、ネーミングの一致は偶然であり、機能が共通するということではありません。com.oracle.bigdata.rowformatアクセス・パラメータは、デフォルトのHive SerDeに変更を加えることなく渡されます。行から列を抽出するために使用されるHive SerDeは意図的に制限されます。複雑なケースは、特別なSerDeを使用して処理されます。

デフォルト値

DELIMITED

構文

キーワード/値のペアを持つJSONドキュメントを次の図に示します。

rowformat ::=

図rowformat.epsの説明

セマンティクス

DELIMITED

レコード内のフィールドを区切るために使用する文字を示します。

FIELDS TERMINATED BY: レコード内の各フィールドを区切る文字。オプションのESCAPED BY文字は、フィールド値内に指定する場合、デリミタ文字の前に付けます。
COLLECTION ITEMS TERMINATED BY: 配列要素の終了を示す文字。列がコレクションまたはネストされたレコードである場合に使用します。この場合、結果の値はJSON配列になります。
MAP KEYS TERMINATED BY: MAPフィールドのエントリの終了を示す文字。列がコレクションまたはネストされたレコードである場合に使用します。結果の値はJSONオブジェクトになります。
LINES TERMINATED BY: レコードの終了を示す文字。
NULL DEFINED AS: null値を示す文字。

SERDE

アクセス・ドライバが必要とするシリアライザ/デシリアライザ(SerDe)のデータおよびプロパティを解析できるSerDeを識別します。

例

この例では、Avroコンテナ・ファイルにSerDeを指定します。

com.oracle.bigdata.rowformat:
   SERDE'org.apache.hadoop.hive.serde2.avro.AvroSerDe'

次の例では、正規表現を含むファイルのSerDeを指定します。

com.oracle.bigdata.rowformat=\
    SERDE 'org.apache.hadoop.hive.contrib.serde2.RegexSerDe' \
    WITH SERDEPROPERTIES \ 
    ("input.regex" = "(\\\\d{6}) (\\\\d{5}) (.{29}) .*")

親トピック: com.oracle.bigdataパラメータの説明

17.4.9 com.oracle.bigdata.tablename

ソース・データを含む表の名前を識別します。

デフォルト値

DEFAULT.external_table_name

構文

[hive_database_name.]table_name

セマンティクス

hive_database_nameおよびtable_nameの最大長は128 UTF-8文字(512バイト)です。

hive_database_name: ソース・データが存在しているHiveデータベース。DEFAULTはHive初期データベースの名前です。

table_name: データが含まれているHive表。table_nameを省略すると、ORACLE_HIVEは外部表と同じ名前のHive表を検索します。表名の大/小文字は区別されます。

例

この設定は、ソース・データがHiveのORDER_DBデータベース内のORDER_SUMMARYという表にあることを示します。

com.oracle.bigdata.tablename ORDER_DB.ORDER_SUMMARY

親トピック: com.oracle.bigdataパラメータの説明

変数	値
`%p`	オペレーティング・システム・プロセス識別子(PID)
`%a`	プロセスを一意に識別する番号
`%%`	パーセント記号(`%`)

17.1 プロパティを指定するための構文ルール

17.2 ORACLE_HDFSアクセス・パラメータ

17.2.1 ORACLE_HDFSのデフォルトのパラメータ設定

17.2.2 ORACLE_HDFSのオプションのパラメータ設定

17.3 ORACLE_HIVEアクセス・パラメータ

17.3.1 ORACLE_HIVEのデフォルトのパラメータ設定

17.3.2 ORACLE_HIVEのオプションのパラメータ設定

17.4 com.oracle.bigdataパラメータの説明

17.4.1 com.oracle.bigdata.colmap

17.4.2 com.oracle.bigdata.erroropt

17.4.3 com.oracle.bigdata.fields

17.4.4 com.oracle.bigdata.fileformat

17.4.5 com.oracle.bigdata.log.exec

17.4.6 com.oracle.bigdata.log.qc

17.4.7 com.oracle.bigdata.overflow

17.4.8 com.oracle.bigdata.rowformat

17.4.9 com.oracle.bigdata.tablename

17.2 `ORACLE_HDFS`アクセス・パラメータ

17.2.1 `ORACLE_HDFS`のデフォルトのパラメータ設定

17.3 `ORACLE_HIVE`アクセス・パラメータ

17.3.1 `ORACLE_HIVE`のデフォルトのパラメータ設定