XMLELEMENT スカラー関数
XMLELEMENT 関数は、XQuery エレメント・ノードである XML 値を戻します。
スキーマは SYSIBM です。 関数名を修飾名で指定することはできません。
- NAME エレメント名
- XML エレメントの名前を指定します。 この名前は SQL ID であり、XML 修飾名の形式かまたは QName でなければなりません (SQLSTATE 42634)。 有効な名前の詳細については、 W3C XML namespace specifications を参照してください。 名前が修飾される場合は、名前空間の接頭部をその有効範囲内で宣言する必要があります (SQLSTATE 42635)。 xmlnamespaces-宣言
- XMLNAMESPACES 宣言の結果である XML 名前空間宣言を指定します。 宣言される名前空間は、XMLELEMENT 関数の有効範囲内です。 この名前空間は、それらが別の副選択内に現れるかどうかに関係なく、XMLELEMENT 関数内のネストされた XML 関数に適用されます。
xmlnamespaces-declaration が指定されない場合、名前空間宣言は構成されたエレメントとは関連付けられません。
xmlattributes-関数 - エレメントの XML 属性を指定します。 この属性は、XMLATTRIBUTES 関数の結果です。 エレメント内容式 (element-content-expression)
- 生成される XML エレメント・ノードの内容を、式によって、または式リストによって指定します。 element-content-expression のデータ・タイプを BINARY タイプ、VARBINARY タイプ、または構造化タイプにすることはできません (SQLSTATE 42884)。 式には任意の SQL 式を指定できます。
element-content-expression を指定しない場合、空ストリングがエレメントの内容として使用され、OPTION NULL ON NULL または EMPTY ON NULL は指定できません。
- OPTION
- XML エレメントを構成するための追加オプションを指定します。 OPTION 節を指定しない場合、デフォルトは EMPTY ON NULL XMLBINARY USING BASE64 です。 この節は、 element-content-expressionで指定されたネストされた XMLELEMENT 呼び出しには影響しません。
- EMPTY ON NULL または NULL ON NULL
- 各 element-content-expression の値が NULL 値の場合に NULL 値を戻すか、あるいは空エレメントを戻すかを指定します。 このオプションはエレメントの内容の NULL 処理にのみ影響し、属性値の NULL 処理には影響を及ぼしません。 デフォルトは EMPTY ON NULL です。
- EMPTY ON NULL
- それぞれの element-content-expression の値が NULL であれば、空のエレメントが戻されます。
- NULL ON NULL
- それぞれの element-content-expression の値が NULL であれば、NULL 値が戻されます。
- XMLBINARY USING BASE64 または XMLBINARY USING HEX
- バイナリー入力データ、FOR BIT DATA 属性を持つ文字ストリング・データ、またはこれらのタイプのいずれかに基づく特殊タイプの想定エンコードを指定します。 エンコードはエレメントの内容または属性値に適用されます。 デフォルトは XMLBINARY USING BASE64 です。
- XMLBINARY USING BASE64
- 想定エンコードが Base64 文字である (XML スキーマ・タイプ xs:base64Binary のエンコードに対して定義される) ことを指定します。 Base64 エンコードは、US-ASCII の 65 文字のサブセット (10 個の数字、26 個の小文字、26 個の大文字、'+' および '/') を使用して、サブセット内の 1 つの印刷可能文字により、バイナリーまたはビット・データのすべての 6 ビットを表します。 文字を普遍的に表せるようにこれらの文字が選ばれています。 この方法を使うと、エンコード・データのサイズが元のバイナリーまたはビット・データより 33 % 大きくなります。
- XMLBINARY USING HEX
- 想定エンコードが 16 進文字である (XML スキーマ・タイプ xs:hexBinary のエンコードに対して定義される) ことを指定します。 16 進数エンコードは、各バイト (8 ビット) を 2 つの 16 進文字で表します。 この方法を使うと、エンコード・データが元のバイナリーまたはビット・データの 2 倍のサイズになります。
この関数は、エレメント名、オプションの名前空間宣言の集合、オプションの属性の集合、および XML エレメントの内容を構成するゼロ個以上の引数をとります。 この結果は、XML エレメント・ノードを含む XML シーケンスまたは NULL 値です。
結果のデータ・タイプは XML です。 いずれかの element-content-expression 引数が NULL の可能性がある場合、結果も NULL になる可能性があります。すべての element-content-expression 引数値が NULL で NULL ON NULL オプションが有効になっている場合、結果は NULL 値になります。
注
- デフォルトの名前空間を定義する別のエレメントの内容としてコピーされるエレメントを構成する場合、デフォルトの名前空間はコピーされたエレメント内で明示的に宣言解除する必要があります。これは、新規の親エレメントからデフォルトの名前空間を継承した結果として生じる可能性のあるエラーを避けるためです。 事前定義名前空間接頭部 (「xs」、「xsi」、「xml」、および「sqlxml」) をその使用時に明示的に宣言する必要もあります。
- エレメント・ノードの構成: 結果のエレメント・ノードは以下のように構成されます。
- xmlnamespaces-declaration は、構成されたエレメントの有効範囲内の名前空間のセットを追加します。 それぞれの有効範囲内の名前空間は、名前空間接頭部 (またはデフォルトの名前空間) を、名前空間 URI と関連付けます。 有効範囲内の名前空間は、エレメントの有効範囲内の QNames の解釈に使用できる名前空間接頭部のセットを定義します。
- xmlattributes-function を指定した場合、それが評価され、結果は属性ノードのシーケンスになります。
- それぞれの element-content-expression は評価され、結果は以下のようにノードのシーケンスに変換されます。
- 結果タイプが XML でない場合、結果タイプは XML テキスト・ノードに変換されます。その内容は、SQL データ値から XML データ値へのマッピング (
データ・タイプ間のキャスト
の非 XML 値から XML 値へのサポートされるキャストを示す表を参照) の規則に従って XML にマップされた element-content-expression の結果です。 - 結果タイプが XML である場合、一般に結果は項目のシーケンスになります。 そのシーケンス内のいくつかの項目は、文書ノードである場合があります。 シーケンス内の各文書ノードは、その最上位の子のシーケンスによって置き換えられます。 次いで結果のシーケンス内の各ノードに対して、その子と属性を組み込んだノードの新しいディープ・コピーが構成されます。 コピーされた各ノードは、新しいノード ID を持ちます。 コピーされたエレメントおよび属性ノードは、それぞれのタイプのアノテーションを保持します。 シーケンス内で戻される 1 つ以上の原子値の隣接する各シーケンスごとに、新規テキスト・ノードが構成され、隣接値の間に単一ブランク文字が挿入された、ストリングに対する各原子値のキャストの結果が含まれます。 内容のシーケンス内の隣接するテキスト・ノードは、ブランクを間に挟まずにその内容を連結して単一のテキスト・ノードにマージされます。 連結後に、内容がゼロ長ストリングであるテキスト・ノードは、内容のシーケンスから削除されます。
- 結果タイプが XML でない場合、結果タイプは XML テキスト・ノードに変換されます。その内容は、SQL データ値から XML データ値へのマッピング (
- XML 属性の結果のシーケンス、およびすべての element-content-expression 指定の結果のシーケンスは、内容シーケンスと呼ばれる 1 つのシーケンスに連結されます。 内容シーケンス内の隣接するテキスト・ノードのすべてのシーケンスは、単一のテキスト・ノードにマージされます。 すべての element-content-expression 引数が空ストリングである場合、または element-content-expression 引数が指定されていない場合、空のエレメントが戻されます。
- 内容シーケンスには、属性ノードではないノードに続けて属性ノードを含めることはできません (SQLSTATE 10507)。 内容シーケンス内の属性ノードは、新規エレメント・ノードの属性になります。 これらの属性ノードの複数が同じ名前を持つことはできません (SQLSTATE 10503)。 名前空間 URI が、構成されたエレメントの有効範囲内名前空間にない場合、名前空間宣言は、属性ノードの名前で使用されるすべての名前空間に対応して作成されます。
- 内容シーケンス内のエレメント、テキスト、コメント、および処理命令ノードは、構成されたエレメント・ノードの子になります。
- 構成されたエレメント・ノードには
xs:anyType
のタイプ・アノテーションが付与され、その各属性にはxdt:untypedAtomic
のタイプ・アノテーションが付与されます。 構成されたエレメント・ノードのノード名は、NAME キーワードの後に指定された element-name です。
- XMLELEMENT 内でのネーム・スペースの使用規則: ネーム・スペースの有効範囲に関する以下の規則を考慮してください。
- XMLNAMESPACES 宣言 で宣言されるネーム・スペースは、XMLELEMENT 関数によって構成されるエレメント・ノードの有効範囲内ネーム・スペースです。 エレメント・ノードが直列化される場合、そのそれぞれの有効範囲内名前空間は名前空間属性として直列化されます。ただしこれは、エレメント・ノードの親の有効範囲内名前空間であったり、親エレメントも直列化されていたりするのではない場合に限ります。
- XMLQUERY または XMLEXISTS が element-content-expression にある場合、名前空間は XMLQUERY または XMLEXISTS の XQuery 式の静的に既知の名前空間になります。 静的に既知の名前空間は、XQuery 式内の QNames を解決するために使用されます。 XQuery プロローグが、XQuery 式の有効範囲内で、同じ接頭部を持つ名前空間を宣言する場合、プロローグ内で宣言される名前空間は、XMLNAMESPACES 宣言内で宣言された名前空間をオーバーライドします。
- 構成されたエレメントの属性が element-content-expression に由来するものである場合、その名前空間は構成されたエレメントの有効範囲内名前空間としてまだ宣言されていない可能性があり、その場合には、それに対して新規名前空間が作成されます。 この結果として競合が生じる場合、つまり属性名の接頭部が、別の URI に有効範囲内名前空間によってバインド済みである場合は、そのような競合を生じさせない接頭部が生成され、属性名で使用されている接頭部はその新規接頭部に変更され、その新規接頭部に対して名前空間が作成されます。 生成される新規接頭部は、「db2ns-xx」というパターンに従います。ここで x は、A から Z、a から z、0 から 9 の範囲から選択された文字です。 以下に例を示します。
これは、以下のものを戻します。VALUES XMLELEMENT( NAME "c", XMLQUERY( 'declare namespace ipo="www.ipo.com"; $m/ipo:a/@ipo:b' PASSING XMLPARSE( DOCUMENT '<tst:a xmlns:tst="www.ipo.com" tst:b="2"/>' ) AS "m" ) )
2 番目の例は、以下のようなものです。<c xmlns:tst="www.ipo.com" tst:b="2"/>
これは、以下のものを戻します。VALUES XMLELEMENT( NAME "tst:c", XMLNAMESPACES( 'www.tst.com' AS "tst" ), XMLQUERY( 'declare namespace ipo="www.ipo.com"; $m/ipo:a/@ipo:b' PASSING XMLPARSE( DOCUMENT '<tst:a xmlns:tst="www.ipo.com" tst:b="2"/>' ) AS "m" ) )
<tst:c xmlns:tst="www.tst.com" xmlns:db2ns-a1="www.ipo.com" db2ns-a1:b="2"/>
例
注: XMLELEMENT は、出力にブランク・スペースや改行文字を挿入しません。 例の出力はすべて、読みやすくするために書式を整えています。
- 例 1: エレメントを NULL ON NULL オプションを使用して構成します。
この照会は、次のような結果を生成します。SELECT E.FIRSTNME, E.LASTNAME, XMLELEMENT( NAME "Emp", XMLELEMENT( NAME "firstname", E.FIRSTNME ), XMLELEMENT( NAME "lastname", E.LASTNAME ) OPTION NULL ON NULL ) AS "Result" FROM EMPLOYEE E WHERE E.EDLEVEL = 12
FIRSTNME LASTNAME Emp JOHN PARKER <Emp><firstname>JOHN</firstname> <lastname>PARKER</lastname></Emp> MAUDE SETRIGHT <Emp><firstname>MAUDE</firstname> <lastname>SETRIGHT</lastname></Emp> MICHELLE SPRINGER <Emp><firstname>MICHELLE</firstname> <lastname>SPRINGER</lastname></Emp>
- 例 2: 子エレメントとしてネストしたエレメントのリストを使用してエレメントを生成します。
この照会は、次のような結果を生成します。SELECT XMLELEMENT( NAME "Department", XMLATTRIBUTES( E.WORKDEPT AS "name" ), XMLAGG( XMLELEMENT( NAME "emp", E.FIRSTNME ) ORDER BY E.FIRSTNME ) ) AS "dept_list" FROM EMPLOYEE E WHERE E.WORKDEPT IN ('A00', 'B01') GROUP BY WORKDEPT
dept_list <Department name="A00"> <emp>CHRISTINE</emp> <emp>SEAN</emp> <emp>VINCENZO</emp> </Department> <Department name="B01"> <emp>MICHAEL</emp> </Department>
- 例 3: デフォルトの XML エレメント名前空間を指定し、副選択を使用して、ネストされた XML エレメントを作成します。
このステートメントは、以下のような、ルート・エレメント内でデフォルト・エレメント名前空間が宣言された XML 文書を戻します。SELECT XMLELEMENT( NAME "root", XMLNAMESPACES(DEFAULT 'http://mytest.uri'), XMLATTRIBUTES(cid), (SELECT XMLAGG( XMLELEMENT( NAME "poid", poid ) ) FROM purchaseorder WHERE purchaseorder.custid = customer.cid ) ) FROM customer WHERE cid = '1002'
<root xmlns="http://mytest.uri" CID="1002"> <poid>5000</poid> <poid>5003</poid> <poid>5006</poid> </root>
- 例 4: XML 名前空間を指定した共通表式を使用します。共通表式を使用して XML エレメントを構成する際に、このエレメントを同じ SQL ステートメント内の他の場所で使用する場合は、エレメントの構成の一部として名前空間宣言を指定する必要があります。 以下のステートメントは、PURCHASEORDER 表を使用して poid エレメントを作成する共通表式と、CUSTOMER 表を使用してルート・エレメントを作成する SELECT ステートメントの両方でデフォルトの XML 名前空間を指定します。
このステートメントは、以下のような、ルート・エレメント内でデフォルト・エレメント名前空間が宣言された XML 文書を戻します。WITH tempid(id, elem) AS (SELECT custid, XMLELEMENT(NAME "poid", XMLNAMESPACES(DEFAULT 'http://mytest.uri'), poid) FROM purchaseorder ) SELECT XMLELEMENT(NAME "root", XMLNAMESPACES(DEFAULT 'http://mytest.uri'), XMLATTRIBUTES(cid), (SELECT XMLAGG(elem) FROM tempid WHERE tempid.id = customer.cid ) ) FROM customer WHERE cid = '1002'
<root xmlns="http://mytest.uri" CID="1002"> <poid>5000</poid> <poid>5003</poid> <poid>5006</poid> </root>
以下のステートメントでは、CUSTOMER 表を使用してルート・エレメントを作成する SELECT ステートメントのみでデフォルト・エレメント名前空間が宣言されています。
このステートメントは、以下のような、ルート・エレメント内でデフォルト・エレメント名前空間が宣言された XML 文書を戻します。 poid エレメントはデフォルト・エレメント名前空間宣言のない共通表式内で作成されるので、poid エレメントのデフォルト・エレメント名前空間は定義されません。 XML 文書では、poid エレメントのデフォルト・エレメント名前空間は空ストリング "" に設定されます。これは、poid エレメントのデフォルト・エレメント名前空間が定義されておらず、poid エレメントがルート・エレメントWITH tempid(id, elem) AS (SELECT custid, XMLELEMENT(NAME "poid", poid) FROM purchaseorder ) SELECT XMLELEMENT(NAME "root", XMLNAMESPACES(DEFAULT 'http://mytest.uri'), XMLATTRIBUTES(cid), (SELECT XMLAGG(elem) FROM tempid WHERE tempid.id = customer.cid ) ) FROM customer WHERE cid = '1002'
xmlns="http://mytest.uri"
のデフォルト・エレメント名前空間に属していないためです。<root xmlns="http://mytest.uri" CID="1002"> <poid xmlns="">5000</poid> <poid xmlns="">5003</poid> <poid xmlns="">5006</poid> </root>