---

順序ファイル・アダプタ

順序ファイル・アダプタは、Hadoop順序ファイルの読取りおよび書込みを実行する関数を提供します。順序ファイルは、キーと値のペアで構成されるHadoop固有のファイル形式です。

次のトピックでは、関数について説明します。

• 順序ファイルの読取りおよび書込みを実行する組込み関数

• 順序ファイルを読み取るカスタム関数

• 順序ファイルを書き込むカスタム関数

関連項目: Hadoop順序ファイルについては、次のサイトにあるHadoop Wiki http://wiki.apache.org/hadoop/SequenceFile

---

順序ファイルの読取りおよび書込みを実行する組込み関数

問合せで組込み関数を使用するには、次のように順序ファイル・モジュールをインポートする必要があります。

import module "oxh:seq";

順序ファイル・モジュールには、次の関数が含まれています。

• seq:collection

• seq:collection-xml

• seq:collection-binxml

• seq:put

• seq:put-xml

• seq:put-binxml

例については、「順序ファイル・アダプタの関数の例」を参照してください。

seq:collection

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つの文字列

seq:collection-xml

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ドキュメント。

seq:collection-binxml

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」を参照してください。

関連項目

『Oracle XML Developer's Kitプログラマーズ・ガイド』

seq:put

キーと値のペアの文字列値を、問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。

キー値がないため、この関数は値をorg.apache.hadoop.io.Textとして書き込み、キー・クラスをorg.apache.hadoop.io.NullWritableに設定します。

シグネチャ

declare %seq:put("text") function 
   seq:put($value as xs:string) external;

パラメータ

$value

書き込む文字列

戻り値

empty-sequence()

注意

作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前は「part」で始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。

seq:put

キーと文字列値を、問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。

この関数は、キーと値をorg.apache.hadoop.io.Textとして書き込みます。

シグネチャ

declare %seq:put("text") function
   seq:put($key as xs:string, $value as xs:string) external;

パラメータ

$key

キーと値のペアのキー

$value

キーと値のペアの値

戻り値

empty-sequence()

seq:put-xml

XML値を、問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。

キー値がないため、この関数は値をorg.apache.hadoop.io.Textとして書き込み、キー・クラスをorg.apache.hadoop.io.NullWritableに設定します。

シグネチャ

declare %seq:put("xml") function 
   seq:put-xml($xml as node()) external;

パラメータ

$value

書き込むXML

戻り値

empty-sequence()

注意

作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前は「part」で始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。

seq:put-xml

キーとXML値を、問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。

この関数は、キーと値をorg.apache.hadoop.io.Textとして書き込みます。

シグネチャ

declare %seq:put("xml") function
   seq:put-xml($key as xs:string, $xml as node()) external;

パラメータ

$key

キーと値のペアのキー

$value

キーと値のペアの値

戻り値

empty-sequence()

注意

作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前は「part」で始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。

seq:put-binxml

XML値をバイナリXMLとしてエンコードし、エンコードされたバイトを問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。

キー値がないため、この関数は値をorg.apache.hadoop.io.BytesWritableとして書き込み、キー・クラスをorg.apache.hadoop.io.NullWritableに設定します。

シグネチャ

declare %seq:put("binxml") function 
   seq:put-binxml($xml as node()) external;

パラメータ

$value

書き込むXML

戻り値

empty-sequence()

注意

作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前は「part」で始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。

seq:collection-binxml関数を使用すると、この関数によって作成されたファイルを読み取ることができます。「seq:collection-binxml」を参照してください。

関連項目

『Oracle XML Developer's Kitプログラマーズ・ガイド』

seq:put-binxml

XML値をバイナリXMLとしてエンコードし、エンコードされたバイトを問合せの出力ディレクトリ内の順序ファイルに書き込みます。値は1つ以上の順序ファイルに展開されます。

この関数は、キーをorg.apache.hadoop.io.Textとして書き込み、値をorg.apache.hadoop.io.BytesWritableとして書き込みます。

シグネチャ

declare %seq:put("binxml") function
   seq:put-binxml($key as xs:string, $xml as node()) external;

パラメータ

$key

キーと値のペアのキー

$value

書き込む値

戻り値

empty-sequence()

注意

作成されるファイル数は、問合せがどのように複数のタスクに分散されているかによって異なります。各ファイルの名前は「part」で始まります(例: part-m-00000)。問合せの実行時に、出力ディレクトリを指定します。「問合せの実行」を参照してください。

seq:collection-binxml関数を使用すると、この関数によって作成されたファイルを読み取ることができます。「seq:collection-binxml」を参照してください。

