| Oracle® Big Data Connectorsユーザーズ・ガイド リリース2 (2.5) E53261-01 |
|
 前 |
 次 |
Oracle Databaseアダプタは、データをOracle Databaseの表にロードするためのカスタム関数を提供します。
このアダプタでサポートされているカスタムput関数は、実行時にOracle Loader for Hadoopを自動的に呼び出し、データをただちにロードするか、またはデータをHDFSに出力します。Oracle Databaseアダプタの複数のカスタムput関数を1つの問合せ内で宣言して使用できます。たとえば、1つの問合せを使用して、データを異なる表または異なるOracleデータベースにロードできます。
Oracle Loader for Hadoopがシステムにインストールされていること、およびOLH_HOME環境変数がインストール・ディレクトリに設定されていることを確認してください。「Oracle XQuery for Hadoopのインストール」のステップ2を参照してください。必須ではありませんが、このアダプタを使用する前に、Oracle Loader for Hadoopをよく理解しておくと役立ちます。
次のトピックでは、Oracle Databaseアダプタについて説明します。
別のユーティリティ(SQL*Loaderなど)を使用した後続のロード用に、次の注釈を使用して、直接またはバイナリ・ファイルやテキスト・ファイルを生成してOracleデータベースの表に書き込む関数を定義できます。
シグネチャ
Oracleデータベース表に書き込むカスタム関数には、次のシグネチャが必要です。
declare %oracle:put(["jdbc" | "oci" | "text" | "datapump"]) [%oracle:columns(col1 [, col2...])] [%oracle-property annotations] function local:myPut($column1 [as xs:allowed_type_name[?]], [$column2 [as xs:allowed_type_name[?]], ...]) external;
put関数および出力モードを宣言します。必須。
オプションのoutput_modeパラメータは、次のいずれかの文字列リテラル値です。
jdbc: JDBC接続を使用して、Oracleデータベース表に書き込みます。デフォルト。
「JDBC出力書式」を参照してください。
oci: Oracle Call Interface (OCI)接続を使用して、Oracleデータベース表に書き込みます。
「Oracle OCIダイレクト・パス出力形式」を参照してください。
datapump: 別のユーティリティによる後続のロード用に、データ・ポンプ・ファイルおよび関連するスクリプトをHDFSに作成します。
「Oracle Data Pump出力形式」を参照してください。
text: デリミタ付きテキスト・ファイルおよび関連するスクリプトをHDFSに作成します。
「デリミタ付きテキスト出力形式」を参照してください。
Oracle XQuery for HadoopでJDBCまたはOCIのいずれかを使用してOracleデータベース表に直接書き込むには、問合せの処理に関連するすべてのシステムがOracle Databaseシステムに接続できる必要があります。「操作モードの概要」を参照してください。
ターゲット表で選択された1つ以上の列名を識別します。列名の順序は、関数パラメータの順序に対応します。「パラメータ」を参照してください。オプション。
この注釈により、表列のサブセットのロードが可能になります。省略すると、put関数はターゲット表のすべての列をロードしようとします。
データベースへの接続およびデータの書込みの様々な側面を制御します。複数の%oracle-property注釈を指定できます。これらの注釈は、Oracle Loader for Hadoop構成プロパティに対応します。各%oracle-property注釈には、同等のOracle Loader for Hadoop構成プロパティがあります。この関係の詳細は、「Oracle Loader for Hadoop構成プロパティおよび対応する%oracle-property注釈」を参照してください。
%oracle-property注釈はオプションです。ただし、様々なロード・シナリオでその一部、または同等の構成プロパティを指定する必要があります。たとえば、JDBCまたはOCIを使用してデータをOracleデータベースにロードするには、ターゲット表および接続情報を指定する必要があります。
次の例は、VISITSという名前のターゲット表、ユーザー名のdb、パスワードのpassword、およびURL接続文字列を指定します。
%oracle-property:targetTable('visits')
%oracle-property:connection.user('db')
%oracle-property:connection.password('password')
%oracle-property:connection.url('jdbc:oracle:thin:@//localhost:1521/orcl.example.com')
パラメータ
すべての列をロードするには、Oracle表の列と同じ順序で各列のパラメータを入力し、選択した列をロードするには、%oracle:columns注釈を使用します。
パラメータとデータベース列の関係は位置によって決まるため、パラメータの名前(パラメータ構文のcolumn1)はデータベース列の名前と一致する必要はありません。
任意のパラメータで明示的なas xs:allowed_type_nameタイプ宣言は省略できます。たとえば、NUMBER列に対応するパラメータを単に$column1として宣言できます。この場合、パラメータはXQueryタイプのitem()*に自動的に割り当てられます。表6-3に説明するように、入力値は実行時に、対応する表列タイプに対して許容されるXQueryタイプにキャストされます。たとえば、NUMBERデータ型の列にマップされるデータ値は、xs:decimalとして自動的にキャストされます。キャストが失敗すると、エラーが発生します。
あるいは、パラメータのタイプまたはそのサブタイプを指定できます。この場合、コンパイル時タイプのチェックが実行されます。たとえば、NUMBER列に対応するパラメータを$column as xs:decimalとして宣言できます。また、xs:decimalのサブタイプ(xs:integerなど)として宣言することもできます。
指定する各パラメータ・タイプにオプションのオカレンス・インジケータ?を含めることができます。このインジケータを使用すると、実行時に空の順序をパラメータ値として渡すことができ、nullがデータベース表に挿入されます。?以外のオカレンス・インジケータを使用するとコンパイル時エラーが発生します。
表6-3に、サポートされているOracle Databaseデータ型に対するXQueryデータ型の適切なマッピングを示します。リストされているXQueryデータ型に加えて、xs:decimalのかわりにxs:integerを使用するなど、サブタイプも使用できます。Oracleデータ型はXQueryデータ型よりも制限があるため、表ではその制限を説明しています。
表6-3 Oracle DatabaseとXQuery間のデータ型マッピング
| Database型 | XQuery型 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
紀元前4712年1月1日から西暦9999年12月31日の範囲に制限されます。 |
|
|
紀元前4712年1月1日から西暦9999年12月31日の範囲に制限されます。 |
|
|
紀元前4712年1月1日から西暦9999年12月31日の範囲に制限されます。協定世界時からのオフセットで、タイムゾーン時間フィールドは-12:00から14:00に制限されます。小数秒の精度は0から9桁に制限されます。 「セッション・タイムゾーンについて」を参照してください。 |
|
|
紀元前4712年1月1日から西暦9999年12月31日の範囲に制限されます。協定世界時からのオフセットで、タイムゾーン時間フィールドは-12:00から14:00に制限されます。小数秒の精度は0から9桁に制限されます。 「セッション・タイムゾーンについて」を参照してください。 |
|
|
日および小数秒の精度は、それぞれ0から9桁に制限されます。時間は0から23、分と秒は0から59の範囲に制限されます。 |
|
|
年の精度は0から9桁に制限され、月は0から11の範囲に制限されます。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
セッション・タイムゾーンについて
タイムゾーンが指定されていないxs:dateTime値がTIMESTAMP W TIME ZONEまたはTIMESTAMP W LOCAL TIME ZONEにロードされると、タイムゾーンはsessionTimeZoneパラメータの値(JVMタイムゾーンにデフォルト設定される)に設定されます。Oracle XQuery for Hadoopを使用して、sessionTimeZoneプロパティを設定できます(「Oracle Loader for Hadoop構成プロパティおよび対応する%oracle-property注釈」を参照)。
注意
JDBCまたはOCI出力モードを使用して、Oracle Databaseアダプタはデータをデータベース表に直接ロードします。さらに、問合せ出力ディレクトリの下に、カスタムput関数と同じ名前のディレクトリを作成します。たとえば、問合せ出力ディレクトリがmyoutputで、カスタム関数がmyPutの場合は、myoutput/myPutディレクトリが作成されます。
Oracle Databaseアダプタのすべてのカスタムput関数ごとに、個別のディレクトリが作成されます。このディレクトリには、Oracle Loader for Hadoopのジョブで作成された出力が格納されます。datapumpまたはtext出力モードを使用すると、データ・ファイルがこのディレクトリに書き込まれます。ファイルをロードするための制御およびSQLスクリプトは、_olhサブディレクトリ(例: myoutput/myPut/_olh)に書き込まれます。
生成されるファイルについては、「デリミタ付きテキスト出力形式」および「Oracle Data Pump出力形式」を参照してください。
次の各例では、HDFS内の次のテキスト・ファイルを使用します。ファイルには、異なるWebページへのアクセス・ログが格納されます。各行はWebページへのアクセスを表し、時間、ユーザー名、アクセスしたページが格納されます。
mydata/visits1.log 2013-10-28T06:00:00, john, index.html, 200 2013-10-28T08:30:02, kelly, index.html, 200 2013-10-28T08:32:50, kelly, about.html, 200 2013-10-30T10:00:10, mike, index.html, 401 mydata/visits2.log 2013-10-30T10:00:01, john, index.html, 200 2013-10-30T10:05:20, john, about.html, 200 2013-11-01T08:00:08, laura, index.html, 200 2013-11-04T06:12:51, kelly, index.html, 200 2013-11-04T06:12:40, kelly, contact.html, 200
この例では、匿名のページ・アクセスが格納されている、HDFS内の次のファイルも使用します。
mydata/anonvisits.log 2011-10-30T10:01:01, index.html, 401 2011-11-04T06:15:40, contact.html, 401
このSQLコマンドでは、VISITS表がOracleデータベースに作成されます。
CREATE TABLE visits (time TIMESTAMP, name VARCHAR2(15), page VARCHAR2(15), code NUMBER)
最初の問合せは、ページ・アクセスに関連するすべての情報(アクセスの時間、ユーザー名、アクセスしたページ、およびステータス・コード)をVISITS表にロードします。匿名アクセスの場合はユーザー名が欠落しているため、問合せでは()を指定してnullを表に挿入します。ターゲット表名、ユーザー名、パスワードおよび接続URLは、%oracle-property注釈を使用して指定します。
この例ではクリア・テキストのユーザー名とパスワードを使用していますが、セキュリティのために、かわりにウォレットを使用することをお薦めします。Oracle Loader for Hadoopプロパティ、またはそれと同等の%oracle-property注釈のいずれかを使用して、Oracleウォレットを構成できます。設定が必要な特定のプロパティについては、「オンライン・データベース・モードの接続詳細の指定」を参照してください。
import module "oxh:text";
declare
%oracle:put
%oracle-property:targetTable('visits')
%oracle-property:connection.user('db')
%oracle-property:connection.password('password')
%oracle-property:connection.url('jdbc:oracle:thin:@//localhost:1521/orcl.example.com')
function local:myPut($c1, $c2, $c3, $c4) external;
for $line in text:collection("mydata/*visits*.log")
let $split := fn:tokenize($line, "\s*,\s*")
return
if (count($split) > 3) then
local:myPut($split[1], $split[2], $split[3], $split[4])
else
local:myPut($split[1], (), $split[2], $split[3])
問合せの実行後に、VISITS表には次のデータが格納されます。
TIME NAME PAGE CODE ------------------------------ --------------- --------------- ---------- 30-OCT-13 10.00.01.000000 AM john index.html 200 30-OCT-13 10.05.20.000000 AM john about.html 200 01-NOV-13 08.00.08.000000 AM laura index.html 200 04-NOV-13 06.12.51.000000 AM kelly index.html 200 04-NOV-13 06.12.40.000000 AM kelly contact.html 200 28-OCT-13 06.00.00.000000 AM john index.html 200 28-OCT-13 08.30.02.000000 AM kelly index.html 200 28-OCT-13 08.32.50.000000 AM kelly about.html 200 30-OCT-13 10.00.10.000000 AM mike index.html 401 30-OCT-11 10.01.01.000000 AM index.html 401 04-NOV-11 06.15.40.000000 AM contact.html 401
この例では、%oracle:columns注釈を使用して、表のtime列およびname列のみをロードします。また、johnによるアクセスのみをロードします。
%oracle:columnsで指定した列名は、put関数パラメータと位置的に関連しています。$c1パラメータに指定したデータ値はTIME列にロードされ、$c2パラメータに指定したデータ値はNAME列にロードされます。
import module "oxh:text";
declare
%oracle:put
%oracle:columns('time', 'name')
%oracle-property:targetTable('visits')
%oracle-property:connection.user('db')
%oracle-property:connection.password('password')
%oracle-property:connection.url('jdbc:oracle:thin:@//localhost:1521/orcl.example.com')
function local:myPut($c1, $c2) external;
for $line in text:collection("mydata/*visits*.log")
let $split := fn:tokenize($line, "\s*,\s*")
where $split[2] eq 'john'
return
local:myPut($split[1], $split[2])
問合せの実行前にVISITS表が空の場合、実行後には次のデータが格納されます。
TIME NAME PAGE CODE ------------------------------ --------------- --------------- ---------- 30-OCT-13 10.00.01.000000 AM john 30-OCT-13 10.05.20.000000 AM john 28-OCT-13 06.00.00.000000 AM john
Oracle XQuery for HadoopのOracle Databaseアダプタを使用するときは、Oracle Loader for Hadoopを間接的に使用します。Oracle Loader for Hadoopは、Oracle Databaseへの接続およびデータの書込みの様々な側面を制御する構成プロパティを定義します。Oracle XQuery for Hadoopは、これらのプロパティ(表6-4の最後の列を参照)の多くをサポートしています。
これらのプロパティは、汎用の-confおよび-D hadoopコマンドライン・オプションを使用してOracle XQuery for Hadoopに指定できます。この方法を使用して指定されるプロパティは、問合せ内のOracle Databaseアダプタのすべてのput関数に適用されます。hadoopコマンドライン・オプションの詳細は、「問合せの実行」と特に「汎用オプション」を参照してください。
あるいは、%oracle-property接頭辞を使用して、これらのプロパティをOracle Databaseアダプタのput関数の注釈として指定できます。これらの注釈は、表6-4の2番目の列を参照してください。注釈は、宣言にその注釈があるOracle Databaseアダプタの特定のput関数にのみ適用されます。
たとえば、ターゲット表をVISITSに設定するには、次の行を構成ファイルに追加し、-confオプションを使用して構成ファイルを指定します。
<property> <name>oracle.hadoop.loader.targetTable</name> <value>visits</value> </property>
また、同じOracle Loader for Hadoopプロパティを使用して、-Dオプションを指定してターゲット表をVISITSに設定することもできます。
-D oracle.hadoop.loader.targetTable=visits
どちらの方法も、問合せ内のOracle Databaseアダプタのすべてのput関数について、ターゲット表をVISITSに設定します。
あるいは、この注釈は、宣言に注釈がある特定のput関数の場合のみ、ターゲット表をVISITSに設定します。
%oracle-property:connection.url('visits')
利便性を考慮して柔軟に設定できます。たとえば、問合せに複数のOracle Databaseアダプタのput関数があり、それぞれが異なる表を同じデータベースに書き込む場合、必要な情報の指定に最も利便性の高い方法は次のとおりです。
oracle.hadoop.loader.connection.urlプロパティを構成ファイルで使用し、データベース接続URLを指定します。次に、-confオプションを使用して構成ファイルを指定します。このオプションにより、問合せ内のOracle Databaseアダプタのすべてのput関数について同じデータベース接続URLが設定されます。
Oracle Databaseアダプタの各put関数宣言で%oracle-property:targetTable注釈を使用して、異なる表名を設定します。
表6-4に、Oracle Loader for Hadoopプロパティおよびそれと同等のOracle XQuery for Hadoop注釈を機能カテゴリ別に示します。Oracle XQuery for Hadoopは、この表に示されているOracle Loader for Hadoopプロパティのみサポートしています。
表6-4 構成プロパティおよび対応する%oracle-property注釈
| カテゴリ | プロパティ | 注釈 |
|---|---|---|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
接続 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
一般 |
|
|
|
出力 |
|
|
|
出力 |
|
|
|
出力 |
|
|
|
出力 |
|
|
|
出力 |
|
|
|
出力 |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
|
サンプラ |
|
|
