このアダプタは、Oracle NoSQL Databaseに格納する値の読取りおよび書込みを実行する関数を提供します。
次のトピックでは、このアダプタについて説明します。
Oracle NoSQL Databaseアダプタを使用する問合せを記述する前に、Oracle NoSQL Databaseサーバーを使用するようにOracle XQuery for Hadoopを構成する必要があります。
次を設定する必要があります。
Oracle NoSQL Databaseのlibディレクトリを含むローカル・ディレクトリへのKVHOME
環境変数。
oracle.kv.hosts
およびoracle.kv.kvstore
構成プロパティ。
構成プロパティは、問合せの実行時にhadoop
コマンドで-D
オプションまたは-conf
オプションを使用すると設定できます。「問合せの実行」を参照してください。
次の例は、KVHOME
を設定し、問合せでhadoop
-D
オプションを使用してoracle.kv.kvstore
を設定します。
$ export KVHOME=/local/path/to/kvstore/ $ hadoop jar $OXH_HOME/lib/oxh.jar -D oracle.kv.hosts=example.com:5000 -D oracle.kv.kvstore=kvstore ./myquery.xq -output ./myoutput
「Oracle NoSQL Databaseアダプタの構成プロパティ」を参照してください。
問合せで組込み関数を使用するには、次のようにOracle NoSQL Databaseモジュールをインポートする必要があります。
import module "oxh:kv";
Oracle NoSQL Databaseモジュールには、次の関数が含まれています。
データベース内の値のコレクションにアクセスします。各値はUTF-8としてデコードされ、文字列として返されます。
シグネチャ
declare %kv:collection("text") function kv:collection-text($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as xs:string* external; declare %kv:collection("text") function kv:collection-text($parent-key as xs:string?, $depth as xs:int?) as xs:string* external; declare %kv:collection("text") function kv:collection-text($parent-key as xs:string?) as xs:string* external;
パラメータ
「パラメータ」を参照してください。$subrange
を省略すると、$subrange()
を指定したのと同じです。同様に、$depth
を省略すると、$depth()
を指定したのと同じです。
戻り値
各値に対して1つの文字列
データベース内の値のコレクションにアクセスします。各値はAvroレコードとして読み取られ、XML要素として返されます。レコードはXMLに変換されます(「レコードの読取り」を参照)。
シグネチャ
declare %kv:collection("avroxml") function kv:collection-avroxml($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as element()* external; declare %kv:collection("avroxml") function kv:collection-avroxml($parent-key as xs:string?, $depth as xs:int?) as element()* external; declare %kv:collection("avroxml") function kv:collection-avroxml($parent-key as xs:string?) as element()* external;
パラメータ
「パラメータ」を参照してください。$subrange
を省略すると、$subrange()
を指定したのと同じです。同様に、$depth
を省略すると、$depth()
を指定したのと同じです。
戻り値
各Avroレコードに対して1つのXML要素
データベース内の値のコレクションにアクセスします。各値は一連のバイトとして読み取られ、XMLとして解析されます。
シグネチャ
declare %kv:collection("xml") function kv:collection-xml($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as document-node()* external; declare %kv:collection("xml") function kv:collection-xml($parent-key as xs:string?, $depth as xs:int?) as document-node()* external; declare %kv:collection("xml") function kv:collection-xml($parent-key as xs:string?) as document-node()* external;
パラメータ
「パラメータ」を参照してください。$subrange
を省略すると、$subrange()
を指定したのと同じです。同様に、$depth
を省略すると、$depth()
を指定したのと同じです。
戻り値
各値に対して1つのXMLドキュメント。
データベース内の値のコレクションにアクセスします。各値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。
シグネチャ
declare %kv:collection("binxml") function kv:collection-binxml($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as document-node()* external;
declare %kv:collection("binxml") function kv:collection-binxml($parent-key as xs:string?, $depth as xs:int?) as document-node()* external;
declare %kv:collection("binxml") function kv:collection-binxml($parent-key as xs:string?) as document-node()* external;
パラメータ
「パラメータ」を参照してください。$subrange
を省略すると、$subrange()
を指定したのと同じです。同様に、$depth
を省略すると、$depth()
を指定したのと同じです。
戻り値
各値に対して1つのXMLドキュメント。
関連項目
『Oracle XML Developer's Kitプログラマーズ・ガイド』
キーと値のペアを書き込みます。$value
はUTF-8としてエンコードされます。
シグネチャ
declare %kv:put("text") function kv:put-text($key as xs:string, $value as xs:string) external;
キーと値のペアを書き込みます。$xml
はシリアライズされ、UTF-8としてエンコードされます。
シグネチャ
declare %kv:put("xml") function kv:put-xml($key as xs:string, $xml as node()) external;
キーと値のペアを書き込みます。$xml
はXDKバイナリXMLとしてエンコードされます。『Oracle XML Developer's Kitプログラマーズ・ガイド』を参照してください。
シグネチャ
declare %kv:putkv:put-binxml("binxml") function ($key as xs:string, $xml as node()) external;
キーに関連付けられた値を取得します。値はUTF-8としてデコードされ、文字列として返されます。
シグネチャ
declare %kv:get("text") function kv:get-text($key as xs:string) as xs:string? external;
キーに関連付けられた値を取得します。値はAvroレコードとして読み取られ、XML要素として返されます。レコードはXMLに変換されます(「レコードの読取り」を参照)。
シグネチャ
declare %kv:get("avroxml") function kv:get-avroxml($key as xs:string) as element()? external;
キーに関連付けられた値を取得します。値は一連のバイトとして読み取られ、XMLとして解析されます。
シグネチャ
declare %kv:get("xml") function kv:get-xml($key as xs:string) as document-node()? external;
キーに関連付けられた値を取得します。値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。
シグネチャ
declare %kv:get("binxml") function kv:get-binxml($key as xs:string) as document-node()? external;
関連項目
『Oracle XML Developer's Kitプログラマーズ・ガイド』
接頭辞の範囲を定義します。接頭辞は、上限と下限(両端を含む)の両方を定義します。
この関数は、kv:collection
関数のsubrange引数として使用します。
シグネチャ
kv:key-range($prefix as xs:string) as xs:string;
キーの範囲を指定します。
この関数は、kv:collection
関数のsubrange引数として使用します。
シグネチャ
kv:key-range($start as xs:string, $start-inclusive as xs:boolean, $end as xs:string, $end-inclusive as xs:boolean) as xs:string;
パラメータ
$start
: キー範囲の下限を定義します。
$start-inclusive
: 値がtrue
の場合は範囲内に$start
が含まれ、false
の場合は含まれません。
$end
: キー範囲の上限を定義します。これは$start
より大きい必要があります。
$end-inclusive
: 値がtrue
の場合は範囲内に$end
が含まれ、falseの場合は含まれません。
次の関数を使用して、Oracle NoSQL Databaseから値を読み取ることができます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
NoSQL値のコレクションを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv:collection("text") [additional annotations] function local:myFunctionName($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as xs:string* external; declare %kv:collection(["xml"|"binxml"]) [additional annotations] function local:myFunctionName($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as document-node()* external; declare %kv:collection("avroxml") [additional annotations] function local:myFunctionName($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) as element()* external;
NoSQL Databaseのcollection関数を宣言します。必須。
methodパラメータは次のいずれかの値です。
text
: 各値は、%output:encoding
注釈で指定された文字セットを使用してデコードされます。
avroxml
: 各値はAvroレコードとして読み取られ、XML要素として返されます。レコードはXMLに変換されます(「レコードの読取り」を参照)。
binxml
: 各値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。
xml
: 各値はXMLとして解析され、XMLドキュメントとして返されます。
キーと値のペアのキーが、戻り値のdocument-uri
として設定されるかどうかを制御します。キーを返すにはtrue
に指定します。
デフォルト設定は、methodがxml
、avroxml
またはbinxml
の場合はtrue、textの場合はfalse
です。この注釈がtrue
に設定されたテキスト関数は、xs:string?
ではなくtext()?
を返すように宣言する必要があります。アトミックのxs:string
値はdocumentノードには関連付けられませんが、textノードには関連付けられます。次に例を示します。
declare %kv:collection("text") %kv:key("true") function local:col($parent-key as xs:string?) as text()* external;
キーが返されると、kv:key()
関数を使用してその文字列表現を取得できます。次に例を示します。
for $value in local:col(...) let $key := $value/kv:key() return ...
Avroリーダー・スキーマを指定します。この注釈は、methodがavroxml
の場合のみ有効です。オプション。
schema-nameは完全修飾されたレコード名です。レコード・スキーマは、Oracle NoSQL Databaseカタログから取得されます。レコード値はリーダー・スキーマにマップされます。例: %avro:schema-kv("org.example.PersonRecord")
。
関連項目: Avroスキーマについては、次のサイトにある『Oracle NoSQL Databaseスタート・ガイド』
|
テキスト値の文字エンコードを指定します。この注釈を使用しないと、UTF-8とみなされます。有効なエンコードは、JVMでサポートされているエンコードです。
現在、この注釈はテキスト・メソッドにのみ適用されます。XMLファイルの場合は、ドキュメントのエンコード宣言が使用されます(使用可能な場合)。
関連項目: 次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項
|
パラメータ
関数によって子のキーと値のペアが返される親キーを指定します。メジャー・キー・パスを部分パスとし、マイナー・キー・パスを空にする必要があります。空の順序によって、ストア内のすべてのキーがフェッチされます。
関連項目: キーの書式については、次のサイトにあるOracle NoSQL Database Javaリファレンス
|
親、子、子孫またはその組合せを返すかどうかを指定します。次の値が有効です。
kv:depth-parent-and-descendants()
: 親とすべての子孫を選択します。
kv:depth-children-only()
: 直下の子のみ選択しますが、親は選択しません。
kv:depth-descendants-only()
: すべての子孫を選択しますが、親は選択しません。
kv:depth-parent-and-children()
: 親と直下の子を選択します。
空の順序は、kv:depth-parent-and-descendants()
を暗黙的に示します。
次の例は、すべての子孫を選択しますが、親は選択しません。
kv:collection-text("/parent/key", kv:depth-descendants-only(), ...
parentKey
下の範囲をメジャー・パス・コンポーネントに制限するための部分範囲を指定します。文字列の書式は次のとおりです。
<startType>/<start>/<end>/<endType>
startType
およびendType
は、I
(含む場合)またはE
(含まない場合)のいずれかです。
start
およびend
は、開始および終了のキー文字列です。
範囲に下限がない場合は、先頭のstartType/start
指定を文字列表現から省略します。同様に、範囲に上限がない場合は、末尾のend/endType
指定を省略します。KeyRange
には少なくとも1つの境界が必要であるため、文字列表現に少なくとも1つの指定が必要です。
kv:key-range
関数を使用すると、範囲文字列を簡単に作成できます。
値に空の順序を指定することもできます。
次の例は、有効な部分範囲の指定です。
例 | 説明 |
---|---|
I/alpha/beta/E |
alpha (この値を含む)からbeta (この値を含まない) |
E//0123/I |
"" (この値を含まない)から0123 (この値を含む) |
I/chi/ |
chi (この値を含む)から無限大 |
E// |
"" (この値を含まない)から無限大 |
/chi/E |
負の無限大からchi (この値を含まない) |
//I |
負の無限大から"" (この値を含む) |
Oracle NoSQL Databaseアダプタにはget関数があり、この関数を使用して単一値をデータベースから取得できます。collection関数とは異なり、get関数の呼出しはクラスタに分散されません。get関数が呼び出されると、単一のタスクによって値が取得されます。
シグネチャ
カスタムのget
関数には、次のいずれかのシグネチャが必要です。
declare %kv:get("text") [additional annotations] function local:myFunctionName($key as xs:string) as xs:string? external; declare %kv:get("avroxml") [additional annotations] function local:myFunctionName($key as xs:string) as element()? external; declare %kv:get(["xml"|"binxml"]) [additional annotations] function local:myFunctionName($key as xs:string) as document-node()?
注釈
NoSQL Databaseのget関数を宣言します。必須。
methodパラメータは次のいずれかの値です。
text
: 値は、%output:encoding
注釈で指定された文字セットを使用してデコードされます。
avroxml
: 値はAvroレコードとして読み取られ、XML要素として返されます。レコードはXMLに変換されます(「レコードの読取り」を参照)。
binxml
: 値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。
xml
: 値はXMLとして解析され、XMLドキュメントとして返されます。
キーと値のペアのキーが、戻り値のdocument-uri
として設定されるかどうかを制御します。キーを返すにはtrue
に指定します。
デフォルト設定は、methodがxml
、avroxml
またはbinxml
の場合はtrue
、textの場合はfalse
です。この注釈がtrue
に設定されたテキスト関数は、xs:string?
ではなくtext()?
を返すように宣言する必要があります。アトミックのxs:string
値はdocumentノードには関連付けられませんが、textノードには関連付けられます。
キーが返されると、kv:key()
関数を使用してその文字列表現を取得できます。
Avroリーダー・スキーマを指定します。この注釈は、methodがavroxml
の場合のみ有効です。オプション。
schema-nameは完全修飾されたレコード名です。レコード・スキーマは、Oracle NoSQL Databaseカタログから取得されます。レコード値はリーダー・スキーマにマップされます。例: %avro:schema-kv("org.example.PersonRecord")
。
関連項目: Avroスキーマについては、次のサイトにある『Oracle NoSQL Databaseスタート・ガイド』
|
テキスト値の文字エンコードを指定します。この注釈を使用しないと、UTF-8とみなされます。有効なエンコードは、JVMでサポートされているエンコードです。
現在、この注釈はテキスト・メソッドにのみ適用されます。XMLファイルの場合は、ドキュメントのエンコード宣言が使用されます(使用可能な場合)。
関連項目: 次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項
|
次の注釈を使用して、Oracle NoSQL Databaseに書き込む関数を定義できます。
シグネチャ
Oracle NoSQL Databaseに書き込むカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv:put("text") function local:myFunctionName($key as xs:string, $value as xs:string) external; declare %kv:put(["xml"|"binxml"|"avroxml"]) function local:myFunctionName($key as xs:string, $xml as node()) external;
注釈
NoSQL Databaseモジュールのput関数を宣言します。必須。
methodは値の格納方法を決定します。次のいずれかの値です。
text
: $value
は、%output:encoding
注釈で指定された文字セットを使用してシリアライズおよびエンコードされます。
avroxml
: $xml
は、%avro:schema-kv
注釈で指定されたAvroレコードのインスタンスにマップされます。「AvroとしてのXMLの書込み」を参照してください。
binxml
: $xmlはXDKバイナリXMLとしてエンコードされます。
xml
: $xml
は、%output:encoding
注釈で指定された文字セットを使用してシリアライズおよびエンコードされます。%output:*
を使用すると、他のXMLシリアライズ・パラメータを指定できます。
書き込まれる値のレコード・スキーマを指定します。注釈値は完全修飾されたレコード名です。レコード・スキーマは、Oracle NoSQL Databaseカタログから取得されます。
例: %avro:schema-kv("org.example.PersonRecord")
%kv:put
で指定される出力方法(テキストまたはXML)に対する標準XQueryシリアライズ・パラメータ。「シリアライズ注釈」を参照してください。
関連項目: XMLおよびテキスト出力方法については、次のサイトにある『XSLT and XQuery Serialization 3.0』のシリアライズ・パラメータの影響に関する項 |
この例では、HDFS内の次のテキスト・ファイルを使用します。このファイルには、ユーザーID、姓名、年齢などのユーザー・プロファイル情報がコロン(:)区切りで格納されています。
mydata/users.txt john:John Doe:45 kelly:Kelly Johnson:32 laura:Laura Smith: phil:Phil Johnson:27
最初の問合せは、このテキスト・ファイルの行をテキスト値としてOracle NoSQL Databaseに格納します。
import module "oxh:text"; import module "oxh:kv"; for $line in text:collection("mydata/users.txt") let $split := fn:tokenize($line, ":") let $key := "/users/text/" || $split[1] return kv:put-text($key, $line)
次の問合せは、データベースから値を読み取ります。
import module "oxh:text"; import module "oxh:kv"; for $value in kv:collection-text("/users/text") let $split := fn:tokenize($value, ":") where $split[2] eq "Phil Johnson" return text:put($value)
この問合せは、次の行を含むテキスト・ファイルを作成します。
phil:Phil Johnson:27
この例では、次のAvroスキーマがOracle NoSQL Databaseに登録されます。
{ "type": "record", "name": "User", "namespace": "com.example", "fields" : [ {"name": "id", "type": "string"}, {"name": "full_name", "type": "string"}, {"name": "age", "type": ["int", "null"] } ] }
次の問合せは、ユーザー名をAvroレコードとしてデータベースに書き込みます。
import module "oxh:text"; declare %kv:put("avroxml") %avro:schema-kv("com.example.User") function local:put-user($key as xs:string, $value as node()) external; for $line in text:collection("mydata/users.txt") let $split := fn:tokenize($line, ":") let $id := $split[1] let $key := "/users/avro/" || $id return local:put-user( $key, <user> <id>{$id}</id> <full_name>{$split[2]}</full_name> { if ($split[3] castable as xs:int) then <age>{$split[3]}</age> else () } </user> )
この問合せは、データベースから値を読み取ります。
import module "oxh:text"; import module "oxh:kv"; for $user in kv:collection-avroxml("/users/avro") where $user/age gt 30 return text:put($user/full_name)
この問合せは、次の行を含むテキスト・ファイルを作成します。
John Doe Kelly Johnson
Oracle XQuery for Hadoopでは、構成プロパティを指定する汎用オプションをHadoopコマンドで使用します。構成ファイルを指定する場合は-conf
オプションを使用し、個別のプロパティを指定する場合は-D
オプションを使用します。「問合せの実行」を参照してください。
Oracle NoSQL Databaseアダプタには、永続性およびタイムアウト期間を制御する各種の構成プロパティを設定できます。oracle.kv.hosts
およびoracle.kv.kvstore
を設定する必要があります。次のプロパティでOracle NoSQL Databaseアダプタを構成します。
型: String
デフォルト値: NO_SYNC、NO_SYNC、SIMPLE_MAJORITY
説明: %kv:put
操作に関連付けられた永続性を定義します。値は3つの部分で構成され、順番に指定してカンマ(,)で区切ります。
MasterPolicy, ReplicaPolicy, ReplicaAck
MasterPolicy: トランザクションをマスター・データベースにコミットするときに使用される同期化ポリシー。この部分は次のいずれかの定数に設定します。
NO_SYNC
: トランザクションのコミット時に、ログを書き込んだり同期的にフラッシュしません。
SYNC
: トランザクションのコミット時に、ログを書き込み同期的にフラッシュします。
WRITE_NO_SYNC
: トランザクションのコミット時に、ログを書き込みますが、同期的にフラッシュしません。
ReplicaPolicy: トランザクションをレプリカ・データベースにコミットするときに使用される同期化ポリシー。この部分はNO_SYNC
、SYNC
またはWRITE_NO_SYNC
に設定します(MasterPolicyの説明を参照)。
ReplicaAck: レプリカ・データベースからトランザクション受信確認を取得するのに使用される通知ポリシー。この部分は次のいずれかの定数に設定します。
ALL
: すべてのレプリカは、トランザクションをコミットしたことを受信確認する必要があります。
NONE
: トランザクションのコミットの受信確認は不要で、マスターは通知を待機しません。
SIMPLE_MAJORITY
: レプリカの過半数(例: 5つの内の3つ)が、トランザクションをコミットしたことを受信確認する必要があります。
関連項目: 次のサイトにある『Oracle NoSQL Databaseスタート・ガイド』の永続性保証に関する項
|
型: 整数のカンマ区切りのリスト
デフォルト値: 100, 90, 80
説明: 同時要求の数を制限して、サービス時間が長い複数のノードがKVストア・クライアントのすべてのスレッドを消費するのを防ぎます。値は3つの整数で構成され、順番に指定してカンマで区切ります。
maxActiveRequests, requestThresholdPercent, nodeLimitPercent
maxActiveRequests: KVクライアントで許可されるアクティブな要求の最大数。通常、この数は、クライアントが要求を処理するために確保したスレッドの最大数から導出されます。
requestThresholdPercent: 要求が制限されるmaxActiveRequestsのパーセンテージ。
nodeLimitPercent: アクティブな要求の数がrequestThresholdPercentで指定したしきい値を超えた場合に、ノードに関連付けることができるアクティブな要求の最大数。
型: Long
デフォルト値: 5000ミリ秒
説明: 要求のタイムアウト期間をミリ秒で構成します。値はゼロ(0)より大きい必要があります。
型: Long
デフォルト値: 5000ミリ秒
説明: クライアント要求のソケットを確立するときに使用されるオープン・タイムアウトをミリ秒で構成します。タイムアウトが短いほど、より迅速に障害を検出してリカバリできます。ほとんどのアプリケーションは、デフォルトのオープン・タイムアウトが適切です。値はゼロ(0)より大きい必要があります。
型: Long
デフォルト値: 30000ミリ秒
説明: クライアント要求を行うソケットに関連付けられる読取りタイムアウト期間をミリ秒で構成します。タイムアウトが短いほど、より迅速に障害を検出してリカバリできます。ただし、最長のタイムアウトが要求に関連付けられるように、タイムアウト期間は十分な長さにする必要があります。
型: Key
デフォルト値: 定義されていません。
説明: 各ネットワーク・ラウンドトリップ中、InputFormatがフェッチに必要とするキー数。ゼロ(0)値は、プロパティをデフォルト値に設定します。
型: Consistency
デフォルト値: NONE_REQUIRED
説明: 子のキーと値のペアを読み取る際の一貫性保証です。次のキーワードは有効な値です。
ABSOLUTE
: 一貫性が絶対的となるよう、マスターがトランザクションを提供する必要があります。
NONE_REQUIRED
: レプリカが、マスターと比較したレプリカの状態に関係なく、トランザクションを提供することが可能です。
型: String
デフォルト値: 定義されていません。
説明: ソース・データがあるKVストア内のホストを識別する、1つ以上のhostname:portペアの配列。複数のペアはカンマで区切ります。
型: String
デフォルト値: 定義されていません。
説明: ソース・データがあるKVストアの名前。
型: Long
デフォルト値: 定義されていません。
説明: 選択したキーと値のペアを取得する場合の最大時間間隔(ミリ秒)を設定します。ゼロ(0)値は、プロパティをデフォルト値に設定します。
関連項目: 次のサイトにあるOracle NoSQL Database Java APIリファレンス
|