XMLTABLE 表関数

場合によっては指定した入力引数を XQuery 変数として使用して、XMLTABLE 関数は結果表を XQuery 式の評価から戻します。行 XQuery 式の結果シーケンス内の各シーケンス項目は、結果表の行を表しています。

スキーマは SYSIBM です。関数名を修飾名で指定することはできません。

xmlnamespaces-宣言row-xquery-expression-constant および column-xquery-expression-constant の静的コンテキストの一部になる、1 つ以上の XML 名前空間宣言を指定します。 XMLTABLE の引数である XQuery 式の静的に認識される名前空間のセットは、事前設定された静的に認識される名前空間のセットと、この節で指定された名前空間宣言を組み合わせたものです。 XQuery 式内の XQuery プロローグは、これらの名前空間をオーバーライドする場合があります。

xmlnamespaces-declaration を指定しない場合、事前設定された静的に認識される名前空間のセットだけが XQuery 式に適用されます。

row-xquery-expression-constant (row-xquery-expression-constant)サポートされる XQuery 言語構文を使用して、XQuery 式として解釈される SQL 文字ストリング定数を指定します。定数ストリングは、データベース・コード・ページまたはセクション・コード・ページに変換されることなく、UTF-8 に直接変換されます。 XQuery 式は、オプション・セットの入力 XML 値を使用して実行し、シーケンス内の各項目についての行が生成される出力 XQuery シーケンスを戻します。 row-xquery-expression-constant の値は、空ストリングまたはすべてがブランクのストリングにすることはできません (SQLSTATE 10505)。

PASSING

入力値、およびそれらの値を row-xquery-expression-constant で指定された XQuery 式に渡す方法を指定します。デフォルトでは、関数が呼び出された有効範囲内にあるすべての固有の列名が、列の名前を変数名として使用して XQuery 式に暗黙的に渡されます。指定の row-xquery-argument 内の identifier が有効範囲内の列名と一致する場合、明示的な row-xquery-argument はその暗黙的な列をオーバーライドして XQuery 式に渡されます。

BY REF

デフォルトでは XML 入力引数を参照により渡すことを指定します。 XML 値を参照で渡す場合、XQuery の評価は、入力ノード・ツリーがあればそれを使用します。その場合は指定された入力式から直接、元のノードの ID および文書順序を含めすべてのプロパティーを保持したまま使用します。 2 つの引数が同じ XML 値を渡す場合、その 2 つの入力引数の間に含まれている何らかのノードに関係するノード ID 比較および文書順序比較は、同じ XML ノード・ツリー内のノードを参照する場合があります。

この節は、非 XML 値の受け渡しには影響を与えません。非 XML 値は、XML へのキャスト中に値の新規コピーを作成します。

row-xquery-argument

row-xquery-expression-constant により指定された XQuery 式に渡される引数を指定します。 row-xquery-argument を XQuery 式で使用する方式は、引数が xquery-context-item-expression または xquery-variable-expression のどちらとして指定されているかによって異なります。

結果の値は、XML 型である場合、input-xml-value になります。 NULL の XML 値は、XML の空シーケンスに変換されます。
結果の値は、XML 型でない場合、XML データ・タイプにキャスト可能でなければなりません。 NULL 値は、XML の空シーケンスに変換されます。変換される値は、input-xml-value になります。

row-xquery-expression-constant が評価されるとき、XQuery 変数は input-xml-value と等しい値、および AS 節により指定された名前で示されます。

XML、整数、10 進数、文字ストリング、または GRAPHIC ストリング (後者 2 つは LOB 以外) である値を返す式。 xquery-context-item-expression は、ビット・データの文字ストリングであってはなりません。; xquery-context-item-expression は row-xquery-expression の初期コンテキスト項目を指定します。初期コンテキスト項目の値は、XML への xquery-context-item-expression キャストの結果です。 xquery-context-item-expression は、複数回指定してはなりません。; 実行中に row-xquery-expression-constant により指定された XQuery 式が使用できる値を持つ SQL 式を指定します。式には、NEXT VALUE 式、PREVIOUS VALUE 式 (SQLSTATE 428F9)、または OLAP 関数 (SQLSTATE 42903) を含めることはできません。式のデータ・タイプを DECFLOAT にすることはできません。
AS identifier: xquery-variable-expression により生成された値が、row-xquery-expression-constant に XQuery 変数として渡されることを指定します。変数名は identifier になります。 XQuery 言語の変数名に先行する先頭のドル記号 ($) は、identifier には含められません。 identifier は有効な XQuery 変数名でなければならず、XML NCName に制限されます。 identifier は、長さが 128 バイトを超えてはなりません。同じ PASSING 節内の 2 つの引数が同じ identifier を使用することはできません (SQLSTATE 42711)。
BY REF: XML 入力値が参照により渡されるように指示します。 XML 値を参照で渡す場合、XQuery の評価は、入力ノード・ツリーがあればそれを使用します。その場合は指定された入力式から直接、元のノードの ID および文書順序を含めすべてのプロパティーを保持したまま使用します。 2 つの引数が同じ XML 値を渡す場合、その 2 つの入力引数の間に含まれている何らかのノードに関係するノード ID 比較および文書順序比較は、同じ XML ノード・ツリー内のノードを参照する場合があります。 BY REF が xquery-expression-variable に続いて指定されない場合、XML 引数は、PASSING キーワードに続く構文により提供されるデフォルトの受け渡しメカニズムによって渡されます。このオプションは、非 XML 値に指定することはできません (SQLSTATE 42636)。非 XML 値が渡される場合、値は XML に変換されます。このプロセスによりコピーが作成されます。

