1. ユーザーズ・ガイド
  2. Oracle XQuery for Apache Hadoop
  3. Oracle XML Extensions for Hive

7 Oracle XML Extensions for Hive

この章では、Oracle XQuery for Hadoopで提供される、XML Extensions for Apache Hiveの使用方法について説明します。この章の内容は次のとおりです。

XML Extensions for Hiveとは

XML Extensions for Hiveでは、次のことを可能にするXML処理サポートが提供されています。

  • HDFSの大規模なXMLファイルのHive表としての問合せ

  • Hive表のXML文字列の問合せ

  • Hadoop分散キャッシュのXMLファイル・リソースの問合せ

  • 高負荷DOM解析を使用せずにXMLからアトミック値を効率的に抽出

  • 複雑なXML要素の取得、生成および変換

  • 単一XML値からの表の複数行の生成

  • XMLでの欠落およびダーティ・データの管理

XML拡張では、次の各W3C最新標準もサポートされています。

  • XQuery 3.1

  • XQuery Update Facility 1.0 (変換式)

  • XPath 3.1

  • XML Schema 1.0

  • XML Namespaces

XML拡張には2つのコンポーネントがあります。

コマンドラインからのHive拡張の使用

Oracle XQuery for Hadoop拡張を有効にするには、Hiveの起動時に--auxpathおよび-i引数を使用します。 

$ hive --auxpath \
$OXH_HOME/hive/lib/oxh-hive.jar,\
$OXH_HOME/hive/lib/oxh-mapreduce.jar,\
$OXH_HOME/hive/lib/oxquery.jar,\
$OXH_HOME/hive/lib/xqjapi.jar,\
$OXH_HOME/hive/lib/apache-xmlbeans.jar,\
$OXH_HOME/hive/lib/woodstox-core-asl-*.jar,\
$OXH_HOME/hive/lib/stax2-api-*.jar \
-i $OXH_HOME/hive/init.sql

ノート:

Oracle BigDataLite VMでは、HIVE_AUX_JARS_PATHはHive拡張をデフォルトで含み、そのため--auxpathを指定する必要はありません。

拡張を初めて使用するとき、それらがアクセス可能であることを確認します。次の手順では、SRCという表を作成し、その表に1行ロードした後、xml_query関数を呼び出します。

拡張がアクセス可能であることを確認するには、次の手順を実行します。

  1. 作業しようとしているHadoopクラスタにあるサーバーにログインします。

  2. Hiveコマンドライン・インタフェース(CLI)を起動します。

    $ hive --auxpath \
$OXH_HOME/hive/lib/oxh-hive.jar,\
$OXH_HOME/hive/lib/oxh-mapreduce.jar,\
$OXH_HOME/hive/lib/oxquery.jar,\
$OXH_HOME/hive/lib/xqjapi.jar,\
$OXH_HOME/hive/lib/apache-xmlbeans.jar,\
$OXH_HOME/hive/lib/woodstox-core-asl-*.jar,\
$OXH_HOME/hive/lib/stax2-api-*.jar \
-i $OXH_HOME/hive/init.sql

    init.sqlファイルには、XML関数を宣言するCREATE TEMPORARY FUNCTION文が含まれています。

  3. Hive用のOracle XQuery for Hadoop関数を呼び出します。この例では、xml_query関数を呼び出してXML文字列を解析します。 

    hive> SELECT xml_query("x/y", "<x><y>123</y><z>456</z></x>");
     .
     .
     .
["123"]

拡張がアクセス可能な場合は、例に示すように、問合せで["123"]が返されます。

HiveServer2でのHive拡張の使用

HiveServer2でXML Extensions for Hiveを使用可能にするには、環境変数HIVE_AUX_JARS_PATHおよび構成プロパティhive.aux.jars.pathに次のJARを追加する必要があります。
$OXH_HOME/hive/lib/woodstox-core-asl-*.jar            
$OXH_HOME/hive/lib/apache-xmlbeans.jar            
$OXH_HOME/hive/lib/oxh-hive.jar            
$OXH_HOME/hive/lib/oxh-mapreduce.jar           
$OXH_HOME/hive/lib/stax2-api-*.jar            
$OXH_HOME/hive/lib/xqjapi.jar            
$OXH_HOME/hive/lib/oxquery.jar
Cloudera's distribution including Apache Hadoop (Oracle Big Data Applianceまたはコモディティ・ハードウェア上)を使用している場合は、次のようにJARを追加できます。
  1. Cloudera Managerで、「hive」をクリックします。
    Cloudera ManagerでHiveサービスを選択します。
  2. 「Configuration」をクリックして「Configuration」タブに移動します。
    「Configuration」をクリックします
  3. 検索フィールドで、hive_auxと入力します。次に、Gateway Client Environment Advanced Configuration Snippet (Safety Valve) for hive-env.sh内のすべての値の後に、次のテキストを追加します。必ず先頭のカンマを含めてください。後で元に戻す場合に備えて、このフィールドを編集する前に、元のパスのテキストを保存することをお薦めします。
    ,/opt/oracle/oxh-*/hive/lib/woodstox-core-asl-oxh-*.jar,/opt/oracle/oxh-*/hive/lib/apache-xmlbeans.jar,/opt/oracle/oxh-*/hive/lib/oxh-hive.jar,/opt/oracle/oxh-*/hive/lib/oxh-mapreduce.jar,/opt/oracle/oxh-*/hive/lib/stax2-api-*.jar,/opt/oracle/oxh-*/hive/lib/xqjapi.jar,/opt/oracle/oxh-*/hive/lib/oxquery.jar

    上のパス内のJARバージョン番号がワイルドカード(*)であることに注意してください。ワイルドカードを、使用しているOXHリリースに対応する正しいJARバージョンで置き換えます。

    「Gateway Client Advanced Configuration」の編集内容を示します
  4. hive.aux.jars.pathを検索します。Hive Client Advanced Configuration Snippet (Safety Valve) for hive-site.xml内のすべての値の後に、次のテキストを追加します。必ず「Gateway Default Group」パネルの「value」フィールドにこのテキストを追加してください。
    「Gateway Default Group」を示します
  5. 「Save Changes」をクリックします。
  6. 「Actions」、「Deploy Client Configuration」の順にクリックします。「Deploy Client Configuration」をクリックします
  7. サービスが再起動された後、ステータスで、それが正しく機能していることを確認します。
  8. 拡張にアクセス可能であることを確認するには、次のようにBeelineを使用します。
    1. 次のようにBeelineを起動します。
      $ beeline -i $OXH_HOME/hive/init.sql

      ノート:

      前述のように、init.sqlを使用して、関数xml_query、xml_tableなどを一時的に宣言できます。Hive関数の永続的宣言で説明されているように、関数を永続的に有効にすることもできます。
    2. BeelineのCLIで、次のように入力します。(プレースホルダhostとportにhiveserver2のホストとポートを入力します)。
      beeline> !connect jdbc:hive2: //[host]:[port]

      ユーザー名とパスワードを要求されたら、[Enter]を押します。

    3. Hiveに接続したときにすべてのXML拡張関数が作成される必要があります。次のコマンドを試して、それらが正常に動作しているかどうかをテストします。
      beeline> SELECT xml_query("x/y", "<x><y>123</y><z>456</z></x>");
      返される結果は、次の例のようになります。
      +----------+--+
