XMLTABLE
XMLTABLE 関数は、 XPath 式の評価から結果表を戻します。その際、場合によっては、指定された入力引数 を XPath 変数として使用します。行 XPath 式の結果シーケンスに 含まれる各項目が、結果表の 1 つの行を表します。
>>-XMLTABLE--(--+------------------------------+--row-xquery-expression-constant--> '-xmlnamespaces-declaration--,-' >--+--------------------------------------------------------+---> | .-,---------------------------. | | V (1) | | '-PASSING--+----------+----| row-xquery-argument |-----+-' '-BY VALUE-' >--+-----------------------------------------------------------------+--> | .-,--------------------------------------------------. | | V | | '-COLUMNS----+-| xml-table-regular-column-definition |--------+-+-' | (2) | '-| xml-table-ordinality-column-definition |-----' >--)----------------------------------------------------------->< row-xquery-argument |--+-xquery-context-item-expression---------------------------+--| '-xquery-variable-expression--AS--identifier--+----------+-' '-BY VALUE-' xml-table-regular-column-definition .-------------------------------------------------. V (3) | |--column-name--data-type--+----------+--------+-----------------------------------------+-+--| '-BY VALUE-' +-| default-clause |----------------------+ '-PATH--column-xquery-expression-constant-' xml-table-ordinality-column-definition |--column-name--FOR ORDINALITY----------------------------------|
注:
- xquery-context-item-expression は、複数回指定してはなりません。
- xml-table-ordinality-column-definition 文節は、複数回指定してはなりません。
- default-clause と PATH 節はどちらも複数回 指定することはできません。
関数名は修飾名として指定することはできません。
- xmlnamespaces-declaration
- XMLNAMESPACES 関数を使用して、1 つ以上の XML ネーム・スペース宣言を指定します。これは row-xquery-expression-constant および column-xquery-expression-constant の静的コンテキストの一部になります。XMLTABLE の引数である XPath 式の静的な既知のネーム・スペースの集合は、事前設定された静的な既知のネーム・スペースの集合と、この文節で指定されたネーム・スペース宣言を組み合わせたものです。XPath 式内の XPath プロローグはこれらのネーム・スペースをオーバーライドすることができます。
xmlnamespaces-declaration を指定しない場合は、事前設定された静的な既知のネーム・スペースの集合のみが XPath 式に適用されます。
- row-xquery-expression-constant
- サポートされる XPath 言語構文を使用して、XPath 式として解釈される SQL ストリング定数を指定します。 この式は、結果表の行数を決定します。row-xquery-argument で指定されたオプションの 1 組の入力 XML 値を使用して式を評価し、出力 XPath シーケンス (シーケンス内の各項目ごとに 1 行を生成) を戻します。シーケンスが空の場合、XMLTABLE の結果は空の表です。row-xquery-expression-constant に、空ストリングまたはすべてがブランクのストリングを指定してはいけません。
- PASSING
- 入力値、およびそれらの値を row-xquery-expression-constant で指定された XPath 式に渡す方法を指定します。
- BY VALUE
- すべての XML 引数が値によって受け渡されることを指定します。XML 値が
値によって受け渡される場合、XPath 評価は XML データのコピーを
使用します。これがデフォルトの動作です。
DB2® for
i は、XPath 変数式を、XML 入力値を表す文書ノードにバインド
します。
この節は、非 XML 値の受け渡し方法には 影響しません。非 XML 値は、常に、XML へのキャスト中に値のコピーを作成します。
- row-xquery-argument
- row-xquery-expression-constant により指定された XPath 式に渡される引数を指定します。
row-xquery-argument は、XPath 式に渡される前に評価される SQL 式を
指定します。
row-xquery-argument のデータ・タイプ が XML でない場合、式の結果は XML に変換されます。xquery-variable-expression の場合、 NULL 値は XML 空シーケンスに変換されます。
row-xquery-argument を XPath 式で使用する方法は、引数が xquery-context-item-expression または xquery-variable-expression のどちらとして指定されているかによって異なります。
row-xquery-argument には、 NEXT VALUE 式または PREVIOUS VALUE 式、あるいは OLAP 仕様を含めてはなりません。
- xquery-context-item-expression
- XML であるか、または XML への変換がサポートされているタイプの値を戻す、SQL 式
を指定します。
xquery-context-item-expression は row-xquery-expression の初期コンテキスト項目を指定します。 初期コンテキスト項目の値は、XML への変換後の xquery-context-item-expression の結果です。 xquery-context-item-expression は、複数回指定してはなりません。
- xquery-variable-expression
- 実行中に row-xquery-expression-constant により指定された XPath 式が使用できる値を持つ SQL 式を指定します。
この式は、XML であるか、または XML への変換がサポートされているタイプの値を戻す
必要があります。
xquery-variable-expression は、row-xquery-expression-constant に XPath 変数として渡される引数を指定します。xquery-variable-expression が NULL 値である場合、XPath 変数は XML 空シーケンスに設定されます。PASSING 文節から作成された XPath 変数の有効範囲は、row-xquery-expression-constant で指定される XPath 式です。
- AS identifier
- xquery-variable-expression により生成された値が、row-xquery-expression-constant に XPath 変数として渡されることを指定します。 identifier が示す名前は、XML NCName の形式でなければ なりません。有効な名前についての詳細は、W3C XML ネーム・スペースの指定の項目を参照してください。XPath 言語で変数名の前に置かれる先行ドル記号 ($) を identifier の一部として含めてはなりません。 この ID の長さは 128 バイトを超えてはなりません。同じ PASSING 文節内の 2 つの引数が同じ ID を使用することはできません。
- BY VALUE
- xquery-variable-expression が値によって受け渡されることを 指定します。XML 値が 値によって受け渡される場合、XPath 評価は XML データのコピーを 使用します。DB2 for i は、XPath 変数式を、XML 入力値を表す文書ノードにバインド します。BY VALUE が xquery-variable-expression に続いて指定されない場合、XML 引数は、PASSING キーワードに続く構文により提供されるデフォルトの受け渡しメカニズムを使用して渡されます。
- この節は、入力値が XML データ・タイプの場合のみ有効です。 非 XML 値は、常に、XML へのキャスト中に値のコピーを作成します。
表 1. SQL から XML へのサポートされる変換 SQL タイプ XML タイプ 注意 SMALLINT xs:integer INTEGER xs:integer BIGINT xs:integer DECIMAL
NUMERICxs:decimal 精度が 34 より大きい 10 進数の場合、処理中に精度が失われる可能性があります。 FLOAT
DOUBLE
DECFLOATxs:double CHAR
VARCHAR
CLOB
GRAPHIC
VARGRAPHIC
DBCLOBxs:string 文字ストリング値を XML 値にキャストする場合、結果の xs:string アトミック値は正しくない XML 文字を含むことができません。入力文字ストリングが Unicode でない場合、入力文字は Unicode に変換されます。 CHAR ストリングおよび VARCHAR ストリング では、CCSID を 65535 にすることはできず、ビット・データ用に指定することもできません。
DATE xs:date xs:date 値にはタイム・ゾーン・コンポーネントは含まれません。 比較のため、タイム・ゾーンは暗黙的に UTC であると想定されます。 必要 な場合、fn:adjust-timezone() 関数を使用してタイム・ゾーンを明示的に設定できます。
TIME xs:time xs:time 値にはタイム・ゾーン・コンポーネントは含まれません。 比較のため、タイム・ゾーンは暗黙的に UTC であると想定されます。 必要 な場合、fn:adjust-timezone() 関数を使用してタイム・ゾーンを明示的に設定できます。
TIMESTAMP xs:dateTime xs:dateTime 値にはタイム・ゾーン・コンポーネントは 含まれません。比較のため、タイム・ゾーンは暗黙的に UTC であると想定されます。 必要 な場合、fn:adjust-timezone() 関数を使用してタイム・ゾーンを明示的に設定できます。
- COLUMNS
- 列名、データ・タイプ、および各行の列値の計算方法を組み込んで、結果表の出力列を指定します。この節を指定しない場合は、
タイプが XML の単一の無名列が戻され、その値は row-xquery-expression 内の XPath 式の評価から得られるシーケンス項目に
基づきます (PATH '.' を指定することと同等です)。この結果列を参照するには、表関数の後に続く correlation-clause で column-name を指定する必要があります。
すべての結果列の長さの合計 は 64K バイトを超えてはなりません。データ・タイプごとの列のバイト・カウントについて は、最大行サイズを参照してください。row-xquery-arguments の数が N であるとすると、
列の数は 8000-N 以下でなければなりません。
- xml-table-regular-column-definition
- 列名、データ・タイプ、およびその行のシーケンス項目から値を抽出するための XPath 式を組み込んで、結果表の 1 つの出力列を指定します。
- column-name
- 結果表の列の名前を指定します。名前を修飾することはできず、結果表の複数の列に対して同じ名前を使用することはできません。
- data-type
- 列のデータ・タイプを指定します。CHAR 列および VARCHAR 列の場合、CCSID を 65535 にすることはできません。
- BY VALUE
- 結果列が値によって戻されることを指定します。XML 値が 値によって戻される場合、XML データのコピーが戻されます。 これがデフォルトの動作です。 DB2 for i は、値が表関数から戻されると、XML 結果の文書ノードを作成 します。この節は、データ・タイプが XML ではない列に対して 指定してはなりません。
- default-clause
- 列のデフォルト値を指定します。XMLTABLE 結果列の場合、column-xquery-expression-constant に含まれる XPath 式の処理が空のシーケンスを戻す場合は、デフォルトが適用されます。
- PATH column-xquery-expression-constant
- サポートされる XPath 言語構文を使用して、XPath 式として解釈されるストリング定数を指定します。
column-xquery-expression-constant は XPath 式を指定しますが、これは row-xquery-expression-constant 内の XPath 式の評価の結果である項目に関連して列値を決定します。
row-query-expression-constant の処理の結果得られた項目が外部提供のコンテキスト項目として入力されると、column-xquery-expression-constant が評価されて、出力シーケンスが戻されます。この出力シーケンスに基づいて、列値は以下のように決定されます。
- 空シーケンスが戻される場合、default-clause が列の値を提供します。
- 空のシーケンスが戻され、default-clause が指定されていない場合、列には NULL 値が割り当てられます。
- 空でないシーケンスが戻される場合、値は列に対して指定されたデータ・タイプに変換されます。この暗黙的な変換 処理からエラーが戻される可能性があります。
column-xquery-expression-constant の値は、空ストリングまたはすべてがブランクのストリングであってはなりません。この節が指定されない場合、デフォルトの XPath 式は column-name になります。
- xml-table-ordinality-column-definition
- 結果表の順序を示す列を指定します。
- colum-name
- 結果表の列の名前を指定します。名前を修飾することはできず、結果表の複数の列に対して同じ名前を使用することはできません。
- FOR ORDINALITY
- column-name は結果表の順序を示す列であることを指定します。この列のデータ・タイプは BIGINT です。結果表のこの列の値は、row-xquery-expression-constant 内の XPath 式を評価した結果シーケンスにおける行の項目の順序番号です。
| XML タイプ | SQL タイプ | 注意 |
|---|---|---|
| xs:integer | SMALLINT |
|
| xs:decimal | DECIMAL |
結果の xs:decimal 値は、必要に応じて、 ターゲット・データ・タイプの精度と位取りに変換されます。必要な数の先行ゼロが追加または除去されます。数字の小数部分では、必要な数の後続ゼロが追加されるか、必要な桁数が除去されます。この切り捨て動作は、DECIMAL から DECIMAL へのキャストの動作と同様です。精度が 34 より大きい 10 進数の場合、処理中に精度が失われる可能性があります。 |
| xs:double | FLOAT |
ターゲット・タイプが FLOAT、DOUBLE、または REAL で、 XPath キャストの後のソース XML 値が、INF、-INF、または Nan の xs:double 値 である場合、エラーが戻されます。ソース値が xs:double の負のゼロの場合、値は正のゼロに変換されます。ソース値がターゲット・データ・タイプの範囲を超える場合、オーバーフロー・エラーが戻されます。ソース値にターゲット・データ・タイプの精度を超える有効数字が含まれている場合、ソース値はターゲット・データ・タイプの精度に丸められます。 ターゲット・タイプが DECFLOAT で、ソース XML 値が INF、-INF、または NaN の xs:double 値である場合、結果は対応する特殊 DECFLOAT 値 INF、-INF、または NaN になります。ソース値が xs:double の負のゼロの場合、結果は負のゼロです。ターゲット・タイプが DECFLOAT(16) で、ソース値が DECFLOAT(16) の範囲を超える場合、オーバーフロー・エラーが戻されます。 ソース値の有効数字が 16 桁を超える場合、値は有効な ROUNDING モードに従って丸められます。丸めの動作は、DECFLOAT(34) から DECFLOAT(16) へのキャスト時に使用されるものと同じです。 |
| xs:string | CHAR |
結果の XML 値は、必要に応じて、限定された長さのターゲット・タイプに変換される前に、 割り当ての際の変換規則に説明されている規則を 使用してターゲット・データ・タイプの CCSID に変換されます。指定された長さの制限が CCSID 変換後のストリングの長さより短い場合、切り捨てが行われます。非ブランク文字が切り捨てられる場合は、警告が出されます。ターゲット・タイプが固定長ストリング・タイプ (CHAR または GRAPHIC) であり、ターゲット・タイプの指定の長さが CCSID 変換後のストリングの長さより長い場合、末尾にブランクが埋め込まれます。 この切り捨ておよび埋め込みの動作は、文字ストリングまたはグラフィック・ストリングの取り出し割り当てと同様です。 |
| xs:date | DATE | 結果の XML 値は UTC 時間に調整され、タイム・ゾーン・コンポーネントは除去 されます。結果の xs:date 値の年の部分 は 0001 から 9999 の範囲内でなければなりません。 |
| xs:time | TIME | 結果の XML 値は UTC 時間に調整され、タイム・ゾーン・コンポーネントは除去 されます。小数秒は結果から切り捨てられます。 |
| xs:dateTime | TIMESTAMP | 結果の XML 値は UTC 時間に調整され、タイム・ゾーン・コンポーネントは除去 されます。結果の xs:dateTime 値 の年の部分は 0001 から 9999 までの範囲内でなければなりません。ターゲットの タイム・スタンプ・タイプの精度が 12 より小さい場合、xs:dateTime 値の小数秒の部分は、ターゲットのタイム・スタンプの精度までに 切り捨てられます。 |
この関数の結果は表です。いずれかの XPath 式の評価結果が
エラーになる場合、XMLTABLE 関数は XPath エラーを戻します。
例
- 以下は、注文の購入注文項目で状況が「NEW」の結果である表のリストです。
SELECT U."PO ID", U."Part #", U."Product Name", U."Quantity", U."Price", U."Order Date" FROM PURCHASEORDER P, XMLTABLE(XMLNAMESPACES('http://podemo.org' AS "pod"), '$po/PurchaseOrder/itemlist/item' PASSING P.PORDER AS "po" COLUMNS "PO ID" INTEGER PATH '../../@POid', "Part #" CHAR(6) PATH 'product/@pid', "Product Name" CHAR(50) PATH 'product/pod:name', "Quantity" INTEGER PATH 'quantity', "Price" DECIMAL(9,2) PATH 'product/pod:price', "Order Date" TIMESTAMP PATH '../../dateTime' ) AS U WHERE P.STATUS = 'NEW'