COLUMNS

結果表の出力列を指定します。この節が指定されない場合、row-xquery-expression-constant 内の XQuery 式を評価して得られたシーケンス項目に基づく値が指定されて、データ・タイプ XML の単一の無名列が参照によって戻されます (PATH '.' を指定した場合と同じ結果になります)。結果列を参照するには、関数に続く correlation-clause に column-name が指定されている必要があります。

xml-table-regular-column-definition結果表の出力列を指定します。これには列名、データ・タイプ、XML 受け渡しメカニズム、および行のシーケンス項目から値を抽出する XQuery 式が含まれます。

column-name結果表の列の名前を指定します。名前を修飾したり、表の複数の列に対して同じ名前を使用することはできません (SQLSTATE 42711)。

data-type列のデータ・タイプを指定します。使用可能な型の構文および説明については、CREATE TABLE を参照してください。 data-type は、XML データ・タイプから、指定された data-type へのサポートされる XMLCAST がある場合に、XMLTable で使用できます。

BY REF

XML 値を、データ・タイプ XML の列の参照により戻すことを指定します。デフォルトでは、XML 値は BY REF により戻されます。 XML 値を参照で戻す場合、XML 値は、入力ノード・ツリーがあればそれを組み込みます。その場合は結果の値から直接、元のノードの ID および文書順序を含めすべてのプロパティーを保持したまま組み込みます。このオプションは、非 XML 列に指定することはできません (SQLSTATE 42636)。非 XML 列が処理される場合、値は XML から変換されます。このプロセスによりコピーが作成されます。

デフォルト節列のデフォルト値を指定します。 default-clause の構文および説明については、CREATE TABLE を参照してください。 XMLTABLE 結果列の場合、column-xquery-expression-constant に含まれる XQuery 式の処理が空のシーケンスを戻す場合は、デフォルトが適用されます。

PATH 列-xquery-式-定数

サポートされる XQuery 言語構文を使用して、XQuery 式として解釈される SQL 文字ストリング定数を指定します。定数ストリングは、データベース・コード・ページまたはセクション・コード・ページに変換されることなく、UTF-8 に直接変換されます。 column-xquery-expression-constant は XQuery 式を指定しますが、これは row-xquery-expression-constant 内の XQuery 式の評価の結果である項目に関連して列値を決定します。外部で提供されたコンテキスト項目として row-xquery-expression-constant の処理の結果による項目がある場合、column-xquery-expression-constant が評価され、出力シーケンスが戻されます。列値は、以下のようにこの出力シーケンスに基づいて決定されます。

出力シーケンスに含まれている項目がゼロの場合、default-clause は列の値を提供します。
空のシーケンスが戻され、default-clause が指定されていない場合、NULL 値が列に割り当てられます。
空でないシーケンスが戻される場合、値は列に指定された data-type に対する XMLCAST です。この XMLCAST の処理によりエラーが戻される場合があります。

column-xquery-expression-constant の値は、空ストリングまたはすべてがブランクのストリングにすることはできません (SQLSTATE 10505)。この節が指定されない場合、デフォルトの XQuery 式は単に column-name になります。

xml-table-ordinality-column-definition結果表の順序を示す列を指定します。

column-name

結果表の列の名前を指定します。名前を修飾したり、表の複数の列に対して同じ名前を使用することはできません (SQLSTATE 42711)。

順序性の場合

column-name が結果表の順序を示す列になるように指定します。この列のデータ・タイプは BIGINT です。結果表のこの列の値は、row-xquery-expression-constant 内の XQuery 式を評価した結果シーケンスにおける行の項目の順序番号です。

いずれかの XQuery 式の評価の結果がエラーになる場合、XMLTABLE 関数は XQuery エラーを戻します (SQLSTATE クラス '10')。

例

以下は、注文の購入注文項目で状況が「NEW」の結果である表のリストです。

   SELECT U."PO ID", U."Part #", U."Product Name", 
        U."Quantity", U."Price", U."Order Date"
     FROM PURCHASEORDER P,
        XMLTABLE('$po/PurchaseOrder/item' PASSING P.PORDER AS "po"
                 COLUMNS "PO ID"         INTEGER       PATH '../@PoNum',
                         "Part #"        CHAR(10)      PATH 'partid',
                         "Product Name"  VARCHAR(50)   PATH 'name',
                         "Quantity"      INTEGER       PATH 'quantity',
                         "Price"         DECIMAL(9,2)  PATH 'price',
                         "Order Date"    DATE          PATH '../@OrderDate'
                 ) AS U
      WHERE P.STATUS = 'Unshipped'