|   _c0    |
+----------+--+
| ["123"]  |
+----------+--+
    このテストに成功した場合は、HiveServer2でHive用のOracle XQuery for Hadoop関数を使用する準備はできています。

関連項目:

  • Hive関数の永続的宣言

    前の例で示したように、init.sqlを使用して関数を一時的に宣言できます。それらを永続的に宣言することもできます。

Hive関数について

Oracle XQuery for Hadoopの拡張を使用すると、Hadoop分散キャッシュのHive表およびXMLファイル・リソース内のXML文字列を問い合せることができます。これらは次の関数です。

  • xml_query: 問合せの結果をSTRING値の配列として返します。

  • xml_query_as_primitive: 問合せの結果をHiveプリミティブ値として返します。各Hiveプリミティブ・データ型には、それに対応する名前の個別の関数があります。

  • xml_exists: 問合せの結果が空かどうかをテストします。

  • xml_table: XML値をゼロ以上の表の行にマップします。この関数を使用すると、XMLのネストされた繰返し要素をHive表の行にマップできます。

「Hive用のOracle XML関数のリファレンス」を参照してください。

Hive関数の永続的宣言

前の項の例では、Hive関数のXML拡張を一時的に宣言するために$OXH_HOME/hive/init.sqlが使用されていました。ただし、代替手段として、init.sqlが不要なように関数を永続的に宣言できます。関数を永続的に宣言するには、次のコマンドを使用します。 

CREATE FUNCTION xml_query AS 'oracle.hadoop.xquery.hive.OXMLQueryUDF' ;
CREATE FUNCTION xml_query_as_bigint AS 'oracle.hadoop.xquery.hive.OXMLQueryBigintUDF' ;
CREATE FUNCTION xml_query_as_int AS 'oracle.hadoop.xquery.hive.OXMLQueryIntUDF' ;
CREATE FUNCTION xml_query_as_smallint AS 'oracle.hadoop.xquery.hive.OXMLQuerySmallintUDF' ;
CREATE FUNCTION xml_query_as_tinyint AS 'oracle.hadoop.xquery.hive.OXMLQueryTinyintUDF' ;
CREATE FUNCTION xml_query_as_float AS 'oracle.hadoop.xquery.hive.OXMLQueryFloatUDF' ;
CREATE FUNCTION xml_query_as_double AS 'oracle.hadoop.xquery.hive.OXMLQueryDoubleUDF' ';
CREATE FUNCTION xml_query_as_boolean AS 'oracle.hadoop.xquery.hive.OXMLQueryBooleanUDF' ;
CREATE FUNCTION xml_query_as_string AS 'oracle.hadoop.xquery.hive.OXMLQueryStringUDF' ;
CREATE FUNCTION xml_exists AS 'oracle.hadoop.xquery.hive.OXMLExists' ;
CREATE FUNCTION xml_table AS 'oracle.hadoop.xquery.hive.OXMLTableUDTF' ;

XML表の作成

この項では、HiveのCREATE TABLE文を使用して大規模なXMLドキュメントに関する表を作成する方法を説明します。

XML表に関するHive問合せは、MapReduceフレームワークでXMLを並列で処理できるようにOracle XQuery for HadoopによってXMLが分割されるため、適切な規模で行われます。

スケーラブルな処理をサポートし、MapReduceフレームワークで動作するために、表アダプタによって、表の行の作成に使用する要素がスキャンされます。表の一部であると識別した要素のみが解析され、残りのXMLは無視されます。したがって、XML表アダプタでは、入力XMLに制限が課される、XMLドキュメント全体の真の意味での解析は実行されません。これらの制限のため、「XQuery変換の要件」にリストされている制約を満たすXMLドキュメントに関してのみ表を作成できます。それ以外の場合は、エラーが発生するか、誤った結果となる場合があります。

XML表に対するHiveのCREATE TABLE構文

次に、XMLファイルに関するHive表を作成するためのHiveのCREATE TABLE文の基本構文を示します。 

CREATE TABLE table_name (columns)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(configuration)

パラメータ

パラメータ 説明

columns

XML表の列タイプはすべて、「データ型変換」で示されているHiveプリミティブ・タイプの1つである必要があります。

configuration

「CREATE TABLE構成プロパティ」で説明されているいずれかのプロパティ。複数のプロパティはカンマで区切ります。

ノート:

XML表へのデータの挿入はサポートされていません。