順序ファイル・アダプタの関数の例

この例は、次の内容で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>

例1   

次の問合せは、comment要素を順序ファイルに格納します。

import module "oxh:seq";
import module "oxh:xmlf";
 
for $comment in xmlf:collection("mydata/comments*.xml", "comment")
return 
   seq:put-xml($comment)

例2   

次の問合せは、前の問合せによって生成され、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ファイル・アダプタ」を参照してください。

---

順序ファイルを読み取るカスタム関数

次の注釈を使用して、順序ファイルのコレクションを読み取る関数を定義できます。これらの注釈によって、組込み関数では使用できない追加機能を使用できます。

シグネチャ

順序ファイルを読み取るカスタム関数には、次のいずれかのシグネチャが必要です。

declare %seq:collection("text") [additional annotations] 
   function local:myFunctionName($uris as xs:string*) as xs:string* external;

declare %seq:collection(["xml"|"binxml"]) [additional annotations]
   function local:myFunctionName($uris as xs:string*) as document-node()* external;

注釈

%seq:collection(["method"])

順序ファイルを読み取るための、順序ファイルのcollection関数を宣言します。必須。

オプションのmethodパラメータは次のいずれかの値です。

• text: 順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります^脚注 1 。これらはxs:stringとして返されます。デフォルト。

• xml: 順序ファイル内の値は、org.apache.hadoop.io.Textまたはorg.apache.hadoop.io.BytesWritableのいずれかである必要があります。関数によって、値はXMLとして解析されて返されます。

• binxml: 順序ファイル内の値は、org.apache.hadoop.io.BytesWritableである必要があります。関数によって、値はXDKバイナリXMLとして読み取られて返されます。『Oracle XML Developer's Kitプログラマーズ・ガイド』を参照してください。

%output:encoding("charset")

入力ファイルの文字エンコードを指定します。有効なエンコードは、JDKでサポートされているエンコードです。UTF-8がデフォルトのエンコードです。

関連項目: 次のサイトにあるOracle Java SEドキュメントのサポートされているエンコードに関する項 http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html

%seq:key("true" | "false")

キーと値のペアのキーが、ドキュメント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 
   .
   .
   .

%seq:split-max("split-size")

最大分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。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")

%seq:split-min("split-size")

最小分割サイズを整数または文字列値で指定します。分割サイズによって、入力ファイルがタスクに分割される方法を制御します。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;

注釈

%seq:put("method")

キーと値のペアを順序ファイルに書き込むための、順序ファイルの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

%seq:compress("codec", "compressionType")

出力で使用する圧縮形式を指定します。デフォルトは圧縮なしです。オプション。

codecパラメータは圧縮コーデックを識別します。値が一致して、最初に登録された圧縮コーデックが使用されます。値は、次のいずれかと等しい場合にコーデックに一致します。

1. コーデックの完全修飾されたクラス名

2. コーデックの修飾されていないクラス名

3. Codec (大文字と小文字を区別しない)の前にある、修飾されていないクラス名の接頭辞

compressionTypeパラメータを次のいずれかの値に設定します。

• block: キーと値がグループに収集され、まとめて圧縮されます。ブロック圧縮は、圧縮アルゴリズムで異なる値の類似性を利用できるため、通常はよりコンパクトになります。

• record: 順序ファイル内の値のみ圧縮されます。

次のすべての例では、デフォルトのコーデックおよびブロック圧縮を使用します。

%seq:compress("org.apache.hadoop.io.compress.DefaultCodec", "block")
%seq:compress("DefaultCodec", "block")
%seq:compress("default", "block") 

%seq:file("name")

出力ファイル名の接頭辞を指定します。デフォルトの接頭辞はpartです。

%output:parameter

%seq:putで指定される出力方法(テキストまたはXML)に対する標準XQueryシリアライズ・パラメータ。「シリアライズ注釈」を参照してください。

関連項目: 次のサイトにあるHadoop Wikiの順序ファイルに関するトピック http://wiki.apache.org/hadoop/SequenceFile XMLおよびテキスト出力方法については、次のサイトにある『XSLT and XQuery Serialization 3.0』のシリアライズ・パラメータの影響に関する項 http://www.w3.org/TR/xslt-xquery-serialization-30/

順序ファイル・アダプタの関数の例

次の問合せは、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)

次の問合せは、前の問合せによって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 :( "/>

---

脚注の説明

脚注 1: バイトは、%output:encoding注釈で指定された文字セットを使用してデコードされます。