| Oracle® Big Data Connectorsユーザーズ・ガイド リリース5 (5.0) F21918-01 |
|
 前 |
 次 |
この章では、Oracle XQuery for Apache Hadoopで使用できるアダプタについて説明します。
この章では、その他のライブラリ・モジュールについても説明します。
Avroファイル・アダプタは、HDFS内のAvroコンテナ・ファイルの読取りおよび書込みを実行する関数を提供します。この項の内容は次のとおりです。
注意:
HDPユーザーのための追加構成ステップ
Oracle XQuery for Hadoopは、ClouderaのCDH5およびHortonworkのHDP 2.3.3の両方で動作することが確認されています。 ただし、HDP 2.3.2でAvroコンテナファイルに書き込む問合せを実行するには、OXHクラスパスの定義を変更し、avro-mapred-1.7.4-hadoop2.jarを使用する必要があります。Apacheアーカイブhttps://archive.apache.org/dist/avro/avro-1.7.4/java/からJARファイルをダウンロードします。
$OXH_HOME/lib/oxh-lib.xmlの、次のパスタグを探します。
<path id="oracle.hadoop.xquery.avro.lib">
<fileset dir="${oracle.hadoop.loader.olh_home}/jlib" erroronmissingdir="false">
<include name="avro-mapred*.jar"/>
</fileset>
</path>
前述のpathタグを次のように変更します。この例における[DIRECTORY]はプレースホルダーです。これをJARファイルのディレクトリ・パスに置き換えます。
<path id="oracle.hadoop.xquery.avro.lib”>
<fileset dir="[DIRECTORY]">
<include name="avro-mapred-1.7.4-hadoop2.jar"/>\
</fileset>
</path>
問合せで組込み関数を使用するには、次のようにAvroファイル・モジュールをインポートする必要があります。
import module "oxh:avro";
Avroファイル・モジュールには、次の関数が含まれています。
Avroコンテナ・ファイルを書き込む組込み関数はありません。Avroファイルを書き込むには、Avroライター・スキーマを指定するカスタム関数を使用する必要があります。
HDFS内のAvroファイルのコレクションにアクセスします。ファイルを分割して、複数のタスクで並列で処理できます。関数は、各オブジェクトのXML要素を返します。「AvroとXML間の値の変換について」を参照してください。
シグネチャ
declare %avro:collection("avroxml") function
avro:collection-avroxml($uris as xs:string*) as element()* external;
パラメータ
$uris: AvroファイルのURI
戻り値
各Avroオブジェクトに対して1つのXML要素。
XMLとしてモデル化されたAvroマップからエントリを取得します。
$mapパラメータを省略すると、動作は、2つの引数の関数を呼び出して$mapのコンテキスト項目を使用するのと同じです。
シグネチャ
avro:get($key as xs:string?, $map as node()?) as element(oxh:entry)? avro:get($key as xs:string?) as element(oxh:entry)?
戻り値
このXPath式の値は次のとおりです。
$map/oxh:entry[@key eq $key]
例
次の関数呼出しは同等です。
$var/avro:get("key")
avro:get("key", $var)
$var/oxh:entry[@key eq "key"]
この例では、$varはXMLとしてモデル化されたAvroマップです。「マップの読取り」を参照してください。
次の注釈を使用して、HDFS内のAvroコンテナ・ファイルのコレクションを読み取る関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
Avroファイルを読み取るカスタム関数には、次のシグネチャが必要です。
declare %avro:collection("avroxml") [additional annotations]
function local:myFunctionName($uris as xs:string*) as element()* external;
注釈
avroxml collection関数を宣言します。必須。
collection関数によって、HDFS内のAvroファイルにアクセスします。ファイルを分割して、複数のタスクで並列で処理できます。関数は、各オブジェクトのXML要素を返します。「AvroとXML間の値の変換について」を参照してください。
注釈の値としてAvroリーダー・スキーマを指定します。オプション。
指定時に、ファイル内のオブジェクトがリーダー・スキーマにマップされます。次に例を示します。
%avro:schema('
{
"type": "record",
"name": "Person",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
')
この注釈は、%avro:schema-fileまたは%avro:schema-kvと組み合せることはできません。
関連項目:
次のサイトにある『Apache Avro Specification』のスキーマ解決に関する項
http://avro.apache.org/docs/current/spec.html#Schema+Resolution
%avro:schemaと似ていますが、注釈値はAvroリーダー・スキーマを含むファイルURIです。相対URIは、クライアントのローカル・ファイル・システムの現行作業ディレクトリに対して解決されます。オプション。
例: %avro:schema-file("schemas/person.avsc")。
この注釈は、%avro:schemaまたは%avro:schema-kvと組み合せることはできません。
%avro:schemaと似ていますが、注釈値は完全修飾されたレコード名です。レコード・スキーマは、Oracle NoSQL Databaseカタログから取得されます。オプション。
例: %avro:schema-kv("org.example.PersonRecord")。
この注釈を使用する場合は、Oracle NoSQL Databaseへの接続パラメータを指定する必要があります。「Oracle NoSQL Databaseアダプタの構成プロパティ」を参照してください。
この注釈は、%avro:schemaまたは%avro:schema-fileと組み合せることはできません。
最大分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%avro:split-max(1024)
%avro:split-max("1024")
%avro:split-max("1K")
最小分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%avro:split-min(1024)
%avro:split-min("1024")
%avro:split-min("1K")
次の注釈を使用して、Avroファイルを書き込む関数を定義できます。
シグネチャ
Avroファイルを書き込むカスタム関数には、次のシグネチャが必要です。
declare %avro:put("avroxml") [additional annotations]
local:myFunctionName($value as item()) external;
注釈
avroxml put関数を宣言します。必須。
Avroスキーマは、次のいずれかの注釈を使用して指定する必要があります。
%avro:schema
%avro:schema-file
%avro:schema-kv
入力XML値はスキーマのインスタンスに変換されます。「AvroとしてのXMLの書込み」を参照してください。
ファイルのスキーマを指定します。次に例を示します。
%avro:schema('
{
"type": "record",
"name": "Person",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
')
この注釈は、%avro:schema-fileまたは%avro:schema-kvと組み合せることはできません。
%avro:schemaと似ていますが、注釈値はAvroリーダー・スキーマを含むファイルURIです。相対URIは、クライアントのローカル・ファイル・システムの現行作業ディレクトリに対して解決されます。
例: %avro:schema-file("schemas/person.avsc")
この注釈は、%avro:schemaまたは%avro:schema-kvと組み合せることはできません。
%avro:schemaと似ていますが、注釈値は完全修飾されたレコード名です。レコード・スキーマは、Oracle NoSQL Databaseカタログから取得されます。
例: %avro:schema-kv("org.example.PersonRecord")
この注釈を使用する場合は、Oracle NoSQL Databaseへの接続パラメータを指定する必要があります。「Oracle NoSQL Databaseアダプタの構成プロパティ」を参照してください。
この注釈は、%avro:schemaまたは%avro:schema-fileと組み合せることはできません。
codecは、次のいずれかの文字列リテラル値です。
deflate: levelは、速度と圧縮の兼合いを制御します。有効な値は1から9で、1は最速で、9は最も圧縮されます。
snappy: このアルゴリズムは、高速で中程度の圧縮に設計されています。
デフォルトは圧縮なしです。
levelは整数値です。これはオプションで、codecがdeflateの場合のみサポートされています。
次に例を示します。
%avro:compress("snappy")
%avro:compress("deflate")
%avro:compress("deflate", 3)
出力ファイル名の接頭辞を指定します。デフォルトの接頭辞はpartです。
次の各例では、HDFS内の次のテキスト・ファイルを使用します。
mydata/ages.txt john,45 kelly,36 laura, mike,27
例6-1 テキスト・ファイルからAvroへの変換
次の問合せは、ファイルを圧縮済Avroコンテナ・ファイルに変換します。
import module "oxh:text";
declare
%avro:put("avroxml")
%avro:compress("snappy")
%avro:schema('
{
"type": "record",
"name": "AgeRec",
"fields" : [
{"name": "user", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
')
function local:put($arg as item()) external;
for $line in text:collection("mydata/ages.txt")
let $split := fn:tokenize($line, ",")
return
local:put(
<rec>
<user>{$split[1]}</user>
{
if ($split[2] castable as xs:int) then
<age>{$split[2]}</age>
else
()
}
</rec>
)
この問合せは、次のレコードを含むAvroファイルを生成します(ここではJSONと表されています)。
{"user":"john","age":{"int":45}}
{"user":"kelly","age":{"int":36}}
{"user":"laura","age":null}
{"user":"mike","age":{"int":27}}
例6-2 Avroコンテナ・ファイル内のレコードの問合せ
次の問合せは、myoutputディレクトリから、ageがnullまたは30を超えるレコードを選択します。レコードは、例6-1の問合せで生成されています。
import module "oxh:text";
import module "oxh:avro";
for $rec in avro:collection-avroxml("myoutput/part*.avro")
where $rec/age/nilled() or $rec/age gt 30
return
text:put($rec/user)
この問合せは、次の行を含むファイルを作成します。
john kelly laura
この項では、Oracle XQuery for HadoopがデータをAvroとXML間で変換する方法について説明します。
Avroファイル・アダプタとOracle NoSQL Databaseアダプタの両方にavroxmlメソッドがあり、このメソッドとcollection関数を使用して、AvroレコードをXMLとして読み取ることができます。AvroをXMLに変換した後、XQueryを使用してデータを問い合せて変換できます。
次のトピックでは、Oracle XQuery for HadoopがAvroを読み取る方法について説明します。
Avroレコードは、レコード内のフィールドごとに1つの子要素を持つ<oxh:item>要素に変換されます。
たとえば、次のAvroスキーマを考えてみます。
{
"type": "record",
"name": "Person",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
これは、XMLとしてモデル化されたレコードのインスタンスです。
<oxh:item> <full_name>John Doe</full_name> <age>46</age> </oxh:item>
AvroレコードをXMLに変換することによって、XQueryによるレコードの問合せが可能になります。次の例は、Personレコードを含むperson.avroというAvroコンテナ・ファイルを問い合せます。この問合せは、各行にfull_name値とage値を含むCSVテキスト・ファイルにレコードを変換します。
import module "oxh:avro";
import module "oxh:text";
for $x in avro:collection-avroxml("person.avro")
return
text:put($x/full_name || "," || $x/age)
null値はnilled要素に変換されます。nilled要素によってxsi:nil属性がtrueに設定されるため、常に空になります。XQueryのfn:nilled関数を使用して、レコード・フィールドがnullかどうかをテストできます。たとえば、次の問合せは、ageがnull値のPersonレコードの名前を書き込みます。
import module "oxh:avro";
import module "oxh:text";
for $x in avro:collection-avroxml("person.avro")
where $x/age/nilled()
return
text:put($x/full_name)
ネストされたレコードの場合、内部スキーマのフィールドは、外部スキーマのフィールドに対応する要素の子要素になります。たとえば、このスキーマにはネストされたレコードがあります。
{
"type": "record",
"name": "PersonAddress",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "address", "type":
{ "type" : "record",
"name" : "Address",
"fields" : [
{ "name" : "street", "type" : "string" },
{ "name" : "city", "type" : "string" }
]
}
}
]
}
これは、XMLとしてのレコードのインスタンスです。
<oxh:item>
<full_name>John Doe</full_name>
<address>
<street>123 First St.</street>
<city>New York</city>
</address>
</oxh:item>
次の例は、PersonAddressレコードを含むpeople-address.avroという名前のAvroコンテナ・ファイルを問い合せて、ニューヨーク在住の個人の名前をテキスト・ファイルに書き込みます。
import module "oxh:avro";
import module "oxh:text";
for $person in avro:collection-avroxml("examples/person-address.avro")
where $person/address/city eq "New York"
return
text:put($person/full_name)
Avroマップ値は、マップ内のエントリごとに1つの子<oxh:entry>要素を含む要素に変換されます。たとえば、次のスキーマを考えてみます。
{
"type": "record",
"name": "PersonProperties",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "properties", "type":
{"type": "map", "values": "string"}
}
]
}
これは、XMLとしてのスキーマのインスタンスです。
<oxh:item>
<full_name>John Doe</full_name>
<properties>
<oxh:entry key="employer">Example Inc</oxh:entry>
<oxh:entry key="hair color">brown</oxh:entry>
<oxh:entry key="favorite author">George RR Martin</oxh:entry>
</properties>
</oxh:item>
次の例では、PersonAddressレコードを含むperson-properties.avroという名前のファイルを問い合せて、Example Inc.社に雇用された人の名前を書き込みます。この問合せは、XPath正規表現によってどのようにマップ・エントリを取得できるかを示しています。さらに、avro:get関数をショートカットとして使用して、マップ・エントリを取得することもできます。
import module "oxh:avro";
import module "oxh:text";
for $person in avro:collection-avroxml("person-properties.avro")
where $person/properties/oxh:entry[@key eq "employer"] eq "Example Inc"
return
text:put($person/full_name)
次の問合せは、avro:get関数を使用して、employerエントリを取得します。これは、前の問合せと同等です。
import module "oxh:avro";
import module "oxh:text";
for $person in avro:collection-avroxml("person-properties.avro")
where $person/properties/avro:get("employer") eq "Example Inc"
return
text:put($person/full_name)
XQueryのfn:nilled関数を使用して、null値をテストできます。次の例は、マップ・エントリがnullの場合にtrueを返します。
$var/avro:get("key")/nilled()
Oracle XQuery for Hadoopは、Avro配列値を、配列内の項目ごとに子<oxh:item>要素を含む要素に変換します。たとえば、次のスキーマを考えてみます。
{
"type": "record",
"name": "PersonScores",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "scores", "type":
{"type": "array", "items": "int"}
}
]
}
これは、XMLとしてのスキーマのインスタンスです。
<oxh:item>
<full_name>John Doe</full_name>
<scores>
<oxh:item>128</oxh:item>
<oxh:item>151</oxh:item>
<oxh:item>110</oxh:item>
</scores>
</oxh:item>
次の例は、PersonScoresレコードを含むperson-scores.avroという名前のファイルを問い合せて、個人ごとのスコアの合計と件数を書き込みます。
import module "oxh:avro";
import module "oxh:text";
for $person in avro:collection-avroxml("person-scores.avro")
let $scores := $person/scores/*
return
text:put($person/full_name || "," || sum($scores) || "," || count($scores))
数値のXPath述語を使用すると、配列の特定の要素にアクセスできます。たとえば、このパス式は2番目のスコアを選択します。XPath索引は(0ではなく)1から始まります。
$person/scores/oxh:item[2]
Oracle XQuery for Hadoopは、値の実際のメンバー・タイプに基づいて、Avro共用体タイプのインスタンスを変換します。メンバー・タイプの名前はXML avro:type属性として包含する要素に追加されるため、問合せでは異なるメンバー・タイプのインスタンスを識別できます。ただし、メンバー・タイプが2つのみで、そのいずれかがnullの単純な共用体の場合、属性は追加されません。
たとえば、2つのレコードの次の共用体を考えてみます。
[
{
"type": "record",
"name": "Person1",
"fields" : [
{"name": "full_name", "type": "string"}
]
}
,
{
"type": "record",
"name": "Person2",
"fields" : [
{"name": "fname", "type": "string"}
]
}
]
これは、XMLとしてのスキーマのインスタンスです。
<oxh:item avro:type="Person2"> <fname>John Doe</fname> </oxh:item>
次の例は、前の共用体スキーマのインスタンスを含むperson-union.avroという名前のファイルを問い合せて、両方のレコード・タイプから個人の名前をテキスト・ファイルに書き込みます。
import module "oxh:avro";
import module "oxh:text";
for $person in avro:collection-avroxml("examples/person-union.avro")
return
if ($person/@avro:type eq "Person1") then
text:put($person/full_name)
else if ($person/@avro:type eq "Person2") then
text:put($person/fname)
else
error(xs:QName("UNEXPECTED"), "Unexpected record type:" || $person/@avro:type)
次の表に、Oracle XQuery for HadoopがAvroプリミティブ・タイプをXQueryアトミック・タイプにマップする方法を示します。
表6-1 Avroプリミティブ・タイプからXQueryアトミック・タイプへのマッピング
| Avro | XQuery |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Avro null値は空のnilled要素にマップされます。nullの文字列値と空の文字列値を識別するには、XQueryのnilled関数を使用します。このパス式は、フィールド値がnullの場合のみtrueを返します。
$record/field/fn:nilled()
Avro固定値はxs:hexBinaryにマップされ、enumsはxs:stringにマップされます。
Avroファイル・アダプタとOracle NoSQL Databaseアダプタの両方にavroxmlメソッドがあり、このメソッドとput関数を使用してXMLをAvroとして書き込むことができます。次のトピックでは、XMLをAvroインスタンスに変換する方法について説明します。
Oracle XQuery for Hadoopは、子要素名とレコードのフィールド名を照合してXMLをAvroレコード・スキーマにマップします。たとえば、次のAvroスキーマを考えてみます。
{
"type": "record",
"name": "Person",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
次のXML要素を使用して、full_nameフィールドがJohn Doeでageフィールドが46のレコードのインスタンスを書き込むことができます。ルート要素の名前(Person)は重要ではありません。子要素の名前のみを使用して、Avroレコード・フィールド(full_nameおよびage)にマップされます。
<person> <full_name>John Doe</full_name> <age>46</age> </person>
次の例では、people.csvという名前の次のCSVファイルを使用します。
John Doe,46
Jane Doe,37
.
.
.
この問合せは、CSVファイルからAvro Personレコードに値を変換します。
import module "oxh:avro";
import module "oxh:text";
declare
%avro:put("avroxml")
%avro:schema('
{
"type": "record",
"name": "Person",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
')
function local:put-person($person as element()) external;
for $line in text:collection("people.csv")
let $split := tokenize($line, ",")
return
local:put-person(
<person>
<full_name>{$split[1]}</full_name>
<age>{$split[2]}</age>
</person>
)
null値の場合は、要素を省略するか、xsi:nil="true"属性を設定できます。たとえば、この変更した問合せは、値が数値でない場合にageをnullに設定します。
.
.
.
for $line in text:collection("people.csv")
let $split := tokenize($line, ",")
return
local:put-person(
<person>
<full_name>{$split[1]}</full_name>
{
if ($split[2] castable as xs:int) then
<age>{$split[2]}</age>
else
()
}
</person>
)
ネストされたレコードの場合、値はネストされた要素から取得されます。次の例では、次のスキーマを使用します。
{
"type": "record",
"name": "PersonAddress",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "address", "type":
{ "type" : "record",
"name" : "Address",
"fields" : [
{ "name" : "street", "type" : "string" },
{ "name" : "city", "type" : "string" }
]
}
}
]
}
次のXMLを使用して、このレコードのインスタンスを書き込むことができます。
<person>
<full_name>John Doe</full_name>
<address>
<street>123 First St.</street>
<city>New York</city>
</address>
</person>
Oracle XQuery for Hadoopは、XMLを、<oxh:entry>子要素ごとに1つのマップ・エントリを持つAvroマップに変換します。たとえば、次のスキーマを考えてみます。
{
"type": "record",
"name": "PersonProperties",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "properties", "type":
{"type": "map", "values": "string"}
}
]
}
次のXML要素を使用して、full_nameフィールドがJohn Doeでpropertiesフィールドが3つのエントリを持つマップに設定されたスキーマのインスタンスを書き込むことができます。
<person>
<full_name>John Doe</full_name>
<properties>
<oxh:entry key="hair color">brown</oxh:entry>
<oxh:entry key="favorite author">George RR Martin</oxh:entry>
<oxh:entry key="employer">Example Inc</oxh:entry>
</properties>
</person>
Oracle XQuery for Hadoopは、XMLを、<oxh:item>子要素ごとに1つの項目を持つAvro配列に変換します。たとえば、次のスキーマを考えてみます。
{
"type": "record",
"name": "PersonScores",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "scores", "type":
{"type": "array", "items": "int"}
}
]
}
次のXML要素を使用して、full_nameフィールドがJohn Doeでscoresフィールドが[128、151、110]に設定されたスキーマのインスタンスを書き込むことができます。
<person>
<full_name>John Doe</full_name>
<scores>
<oxh:item>128</oxh:item>
<oxh:item>151</oxh:item>
<oxh:item>110</oxh:item>
</scores>
</person>
Avro共用体タイプを書き込むとき、Oracle XQuery for Hadoopはavro:type属性の値に基づいてメンバー・タイプを選択します。
この例では、次のスキーマを使用します。
[
{
"type": "record",
"name": "Person1",
"fields" : [
{"name": "full_name", "type": "string"}
]
}
,
{
"type": "record",
"name": "Person2",
"fields" : [
{"name": "fname", "type": "string"}
]
}
]
次のXMLは、Person1レコードのインスタンスにマップされます。
<person avro:type="Person1"> <full_name>John Doe</full_name> </person>
このXMLは、Person2レコードのインスタンスにマップされます。
<person avro:type="Person2"> <fname>John Doe</fname> </person>
avro:type属性では、共用体のメンバー・タイプを選択します。nullと他のタイプを1つずつ含む単純な共用体の場合、avro:type属性は不要です。メンバー・タイプが判別できない場合は、エラーが発生します。
プリミティブ値をマップするために、Oracle XQuery for Hadoopは表6-1に示す同等のデータ型を使用して、XML値を対応するAvroタイプにキャストします。値をAvroタイプに変換できない場合は、エラーが発生します。
この例では、次のスキーマを使用します。
{
"type": "record",
"name": "Person",
"fields" : [
{"name": "full_name", "type": "string"},
{"name": "age", "type": ["int", "null"] }
]
}
string値appleをintに変換できないため、次のXMLをこのスキーマのインスタンスにマップしようとするとエラーが発生します。
<person> <full_name>John Doe</full_name> <age>apple</age> </person>
JSONファイル・アダプタは、HDFSに格納されたJSONファイルへのアクセスを提供します。他のファイル形式で埋め込まれているJSONデータを処理するための関数も含まれています。たとえば、大規模なテキスト・ファイルに行として格納されているJSONを問い合せるには、json:parse-as-xmlおよびtext:collection関数を使用します。
現在、単一のJSONファイルの並列処理はサポートされていません。一連のJSONファイルの並列処理は、各ファイルを順次処理して行うことができます。
JSONモジュールについては、次のトピックを参照してください。
問合せで組込み関数を使用するには、次のようにJSONファイル・モジュールをインポートする必要があります。
import module "oxh:json";
JSONモジュールには、次の関数が含まれています。
Big Data Connectorsリリース4.9以上では、Oracle XQuery for HadoopでもXQuery 3.1がサポートされるようになりました(fn:parse-json、fn:json-to-xml、fn:xml-to-jsonなど、JSONを処理するための標準機能を含む)
HDFS内のJSONファイルのコレクションにアクセスします。複数のファイルを同時に処理できますが、個々のファイルは1つのタスクによって解析されます。
Hadoopでサポートされている圧縮コーデックを使用して圧縮されたファイルは、JSONファイル・アダプタによって自動的に解凍されます。
シグネチャ
json:collection-jsonxml($uris as xs:string*) as element()* external;
パラメータ
$uris: JSONファイルのURI
戻り値
JSON値をモデル化するXML要素。「XMLへのJSONデータ形式の変換について」を参照してください。
JSON値をXMLとして解析します。
シグネチャ
json:parse-as-xml($arg as xs:string?) as element(*)?
パラメータ
$arg: 空の順序を指定できます。
戻り値
JSON値をモデル化するXML要素。$argが空の順序の場合は、空の順序です。「XMLへのJSONデータ形式の変換について」を参照してください。
XMLとしてモデル化されたJSONオブジェクトからエントリを取得します。「XMLへのJSONデータ形式の変換について」を参照してください。
シグネチャ
json:get($key as xs:string?, $obj as node()?) as element(oxh:entry)? json:get($key as xs:string?) as element(oxh:entry)?
パラメータ
$key: JSONデータ・キー
$obj: JSONオブジェクト値
戻り値
次のXPath式の値。
$obj/oxh:entry[@key eq $key]
$inputが存在しない場合、動作は、2つの引数の関数を呼び出して$objのコンテキスト項目を使用するのと同じです。「注意」を参照してください。
注意
次の関数呼出しは同等です。
$var/json:get("key")
json:get("key", $var)
$var/oxh:entry[@key eq "key"]
$varは、XMLとしてモデル化されたJSONオブジェクトです。「マップの読取り」を参照してください。
次の注釈を使用して、HDFS内のJSONファイルのコレクションを読み取る関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
JSONファイルを読み取るカスタム関数には、次のシグネチャが必要です。
declare %json:collection("jsonxml") [additional annotations]
function local:myFunctionName($uris as xs:string*) as element()* external;
注釈
collection関数を宣言します。注釈パラメータはjsonxmlである必要があります。
入力ファイルのテキスト・エンコードを識別します。
有効なエンコードは、JVMでサポートされているエンコードです。この注釈を省略すると、エンコードは、UTF-8、UTF-16のビッグエンディアン・シリアライズ(BE)またはリトルエンディアン・シリアライズ(LE)、UTF-32 (BEまたはLE)としてJSONファイルから自動的に検出されます。
パフォーマンスを向上させるには、次のInternet Engineering Task Force (IETF)のWebサイトにある『JSON Request for Comment 4627』のエンコードに関する項に従って実際のファイル・エンコードを指定する場合に、エンコードの注釈を省略します。
戻り値
XML要素のコレクション。各要素は対応するJSON値をモデル化します。「XMLへのJSONデータ形式の変換について」を参照してください。
例6-3
この例では、HDFSに格納されている次のJSONテキスト・ファイルを使用します。
mydata/users1.json
[
{ "user" : "john", "full name" : "John Doe", "age" : 45 },
{ "user" : "kelly", "full name" : "Kelly Johnson", "age" : 32 }
]
mydata/users2.json
[
{ "user" : "laura", "full name" : "Laura Smith", "age" : null },
{ "user" : "phil", "full name" : "Phil Johnson", "age" : 27 }
]
次の問合せは、姓がJohnsonであるユーザーの名前をusers1.jsonおよびusers2.jsonから選択します
import module "oxh:text";
import module "oxh:json";
for $user in json:collection-jsonxml("mydata/users*.json")/oxh:item
let $fullname := $user/json:get("full name")
where tokenize($fullname, "\s+")[2] eq "Johnson"
return
text:put-text($fullname)
この問合せは、次の行を含むテキスト・ファイルを生成します。
Phil Johnson Kelly Johnson
残りの例では、HDFS内の次のテキスト・ファイルを問い合せます。
mydata/users-json.txt
{ "user" : "john", "full name" : "John Doe", "age" : 45 }
{ "user" : "kelly", "full name" : "Kelly Johnson", "age" : 32 }
{ "user" : "laura", "full name" : "Laura Smith", "age" : null }
{ "user" : "phil", "full name" : "Phil Johnson", "age" : 27 }
例6-4
次の問合せは、30歳を超えるユーザーの名前をusers-json.txtから選択します。
import module "oxh:text";
import module "oxh:json";
for $line in text:collection("mydata/users-json.txt")
let $user := json:parse-as-xml($line)
where $user/json:get("age") gt 30
return
text:put($user/json:get("full name"))
この問合せは、次の行を含むテキスト・ファイルを生成します。
John Doe Kelly Johnson
例6-5
次の問合せは、age値がnullの従業員の名前をusers-json.txtから選択します。
import module "oxh:text";
import module "oxh:json";
for $line in text:collection("mydata/users-json.txt")
let $user := json:parse-as-xml($line)
where $user/json:get("age")/nilled()
return
text:put($user/json:get("full name"))
この問合せは、次の行を含むテキスト・ファイルを生成します。
Laura Smith
Oracle XQuery for Hadoopでは、構成プロパティを指定する汎用オプションをhadoopコマンドで使用します。構成ファイルを指定する場合は-confオプションを使用し、個別のプロパティを指定する場合は-Dオプションを使用します。
次の構成プロパティは、同じ名前のJacksonパーサー・オプションと同等です。オプション名は、大文字で入力しても小文字で入力してもかまいません。たとえば、oracle.hadoop.xquery.json.parser.ALLOW_BACKSLASH_ESCAPING_ANY_CHARACTERとoracle.hadoop.xquery.json.parser.allow_backslash_escaping_any_characterは同じです。
型: Boolean
デフォルト値: false
説明: 文字をバックスラッシュ(\)でエスケープできます。それ以外の場合は、次の文字のみをエスケープできます: 引用符(")、スラッシュ(/)、バックスラッシュ(\)、バックスペース、フォーム・フィード(f)、改行(n)、キャリッジ・リターン(r)、水平タブ(t)および16進表現(unnnn)。
型: Boolean
デフォルト値: false
説明: 解析されたテキスト内でJavaおよびC++のコメント(/* and //)を使用できます。
型: Boolean
デフォルト値: false
説明: 非数(NaN)トークンを浮動小数点値として解析できます。
型: Boolean
デフォルト値: false
説明: 整数値を、00001などゼロで始めることができます。ゼロによって値が変わることはなく、ゼロは無視できます。
型: Boolean
デフォルト値: false
説明: 一重引用符(')で文字列値を区切ることができます。
型: Boolean
デフォルト値: false
説明: JSON文字列に引用符で囲まれていない制御文字(つまり、タブやライン・フィードなど、32未満の10進値であるASCII文字)を含めることができます。
型: Boolean
デフォルト値: false
説明: 引用符で囲まれていないフィールド名を使用できます。これは、JSON仕様ではなく、Javascriptによって許可されます。
関連項目
この項では、JSONデータ形式がどのようにXMLに変換されるかについて説明します。この項の内容は次のとおりです。
Big Data Connectorsリリース4.9以上では、Oracle XQuery for HadoopでもXQuery 3.1がサポートされるようになりました(fn:parse-json、fn:json-to-xml、fn:xml-to-jsonなど、JSONを処理するための標準機能を含む)
JSONオブジェクトはAvroマップに似ており、同じXML構造に変換されます。「マップの読取り」を参照してください。
たとえば、次のJSONオブジェクトがXML要素に変換されます。
{
"user" : "john",
"full_name" : "John Doe",
"age" : 45
}
オブジェクトは次の要素としてモデル化されます。
<oxh:item>
<oxh:entry key="user">john</oxh:entry>
<oxh:entry key="full_name">John Doe</oxh:entry>
<oxh:entry key="age">45</oxh:entry>
</oxh:item>
JSON配列はAvro配列に似ており、同じXML構造に変換されます。「配列の読取り」を参照してください。
たとえば、次のJSON配列がXML要素に変換されます。
[ "red", "blue", "green" ]
配列は次の要素としてモデル化されます。
<oxh:item> <oxh:item>red</oxh:item> <oxh:item>blue</oxh:item> <oxh:item>green</oxh:item> </oxh:item>
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のインストール」のステップ3を参照してください。必須ではありませんが、このアダプタを使用する前に、Oracle Loader for Hadoopをよく理解しておくと役立ちます。
次のトピックでは、Oracle Databaseアダプタについて説明します。
関連項目:
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()*に自動的に割り当てられます。次の表に説明するように、入力値は実行時に、対応する表列タイプに対して許容されるXQueryタイプにキャストされます。たとえば、NUMBERデータ型の列にマップされるデータ値は、xs:decimalとして自動的にキャストされます。キャストが失敗すると、エラーが発生します。
あるいは、パラメータのタイプまたはそのサブタイプを指定できます。この場合、コンパイル時タイプのチェックが実行されます。たとえば、NUMBER列に対応するパラメータを$column as xs:decimalとして宣言できます。また、xs:decimalのサブタイプ(xs:integerなど)として宣言することもできます。
指定する各パラメータ・タイプにオプションのオカレンス・インジケータ?を含めることができます。このインジケータを使用すると、実行時に空の順序をパラメータ値として渡すことができ、nullがデータベース表に挿入されます。?以外のオカレンス・インジケータを使用するとコンパイル時エラーが発生します。
次の表に、サポートされている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)
例6-6 すべての列のロード
最初の問合せは、ページ・アクセスに関連するすべての情報(アクセスの時間、ユーザー名、アクセスしたページ、およびステータス・コード)をVISITS表にロードします。匿名アクセスの場合はユーザー名が欠落しているため、問合せでは()を指定してnullを表に挿入します。ターゲット表名、ユーザー名、パスワードおよび接続URLは、%oracle-property注釈を使用して指定します。
例ではクリア・テキストのユーザー名およびパスワードを使用しています。これは安全ではありませんが開発環境では受け入れられます。セキュリティのために、特に本番のアプリケーションではクリア・テキストではなくウォレットの使用をお薦めします。Oracle Loader for Hadoopプロパティ、またはそれと同等の%oracle-property注釈のいずれかを使用して、Oracleウォレットを構成できます。設定する必要がある特定のプロパティは、「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
例6-7 選択した列のロード
この例では、%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は、これらのプロパティ(次の表の最後の列を参照)の多くをサポートしています。
これらのプロパティは、汎用の-confおよび-D hadoopコマンドライン・オプションを使用してOracle XQuery for Hadoopに指定できます。この方法を使用して指定されるプロパティは、問合せ内のOracle Databaseアダプタのすべてのput関数に適用されます。hadoopコマンドライン・オプションの詳細は、「問合せの実行」、特に「汎用オプション」を参照してください。
あるいは、%oracle-property接頭辞を使用して、これらのプロパティをOracle Databaseアダプタのput関数の注釈として指定できます。これらの注釈は、次の表の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注釈を使用して、異なる表名を設定します。
次の表に、Oracle Loader for Hadoopプロパティおよびそれと同等のOracle XQuery for Hadoop注釈を機能カテゴリ別に示します。Oracle XQuery for Hadoopは、この表に示されているOracle Loader for Hadoopプロパティのみサポートしています。
表6-4 構成プロパティおよび対応する%oracle-property注釈
| カテゴリ | プロパティ | 注釈 |
|---|---|---|
接続 |
|
|
接続 |
|
|
接続 |
|
|
接続 |
|
|
接続 |
|
|
接続 |
|
|
接続 |
|
|
接続 |
|
|
接続 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
一般 |
|
|
出力 |
|
|
出力 |
|
|
出力 |
|
|
出力 |
|
|
出力 |
|
|
出力 |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
|
サンプラ |
|
このアダプタは、Oracle NoSQL Databaseに格納する値の読取りおよび書込みを実行する関数を提供します。
次のトピックでは、このアダプタについて説明します。
Oracle NoSQL Databaseアダプタを使用する問合せを記述する前に、Oracle NoSQL Databaseサーバーを使用するようにOracle XQuery for Hadoopを構成する必要があります。
次を設定する必要があります。
Oracle NoSQL Databaseのlibディレクトリを含むローカル・ディレクトリへのKVHOME環境変数。
oracle.kv.hostsおよびoracle.kv.kvstore構成プロパティ。
search-mr-<version>.jarおよびsearch-mr-<version>-job.jarを含むローカル・ディレクトリへのOXH_SOLR_MR_HOME環境変数。Tikaパーサーが呼び出される場合のみ。つまり、kv:collection-tika()関数またはkv:get-tika()関数が呼び出されるとき、あるいは外部関数で%kv:collection('tika')注釈または%kv:get('tika')注釈が使用されるときのみです。
構成プロパティは、問合せの実行時に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
この例では、Tikaパーサーが呼び出されるときのOXH_SOLR_MR_HOME環境変数を設定します。
$ export OXH_SOLR_MR_HOME=/usr/lib/solr/contrib/mr
注意:
HADOOP_CLASSPATH環境変数または-libjarsコマンドライン・オプションには、NoSQL DB jarsは含まれません。
「Oracle NoSQL Databaseアダプタの構成プロパティ」を参照してください。
問合せで組込み関数を使用するには、次のようにOracle NoSQL Databaseモジュールをインポートする必要があります。
import module "oxh:kv";
データベース内の値のコレクションにアクセスします。各値は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ドキュメント。
指定された値が呼び出されてドキュメント・ノードとして返されるときに、Tikaを使用してこの値を解析します。
シグネチャ
declare %kv:collection("tika") function
kv:collection-tika($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?) $contentType as xs:string?) as document-node()* external;
パラメータ
「パラメータ」を参照してください。$subrangeを省略すると、$subrange()を指定したことと同じになります。同様に、$depthを省略すると、$depth()を指定したのと同じです。
戻り値
各値に対して1つのドキュメント・ノード。
キーと値のペアを書き込みます。$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;
キーに関連付けられた値を取得します。値はバイト配列として解析され、ドキュメント・ノードとして返されます。
シグネチャ
declare %kv:get("tika") function
kv:get-tika($key as xs:string, $contentType as xs:string?) as document-node()? external;
接頭辞の範囲を定義します。接頭辞は、上限と下限(両端を含む)の両方を定義します。
この関数は、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の場合は含まれません。
問合せで組込み関数を使用するには、次のように、ネームスペースが宣言され、モジュールがインポートされている必要があります。
declare namespace kv-table = "oxh:kv-table"; import module "oxh:kv-table";
これらの関数は、NoSQL Databaseの単一表に格納されたすべての列または列のサブセットを反復します。それぞれの列は、JSON文字列形式で返されます。
シグネチャ
declare %kv-table:collection-jsontext("jsontext") function
kv-table:collection-jsontext($tableName as xs:string) as xs:string*
declare %kv-table:collection(“jsontext") function kv-table:collection-jsontext($tableName as xs:string, $primaryKeyJsonValue as xs:string?) as xs:string*
declare %kv-table:collection(“jsontext") function kv-table:collection-jsontext($tableName as xs:string, $primaryKeyJsonValue as xs:string?, $fieldRangeJsonValue as xs:string?) as xs:string*
パラメータ
$tableName as xs:string – NoSQL Database内の表の名前
$primaryKeyJsonValue as xs:string? – JSONテキストとして指定された部分主キー
$fieldRangeJsonValue as xs:string? – JSONテキストとして指定された主キーの残りのフィールドのフィールド幅
{
"name": “fieldname",
"start": “startVal",
"startInclusive": true|false,
"end" : "endVal",
"endInclusive": true|false
}
戻り値
それぞれの列のJSON値
json:parse-as-xml関数を使用して、JSON文字列をXMLドキュメントに解析します
この関数は、NoSQL Database内の表に格納された単一列を読み込みます。列は、JSON文字列形式で返されます。列が見つからない場合は、空の順序が返されます。
シグネチャ
declare %kv-table:get(“jsontext") function kv-table:get-jsontext($tableName as xs:string, $primaryKeyJsonValue as xs:string) as xs:string?
パラメータ
$tableName as xs:string – NoSQL Database内の表の名前
$primaryKeyJsonValue as xs:string? – JSONテキストとして指定された完全主キー
関連項目:
http://docs.oracle.com/cd/NOSQL/html/GettingStartedGuideTables/primaryshardkeys.html#primarykeys
戻り値
列が見つからない場合、列のJSON値または空の順序。
json:parse-as-xml関数を使用して、JSON文字列をXMLドキュメントに解析します
問合せで組み込み関数を使用するには、次のように、ネームスペースが宣言され、モジュールがインポートされている必要があります。
declare namespace kv-lob = "oxh:kv-lob"; import module "oxh:kv-lob";
ラージ・オブジェクトAPIを使用したOracle NoSQL Databaseモジュールには、次の関数が含まれています。
キーに関連付けられた値を取得します。値はUTF-8としてデコードされ、文字列として返されます。
シグネチャ
declare %kv-lob:get("text")
function kv-lob:get-text($key as xs:string) as xs:string?
キーに関連付けられた値を取得します。値は一連のバイトとして読み取られ、XMLとして解析されます。
シグネチャ
declare %kv-lob:get("xml")
function kv-lob:get-xml($key as xs:string) as document-node()?
キーに関連付けられた値を取得します。値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。『Oracle XML Developer's Kitプログラマーズ・ガイド』を参照してください。
シグネチャ
declare %kv-lob:get("binxml")
function kv-lob:get-binxml($key as xs:string) as document-node()?
キーに関連付けられた値を取得します。値はバイト配列として解析され、ドキュメント・ノードとして返されます。
シグネチャ
declare %kv-lob:get("tika")
function kv-lob:get-tika($key as xs:string) as document-node()?
declare %kv-lob:get("tika")
function kv-lob:get-tika($key as xs:string, $contentType as xs:string?) as document-node()?
キーと値のペアを書き込みます。$valueはUTF-8としてエンコードされます。
シグネチャ
declare %kv-lob:put("text")
function kv-lob:put-text($key as xs:string, $value as xs:string)
キーと値のペアを書き込みます。$xmlはシリアライズされ、UTF-8としてエンコードされます。
シグネチャ
declare %kv-lob:put("xml")
function kv-lob:put-xml($key as xs:string, $document as node())
次の関数を使用して、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"|"tika"]) [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("tika") [additional annotations]
function local:myFunctionName($parent-key as xs:string?, $depth as xs:int?, $subrange as xs:string?, $contentType as xs:string?) as document-node()* external;
注釈
NoSQL Databaseのcollection関数を宣言します。必須。
methodパラメータは次のいずれかの値です。
avroxml: 各値はAvroレコードとして読み取られ、XML要素として返されます。レコードはXMLに変換されます(「レコードの読取り」を参照)。
binxml: 各値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。
text: 各値は、%output:encoding注釈で指定された文字セットを使用してデコードされます。
tika: 各値はTikaにより解析され、ドキュメント・ノードとして返されます。
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スタート・ガイド』
http://docs.oracle.com/cd/NOSQL/html/GettingStartedGuide/schemaevolution.html
テキスト値の文字エンコードを指定します。この注釈を使用しないと、UTF-8とみなされます。有効なエンコードは、JVMでサポートされているエンコードです。
現在、この注釈はテキスト・メソッドにのみ適用されます。XMLファイルの場合は、ドキュメントのエンコード宣言が使用されます(使用可能な場合)。
関連項目:
次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項
http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html
パラメータ
関数によって子のキーと値のペアが返される親キーを指定します。メジャー・キー・パスを部分パスとし、マイナー・キー・パスを空にする必要があります。空の順序によって、ストア内のすべてのキーがフェッチされます。
関連項目:
キーの書式については、次のサイトにあるOracle NoSQL Database Javaリファレンス
http://docs.oracle.com/cd/NOSQL/html/javadoc/oracle/kv/Key.html#toString
親、子、子孫またはその組合せを返すかどうかを指定します。次の値が有効です。
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関数を使用すると、範囲文字列を簡単に作成できます。
値に空の順序を指定することもできます。
次の例は、有効な部分範囲の指定です。
| 例 | 説明 |
|---|---|
|
alpha (この値を含む)からbeta (この値を含まない) |
|
"" (この値を含まない)から0123 (この値を含む) |
|
chi (この値を含む)から無限大 |
|
"" (この値を含まない)から無限大 |
|
負の無限大からchi (この値を含まない) |
|
負の無限大から"" (この値を含む) |
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"|"tika"]) [additional annotations]
function local:myFunctionName($key as xs:string) as document-node()?
declare %kv:get(["tika"]) [additional annotations]
function local:myFunctionName($key as xs:string $contentType as xs:string?) as document-node()?
注釈
NoSQL Databaseのget関数を宣言します。必須。
methodパラメータは次のいずれかの値です。
avroxml: 値はAvroレコードとして読み取られ、XML要素として返されます。レコードはXMLに変換されます(「レコードの読取り」を参照)。
binxml: 値はXDKバイナリXMLとして読み取られ、XMLドキュメントとして返されます。
text: 値は、%output:encoding注釈で指定された文字セットを使用してデコードされます。
tika: 各値はTikaにより解析され、ドキュメント・ノードとして返されます。
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スタート・ガイド』
http://docs.oracle.com/cd/NOSQL/html/GettingStartedGuide/schemaevolution.html
テキスト値の文字エンコードを指定します。この注釈を使用しないと、UTF-8とみなされます。有効なエンコードは、JVMでサポートされているエンコードです。
現在、この注釈はテキスト・メソッドにのみ適用されます。XMLファイルの場合は、ドキュメントのエンコード宣言が使用されます(使用可能な場合)。
関連項目:
次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項
http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html
次の関数を使用して、表APIでOracle NoSQL Databaseから値を読み取ることができます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
表APIを使用してNoSQL値のコレクションを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv-table:collection(“jsontext") function local:myFunctionName($tableName as xs:string) as xs:string* external;
declare %kv-table:collection(“jsontext") function local:myFunctionName($tableName as xs:string, $primaryKeyJsonValue as xs:string?) as xs:string* external;
declare %kv-table:collection(“jsontext") function local:myFunctionName($tableName as xs:string, $primaryKeyJsonValue as xs:string?, $fieldRangeJsonValue as xs:string?) as xs:string* external;
パラメータ
「パラメータ」と同様です。
戻り値
「戻り値」と同様です。
次の関数を使用して、表APIでOracle NoSQL Databaseから単一列を読み取ることができます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
表APIを使用してNoSQL Databaseのシグネチャ列を読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv-table:get(“jsontext") function local:myFunctionName($tableName as xs:string, $primaryKeyJsonValue as xs:string?) as xs:string? external;
パラメータ
「パラメータ」と同様です。
戻り値
「戻り値」と同様です。
次の関数を使用して、ラージ・オブジェクトAPIでOracle NoSQL Databaseから値を読み取ることができます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
ラージ・オブジェクトAPIを使用して単一値を読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv-lob:get("text") [additional annotations]
function local:myFunctionName($key as xs:string) as xs:string? external;
declare %kv-lob:get(["xml"|"binxml"|"tika"]) [additional annotations] function local:myFunctionName($key as xs:string) as document-node()?
declare %kv-lob:get(["tika"]) [additional annotations] function local:myFunctionName($key as xs:string $contentType as xs:string?) as document-node()?
注釈
ラージ・オブジェクトAPIを使用するNoSQL Databaseのget関数を宣言します。必須。サポートされているメソッド・パラメータは、binxml、text、tikaおよびxmlです(%kv:get("method")と同様です)。
注意:
avroxmlメソッドは、ラージ・オブジェクトAPIではサポートされていません。
キーと値のペアのキーが、ドキュメントURIの戻り値として設定されるかどうかを制御します。キーを返すにはtrueに指定します。%kv:key()と同様です。
テキスト値の文字エンコードを指定します。この注釈を使用しないと、UTF-8とみなされます。有効なエンコードは、JVMでサポートされているエンコードです。現在、この注釈はテキスト・メソッドにのみ適用されます。XMLファイルの場合は、ドキュメントのエンコード宣言が使用されます(使用可能な場合)。
次の注釈を使用して、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;
注釈
| 注釈 | 説明 |
|---|---|
%kv:put("method") |
NoSQL Databaseモジュールのput関数を宣言します。必須。 methodは値の格納方法を決定します。次のいずれかの値です。
|
%avro:schema-kv("schema-name") |
書き込まれる値のレコード・スキーマを指定します。注釈値は完全修飾されたレコード名です。レコード・スキーマは、Oracle NoSQL Databaseカタログから取得されます。 例: |
%output:* |
|
次の注釈を使用して、表APIを使用するOracle NoSQL Databaseに書き込む関数を定義できます。
シグネチャ
表APIを使用して列を書き込むカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv-table:put(“jsontext") function local:myFunctionName($tableName as xs:string, $jsonValue as xs:string?) external;
パラメータ
「パラメータ」と同様です。
次の注釈を使用して、ラージ・オブジェクトAPIを使用するOracle NoSQL Databaseに書き込む関数を定義できます。
シグネチャ
ラージ・オブジェクトAPIを使用して値を書き込むカスタム関数には、次のいずれかのシグネチャが必要です。
declare %kv-lob:put("text")
function local:myFunctionName($key as xs:string, $value as xs:string) external;
declare %kv-lob:put(["xml"|"binxml"]) function local:myFunctionName($key as xs:string, $xml as node()) external;
注釈
NoSQL Databaseのput関数を宣言します。必須。サポートされているメソッド・パラメータは、binxml、textおよびxmlです("%kv:put("method")"と同様です)
注意:
avroxmlメソッドは、ラージ・オブジェクトAPIではサポートされていません。
%kv-lob:putで指定される出力方法(テキストまたはXML)に対する標準XQueryシリアライズ・パラメータ。「シリアライズ注釈」を参照してください。
例6-8 Oracle NoSQL Databaseに対するテキストの書込みと読取り
この例では、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
例6-9 Oracle NoSQL Databaseに対するAvroの書込みと読取り
この例では、次の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
例6-10 NoSQL DatabaseへのXMLの格納
次の問合せは、「XMLファイル・アダプタの関数の例」の例6-24に示されているXMLファイルを入力として使用します。Oracle NoSQL Databaseの値として、各コメント要素を書き込みます。
import module "oxh:xmlf";
import module "oxh:kv";
for $comment in xmlf:collection("mydata/comments*.xml")/comments/comment
let $key := "/comments/" || $comment/@id
return
kv:put-xml($key, $comment)
問合せは5つのcomment要素をXML値としてOracle NoSQL Databaseに書き込みます。
非常に大きなXMLファイルの場合、問合せを次のように修正することでパフォーマンスを向上し、ディスク・スペースの消費を削減します。
次のfor句を使用します。これにより、各XMLファイルが分割されて複数のタスクで並行して実行されるようになります。
for $comment in xmlf:collection("mydata/comments*.xml", "comment")
return句ではkv:put-xmlではなく、kv:put-binxmlを使用して、プレーン・テキストではなくバイナリXMLで値を格納します。
kv:collection-xml関数を使用してデータベースの値を読み込みます。次に例を示します。
import module "oxh:text";
import module "oxh:kv";
for $comment in kv:collection-xml("/comments")/comment
return
text:put($comment/@id || " " || $comment/@user)
この問合せは、次の行を含むテキスト・ファイルを作成します。
12345 john 23456 john 54321 mike 56789 kelly 87654 mike
例6-11 XMLをAvroとしてOracle NoSQL Databaseに格納
この例は、XML値をAvroに変換してから格納します。
次のAvroスキーマをOracle NoSQL Databaseに追加します。
{
"type": "record",
"name": "Comment",
"namespace": "com.example",
"fields" : [
{"name": "cid", "type": "string"},
{"name": "user", "type": "string"},
{"name": "content", "type": "string"},
{"name": "likes", "type" : { "type" : "array", "items" : "string" } }
]
}
次の問合せは、5つのcomment要素をAvro値としてOracle NoSQL Databaseに書き込みます。
import module "oxh:xmlf";
import module "oxh:kv";
declare %kv:put("avroxml") %avro:schema-kv("com.example.Comment")
function local:put-comment($key as xs:string, $value as node()) external;
for $comment in xmlf:collection("mydata/comments*.xml", "comment")
let $key := "/comments/" || $comment/@id
let $value :=
<comment>
<cid>{$comment/@id/data()}</cid>
<user>{$comment/@user/data()}</user>
<content>{$comment/@text/data()}</content>
<likes>{
for $like in $comment/like
return <oxh:item>{$like/@user/data()}</oxh:item>
}</likes>
</comment>
return
local:put-comment($key, $value)
kv:collection-avroxml関数を使用して、データベースの値を読み込みます。次に例を示します。
import module "oxh:text";
import module "oxh:kv";
for $comment in kv:collection-avroxml("/comments")
return
text:put($comment/cid || " " || $comment/user || " " || count($comment/likes/*))
この問合せは、次の行を含むテキスト・ファイルを作成します。
12345 john 0 23456 john 2 54321 mike 1 56789 kelly 2 87654 mike 0
例6-12 Oracle NoSQL Database表APIを使用するデータの読取りおよび書込み
この例では、HDFS内の次のテキスト・ファイルを使用します。このファイルには、ユーザーID、姓名、年齢などのユーザー・プロファイル情報がコロン(:)区切りで格納されています。
mydata/users.txt john:John Doe:45 kelly:Kelly Johnson:32 laura:Laura Smith: phil:Phil Johnson:27
次のようにして、usersという名前の表をNoSQL DBに作成します。
CREATE TABLE users (id STRING, name STRING, age INTEGER, PRIMARY KEY (id));
最初の問合せは、この表にユーザーの年齢を格納します。
import module "oxh:text";
import module "oxh:kv-table";
for $line in text:collection("mydata/users.txt")
let $split := tokenize($line, ":")
let $id := $split[1]
let $name := $split[2]
let $age := $split[3]
where string-length($age) gt 0
let $row :=
'{' ||
'"id":"' || $id || '",' ||
'"name":"' || $name || '",' ||
'"age":' || $age ||
'}'
return
kv-table:put-jsontext(“users", $row)
この問合せを実行すると、表には次のレコードが含まれます。
| id | name | age |
|---|---|---|
john |
John Doe |
45 |
kelly |
Kelly Johnson |
32 |
phil |
Phil Johnson |
27 |
2番目の問合せは、表から列を読み取り、名前がJohnsonで終わるユーザーのIDを返します。
import module "oxh:text ";
import module "oxh:json";
import module "oxh:kv-table";
for $row in kv-table:collection("users")
let $user := json:parse-as-xml($row)
let $id := $user/json:get(“id")
let $name := $user/json:get(“name")
where ends-with($name, “Johnson")
return text:put($id)
この問合せは、次の行を含むテキスト・ファイルを作成します。
kelly phil
例6-13 Oracle NoSQL Databaseラージ・オブジェクトAPIを使用するデータの読取り
Oracle NoSQL Databaseに次の情報が含まれているとします。
表userImages
CREATE TABLE userImages (imageFileName STRING、imageVersion STRING、imageDescription INTEGER、PRIMARY KEY (imageFileName))
| imageFileName | imageVersion | imageDescription |
|---|---|---|
IMG_001.JPG |
1 |
Sunrise |
IMG_002.JPG |
1 |
Sunrise |
ラージ・オブジェクトAPIでロードされるKey/Valueデータは次のとおりです。
Keyは、lob/imageFileName/image.lobです
Valueは、JPEGイメージでEXIF形式の位置情報のメタデータを含みます
次の問合せは、メタデータを抽出して、imageFileName、緯度および経度としてCSV形式に変換します。
import module “oxh:kv-table";
import module “oxh:kv-lob";
import module "oxh:tika";
import module "oxh:json";
import module "oxh:text ";
for $row in kv-table:collection("userImages")
let $imageFileName := json:parse-as-xml($row)/json:get(“imageFileName")
let $imageKey := “lob/" || $imageFileName || “/image.lob"
let $doc := kv-lob:get-tika($imageKey, “image/jpeg")
let $lat := $doc/tika:metadata/tika:property[@name eq "GPS Latitude"]
let $lon := $doc/tika:metadata/tika:property[@name eq "GPS Longitude"]
where exists($lat) and exists($lon)
return text:put($imageFileName || "," || $lat || "," || $lon)
Oracle XQuery for Hadoopでは、構成プロパティを指定する汎用オプションをHadoopコマンドで使用します。構成ファイルを指定する場合は-confオプションを使用し、個別のプロパティを指定する場合は-Dオプションを使用します。「問合せの実行」を参照してください。
Oracle NoSQL Databaseアダプタには、永続性およびタイムアウト期間を制御する各種の構成プロパティを設定できます。oracle.kv.hostsおよびoracle.kv.kvstoreを設定する必要があります。次のプロパティでOracle NoSQL Databaseアダプタを構成します。
| プロパティ | 説明 |
|---|---|
oracle.hadoop.xquery.kv.config.durability |
型: String デフォルト値: 説明: MasterPolicy, ReplicaPolicy, ReplicaAck
|
oracle.hadoop.xquery.kv.config.requestLimit |
型: 整数のカンマ区切りのリスト デフォルト値: 100, 90, 80 説明: 同時要求の数を制限して、サービス時間が長い複数のノードがKVストア・クライアントのすべてのスレッドを消費するのを防ぎます。値は3つの整数で構成され、順番に指定してカンマで区切ります。 maxActiveRequests, requestThresholdPercent, nodeLimitPercent
|
oracle.hadoop.xquery.kv.config.requestTimeout |
型: Long デフォルト値: 5000ミリ秒 説明: 要求のタイムアウト期間をミリ秒で構成します。値はゼロ(0)より大きい必要があります。 |
oracle.hadoop.xquery.kv.config.socketOpenTimeout |
型: Long デフォルト値: 5000ミリ秒 説明: クライアント要求のソケットを確立するときに使用されるオープン・タイムアウトをミリ秒で構成します。タイムアウトが短いほど、より迅速に障害を検出してリカバリできます。ほとんどのアプリケーションは、デフォルトのオープン・タイムアウトが適切です。値はゼロ(0)より大きい必要があります。 |
oracle.hadoop.xquery.kv.config.socketReadTimeout |
型: Long デフォルト値: 30000ミリ秒 説明: クライアント要求を行うソケットに関連付けられる読取りタイムアウト期間をミリ秒で構成します。タイムアウトが短いほど、より迅速に障害を検出してリカバリできます。ただし、最長のタイムアウトが要求に関連付けられるように、タイムアウト期間は十分な長さにする必要があります。 |
oracle.kv.batchSize |
型: Key デフォルト値: 定義されていません。 説明: 各ネットワーク・ラウンドトリップ中、InputFormatがフェッチに必要とするキー数。ゼロ(0)値は、プロパティをデフォルト値に設定します。 |
oracle.kv.consistency |
型: Consistency デフォルト値: 説明: 子のキーと値のペアを読み取る際の一貫性保証です。次のキーワードは有効な値です。
|
oracle.kv.hosts |
型: String デフォルト値: 定義されていません。 説明: ソース・データがあるKVストア内のホストを識別する、1つ以上のhostname:portペアの配列。複数のペアはカンマで区切ります。 |
oracle.kv.kvstore |
型: String デフォルト値: 定義されていません。 説明: ソース・データがあるKVストアの名前。 |
oracle.kv.timeout |
型: Long デフォルト値: 定義されていません。 説明: 選択したキーと値のペアを取得する場合の最大時間間隔(ミリ秒)を設定します。ゼロ(0)値は、プロパティをデフォルト値に設定します。 |
oracle.hadoop.xquery.kv.config.LOBSuffix |
型: String デフォルト値: lob 説明: LOBキーに関連付けられたデフォルトの接尾辞を構成します。 |
oracle.hadoop.xquery.kv.config.LOBTimeout |
必要または参考情報ですか。また、ハードコード・リンクです。 |
oracle.hadoop.xquery.kv.config.readZones |
型: 文字列のカンマ区切りのリスト デフォルト値: 定義されていません 説明: 読取り操作で使用するためにノードを配置するゾーンを設定します。 |
oracle.hadoop.xquery.kv.config.security |
型: String デフォルト値: 定義されていません 説明: クライアントのセキュリティ・プロパティを構成します。 |
順序ファイル・アダプタは、Hadoop順序ファイルの読取りおよび書込みを実行する関数を提供します。順序ファイルは、キーと値のペアで構成されるHadoop固有のファイル形式です。
次のトピックでは、関数について説明します。
問合せで組込み関数を使用するには、次のように順序ファイル・モジュールをインポートする必要があります。
import module "oxh:seq";
順序ファイル・モジュールには、次の関数が含まれています。
例については、「順序ファイル・アダプタの関数の例」を参照してください。
HDFS内の順序ファイルのコレクションにアクセスし、値を文字列として返します。ファイルを分割して、複数のタスクで並列で処理できます。
シグネチャ
declare %seq:collection("text") function
seq:collection($uris as xs:string*) as xs:string* external;
パラメータ
$uris: 順序ファイルのURI。順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。BytesWritable値の場合、バイトはUTF-8デコーダを使用して文字列に変換されます。
戻り値
各ファイルの各値に対して1つの文字列。
HDFS内の順序ファイルのコレクションにアクセスし、各値をXMLとして解析して返します。各ファイルを分割して、複数のタスクで並列で処理できます。
シグネチャ
declare %seq:collection("xml") function
seq:collection-xml($uris as xs:string*) as document-node()* external;
パラメータ
$uris: 順序ファイルのURI。順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。BytesWritable値の場合は、XMLドキュメントのエンコード宣言が使用されます(使用可能な場合)。
戻り値
各ファイルの各値に対して1つのXMLドキュメント。「Tikaパーサーの出力形式」を参照してください。
HDFS内の順序ファイルのコレクションにアクセスし、各値をバイナリXMLとして読み取って返します。各ファイルを分割して、複数のタスクで並列で処理できます。
シグネチャ
declare %seq:collection("binxml") function
seq:collection-binxml($uris as xs:string*) as document-node()* external;
パラメータ
$uris: 順序ファイルのURI。順序ファイル内の値は、org.apache.hadoop.io.BytesWritableである必要があります。バイトはバイナリXMLとしてデコードされます。
戻り値
各ファイルの各値に対して1つのXMLドキュメント。
注意
この関数を使用すると、前の問合せでseq:put-binxmlによって作成されたファイルを読み取ることができます。「seq:put-binxml」を参照してください。
Tikaを使用して、HDFS内の順序ファイルを解析します。順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。各値に対して、Tikaにより生成されたドキュメント・ノードが返されます。
シグネチャ
declare %seq:collection("tika") function
seq:collection-tika($uris as xs:string*) as document-node()* external;
declare %seq:collection("tika") function
seq:collection-tika($uris as xs:string*, $contentType as xs:string?) as document-node()* external;
パラメータ
$uris: 順序ファイルのURI。順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。Tikaライブラリによって自動的に文字エンコードが検出されます。または、エンコーディングを$contentTypeパラメータ内でcharset属性として渡すこともできます。
$contentType: 解析するコンテンツのメディア・タイプを指定するもので、charset属性を含めることができます。
戻り値
各ファイルの各値に対して1つのドキュメント・ノード。
キーと値のペアの文字列値か、キーと文字列値の両方を、問合せの出力ディレクトリ内の順序ファイルに書き込みます。
この関数は、キーと値をorg.apache.hadoop.io.Textとして書き込みます。
関数が$keyパラメータなしで呼び出された場合は、キー値がないため、この関数は値をorg.apache.hadoop.io.Textとして書き込み、キー・クラスをorg.apache.hadoop.io.NullWritableに設定します。
シグネチャ
declare %seq:put("text") function
seq:put($key as xs:string, $value as xs:string) external;
declare %seq:put("text") function
seq:put($value as xs:string) external;
パラメータ
$key: キーと値のペアのキー
$value: キーと値のペアの値
戻り値
empty-sequence()
注意
値は1つ以上の順序ファイルに展開されます。作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前はpartで始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。
XML値か、キーとXML値を、問合せの出力ディレクトリ内の順序ファイルに書き込みます。
この関数は、キーと値をorg.apache.hadoop.io.Textとして書き込みます。
関数が$keyパラメータなしで呼び出された場合は、キー値がないため、この関数は値をorg.apache.hadoop.io.Textとして書き込み、キー・クラスをorg.apache.hadoop.io.NullWritableに設定します。
シグネチャ
declare %seq:put("xml") function
seq:put-xml($key as xs:string, $xml as node()) external;
declare %seq:put("xml") function
seq:put-xml($xml as node()) external;
パラメータ
$key: キーと値のペアのキー
$value: キーと値のペアの値
戻り値
empty-sequence()
注意
値は1つ以上の順序ファイルに展開されます。作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前は「part」で始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。
XML値をバイナリXMLとしてエンコードし、エンコードされたバイトを問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。
この関数は、キーをorg.apache.hadoop.io.Textとして書き込み、値をorg.apache.hadoop.io.BytesWritableとして書き込みます。
関数が$keyパラメータなしで呼び出された場合は、キー値がないため、この関数は値をorg.apache.hadoop.io.BytesWritableとして書き込み、キー・クラスをorg.apache.hadoop.io.NullWritableに設定します。
シグネチャ
declare %seq:put("binxml") function
seq:put-binxml($key as xs:string, $xml as node()) external;
declare %seq:put("binxml") function
seq:put-binxml($xml as node()) external;
パラメータ
$key: キーと値のペアのキー
$value: キーと値のペアの値
戻り値
empty-sequence()
注意
作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前はpartで始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。
seq:collection-binxml関数を使用すると、この関数によって作成されたファイルを読み取ることができます。「seq:collection-binxml」を参照してください。
次の注釈を使用して、順序ファイルのコレクションを読み取る関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
順序ファイルを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %seq:collection("text") [additional annotations]
function local:myFunctionName($uris as xs:string*) as xs:string* external;
declare %seq:collection(["xml"|"binxml"|"tika"]) [additional annotations]
function local:myFunctionName($uris as xs:string*) as document-node()* external;
declare %seq:collection(["tika"]) [additional annotations]
function local:myFunctionName($uris as xs:string*, $contentType as xs:string?) as document-node()* external;
注釈
順序ファイルを読み取るための、順序ファイルのcollection関数を宣言します。必須。
オプションのmethodパラメータは次のいずれかの値です。
text: 順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。バイトは、%output:encoding注釈で指定された文字セットを使用してデコードされます。これらはxs:stringとして返されます。デフォルト。
xml: 順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。関数によって、値はXMLとして解析されて返されます。
binxml: 順序ファイル内の値は、org.apache.hadoop.io.BytesWritableである必要があります。関数によって、値はXDKバイナリXMLとして読み取られて返されます。
tika: 順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。値はTikaによって解析され、関数によって返されます。
入力値の文字エンコードを指定します。有効なエンコードは、JVMでサポートされているエンコードです。UTF-8がデフォルトのエンコードです。
関連項目:
次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項
http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html
キーと値のペアのキーが、戻り値のdocument-uriとして設定されるかどうかを制御します。キーを返すにはtrueに指定します。デフォルト設定は、methodがbinxmlまたはxmlの場合はtrue、textの場合はfalseです。
アトミックのxs:stringがドキュメントに関連付けられていないため、この注釈がtrueに設定されたテキスト関数は、xs:string*ではなくtext()*を返す必要があります。
キーが返されると、seq:key関数を使用してその文字列表現を取得できます。
この例は、%seq:keyがtrueに設定されているため、文字列値ではなくテキストを返します。
declare %seq:collection("text") %seq:key("true")
function local:col($uris as xs:string*) as text()* external;
次の例は、seq:key関数を使用して、キーの文字列表現を取得します。
for $value in local:col(...) let $key := $value/seq:key() return . . .
最大分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%seq:split-max(1024)
%seq:split-max("1024")
%seq:split-max("1K")
最小分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%seq:split-min(1024)
%seq:split-min("1024")
%seq:split-min("1K")
次の注釈を使用して、HDFS内の順序ファイルのコレクションを書き込む関数を定義できます。
シグネチャ
順序ファイルを書き込むカスタム関数には、次のいずれかのシグネチャが必要です。キー値を書き込まない場合は、$key引数を省略できます。
declare %seq:put("text") [additional annotations]
function local:myFunctionName($key as xs:string, $value as xs:string) external;
declare %seq:put(["xml"|"binxml"]) [additional annotations]
function local:myFunctionName($key as xs:string, $xml as node()) external;
注釈
キーと値のペアを順序ファイルに書き込むための、順序ファイルのput関数を宣言します。必須。
シグネチャで$key引数を使用する場合、キーはorg.apache.hadoop.io.Textとして書き込まれます。$key引数を省略すると、キー・クラスはorg.apache.hadoop.io.NullWritableに設定されます。
methodパラメータをtext、xmlまたはbinxmlに設定します。methodは、値の書込みに使用されるタイプを決定します。
text: org.apache.hadoop.io.Textとして書き込まれる文字列
xml: org.apache.hadoop.io.Textとして書き込まれるXML
binxml: XDKバイナリXMLとしてエンコードされ、org.apache.hadoop.io.BytesWritableとして書き込まれるXML
出力で使用する圧縮形式を指定します。デフォルトは圧縮なしです。オプション。
codecパラメータは圧縮コーデックを識別します。値が一致して、最初に登録された圧縮コーデックが使用されます。値は、次のいずれかと等しい場合にコーデックに一致します。
コーデックの完全修飾されたクラス名
コーデックの修飾されていないクラス名
Codec (大文字と小文字を区別しない)の前にある、修飾されていないクラス名の接頭辞
compressionTypeパラメータを次のいずれかの値に設定します。
block: キーと値がグループに収集され、まとめて圧縮されます。ブロック圧縮は、圧縮アルゴリズムで異なる値の類似性を利用できるため、通常はよりコンパクトになります。
record: 順序ファイル内の値のみ圧縮されます。
次のすべての例では、デフォルトのコーデックおよびブロック圧縮を使用します。
%seq:compress("org.apache.hadoop.io.compress.DefaultCodec", "block")
%seq:compress("DefaultCodec", "block")
%seq:compress("default", "block")
出力ファイル名の接頭辞を指定します。デフォルトの接頭辞はpartです。
%seq:putで指定される出力方法(テキストまたはXML)に対する標準XQueryシリアライズ・パラメータ。「シリアライズ注釈」を参照してください。
関連項目:
ApacheのHadoop WikiのSequenceFile。
XMLおよびテキスト出力方法については、XSLT and XQuery Serialization 3.1のシリアライズ・パラメータの影響に関する項
次の各例は、次の内容でHDFS内の3つのXMLファイルを問い合せます。各XMLファイルには、特定の日にユーザーが記入したコメントが含まれています。各コメントには、他のユーザーからのlikeが1個以上あるか、likeがない場合もあります。
mydata/comments1.xml
<comments date="2013-12-30">
<comment id="12345" user="john" text="It is raining :( "/>
<comment id="56789" user="kelly" text="I won the lottery!">
<like user="john"/>
<like user="mike"/>
</comment>
</comments>
mydata/comments2.xml
<comments date="2013-12-31">
<comment id="54321" user="mike" text="Happy New Year!">
<like user="laura"/>
</comment>
</comments>
mydata/comments3.xml
<comments date="2014-01-01">
<comment id="87654" user="mike" text="I don't feel so good."/>
<comment id="23456" user="john" text="What a beautiful day!">
<like user="kelly"/>
<like user="phil"/>
</comment>
</comments>
例6-14
次の問合せは、comment要素を順序ファイルに格納します。
import module "oxh:seq";
import module "oxh:xmlf";
for $comment in xmlf:collection("mydata/comments*.xml", "comment")
return
seq:put-xml($comment)
例6-15
次の問合せは、前の問合せによって生成され、myoutputという名前の出力ディレクトリに格納されている順序ファイルを読み取ります。次に、この問合せは、複数のコメントを記入したユーザーの名前をテキスト・ファイルに書き込みます。
import module "oxh:seq";
import module "oxh:text";
for $comment in seq:collection-xml("myoutput/part*")/comment
let $user := $comment/@user
group by $user
let $count := count($comment)
where $count gt 1
return
text:put($user || " " || $count)
前の問合せによって作成されたテキスト・ファイルには、次の行が含まれます。
john 2 mike 2
「XMLファイル・アダプタ」を参照してください。
例6-16
次の問合せは、XMLファイルからcomment要素を抽出して、圧縮された順序ファイルに格納します。各コメントを格納する前に、id属性を削除し、値を順序ファイルのキーとして使用します。
import module "oxh:xmlf";
declare
%seq:put("xml")
%seq:compress("default", "block")
%seq:file("comments")
function local:myPut($key as xs:string, $value as node()) external;
for $comment in xmlf:collection("mydata/comments*.xml", "comment")
let $id := $comment/@id
let $newComment :=
copy $c := $comment
modify delete node $c/@id
return $c
return
local:myPut($id, $newComment)
例6-17
次の問合せは、前の問合せによってmyoutputという名前の出力ディレクトリに作成された順序ファイルを読み取ります。問合せでは、順序ファイルが自動的に解凍されます。
import module "oxh:text";
import module "oxh:seq";
for $comment in seq:collection-xml("myoutput/comments*")/comment
let $id := $comment/seq:key()
where $id eq "12345"
return
text:put-xml($comment)
この問合せは、次の行を含むテキスト・ファイルを作成します。
<comment id="12345" user="john" text="It is raining :( "/>
このアダプタはフルテキスト索引を作成してApache Solrサーバーにロードする関数を提供します。これらの関数は、Solrのorg.apache.solr.hadoop.MapReduceIndexerToolを実行時に呼び出してHDFS上にフルテキスト索引を生成し、オプションでSolrサーバーにマージします。このアダプタから供給された複数のカスタムput関数と組込みput関数を1つの問合せ内で宣言および使用できます。たとえば、別々のSolrコレクションまたは別々のSolrクラスタにデータをロードできます。
次のトピックでは、このアダプタについて説明します。
Solrアダプタを初めて使用するときには、「Oracle XQuery for Hadoopのインストール」に説明されているとおりにHadoopクラスタにSolrがインストールされ構成されていることを確認してください。
Oracle XQuery for Hadoop問合せは次の構成プロパティまたは同等の注釈を使用する必要があります。
oracle.hadoop.xquery.solr.loader.zk-host
oracle.hadoop.xquery.solr.loader.collection
索引がSolrサーバーのライブ・セットにロードされている場合も、この構成プロパティまたは同等の注釈が必要です。
oracle.hadoop.xquery.solr.loader.go-live
構成プロパティは、問合せの実行時にhadoopコマンドで-Dオプションまたは-confオプションを使用すると設定できます。「問合せの実行」および「Solrアダプタ構成プロパティ」を参照してください
この例では、OXH_SOLR_MR_HOMEを設定し、問合せでhadoop -Dオプションを使用して構成プロパティを設定します。
$ export OXH_SOLR_MR_HOME=/usr/lib/solr/contrib/mr $ hadoop jar $OXH_HOME/lib/oxh.jar -D oracle.hadoop.xquery.solr.loader.zk-host=/solr -D oracle.hadoop.xquery.solr.loader.collection=collection1 -D oracle.hadoop.xquery.solr.loader.go-live=true ./myquery.xq -output ./myoutput
問合せで組込み関数を使用するには、次のようにSolrモジュールをインポートする必要があります。
import module "oxh:solr";
Solrモジュールには、次の関数が含まれています。
接頭辞solrは、デフォルトでoxh:solrネームスペースにバインドされます。
Solr索引に単一のドキュメントを書き込みます。
このドキュメントXML形式は、次のサイトでSolrによって指定されます。
https://wiki.apache.org/solr/UpdateXmlMessages
シグネチャ
declare %solr:put function solr:put($value as element(doc)) external;
パラメータ
$value: docと呼ばれる単一のXML要素。この要素には、ここで示すように1つ以上のfield要素が含まれます。
<doc>
<field name="field_name_1">field_value_1</field>
.
.
.
<field name="field_name_N">field_value_N</field>
</doc>
戻り値
output_dir/solr-putディレクトリに書き込まれた生成済索引。output_dirは問合せの出力ディレクトリです
次の注釈を使用して、フルテキスト索引を生成し、Solrにロードする関数を定義できます。
シグネチャ
Solr索引を生成するカスタム関数には、次のシグネチャが必要です。
declare %solr:put [additional annotations] function local:myFunctionName($value as node()) external;
注釈
solr put関数を宣言します。必須。
索引ファイルが書き込まれる、問合せの出力ディレクトリの下にあるサブディレクトリの名前。オプションで、デフォルト値は関数のローカル名です。
索引生成の様々な側面をコントロールします。複数の%solr-property注釈を指定できます。
これらの注釈はorg.apache.solr.hadoop.MapReduceIndexerToolのコマンドライン・オプションに対応します。各MapReduceIndexerTool?オプションには同等のOracle XQuery for Hadoop構成プロパティおよび%solr-property注釈があります。注釈は構成プロパティよりも優先されます。サポートされている構成プロパティおよび対応する注釈の詳細は、「Solrアダプタ構成プロパティ」を参照してください。
関連項目:
MapReduceIndexerTool?コマンドライン・オプションに関する詳細は、次のサイトのCloudera Searchユーザー・ガイドを参照してください。
パラメータ
$value: Solr XML構文と一致する要素またはドキュメント・ノード。詳細は、「solr:put」を参照してください。
例6-18 組込みsolr:put関数の使用
この例では、次のHDFSテキスト・ファイルを使用します。このファイルには、ユーザーID、姓名、年齢などのユーザー・プロファイル情報がコロン(:)区切りで格納されています。
mydata/users.txt john:John Doe:45 kelly:Kelly Johnson:32 laura:Laura Smith: phil:Phil Johnson:27
最初の問合せは、名前で検索可能なフルテキスト索引を作成します。
import module "oxh:text";
import module "oxh:solr";
for $line in text:collection("mydata/users.txt")
let $split := fn:tokenize($line, ":")
let $id := $split[1]
let $name := $split[2]
return solr:put(
<doc>
<field name="id">{ $id }</field>
<field name="name">{ $name }</field>
</doc>
)
2番目の問合せは同じ結果となりますが、カスタムput関数を使用します。また、関数の注釈を使用することですべての構成パラメータを定義します。そのため、この問合せを実行するときに構成パラメータを設定する必要はありません。
import module "oxh:text";
declare %solr:put %solr-property:go-live %solr-property:zk-host("/solr") %solr-property:collection("collection1")
function local:my-solr-put($doc as element(doc)) external;
for $line in text:collection("mydata/users.txt")
let $split := fn:tokenize($line, ":")
let $id := $split[1]
let $name := $split[2]
return local:my-solr-put(
<doc>
<field name="id">{ $id }</field>
<field name="name">{ $name }</field>
</doc>
)
Solrアダプタ構成プロパティは、Solr MapReduceIndexerToolオプションに対応します。
MapReduceIndexerToolは、入力ファイルからSolr索引のシャードを作成し、索引をHDFSに書き込むMapReduceバッチ・ジョブ・ドライバです。また出力シャードのライブSolrサーバー(通常、SolrCloud)へのマージもサポートします。
これらのプロパティは、汎用の-confおよび-D hadoopコマンドライン・オプションを使用してOracle XQuery for Hadoopに指定できます。この方法を使用して指定されるプロパティは、問合せ内のすべてのSolrアダプタput関数に適用されます。hadoopコマンドライン・オプションの詳細は、「問合せの実行」、特に「汎用オプション」を参照してください。
あるいは、%solr-property接頭辞を使用して、これらのプロパティをSolrアダプタのput関数の注釈として指定できます。これらの注釈はプロパティの説明で特定されます。注釈は、宣言にその注釈があるSolrアダプタの特定のput関数にのみ適用されます。
関連項目:
SolrによるMapReduceIndexerToolオプションの使用方法に関する説明は、次のサイトのCloudera Searchユーザー・ガイドを参照してください。
| プロパティ | 概要 |
|---|---|
oracle.hadoop.xquery.solr.loader.collection |
型: String デフォルト値: 定義されていません。 同等の注釈: 説明: 索引のマージのためのSolrCloudコレクション( |
oracle.hadoop.xquery.solr.loader.fair-scheduler-pool |
型: String デフォルト値: 定義されていません。 同等の注釈: 説明: ジョブを発行するための適正なスケジューラ・プールの名前。デフォルトHadoopスケジューリング・メソッドではなく、適正なスケジューリングを使用してジョブが実行されます。オプション。 |
oracle.hadoop.xquery.solr.loader.go-live |
タイプ: 文字列値 デフォルト値: 同等の注釈: 説明: 最終索引をライブSolrクラスタにマージできるようにするには |
oracle.hadoop.xquery.solr.loader.go-live-threads |
型: Integer デフォルト値: 同等の注釈: 説明: 並行に実行できるライブ・マージの最大数。オプション。 |
oracle.hadoop.xquery.solr.loader.log4j |
型: String デフォルト値: 同等の注釈: 説明: ローカル・ファイル・システムにある ファイルは、各MapReduceタスク用にアップロードされます。 |
oracle.hadoop.xquery.solr.loader.mappers |
型: String デフォルト値: 同等の注釈: 説明: Solrが使用するマッパー・タスクの最大数。 |
oracle.hadoop.xquery.solr.loader.max-segments |
型: String デフォルト値: 同等の注釈: 説明: 各リデューサで生成されるセグメントの最大数。 |
oracle.hadoop.xquery.solr.loader.reducers |
型: String デフォルト値: 同等の注釈: 説明: 使用するリデューサの数。
|
oracle.hadoop.xquery.solr.loader.zk-host |
型: String デフォルト値: 定義されていません。 同等の注釈: 説明: SolrCloudクラスタによって使用されるZooKeeperアンサンブルのアドレス。それぞれがZooKeeperサーバーに対応する、カンマ区切りのhost:portペアのリストとしてアドレスを指定します。 アドレスがスラッシュ(/)で始まる場合( このプロパティによってSolrは作成する出力シャードの数および出力シャードをマージするSolr URLの数を決定します。このプロパティを |
問合せで組込み関数を使用するには、次のようにテキスト・ファイル・モジュールをインポートする必要があります。
import module "oxh:text";
テキスト・ファイル・モジュールには、次の関数が含まれています。
例については、「テキスト・ファイル・アダプタの関数の例」を参照してください。
HDFS内のテキスト・ファイルのコレクションにアクセスします。ファイルは、Hadoopでサポートされている圧縮コーデックを使用して圧縮できます。これらは読取り時に自動的に解凍されます。
ファイルを分割して、複数のタスクで並列で処理できます。
シグネチャ
declare %text:collection("text") function
text:collection($uris as xs:string*) as xs:string* external;
declare %text:collection("text") function
function text:collection($uris as xs:string*, $delimiter as xs:string?) as xs:string* external;
パラメータ
$uris: テキスト・ファイルのURI。
$delimiter: ファイルを分割するカスタム・デリミタ。デフォルトは改行文字です。
戻り値
デリミタによって特定される各ファイル・セグメントに1つの文字列値。デフォルトのデリミタの場合、各ファイル内の各行に1つの文字列値
HDFS内のテキスト・ファイルのコレクションにアクセスします。ファイルは、Hadoopでサポートされている圧縮コーデックを使用して圧縮できます。これらは読取り時に自動的に解凍されます。
ファイルを分割して、複数のタスクで並列で処理できます。関数によって、各ファイルの各デリミタ付きセクションはXMLドキュメントとして解析されて返されます。したがって、各セグメントには1つのXMLドキュメントが完全に含まれ、XMLの区切り文字はXML文字参照を使用してエスケープされる必要があります。デフォルトでは、デリミタは改行です。
シグネチャ
declare %text:collection("xml") function
text:collection-xml($uris as xs:string*) as document-node()* external;
declare %text:collection("xml") function
text:collection-xml($uris as xs:string*, $delimiter as xs:string?) as document-node()* external;
パラメータ
$uris: テキスト・ファイルのURI。
$delimiter: ファイルを分割するカスタム・デリミタ。デフォルトは改行文字です。
戻り値
デリミタによって特定される各ファイル・セグメントに1つの文字列値。デフォルトのデリミタの場合、各ファイル内の各行に1つの文字列値
行を、問合せの出力ディレクトリ内のテキスト・ファイルに書き込みます。行は1つ以上のファイルに展開されます。
シグネチャ
declare %text:put("text") function
text:put($value as xs:string) external;
パラメータ
$value: 書き込むテキスト
戻り値
empty-sequence()
注意
作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前はpartで始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。
XMLをテキスト・ファイルの行に書き込みます。行は、問合せの出力ディレクトリ内の1つ以上のファイルに展開されます。
XMLが複数の行にスパンしないように、シリアライズされたXMLの改行文字は文字参照に置換されます。たとえば、
は改行文字(\n)に置換されます。
シグネチャ
declare %text:put("xml") function
text:put-xml($value as node()) external;
パラメータ
$value: 書き込むXML
戻り値
empty-sequence()
注意
作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前はpartで始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。
行を、問合せの出力ディレクトリ内にあるtrace-*という名前のテキスト・ファイルに書き込みます。行は1つ以上のファイルに展開されます。
この関数を使用すると、別の出力に簡単に書き込むことができます。たとえば、トレース・ファイルを作成して問合せ内の無効な行を識別しながら、データをOracleデータベース表にロードできます。
シグネチャ
declare %text:put("text") %text:file("trace") function
text:trace($value as xs:string) external;
パラメータ
$value: 書き込むテキスト
戻り値
empty-sequence()
次の注釈を使用して、HDFS内のテキスト・ファイルのコレクションを読み取る関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
入力ファイルは、Hadoopでサポートされている圧縮コーデックを使用して圧縮できます。これらは読取り時に自動的に解凍されます。
シグネチャ
テキスト・ファイルを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %text:collection("text") [additional annotations]
function local:myFunctionName($uris as xs:string*, $delimiter as xs:string?) as xs:string* external;
declare %text:collection("text") [additional annotations]
function local:myFunctionName($uris as xs:string*) as xs:string* external;
declare %text:collection("xml") [additional annotations]
function local:myFunctionName($uris as xs:string*, $delimiter as xs:string?) as document-node()* external
declare %text:collection("xml") [additional annotations]
function local:myFunctionName($uris as xs:string*) as document-node()* external;
注釈
text collection関数を宣言します。必須。
オプションのmethodパラメータは次のいずれかの値です。
text: テキスト・ファイルの各行はxs:stringとして返されます。デフォルト。
xml: テキスト・ファイルの各行はXMLとして解析され、document-nodeとして返されます。各XMLドキュメントは、1行に完全に含まれる必要があります。ドキュメント内の改行文字は、数値の文字参照によって表される必要があります。
入力ファイルを分割するためのカスタム・デリミタを指定します。デフォルトのデリミタは改行文字です。
この注釈と$delimiterパラメータを組み合せないでください。カスタム・デリミタを指定するには、この注釈または$delimiterパラメータのいずれかを使用します。
最大分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%text:split-max(1024)
%text:split-max("1024")
%text:split-max("1K")
最小分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%text:split-min(1024)
%text:split-min("1024")
%text:split-min("1K")
パラメータ
戻り値
text方法の場合: xs:string*
xml方法の場合: document-node()*
次の注釈を使用して、HDFS内のテキスト・ファイルを書き込む関数を定義できます。
シグネチャ
テキスト・ファイルを書き込むカスタム関数には、次のいずれかのシグネチャが必要です。
declare %text:put("text") [additional annotations] function
text:myFunctionName($value as xs:string) external;
declare %text:put("xml") [additional annotations] function
text:myFunctionName($value as node()) external;
注釈
text put関数を宣言します。必須。
オプションのmethodパラメータは次のいずれかの値です。
text: データをテキスト・ファイルに書き込みます。デフォルト。
xml: データをXMLファイルに書き込みます。XMLはシリアライズされ、改行文字は文字参照に置換されます。このプロセスによって、結果のXMLドキュメントは改行のない1行のテキスト行になります。
出力で使用する圧縮形式を指定します。デフォルトは圧縮なしです。オプション。
codecパラメータは圧縮コーデックを識別します。値が一致して、最初に登録された圧縮コーデックが使用されます。値は、次のいずれかと等しい場合にコーデックに一致します。
コーデックの完全修飾されたクラス名
コーデックの修飾されていないクラス名
Codec (大文字と小文字を区別しない)の前にある、修飾されていないクラス名の接頭辞
次のすべての例では、デフォルトのコーデックおよびブロック圧縮を使用します。
%text:compress("org.apache.hadoop.io.compress.DefaultCodec", "block")
%text:compress("DefaultCodec", "block")
%text:compress("default", "block")
出力ファイル名の接頭辞を指定します。デフォルトの接頭辞はpartです。
%text:putで指定される出力方法(テキストまたはXML)に対する標準XQueryシリアライズ・パラメータ。「シリアライズ注釈」を参照してください。
現在、サポートされている文字エンコードはUTF-8のみです。
例6-19 組込み関数を使用したテキスト・ファイルの問合せ
この例では、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
次の問合せは、johnがアクセスしたページをフィルタ処理し、アクセスした日付とページのみを新規テキスト・ファイルに書き込みます。
import module "oxh:text";
for $line in text:collection("mydata/visits*.log")
let $split := fn:tokenize($line, "\s*,\s*")
where $split[2] eq "john"
return
text:put($split[1] || " " || $split[3])
この問合せは、次の行を含むテキスト・ファイルを作成します。
2013-10-28T06:00:00 index.html 2013-10-30T10:00:01 index.html 2013-10-30T10:05:20 about.html
次の問合せは、ページに対する1日当たりのアクセス数を計算します。
import module "oxh:text";
for $line in text:collection("mydata/visits*.log")
let $split := fn:tokenize($line, "\s*,\s*")
let $time := xs:dateTime($split[1])
let $day := xs:date($time)
group by $day
return
text:put($day || " => " || count($line))
この問合せは、次の行を含むテキスト・ファイルを作成します。
2013-10-28 => 3 2013-10-30 => 3 2013-11-01 => 1 2013-11-04 => 2
例6-20 単純なデリミタ付き形式の問合せ
この例は、fn:tokenize関数を使用して、テキスト・ファイルの行を解析します。この方法は、単純なデリミタ付き形式に適しています。
次の問合せは、カスタムのput関数およびcollection関数を宣言します。これは、ログ内のページごとに、ヒット数および一意のユーザー数を計算します。
import module "oxh:text";
declare
%text:collection("text")
%text:split-max("32m")
function local:col($uris as xs:string*) as xs:string* external;
declare
%text:put("xml")
%text:compress("gzip")
%text:file("pages")
function local:out($arg as node()) external;
for $line in local:col("mydata/visits*.log")
let $split := fn:tokenize($line, "\s*,\s*")
let $user := $split[2]
let $page := $split[3]
group by $page
return
local:out(
<page>
<name>{$page}</name>
<hits>{count($line)}</hits>
<users>{fn:count(fn:distinct-values($user))}</users>
</page>
)
前の問合せの出力ディレクトリ名はmyoutputです。次の行がmyoutput/pages-r-*.gzに書き込まれます。
<page><name>about.html</name><hits>2</hits><users>2</users></page> <page><name>contact.html</name><hits>1</hits><users>1</users></page> <page><name>index.html</name><hits>6</hits><users>4</users></page>
ファイルはgzipコーデックを使用して圧縮されます。次の問合せは、出力ファイルを読み取り、ページ名と合計ヒット数をプレーン・テキストとして書き込みます。collection関数によって、圧縮ファイルが自動的にデコードされます。
import module "oxh:text";
for $page in text:collection-xml("myoutput/page*.gz")/page
return
text:put($page/name || "," || $page/hits)
この問合せは、次の行を含むテキスト・ファイルを作成します。
about.html,2 contact.html,1 index.html,6
例6-21 複雑なテキスト形式の問合せ
fn:tokenize関数は、様々なデータ型やデリミタを含む複雑な形式には適していません。この例は、fn:analyze-string関数を使用して、Apache共通ログ形式のログ・ファイルを処理します。
HDFS内のmydata/access.logという名前のテキスト・ファイルには、次の行が含まれています。
192.0.2.0 - - [30/Sep/2013:16:39:38 +0000] "GET /inddex.html HTTP/1.1" 404 284 192.0.2.0 - - [30/Sep/2013:16:40:54 +0000] "GET /index.html HTTP/1.1" 200 12390 192.0.2.4 - - [01/Oct/2013:12:10:54 +0000] "GET /index.html HTTP/1.1" 200 12390 192.0.2.4 - - [01/Oct/2013:12:12:12 +0000] "GET /about.html HTTP/1.1" 200 4567 192.0.2.1 - - [02/Oct/2013:08:39:38 +0000] "GET /indexx.html HTTP/1.1" 404 284 192.0.2.1 - - [02/Oct/2013:08:40:54 +0000] "GET /index.html HTTP/1.1" 200 12390 192.0.2.1 - - [02/Oct/2013:08:42:38 +0000] "GET /aobut.html HTTP/1.1" 404 283
次の問合せは、サーバーがステータス・コード404 (見つかりません)エラーを返した場合に、2013年9月以降に行われた要求を計算します。正規表現およびfn:analyze-stringを使用して、ログ・エントリのコンポーネントを照合します。例6-20に示すように、時間書式はxs:dateTimeに直接キャストできません。かわりに、ora-fn:dateTime-from-string-with-format関数によって、文字列をxs:dateTimeのインスタンスに変換します。
import module "oxh:text";
declare variable $REGEX :=
'(\S+) (\S+) (\S+) \[([^\]]+)\] "([^"]+)" (\S+) (\S+)';
for $line in text:collection("mydata/access.log")
let $match := fn:analyze-string($line, $REGEX)/fn:match
let $time :=
ora-fn:dateTime-from-string-with-format(
"dd/MMM/yyyy:HH:mm:ss Z",
$match/fn:group[4]
)
let $status := $match/fn:group[6]
where
$status eq "404" and
$time ge xs:dateTime("2013-10-01T00:00:00")
let $host := $match/fn:group[1]
let $request := $match/fn:group[5]
return
text:put($host || "," || $request)
この問合せは、次の行を含むテキスト・ファイルを作成します。
192.0.2.1,GET /indexx.html HTTP/1.1 192.0.2.1,GET /aobut.html HTTP/1.1
関連項目:
fn:tokenize関数およびfn:analyze-string関数については、次のサイトにある『XPath and XQuery Functions and Operators 3.0』仕様
Apache共通ログ形式については、次のサイトを参照してください。
問合せで組込み関数を使用するには、次のようにTikaファイル・モジュールをインポートする必要があります。
import module "oxh:tika";
Tikaファイル・モジュールには、次の関数が含まれています。
例については、「Tikaファイル・アダプタの関数の例」を参照してください。
様々な形式でHDFSに格納されているファイルを解析し、それらのファイルからコンテンツまたはメタデータを抽出します。
シグネチャ
declare %tika:collection function tika:collection($uris as xs:string*) as document-node()* external; declare %tika:collection function function tika:collection($uris as xs:string*, $contentType as xs:string?) as document-node()* external;
パラメータ
$uris: HDFSファイルのURI。
$contentType: 解析するコンテンツのメディア・タイプを指定するもので、charset属性を含めることができます。パラメータを指定する場合、タイプとエンコーディングの両方を定義します。指定しない場合、Tikaはファイル拡張子から値の自動検出を試行します。パラメータを指定することをお薦めします。
戻り値
各値に対して1つのドキュメント・ノードが返されます。「Tikaパーサーの出力形式」を参照してください。
引数として提供されたデータを解析します。たとえば、XMLまたはJSONドキュメント内のhtmlフラグメントを解析できます。
シグネチャ
declare function tika:parse($data as xs:string?, $contentType as xs:string?) as document-node()* external;
パラメータ
$data: 解析する値。
$contentType: 解析するコンテンツのメディア・タイプを指定するもので、charset属性を含めることができます。パラメータを指定する場合、タイプとエンコーディングの両方を定義します。指定しない場合、Tikaはファイル拡張子から値の自動検出を試行します。パラメータを指定することをお薦めします。
戻り値
各値に対して1つのドキュメント・ノードが返されます。「Tikaパーサーの出力形式」を参照してください。
次の注釈を使用すると、Tikaを使用してHDFS内のファイルを解析する関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
HDFSファイルを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %tika:collection [additional annotations] function local:myFunctionName($uris as xs:string*, $contentType as xs:string?) as document-node()* external; declare %tika:collection [additional annotations] function local:myFunctionName($uris as xs:string*) as document-node()* external;
注釈
Tikaファイル・アダプタにより実装される外部関数を識別します。必須。
オプションのmethodパラメータは次のいずれかの値です。
tika: tikaファイル内の各行がdocument-node()として返されます。デフォルト。
ファイル・コンテンツ・タイプを宣言します。これはMIMEタイプであり、XQuery仕様に従ってcharset属性を持つことができません。オプション。
ファイル文字セットを宣言します。オプション。
注意:
%output:media-type注釈と%output:econding注釈は、シグネチャ内に$contentTypeが明示的に指定されていないときのコンテンツ・タイプまたはエンコーディングを指定します。
パラメータ
戻り値
document-node()*および2つのルート要素。「Tikaパーサーの出力形式」を参照してください。
Tika解析の結果は、1つのドキュメント・ノードと2つのルート要素です。
ルート要素#1は、Tikaにより生成されたXHTMLコンテンツです。
ルート要素#2は、Tikaにより抽出されたドキュメント・メタデータです。
ルート要素の形式は次のようになります。
ルート要素#1
<html xmlns="http://www.w3.org/1999/xhtml"> ...textual content of Tika HTML... </html>
ルート要素#2
<tika:metadata xmlns:tika="oxh:tika"> <tika:property name="Name_1">VALUE_1</tika:property> <tika:property name="NAME_2">VALUE_2</tika:property> </tika:metadata>
次のHadoopプロパティは、Tikaアダプタの動作を制御します。
型: ブール
デフォルト値: false。
説明: これをTRUEに設定すると、解析中にすべてのHTML要素が省略されます。これをFALSEに設定すると、解析中に安全な要素が省略されます。
型: 文字列のカンマ区切りのリスト
デフォルト値: 定義されていません。
説明: Microsoft Officeドキュメント・パーサーなどの一部のTikaパーサーにより使用されるロケールを定義します。使用できる文字列は、language、countryおよびvariantの3つのみです。文字列countryおよびvariantはオプションです。ロケールを定義しない場合、システム・ロケールが使用されます。文字列を定義する場合、その文字列はhttp://docs.oracle.com/javase/7/docs/api/java/util/Locale.htmlに記載されているjava.util.Locale仕様形式に対応している必要があり、ロケールは次のように構成できます。
languageのみを指定した場合、ロケールは言語から構成されます。
languageおよびcountryを指定した場合、ロケールは言語と国の両方から構成されます。
language、countryおよびvariantを指定した場合、ロケールは言語、国およびバリアントから構成されます。
例6-22 組込み関数を使用したCloudera SearchによるPDFドキュメントの索引付け
この問合せ例では、Tikaを使用してPDFファイルをHTMLフォームに解析し、HTMLドキュメントをSolrのフルテキスト索引に追加します。
*bigdata*.pdf
次の問合せでは、HDFSファイルを索引付けします。
import module "oxh:tika";
import module "oxh:solr";
for $doc in tika:collection("*bigdata*.pdf")
let $docid := data($doc//*:meta[@name eq "resourceName"]/@content)[1]
let $body := $doc//*:body[1]
return
solr:put(
<doc>
<field name="id">{ $docid }</field>
<field name="text">{ string($body) }</field>
<field name="content">{ serialize($doc/*:html) }</field>
</doc>
)
ドキュメントのHTML表現がSolr索引に追加され、検索可能になります。索引内の各ドキュメントIDはファイル名です。
例6-23 組込み関数を使用したCloudera SearchによるHTMLドキュメントの索引付け
この問合せ例では、順序ファイルおよびTikaを使用して解析を行います(キーがURLで値がhtmlです)。
import module "oxh:tika";
import module "oxh:solr";
import module "oxh:seq";
for $doc in seq:collection-tika(“/path/to/seq/files/*")
let $docid := document-uri($doc)
let $body := $doc//*:body[1]
return
solr:put(
<doc>
<field name="id">{ $docid }</field>
<field name="text">{ string($body) }</field>
<field name="content">{ serialize($doc/*:html) }</field>
</doc>
)
ドキュメントのHTML表現がSolr索引に追加され、検索可能になります。索引内の各ドキュメントIDはファイル名です。
XMLファイル・アダプタは、HDFSに格納されたXMLファイルへのアクセスを提供します。アダプタは必要に応じて個々のXMLファイルを分割するため、1つのファイルを複数のタスクで並列で処理できます。
次のトピックでは、このアダプタについて説明します。
問合せで組込み関数を使用するには、次のようにXMLファイル・モジュールをインポートする必要があります。
import module "oxh:xmlf";
XMLファイル・モジュールには、次の関数が含まれています。
「XMLファイル・アダプタの関数の例」を参照してください。
HDFS内のXMLドキュメントのコレクションにアクセスします。複数のファイルを同時に処理できますが、個々のファイルは1つのタスクによって解析されます。
Hadoopでサポートされているコーデックを使用して圧縮されたファイルは、この関数によって自動的に解凍されます。
注意:
データが多数の小さいファイルに格納されている場合、HDFSは適切に実行されません。多数の小さいXMLドキュメントを含む大規模なデータセットの場合は、Hadoop順序ファイルおよび順序ファイル・アダプタを使用します。
シグネチャ
declare %xmlf:collection function xmlf:collection($uris as xs:string*) as document-node()* external;
パラメータ
$uris: XMLファイルのURI
戻り値
各ファイルに対して1つのXMLドキュメント
HDFS内のXMLドキュメントのコレクションにアクセスします。複数のファイルを同時に処理できますが、個々のファイルは1つのタスクによって解析されます。この関数はxmlf:collectionと同じですが、一緒に連結された複数の整形式XMLドキュメントを各ファイルに含めることができる点が異なります。
Hadoopでサポートされているコーデックを使用して圧縮されたファイルは、この関数によって自動的に解凍されます。たとえば、GZIPを使用して圧縮された複数のXMLドキュメントを含むファイルに、この関数を使用して直接アクセスできます。
シグネチャ
declare %xmlf:collection("multipart")
function xmlf:collection($uris as xs:string*) as document-node()* external;
戻り値
各ファイルに対して1つ以上のXMLドキュメント。
HDFS内のXMLドキュメントのコレクションにアクセスします。ファイルを分割して、複数のタスクで同時に処理できるため、非常に大きなXMLファイルを効率的に処理できます。この関数は、指定した名前に一致する要素のみを返します。
この関数によってファイルは自動的に解凍されません。特定の要件を満たすXMLファイルのみをサポートしています。「XMLファイルを分割する際の制限」を参照してください。
シグネチャ
declare %xmlf:collection function xmlf:collection($uris as xs:string*, $names as xs:anyAtomicType+) as element()* external;
パラメータ
戻り値
$names引数によって指定された名前の1つと一致する各要素
次の注釈を使用して、HDFS内のXMLファイルのコレクションを読み取る関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。
シグネチャ
XMLファイルを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。
declare %xmlf:collection(["xml"|"multipart"]) [additional annotations] function local:myFunctionName($uris as xs:string*) as node()* external; declare %xmlf:collection("xml") [additional annotations] function local:myFunctionName($uris as xs:string*, $names as xs:anyAtomicType+) as element()* external;
注釈
collection関数を宣言します。必須。
methodパラメータは次のいずれかの値です。
xml: 各値はXMLとして解析されます
multipart: 各値(またはファイル)には、複数の整形式XMLドキュメントの連結が含まれている場合があります。このメソッドは、パラレルXML解析とともに使用することはできません。(xmlf:splitおよび2つの引数の関数のシグネチャを参照してください。)
並列のXML解析で使用する要素名を指定します。この注釈は、$names引数のかわりに使用できます。
この注釈を指定すると、1つの引数を取る関数のみ使用できます。この制限によって、要素名を静的に指定できるため、関数の呼出し時に要素名を指定する必要がありません。
入力ドキュメントのテキスト・エンコードを識別します。
このエンコードを%xmlf:split注釈または$names引数とともに使用する場合、有効なエンコードはISO-8859-1、US-ASCIIおよびUTF-8のみです。そうでない場合、有効なエンコードは、JVMでサポートされているエンコードです。この注釈を省略すると、UTF-8とみなされます。
関連項目:
次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項
http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html
この注釈は、追加のネームスペース宣言をパーサーに提供します。これを複数回指定して、1つ以上のネームスペースを宣言できます。
この注釈を使用して、祖先要素のネームスペースを宣言します。XMLが並列で処理される場合は、指定した名前に一致する要素のみがXMLパーサーによって処理されます。一致する要素が祖先要素の1つのネームスペース宣言に依存する場合、パーサーは宣言を識別できず、エラーが発生する場合があります。
これらのネームスペース宣言は、分割名を指定するときに要素名でも使用できます。次に例を示します。
declare
%xmlf:collection
%xmlf:split("eg:foo")
%xmlf:split-namespace("eg", "http://example.org")
function local:myFunction($uris as xs:string*) as document-node() external;
エンティティ定義をXMLパーサーに提供します。XMLが並列で処理される場合は、指定した分割名に一致する要素のみがXMLパーサーによって処理されます。分割されて並列で処理される入力ドキュメントのDTDは処理されません。
この例では、XMLパーサーが&foo;エンティティ参照を"Hello World"として拡張します。
%xmlf:split-entity("foo","Hello World")
最大分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%xmlf:split-max(1024)
%xmlf:split-max("1024")
%xmlf:split-max("1K")
最小分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。Hadoopは、分割サイズをmax($split-min, min($split-max, $block-size))で計算します。オプション。
文字列値の場合、バイト(デフォルトの単位)のかわりに、K、k、M、m、Gまたはgを値に追加してキロバイト、メガバイトまたはギガバイトを表すことができます。これらの修飾子は大文字と小文字を区別しません。次の例は同等です。
%xmlf:split-min(1024)
%xmlf:split-min("1024")
%xmlf:split-min("1K")
注意
$names引数または$xmlf:split注釈を使用して要素名が指定されている場合は、各XMLドキュメントを並列で処理できます。
並列で処理するには、入力ドキュメントが次の制約を満たしている必要があります。
XMLには、コメント、CDATAセクション、または指定した要素名(つまり、<文字の後にQNameに拡張する名前が続く)の1つに一致するテキストを含む処理手順を含めることができません。そうすると、内容は要素として正しく解析されません。
指定した要素名に一致するファイル内の要素には、指定した名前に一致する子孫要素を含めることができません。そうすると、複数のプロセッサが一致する子孫を選択でき、関数は正しい結果を生成できません。
指定した要素名(およびその子孫すべて)の1つに一致する要素は、そのいずれかの祖先のネームスペース宣言に依存できません。一致する要素の祖先は解析されないため、これらの要素のネームスペース宣言は処理されません。
この制限を回避するには、%xmlf:split-namespace注釈を使用してネームスペース宣言を手動で指定します。
指定した要素名は、分割サイズより大きいファイル内の要素と照合しないことをお薦めします。それを行うと、アダプタは正しく機能しますが、効率が悪くなります。
解析はXMLファイルの途中から開始できないため、XMLを並列で処理するのは困難です。XML構造体(CDATAセクション、コメント、ネームスペース宣言など)によって、この制限が発生します。XMLドキュメントの途中から開始するパーサーは、ドキュメントの先頭に向かって逆方向検索してCDATAセクションまたはコメント内にいないことを確認せずに、たとえば、文字列<foo>が開始要素タグであるとみなすことはできません。ただし、通常、大規模なXMLドキュメントには同様に構造化された一連の要素が含まれるため、並列処理の対象になります。要素名を指定すると、各タスクは、指定した名前の1つに一致する要素についてドキュメントの一部をスキャンして実行されます。指定した名前に一致する要素のみ、実際のXMLパーサーに渡されます。したがって、並列プロセッサでは、ドキュメント全体の真の意味での解析は実行されません。
例6-24 組込み関数を使用したXMLファイルの問合せ
この例は、次の内容でHDFS内の3つのXMLファイルを問い合せます。各XMLファイルには、特定の日にユーザーが記入したコメントが含まれています。各コメントには、他のユーザーからのlikeが1個以上あるか、likeがない場合もあります。
mydata/comments1.xml
<comments date="2013-12-30">
<comment id="12345" user="john" text="It is raining :( "/>
<comment id="56789" user="kelly" text="I won the lottery!">
<like user="john"/>
<like user="mike"/>
</comment>
</comments>
mydata/comments2.xml
<comments date="2013-12-31">
<comment id="54321" user="mike" text="Happy New Year!">
<like user="laura"/>
</comment>
</comments>
mydata/comments3.xml
<comments date="2014-01-01">
<comment id="87654" user="mike" text="I don't feel so good."/>
<comment id="23456" user="john" text="What a beautiful day!">
<like user="kelly"/>
<like user="phil"/>
</comment>
</comments>
この問合せは、各年に記入されたコメントの数をテキスト・ファイルに書き込みます。xmlf:collectionに渡される要素名はないため、3つのドキュメント(各ファイルに1つ)を返します。各ファイルは、単一のタスクによって順次処理されます。
import module "oxh:xmlf";
import module "oxh:text";
for $comments in xmlf:collection("mydata/comments*.xml")/comments
let $date := xs:date($comments/@date)
group by $year := fn:year-from-date($date)
return
text:put($year || ", " || fn:count($comments/comment))
この問合せは、次の行を含むテキスト・ファイルを作成します。
2013, 3 2014, 2
次の問合せでは、ユーザーごとのコメント数およびlikeの平均数を書き込みます。各入力ファイルを分割して、複数のタスクで並列で処理できます。xmlf:collection関数は、5つの要素(各コメントに1つ)を返します。
import module "oxh:xmlf";
import module "oxh:text";
for $comment in xmlf:collection("mydata/comments*.xml", "comment")
let $likeCt := fn:count($comment/like)
group by $user := $comment/@user
return
text:put($user || ", " || fn:count($comment) || ", " || fn:avg($likeCt))
この問合せは、次の行を含むテキスト・ファイルを作成します。
john, 2, 1 kelly, 1, 2 mike, 2, 0.5
例6-25 XMLファイルを問い合せるカスタム関数の書込み
次の例は、XMLファイルにアクセスするカスタム関数を宣言します。
import module "oxh:text";
declare
%xmlf:collection
%xmlf:split("comment")
%xmlf:split-max("32M")
function local:comments($uris as xs:string*) as element()* external;
for $c in local:comments("mydata/comment*.xml")
where $c/@user eq "mike"
return text:put($c/@id)
この問合せは、次の行を含むテキスト・ファイルを作成します。
54321 87654
例6-26 圧縮されたマルチパートXMLファイルへのアクセス
例5-24からのファイルcomments1.xml、comments2.xmlおよびcomments3.xmlを連結してGZIPを使用して圧縮し、comments.xml.gzという名前の1つのファイルを作成すると仮定します。次に例を示します。
cat comments1.xml comments2.xml comments3.xml | gzip > comments.xml.gz
次の問合せは、このマルチパートの圧縮されたXMLファイルにアクセスします。
import module "oxh:text"; import module "oxh:xmlf";
for $comment in xmlf:collection-multipart("comments.xml.gz")/comments/comment
return
text:put($comment/@id || "," || $comment/@user)
この問合せは、次の行を含むテキスト・ファイルを作成します。
12345,john 56789,kelly 54321,mike 87654,mike 23456,john
ユーティリティ・モジュールには、文字列および日付を処理するora-fn関数が含まれています。これらの関数はXDK XQueryで定義されますが、oxh関数はOracle XQuery for Hadoop固有です。
次のトピックでは、ユーティリティ関数について説明します。
Oracle XQueryの関数を使用して、XQueryで期間、日付および時刻を操作できます。
Oracle XQuery関数はhttp://xmlns.oracle.com/xdk/xquery/functionネームスペースにあります。ネームスペースの接頭辞ora-fnは事前に宣言され、モジュールは自動的にインポートされます。
このOracle XQuery関数は、指定されたパターンに従って文字列から新しい日付値を返します。
シグネチャ
ora-fn:date-from-string-with-format($format as xs:string?,
$dateString as xs:string?,
$locale as xs:string*)
as xs:date?
ora-fn:date-from-string-with-format($format as xs:string?,
$dateString as xs:string?)
as xs:date?
パラメータ
$format: パターン。「Format引数」を参照してください
$dateString: 日付を表す入力文字列。
$locale: ロケールを表す1つから3つのフィールド値。「Locale引数」を参照してください
例
この例は、指定した日付を現在のタイムゾーンで返します。
ora-fn:date-from-string-with-format("yyyy-MM-dd G", "2013-06-22 AD")
このOracle XQuery関数は、指定されたパターンを持つ日付文字列を返します。
シグネチャ
ora-fn:date-to-string-with-format($format as xs:string?,
$date as xs:date?,
*$locale as xs:string?)
as xs:string?
ora-fn:date-to-string-with-format($format as xs:string?,
$date as xs:date?)
as xs:string?
パラメータ
$format: パターン。「Format引数」を参照してください
$date: 日付
$locale: ロケールを表す1つから3つのフィールド値。「Locale引数」を参照してください
例
この例は、文字列2013-07-15を返します。
ora-fn:date-to-string-with-format("yyyy-mm-dd", xs:date("2013-07-15"))
このOracle XQuery関数は、指定されたパターンに従って入力文字列から新しい日時値を返します。
シグネチャ
ora-fn:dateTime-from-string-with-format($format as xs:string?,
$dateTimeString as xs:string?,
$locale as xs:string?)
as xs:dateTime?
ora-fn:dateTime-from-string-with-format($format as xs:string?,
$dateTimeString as xs:string?)
as xs:dateTime?
パラメータ
$format: パターン。「Format引数」を参照してください
$dateTimeString: 日時。
$locale: ロケールを表す1つから3つのフィールド値。「Locale引数」を参照してください
例
この例は、指定した日付および11:04:00AMを現在のタイムゾーンで返します。
ora-fn:dateTime-from-string-with-format("yyyy-MM-dd 'at' hh:mm",
"2013-06-22 at 11:04")
次の例は、指定した日付および12:00:00AMを現在のタイムゾーンで返します。
ora-fn:dateTime-from-string-with-format("yyyy-MM-dd G",
"2013-06-22 AD")
このOracle XQuery関数は、指定されたパターンを持つ日時文字列を返します。
シグネチャ
ora-fn:dateTime-to-string-with-format($format as xs:string?,
$dateTime as xs:dateTime?,
$locale as xs:string?)
as xs:string?
ora-fn:dateTime-to-string-with-format($format as xs:string?,
$dateTime as xs:dateTime?)
as xs:string?
パラメータ
$format: パターン。「Format引数」を参照してください
$dateTime: 日時。
$locale: ロケールを表す1つから3つのフィールド値。「Locale引数」を参照してください
例
この例は、文字列07 JAN 2013 10:09 PM ADを返します。
ora-fn:dateTime-to-string-with-format("dd MMM yyyy hh:mm a G",
xs:dateTime("2013-01-07T22:09:44"))
次の例は、文字列"01-07-2013"を返します。
ora-fn:dateTime-to-string-with-format("MM-dd-yyyy",
xs:dateTime("2013-01-07T22:09:44"))
このOracle XQuery関数は、指定されたパターンに従って入力文字列から新しい時間値を返します。
シグネチャ
ora-fn:time-from-string-with-format($format as xs:string?,
$timeString as xs:string?,
$locale as xs:string?)
as xs:time?
ora-fn:time-from-string-with-format($format as xs:string?,
$timeString as xs:string?)
as xs:time?
パラメータ
$format: パターン。「Format引数」を参照してください
$timeString: 時間
$locale: ロケールを表す1つから3つのフィールド値。「Locale引数」を参照してください
例
この例は、9:45:22PMを現在のタイムゾーンで返します。
ora-fn:time-from-string-with-format("HH.mm.ss", "21.45.22")
次の例は、8:07:22PMを現在のタイムゾーンで返します。
fn-bea:time-from-string-with-format("hh:mm:ss a", "8:07:22 PM")
このOracle XQuery関数は、指定されたパターンを持つ時間文字列を返します。
シグネチャ
ora-fn:time-to-string-with-format($format as xs:string?,
$time as xs:time?,
$locale as xs:string?)
as xs:string?
ora-fn:time-to-string-with-format($format as xs:string?, $time as xs:time?) as xs:string?
パラメータ
$format: パターン。「Format引数」を参照してください
$time: 時間
$locale: ロケールを表す1つから3つのフィールド値。「Locale引数」を参照してください
例
この例は、文字列"10:09 PM"を返します。
ora-fn:time-to-string-with-format("hh:mm a", xs:time("22:09:44"))
次の例は、文字列"22:09 PM"を返します。
ora-fn:time-to-string-with-format("HH:mm a", xs:time("22:09:44"))
$localeは、地理、政治または文化によって区別される特定の地域を表します。
これは、次に示す最大3つのフィールドで定義されます。
言語コード: ISO 639 alpha-2またはalpha-3の言語コード、または最大8文字の登録済言語サブタグ。たとえば、enは英語、jaは日本語です。
国コード: ISO 3166 alpha-2の国コード、またはUN M.49 numeric-3の地域コード。たとえば、USは米国、029はカリブです。
バリアント: ロケールのバリエーション(特定の方言など)を示します。複数の値を重要度の順に順序付けて、アンダースコア(_)で区切ります。これらの値は大文字と小文字を区別します。
Oracle XQueryの関数を使用して、XQueryで文字列を操作できます。
Oracle XQuery関数はhttp://xmlns.oracle.com/xdk/xquery/functionネームスペースにあります。ネームスペースの接頭辞ora-fnは事前に宣言され、モジュールは自動的にインポートされます。
文字列の左側にパディング文字を追加して、固定長の文字列を作成します。入力文字列が指定のサイズを超えると、切り捨てられて指定の長さの部分文字列が返されます。デフォルトのパディング文字は空白(ASCII 32)です。
シグネチャ
ora-fn:pad-left($str as xs:string?,
$size as xs:integer?,
$pad as xs:string?)
as xs:string?
ora-fn:pad-left($str as xs:string?,
$size as xs:integer?)
as xs:string?
パラメータ
$str: 入力文字列
$size: 任意の固定長で、パディング文字を$strに追加することによってその長さにします。
$pad: パディング文字
いずれかの引数が空の順序の場合、関数は空の順序を返します。
例
この例は、入力文字列が最大長6文字になるまで"01"を先頭に追加します。返される文字列は"010abc"です。関数は、1つの完全なパッド文字、および1つの部分的なパッド文字を返します。
ora-fn:pad-left("abc", 6, "01")
この例は、入力文字列が指定の固定長を超えているため、"ab"のみを返します。
ora-fn:pad-left("abcd", 2, "01")
この例は、文字列が指定の最大長6文字になるまで空白を先頭に追加します。返される文字列は"abcd"で、先頭に2つの空白が含まれます。
ora-fn:pad-left("abcd", 6)
次の例は、入力文字列が指定の固定長を超えているため、"ab"のみを返します。
ora-fn:pad-left("abcd", 2)
文字列の右側にパディング文字を追加して、固定長の文字列を作成します。入力文字列が指定のサイズを超えると、切り捨てられて指定の長さの部分文字列が返されます。デフォルトのパディング文字は空白(ASCII 32)です。
シグネチャ
ora-fn:pad-right($str as xs:string?,
$size as xs:integer?,
$pad as xs:string?)
as xs:string?
ora-fn:pad-right($str as xs:string?,
$size as xs:integer?)
as xs:string?
パラメータ
$str: 入力文字列
$size: 任意の固定長で、パディング文字を$strに追加することによってその長さにします。
$pad: パディング文字
いずれかの引数が空の順序の場合、関数は空の順序を返します。
例
この例は、入力文字列が最大長6文字になるまで"01"を追加します。返される文字列は"abc010"です。関数は、1つの完全なパッド文字、および1つの部分的なパッド文字を返します。
ora-fn:pad-right("abc", 6, "01")
この例は、入力文字列が指定の固定長を超えているため、"ab"のみを返します。
ora-fn:pad-right("abcd", 2, "01")
この例は、文字列が指定の最大長6文字になるまで空白を追加します。返される文字列は"abcd"で、末尾に2つの空白が含まれます。
ora-fn:pad-right("abcd", 6)
次の例は、入力文字列が指定の固定長を超えているため、"ab"のみを返します。
ora-fn:pad-right("abcd", 2)
先頭または末尾の空白をすべて文字列から削除します。
シグネチャ
ora-fn:trim($input as xs:string?) as xs:string?
パラメータ
$input: 切捨て対象の文字列。$inputが空の順序の場合、関数は空の順序を返します。他のデータ型の場合はエラーが発生します。
例
この例は、文字列"abc"を返します。
ora-fn:trim(" abc ")
先頭の空白をすべて削除します。
シグネチャ
ora-fn:trim-left($input as xs:string?) as xs:string?
パラメータ
$input: 切捨て対象の文字列。$inputが空の順序の場合、関数は空の順序を返します。他のデータ型の場合はエラーが発生します。
例
この例は、先頭の空白を削除して、文字列"abc "を返します。
ora-fn:trim-left(" abc ")
これらの関数は、http://xmlns.oracle.com/hadoop/xqueryネームスペースにあります。oxh接頭辞は事前に宣言され、モジュールは自動的にインポートされます。
Hadoopモジュールについては、次のトピックを参照してください。
Hadoop関数
Oracle XQuery for Hadoopには、次の関数が組み込まれています。
パターンに一致する一連のファイル・パスを返します。
シグネチャ
oxh:find($pattern as xs:string?) as xs:string*
パラメータ
$pattern: 検索するファイル・パターン
関連項目:
ファイル・パターンについては、次のサイトにある『Apache Hadoop API』のglobStatusメソッドに関する項
ユーザー定義のMapReduceジョブ・カウンタを増やします。デフォルトの増分は1です。
シグネチャ
oxh:increment-counter($groupName as xs:string, $counterName as xs:string, $value as xs:integer oxh:increment-counter($groupName as xs:string, $counterName as xs:string
パラメータ
$groupName: このカウンタが属するカウンタ・グループ。
$counterName: ユーザー定義カウンタの名前
$value: カウンタを増やす量
Oracle XQuery for Hadoopクライアント・プロセスのstdoutにテキスト行を出力します。この関数は、問合せを開発しているときに使用します。
シグネチャ
declare %updating function oxh:println($arg as xs:anyAtomicType?)
パラメータ
$arg: 出力に追加する値です。cast操作は、最初にstringに変換します。空の順序は空の文字列と同じ方法で扱われます。
例
この例では、data.txtの値をstdoutに出力します。
for $i in text:collection("data.txt")
return oxh:println($i)
テキスト行またはXMLをOracle XQuery for Hadoopクライアント・プロセスのstdoutに出力します。この関数は、問合せを開発しているとき、およびXMLドキュメントのノードを出力しているときに使用します。
シグネチャ
declare %updating function oxh:println-xml($arg as item()?)
パラメータ
$arg: 出力に追加する値です。入力項目は、XSLT 2.0仕様およびXQuery 1.0シリアライズ仕様の定義に従ってテキストに変換されます。空の順序は空の文字列と同じ方法で扱われます。
いくつかのアダプタにはシリアライズ注釈(%output:*)があります。次のリストに、Oracle XQuery for Hadoopがサポートするシリアライズ・パラメータを示します。
text出力方法に対してサポートされているシリアライズ・パラメータは次のとおりです。
encoding: JVMでサポートされているエンコード
normalization-form: none、NFC、NFD、NFKC、NFKD
xml出力方法に対してサポートされているシリアライズ・パラメータ(XQuery仕様で許可されている値を使用)は次のとおりです。
cdata-section-elements
doctype-public
doctype-system
encoding
indent
normalization-form
omit-xml-declaration
standalone
関連項目:
XMLおよびtext出力方法については、次のサイトにある『XSLT and XQuery Serialization』のシリアライズ・パラメータの影響に関する項
http://www.w3.org/TR/xslt-xquery-serialization/#XML_DOCTYPE
http://www.w3.org/TR/xslt-xquery-serialization/#XML_CDATA-SECTION-ELEMENTS