CREATE TABLE構成プロパティ

次の構成プロパティは、CREATE TABLEコマンドのconfigurationパラメータで使用します。

oxh-default-namespace

XML解析の表定義にある式のデフォルト・ネームスペースを設定します。値はURIです。

この例ではデフォルトのネームスペースを定義します。

"oxh-default-namespace" = "http://example.com/foo"
oxh-charset

XMLファイルの文字エンコードを指定します。サポートされているエンコードは、UTF-8 (デフォルト)、ISO-8859-1およびUS-ASCIIです。

表に対するXMLファイルはすべて、同じ文字エンコードを共有する必要があります。XMLファイルでのエンコード宣言は無視されます。

この例では、文字セットを定義します。

"oxh-charset" = "ISO-8859-1"
oxh-column.name

oxh-elementsプロパティで選択した要素を行の列にマップする方法を指定します。このプロパティ名では、nameを表の列の名前に置き換えます。値には任意のXQuery式を指定できます。式の初期コンテキスト項目("."変数)は、選択した要素にバインドされます。

問合せが正常に実行された場合でもログ・ファイルを確認してください。列式で値が返されない場合、または動的エラーが発生した場合、列値はNULLです。エラーが初めて発生したときは、エラーがログに記録され、問合せ処理は続行します。同じ列式で発生した後続のエラーはログに記録されません。

対応するoxh-columnプロパティがない表の列は、次のプロパティが指定されている場合と同様に動作します。 

"oxh-column.name" = "(./name | ./@name)[1]"

したがって、デフォルトの動作では、表の列名と一致する最初の子要素または属性が選択されます。「構文の例」を参照してください。

oxh-elements

表の行にマップするXMLの要素の名前をカンマ区切りリストで示します。このプロパティは1回指定する必要があります。必須。

次の例では、XMLのfooという各要素をHive表の単一の行にマップします。 

"oxh-elements" = "foo"

次の例では、XMLのfooまたはbarという各要素をHive表の行にマップします。 

"oxh-elements" = "foo, bar"
oxh-entity.name

エンティティ参照定義のセットを定義します。

次の例では、XMLのエンティティ参照が、&foo;から"foo value"および&bar;から"bar value"に拡張されます。 

"oxh-entity.foo" = "foo value"
"oxh-entity.bar" = "bar value"
oxh-namespace.prefix

ネームスペース・バインディングを定義します。

次の例では、接頭辞mynsをネームスペースhttp://example.orgにバインドします。 

"oxh-namespace.myns" = "http://example.org"

このプロパティを複数回使用して、追加のネームスペースを定義できます。ネームスペース定義は、XMLの解析時に使用されます。oxh-elementおよびoxh-columnプロパティの値でそれらを参照することもできます。

次の例では、http://example.orgネームスペースのfoo要素のみが表の行にマップされます。 

"oxh-namespace.myns" = "http://example.org",
"oxh-elements" = "myns:foo",
"oxh-column.bar" = "./myns:bar"

CREATE TABLEの例

この項で示す例は次のとおりです。

構文の例

この例では、XML要素を列名にマップする方法を示します。

例7-1 基本的な列マッピング

次の表定義で、oxh-elementsプロパティは、XMLのfooという各要素が表の単一の行にマップされることを指定しています。oxh-columnプロパティは、BARというHive表の列では、STRINGに変換されたbarという子要素の値を取得し、ZIPという列では、INTに変換されたzipという子要素の値を取得することを指定しています。 

CREATE TABLE example (bar STRING, zip INT)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(
   "oxh-elements" = "foo", 
   "oxh-column.bar" = "./bar",
   "oxh-column.zip" = "./zip"
)

例7-2 条件付き列マッピング

次のZIP列の変更された定義で、列は、foo要素に子のzip要素がない場合、またはzip要素に数値以外の値が含まれている場合は、-1の値を受け取ります。 

"oxh-column.zip" = "
   if (./zip castable as xs:int) then 
      xs:int(./zip) 
   else 
      -1
"

例7-3 デフォルトの列マッピング

次の2つの表定義は同等です。表定義2は、BAR列とZIP列のデフォルトのマッピングに基づいています。

表定義1

CREATE TABLE example (bar STRING, zip INT)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(
   "oxh-elements" = "foo", 
   "oxh-column.bar" = "(./bar | ./@bar)[1]",
   "oxh-column.zip" = "(./zip | ./@zip)[1]"
)

表定義2

CREATE TABLE example (bar STRING, zip INT)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(
   "oxh-elements" = "foo"
)
簡単な例

これらの例は、架空のWebサイトのユーザーが送信したコメントを含む小規模なXMLドキュメントに関するHive表を作成する方法を示しています。ドキュメント(comments.xml)の各comment要素には、ユーザーがそのコメントを気に入ったことを示す1つ以上のlike要素があります。 

<comments>
   <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>
   <comment id="54321" user="mike" text="Happy New Year!">
      <like user="laura"/>
   </comment>
</comments>

CREATE TABLEの例では、comments.xml入力ファイルは、ローカル・ファイル・システムの現在の作業ディレクトリにあります。

例7-4 表の作成

次のHiveのCREATE TABLEコマンドでは、COMMENTSというの表を作成します。ユーザー名、テキストおよびlikeの数が含まれる行が各コメントに対して1行あります。 

hive>
CREATE TABLE comments (usr STRING, content STRING, likeCt INT)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(
   "oxh-elements" = "comment",
   "oxh-column.usr" = "./@user",
   "oxh-column.content" = "./@text",
   "oxh-column.likeCt" = "fn:count(./like)"
);

HiveのLOAD DATAコマンドで、comments.xmlをCOMMENTS表にロードします。 

hive> LOAD DATA LOCAL INPATH 'comments.xml' OVERWRITE INTO TABLE comments;
]

次の問合せは、COMMENTS表の内容を示します。 

hive> SELECT usr, content, likeCt FROM comments;
     .
     .
     .
john  It is raining :(     0
kelly I won the lottery!   2
mike  Happy New Year!      1

例7-5 XML列の問合せ

このCREATE TABLEコマンドは前の例と似ていますが、like要素がSTRING列にXMLとして生成される点が異なります。 

hive>
CREATE TABLE comments2 (usr STRING, content STRING, likes STRING)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(
   "oxh-elements" = "comment",
   "oxh-column.usr" = "./@user",
   "oxh-column.content" = "./@text",
   "oxh-column.likes" = "fn:serialize(<likes>{./like}</likes>)"
);

HiveのLOAD DATAコマンドで、comments.xmlを表にロードします。ファイルの内容は、「簡単な例」を参照してください。 

hive> LOAD DATA LOCAL INPATH 'comments.xml' OVERWRITE INTO TABLE comments2;

次の問合せは、COMMENTS2表の内容を示します。 

hive> SELECT usr, content, likes FROM comments2;
     .
     .
     .
john   It is raining :(    <likes/>
kelly  I won the lottery!  <likes><like user="john"/><like user="mike"/></likes>
mike   Happy New Year!     <likes><like user="laura"/></likes>

次の問合せでは、like要素からユーザー名を抽出します。 

hive> SELECT usr, t.user FROM comments2 LATERAL VIEW 
    > xml_table("likes/like", comments2.likes, struct("./@user")) t AS user;
     .
     .
     .
kelly  john
kelly  mike
mike   laura

例7-6 単一の文字列の列におけるXMLの生成

このコマンドでは、各コメントに対する行を含むCOMMENTS3という表を作成し、単一のSTRING列にXMLを生成します。 

hive> 
CREATE TABLE comments3 (xml STRING)
ROW FORMAT
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
TBLPROPERTIES(
   "oxh-elements" = "comment",
   "oxh-column.xml" = "fn:serialize(.)"
   );

HiveのLOAD DATAコマンドで、comments.xmlを表にロードします。ファイルの内容は、「簡単な例」を参照してください。 

hive> LOAD DATA LOCAL INPATH 'comments.xml' OVERWRITE INTO TABLE comments3;

次の問合せは、XML列の内容を示します。

hive> SELECT xml FROM comments3;
     .
     .
     .
<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>
<comment id="54321" user="mike" text="Happy New Year!">
   <like user="laura"/>
</comment>

次の問合せでは、IDを抽出してそれらを整数に変換します。

hive> SELECT xml_query_as_int("comment/@id", xml) FROM comments3;
     .
     .
     .
12345
56789
54321
OpenStreetMapの例

次の各例では、全世界の無料の地図データを提供するOpenStreetMapからのデータを使用します。特定の地理的リージョンまたは地球全体のデータをXMLとしてエクスポートできます。OpenStreetMap XMLドキュメントには主に、一連のnode、wayおよびrelation要素が含まれています。

次の各例では、OpenStreetMap XMLファイルが/user/name/osm HDFSディレクトリに格納されます。

関連項目:

例7-7 OpenStreetMap XMLに関する表の作成

この例では、次のように各node要素に対する1行を含む、OpenStreetMap XMLに関する表を作成します。

  • node要素のid、lat、lonおよびuser属性は、表の列にマップされます。

  • 年がtimestamp属性から抽出され、YEAR列にマップされます。ノードにtimestamp属性がない場合、年には-1が使用されます。

  • node要素に子のtag要素がある場合は、TAGS列にXML文字列として格納されます。nodeに子のtag要素がない場合、列値はNULLです。 

hive>
CREATE EXTERNAL TABLE nodes (
   id BIGINT,
   latitude DOUBLE,
   longitude DOUBLE,
   year SMALLINT,
   tags STRING
) 
ROW FORMAT 
   SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
STORED AS
   INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
   OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
LOCATION '/user/name/osm'
TBLPROPERTIES (
   "oxh-elements" = "node",
   "oxh-column.id" = "./@id",
   "oxh-column.latitude" = "./@lat",
   "oxh-column.longitude" = "./@lon",
   "oxh-column.year" = "
      if (fn:exists(./@timestamp)) then
         fn:year-from-dateTime(xs:dateTime(./@timestamp))
      else
         -1
   ",
   "oxh-column.tags" = "
      if (fn:exists(./tag)) then
         fn:serialize(<tags>{./tag}</tags>)
      else 
         ()
   "
);

次の問合せは、年ごとのノード数を返します。

hive> SELECT year, count(*) FROM nodes GROUP BY year;

次の問合せは、ノード全体の合計タグ数を返します。

hive> SELECT sum(xml_query_as_int("count(tags/tag)", tags)) FROM nodes;

例7-8

OpenStreetMap XMLでは、node、wayおよびrelation要素で、データに関与したユーザーなどの共通属性のセットが共有されます。次の表では、各node、wayおよびrelation要素に対して1行生成します。 

hive>
  CREATE EXTERNAL TABLE osm (
     id BIGINT,
     uid BIGINT,
     type STRING
  ) 
  ROW FORMAT 
    SERDE 'oracle.hadoop.xquery.hive.OXMLSerDe'
  STORED AS
    INPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLInputFormat'
    OUTPUTFORMAT 'oracle.hadoop.xquery.hive.OXMLOutputFormat'
  LOCATION '/user/name/osm'
  TBLPROPERTIES (
    "oxh-elements" = "node, way, relation",
    "oxh-column.id" = "./@id",
    "oxh-column.uid" = "./@uid",
    "oxh-column.type" = "./name()"
  );

次の問合せは、node、wayおよびrelation要素の数を返します。TYPE列は、選択した要素の名前であるnode、wayまたはrelationのいずれかに設定されます。 

hive> SELECT type, count(*) FROM osm GROUP BY type;

次の問合せは、個別のユーザーIDの数を返します。

hive> SELECT count(*) FROM (SELECT uid FROM osm GROUP BY uid) t;

関連項目:

OpenStreetMapの要素および属性の説明は、次のサイトを参照してください。

http://wiki.openstreetmap.org/wiki/Elements

Hive用のOracle XML関数のリファレンス

この項では、Oracle XML Extensions for Hiveについて説明します。次のコマンドおよび関数について説明します。

データ型変換

この表に、Hiveプリミティブ・タイプおよびXMLスキーマ・タイプ間で自動的に行われる変換を示します。

表7-1 同等のデータ型

Hive XMLスキーマ

TINYINT

xs:byte

SMALLINT

xs:short

INT

xs:int

BIGINT

xs:long

BOOLEAN

xs:boolean

FLOAT

xs:float

DOUBLE

xs:double

STRING

xs:string

外部ファイルへのHiveアクセス

Hive関数は、次の外部ファイル・リソースにアクセスできます。

これらのファイルは、HTTP (http://...構文を使用)またはローカル・ファイル・システム(file://...構文を使用)からそれらのURIによってアドレス指定できます。次の例では、タスクのローカル作業ディレクトリに対して相対的なファイルの場所が解決されるため、bar.xsdなどのURIを使用すると、分散キャッシュに追加されたファイルにアクセスできます。 

xml_query("
   import schema namespace tns='http://example.org' at 'bar.xsd';
   validate { ... }
        ",
   .
   .
   .

ローカル・ファイルにアクセスするには、最初に、HiveのADD FILEコマンドを使用してそのファイルをHadoop分散キャッシュに追加します。次に例を示します。 

ADD FILE /local/mydir/thisfile.xsd;

それ以外の場合は、同じネットワーク・ドライブをマウントするか、ファイルをすべてのノードに単純にコピーするなど、クラスタのすべてのノードでファイルが使用できるようにする必要があります。デフォルトのベースURIは、ローカル作業ディレクトリに設定されます。

関連項目:

  • 分散キャッシュへのアクセスの例は、xml_queryについては例7-15、xml_query_as_primitiveについては例7-22、xml_tableについては例7-31を参照してください。

  • デフォルトのベースURIについては、次のサイトにある『XQuery 3.1:An XML Query Language』

    http://www.w3.org/TR/xquery/#dt-base-uri

関数のオンライン・マニュアル

次のコマンドを使用して、Hive拡張関数のオンライン・ヘルプを取得できます。

DESCRIBE FUNCTION [EXTENDED] function_name;

次の例では、xml_query関数の簡単な説明が示されます。 

hive> describe function xml_query;         
OK
xml_query(query, bindings) - Returns the result of the query as a STRING array

EXTENDEDオプションを使用すると、詳細な説明と例が示されます。 

hive> describe function extended xml_query;
OK
xml_query(query, bindings) - Returns the result of the query as a STRING array
Evaluates an XQuery expression with the specified bindings. The query argument must be a STRING and the bindings argument must be a STRING or a STRUCT. If the bindings argument is a STRING, it is parsed as XML and bound to the initial context item of the query. For example:
  
  > SELECT xml_query("x/y", "<x><y>hello</y><z/><y>world</y></x>") FROM src LIMIT 1;
  ["hello", "world"]
     .
     .
     .

xml_exists

問合せの結果が空かどうかをテストします。

シグネチャ

xml_exists(
    STRING query, 
    { STRING | STRUCT } bindings
) as BOOLEAN

説明

query

XQueryまたはXPath式。これは、関数が最初に評価されるときのみ読み込まれるため、定数値である必要があります。最初の問合せ文字列がコンパイルされ、後続のすべての呼出しで再使用されます。

Hadoop分散キャッシュおよびHTTPリソース(http://...)に格納されているファイルにアクセスできます。XMLドキュメントの場合はXQueryのfn:doc関数を使用し、プレーン・テキスト・ファイルにアクセスするにはfn:unparsed-textおよびfn:parsed-text-lines関数を使用します。

問合せのコンパイル中にエラーが発生した場合は、関数でエラーが発生します。問合せの評価中にエラーが発生した場合、エラーは(生成されずに)ログに記録され、空の配列が返されます。

bindings

問合せで処理される入力。値は、XML STRINGまたは変数値のSTRUCTです。

  • STRING: 文字列は、問合せの初期コンテキスト項目にXMLとしてバインドされます。

  • STRUCT: 偶数個のフィールドで構成されるSTRUCT。フィールドの各ペアで、問合せの変数バインディング(名前, 値)が定義されます。名前フィールドのタイプはSTRINGである必要があり、値フィールドにはサポートされているプリミティブを指定できます。「データ型変換」を参照してください。

戻り値

問合せの結果が空でない場合はtrue、結果が空または問合せで動的エラーが発生した場合はfalse。

ノート

問合せで発生した最初の動的エラーはログに記録されますが、後続のエラーは記録されません。

例

例7-9 STRINGバインディング

次の例では、入力XML文字列を解析し、問合せx/yの初期コンテキスト項目にバインドします。 

Hive> SELECT xml_exists("x/y", "<x><y>123</y></x>") FROM src LIMIT 1;
     .
     .
     .
true

例7-10 STRUCTバインディング

次の例では、2つの問合せ変数$dataと$valueを定義します。 

Hive> SELECT xml_exists(
      "parse-xml($data)/x/y[@id = $value]",
      struct(
         "data", "<x><y id='1'/><y id='2'/></x>",
         "value", 2
      )
   ) FROM src LIMIT 1;
     .
     .
     .
true

例7-11 エラー・ロギング

次の例では、入力XMLが無効であるため、エラーがログに書き込まれます。

hive> SELECT xml_exists("x/y", "<x><y>123</invalid></x>") FROM src LIMIT 1;
     .
     .
     .
false

xml_query

問合せの結果をSTRING値の配列として返します。

シグネチャ

xml_query(
   STRING query, 
   { STRING | STRUCT } bindings
) as ARRAY<STRING>

説明

query

XQueryまたはXPath式。これは、関数が最初に評価されるときのみ読み込まれるため、定数値である必要があります。最初の問合せ文字列がコンパイルされ、後続のすべての呼出しで再使用されます。

Hadoop分散キャッシュおよびHTTPリソース(http://...)に格納されているファイルにアクセスできます。XMLドキュメントの場合はXQueryのfn:doc関数を使用し、プレーン・テキスト・ファイルにアクセスするにはfn:unparsed-textおよびfn:parsed-text-lines関数を使用します。例7-15を参照してください。

問合せのコンパイル中にエラーが発生した場合は、関数でエラーが発生します。問合せの評価中にエラーが発生した場合、エラーは(生成されずに)ログに記録され、空の配列が返されます。

bindings

問合せで処理される入力。値は、XML STRINGまたは変数値のSTRUCTです。

  • STRING: 文字列は、問合せの初期コンテキスト項目にXMLとしてバインドされます。例7-12を参照してください。

  • STRUCT: 偶数個のフィールドで構成されるSTRUCT。フィールドの各ペアで、問合せの変数バインディング(名前, 値)が定義されます。名前フィールドのタイプはSTRINGである必要があり、値フィールドにはサポートされているプリミティブを指定できます。「データ型変換」および例7-13を参照してください。

戻り値

STRING値のHive配列であり、一連のアトミック値に変換される問合せの結果です。問合せの結果が空の場合、戻り値は空の配列です。

例

例7-12 STRINGバインディングの使用

次の例では、入力XML文字列を解析し、問合せx/yの初期コンテキスト項目にバインドします。 

hive> 
SELECT xml_query("x/y", "<x><y>hello</y><z/><y>world</y></x>") 
FROM src LIMIT 1;
     .
     .
     .
["hello","world"]

例7-13 STRUCTバインディングの使用

次の例では、2番目の引数は、2つの問合せ変数$dataと$valueを定義するSTRUCTです。STRUCTの変数の値は、「データ型変換」で説明されているように、XMLスキーマ・タイプに変換されます。

hive>
SELECT xml_query(
   "fn:parse-xml($data)/x/y[@id = $value]", 
   struct(
      "data", "<x><y id='1'>hello</y><z/><y id='2'>world</y></x>",
      "value", 1
   )
) FROM src LIMIT 1;
     .
     .
     .
["hello"]

例7-14 シリアライズされたXMLの取得

次の例では、fn:serialize関数を使用して、シリアライズされたXMLを返します。 

hive> 
SELECT xml_query(
"for $y in x/y 
return fn:serialize($y)
",
"<x><y>hello</y><z/><y>world</y></x>"
) FROM src LIMIT 1;
     .
     .
     .
["<y>hello</y>","<y>world</y>"]

例7-15 Hadoop分散キャッシュへのアクセス

次の例では、test.xmlという名前のファイルを分散キャッシュに追加し、fn:doc関数を使用してそれを問い合せます。ファイルには、次の値が格納されます。 

<x><y>hello</y><z/><y>world</y></x>

hive> ADD FILE test.xml;
Added resource: test.xml
hive> SELECT xml_query("fn:doc('test.xml')/x/y", NULL) FROM src LIMIT 1;
     .
     .
     .
["hello","world"]

例7-16 失敗した問合せの結果

次の例は、入力XMLが無効であるため、空の配列を返します。XML解析エラーがログに書き込まれます。

hive> SELECT xml_query("x/y", "<x><y>hello</y></invalid") FROM src LIMIT 1;
     .
     .
     .
[]

xml_query_as_primitive

Hiveプリミティブ値として問合せの結果を返します。各Hiveプリミティブ・データ・タイプには、そのタイプに対応する名前の個別の関数があります。

  • xml_query_as_string

  • xml_query_as_boolean

  • xml_query_as_tinyint

  • xml_query_as_smallint

  • xml_query_as_int

  • xml_query_as_bigint

  • xml_query_as_double

  • xml_query_as_float

シグネチャ

xml_query_as_primitive (
   STRING query,
   {STRUCT | STRING} bindings,
} as primitive

説明

query

XQueryまたはXPath式。これは、関数が最初に評価されるときのみ読み込まれるため、定数値である必要があります。最初の問合せ文字列がコンパイルされ、後続のすべての呼出しで再使用されます。

Hadoop分散キャッシュおよびHTTPリソース(http://...)に格納されているファイルにアクセスできます。XMLドキュメントの場合はXQueryのfn:doc関数を使用し、プレーン・テキスト・ファイルにアクセスするにはfn:unparsed-textおよびfn:parsed-text-lines関数を使用します。例7-15を参照してください。

問合せのコンパイル中にエラーが発生した場合は、関数でエラーが発生します。問合せの評価中にエラーが発生した場合、エラーは(生成されずに)ログに記録され、空の配列が返されます。

bindings

問合せで処理される入力。値は、XML STRINGまたは変数値のSTRUCTです。

  • STRING: 文字列は、問合せの初期コンテキスト項目にXMLとしてバインドされます。例7-17を参照してください。

  • STRUCT: 偶数個のフィールドで構成されるSTRUCT。フィールドの各ペアで、問合せの変数バインディング(名前, 値)が定義されます。名前フィールドのタイプはSTRINGである必要があり、値フィールドにはサポートされているプリミティブを指定できます。「データ型変換」および例7-18を参照してください。

    問合せの結果の最初の項目が、プリミティブ・タイプの関数にマップされるXMLスキーマ・タイプにキャストされます。問合せで複数の項目が返される場合、最初の項目以外はすべて無視されます。

戻り値

アトミック値に変換されたHiveプリミティブ値(問合せによって返される最初の項目)。問合せの結果が空の場合、戻り値はNULLです。

例

例7-17 STRINGバインディングの使用

次の例では、入力XML文字列を解析し、問合せx/yの初期コンテキスト項目にバインドします。 

hive> SELECT xml_query_as_string("x/y", "<x><y>hello</y></x>") FROM src LIMIT 1;
     .
     .
     .
"hello"

次は、他のプリミティブ関数を使用する文字列バインディングの例です。

hive> SELECT xml_query_as_int("x/y", "<x><y>123</y></x>") FROM src LIMIT 1;
     .
     .
     .
123
 
hive> SELECT xml_query_as_double("x/y", "<x><y>12.3</y></x>") FROM src LIMIT 1;
     .
     .
     .
12.3
 
hive> SELECT xml_query_as_boolean("x/y", "<x><y>true</y></x>") FROM src LIMIT 1;
     .
     .
     .
true

例7-18 STRUCTバインディングの使用

次の例では、2番目の引数は、2つの問合せ変数$dataと$valueを定義するSTRUCTです。STRUCTの変数の値は、「データ型変換」で説明されているように、XMLスキーマ・タイプに変換されます。

hive>
SELECT xml_query_as_string(
   "fn:parse-xml($data)/x/y[@id = $value]", 
   struct(
      "data", "<x><y id='1'>hello</y><z/><y id='2'>world</y></x>",
      "value", 2
   )
) FROM src LIMIT 1;
     .
     .
     .
world

例7-19 複数の問合せ結果を返す例

次の例は、問合せから最初の項目(hello)のみを返します。2番目の項目(world)は破棄されます。

hive> SELECT xml_query_as_string("x/y", "<x><y>hello</y><z/><y>world</y></x>") FROM src LIMIT 1;
     .
     .
     .
hello

例7-20 空の問合せ結果を返す例

次の例は、問合せの結果が空であるためNULLを返します。 

hive> SELECT xml_query_as_string("x/foo", "<x><y>hello</y><z/><y>world</y></x>") FROM src LIMIT 1;
     .
     .
     .
NULL

例7-21 シリアライズされたXMLの取得

次の各例は、fn:serialize関数を使用して複雑なXML要素をSTRING値として返します。 

hive> SELECT xml_query_as_string("fn:serialize(x/y[1])", "<x><y>hello</y><z/><y>world</y></x>") FROM src LIMIT 1;
     .
     .
     .
"<y>hello</y>"

hive> SELECT xml_query_as_string(
   "fn:serialize(<html><head><title>{$desc}</title></head><body>Name: {$name}</body></html>)", 
   struct(
      "desc", "Employee Details",
      "name", "John Doe"
   )
) FROM src LIMIT 1;
...
<html><head><title>Employee Details</title></head><body>Name: John Doe</body></html>

例7-22 Hadoop分散キャッシュへのアクセス

次の例では、test.xmlという名前のファイルを分散キャッシュに追加し、fn:doc関数を使用してそれを問い合せます。ファイルには、次の値が格納されます。 

<x><y>hello</y><z/><y>world</y></x>

Hive> ADD FILE test.xml;
Added resource: test.xml
Hive> SELECT xml_query_as_string("fn:doc('test.xml')/x/y[1]", NULL) FROM src LIMIT 1;
     .
     .
     .
hello

例7-23 失敗した問合せの結果

次の例は、</invalidの山カッコがないためNULLを返します。XML解析エラーがログに書き込まれます。 

Hive> SELECT xml_query_as_string("x/y", "<x><y>hello</invalid") FROM src LIMIT 1;
     .
     .
     .
NULL

次の例は、fooをxs:floatとしてキャストできないためNULLを返します。キャスト・エラーがログに書き込まれます。 

Hive> SELECT xml_query_as_float("x/y", "<x><y>foo</y></x>") FROM src LIMIT 1;
     .
     .
     .
NULL

xml_table

XML値を表の1行以上の行にマップするか、または表の行にマップしないユーザー定義の表生成関数(UDTF)。この関数を使用すると、XMLのネストされた繰返し要素をHive表の行にマップできます。

シグネチャ

xml_table( 
   STRUCT? namespaces,
   STRING query, 
   {STRUCT | STRING} bindings,
   STRUCT? columns
)

説明

namespaces

問合せおよび列の式で使用できるネームスペースを指定します。オプション。

値は、偶数個のSTRINGフィールドで構成されるSTRUCTです。フィールドの各ペアで、問合せまたは列の式で使用されるネームスペース・バインディング(接頭辞, URI)が定義されます。例7-26を参照してください。

query

返される各値に対する表の行を生成するXQueryまたはXPath式。これは、関数が最初に評価されるときのみ読み込まれるため、定数値である必要があります。最初の問合せ文字列がコンパイルされ、後続のすべての呼出しで再使用されます。

問合せ処理時に動的エラーが発生した場合、関数でエラーは発生しませんが、最初はエラーがログに記録されます。後続の動的エラーはログに記録されません。

bindings

問合せで処理される入力。値は、XML STRINGまたは変数値のSTRUCTです。

  • STRING: 文字列は、問合せの初期コンテキスト項目にXMLとしてバインドされます。例7-24を参照してください。

  • STRUCT: 偶数個のフィールドで構成されるSTRUCT。フィールドの各ペアで、問合せの変数バインディング(名前, 値)が定義されます。名前フィールドのタイプはSTRINGである必要があり、値フィールドにはサポートされているプリミティブを指定できます。「データ型変換」を参照してください。

columns

生成される行の列を定義するXQueryまたはXPath式。オプション。

値は、追加のXQuery式を含むSTRUCTです。XQuery式は、関数が最初に評価されるときのみ読み込まれるため、定数のSTRING値である必要があります。STRUCTの各列式に対して、表に1つの列があります。

問合せで返される各項目に対して、式の初期コンテキスト項目として現在の項目で列式が評価されます。列式の結果はSTRING値に変換され、行の値になります。

列式の結果が空の場合、または列式の評価時に動的エラーが発生した場合、対応する列値はNULLです。列式で複数の項目が返される場合、最初の項目以外はすべて無視されます。

columns引数の省略は、'struct(".")'と指定することと同じです。例7-25を参照してください。

戻り値

query引数で返される各項目に対する1行の表の行。

ノート

XML表アダプタを使用すると、HDFSの大規模なXMLファイルに関するHive表を作成できます。「XML表に対するHiveのCREATE TABLE構文」を参照してください。

例

ノート:

xml_query_as_string関数を使用すると、この例で同じ結果を得ることができます。ただし、xml_tableは、単一の関数呼出しで3つの列値すべてを設定し、各行に対する入力XMLの解析が1回のみであるため、より効率的です。xml_query_as_string関数では、3つの列それぞれに対して別々の関数呼出しが必要であり、同じ入力XML値が毎回再解析されます。

例7-24 STRINGバインディングの使用

問合せ"x/y"は、2つの<y>要素を返すため、表の行が2行生成されます。2つの列式("./z", "./w")があるため、各行は2列です。 

hive> SELECT xml_table(
   "x/y",
   "<x>
      <y>
         <z>a</z>
         <w>b</w>
      </y>
      <y>
         <z>c</z>
      </y>
   </x>
   ",
   struct("./z", "./w")
 ) AS (z, w)
 FROM src;
     .
     .
     .
a        b
c        NULL

例7-25 columns引数の使用

次の2つの問合せは同等です。最初の問合せでは、columns引数の値が明示的に指定されています。 

hive> SELECT xml_table(
      "x/y",
      "<x><y>hello</y><y>world</y></x>",
      struct(".")
   ) AS (y)
   FROM src;
     .
     .
     .
hello
world

2番目の問合せではcolumns引数が省略されており、デフォルトでstruct(".")に設定されます。 

hive> SELECT xml_table(
      "x/y",
      "<x><y>hello</y><y>world</y></x>"
   ) AS (y)
   FROM src;
     .
     .
     .
hello
world

例7-26 namespaces引数の使用

次の例では、ns接頭辞とURI http://example.orgを指定する、オプションのnamespaces引数を指定します。 

hive> SELECT xml_table(
     struct("ns", "http://example.org"),
     "ns:x/ns:y",
     "<x xmlns='http://example.org'><y><z/></y><y><z/><z/></y></x>",
     struct("count(./ns:z)")
  ) AS (y)
  FROM src;
     .
     .
     .
1
2

例7-27 XMLドキュメントのHive表の問合せ

次の例では、タイプがSTRINGのXML_STRという単一の列がある、COMMENTS3表を問い合せます。次の3行が含まれています。 

hive> SELECT xml_str FROM comments3;

<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>
<comment id="54321" user="mike" text="Happy New Year!"><like user="laura"/></comment>

次の問合せは、COMMENTS3表からユーザー、テキストおよびlikeの数を抽出する方法を示しています。 

hive> SELECT t.id, t.usr, t.likes
     FROM comments3 LATERAL VIEW xml_table(
        "comment",
        comments.xml_str, 
        struct("./@id", "./@user", "fn:count(./like)")
     ) t AS id, usr, likes;

12345   john    0
56789   kelly   2
54321   mike    1

例7-28 ネストされたXML要素の表の行へのマッピング

次の例は、xml_tableを使用して、ネストされた繰返しXML要素を表の行にフラット化する方法を示しています。COMMENTS表は、前の例を参照してください。 

> SELECT t.i, t.u, t.l
    FROM comments3 LATERAL VIEW xml_table (
       "let $comment := ./comment
        for $like in $comment/like
        return
           <r>
              <id>{$comment/@id/data()}</id>
              <user>{$comment/@user/data()}</user>
              <like>{$like/@user/data()}</like>
           </r>
       ",
       comments.xml_str,
       struct("./id", "./user", "./like")
    ) t AS i, u, l;

56789   kelly   john
56789   kelly   mike
54321   mike    laura

例7-29 オプションのネストされたXML要素の表の行へのマッピング

次の例は、前の例を少し変更したもので、コメントにlikeがない場合でも行を生成します。COMMENTS表は、例7-27 を参照してください。 

> SELECT t.i, t.u, t.l
     FROM comments3 LATERAL VIEW xml_table (
        "let $comment := ./comment
         for $like allowing empty in $comment/like
         return 
            <r>
               <id>{$comment/@id/data()}</id>
               <user>{$comment/@user/data()}</user>
               <like>{$like/@user/data()}</like>
            </r>
        ",
        comments.xml_str, 
        struct("./id", "./user", "./like")
     ) t AS i, u, l;

12345   john
56789   kelly   john
56789   kelly   mike
54321   mike    laura

例7-30 新規ビューの作成

表生成関数と同じxml_tableを使用して、ビューおよび新規の表を作成できます。次の例では、COMMENTS表からCOMMENTS_LIKESという新しいビューを作成します。 

hive> CREATE VIEW comments_likes AS 
     SELECT xml_table(
        "comment", 
         comments.xml_str, 
         struct("./@id", "count(./like)")
     ) AS (id, likeCt)
     FROM comments;

次の例では、新しいビューを問い合せます。

> SELECT * FROM comments_likes
     WHERE CAST(likeCt AS INT) != 0;

56789   2
54321   1

例7-31 Hadoop分散キャッシュへのアクセス

fn:docおよびfn:unparsed-text関数を使用して、分散キャッシュに追加されたXMLドキュメントとテキスト・ファイルにアクセスできます。

次の例では、次の文字列を含むtest.xmlというファイルを問い合せます。

<x><y>hello</y><z/><y>world</y></x>

hive> ADD FILE test.xml;
Added resource: test.xml
hive> SELECT xml_table("fn:doc('test.xml')/x/y", NULL) AS y FROM src;
     .
     .
     .
hello
world