XMLGROUP 集約関数

XMLGROUP 関数は、XQuery 文書ノードを 1 つ持つ XML 値を戻します。これには最上位エレメント・ノードが 1 つ含まれています。これは、各行が行のサブエレメントにマップされる行のグループから単一ルートを持つ XML 文書を戻す集約式です。

注:

¹ 同じ節を複数回指定することはできません。

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

expression: 生成される各 XML エレメント・ノード (または生成される各属性の値) の内容を式によって指定します。 expression のデータ・タイプを BINARY タイプ、VARBINARY タイプ、または構造化タイプにすることはできません (SQLSTATE 42884)。式には任意の SQL 式を指定できます。式が単純な列参照でない場合、qname-identifier を指定する必要があります。
AS qname-identifier: SQL ID として XML エレメント名または属性名を指定します。 qname-identifier は、XML 修飾名の形式であるかまたは QName でなければなりません (SQLSTATE 42634)。有効な名前の詳細は、「W3C の XML 名前空間仕様」を参照してください。名前が修飾される場合は、名前空間の接頭部をその有効範囲内で宣言する必要があります (SQLSTATE 42635)。 qname-identifier が指定されない場合、 expression は列名でなければなりません (SQLSTATE 42703)。エレメント名または属性名は、列名から QName への完全にエスケープしたマッピングを使用する列名から作成されます。
OPTION: XML 値を構成するための追加オプションを指定します。 OPTION 節を指定しない場合、デフォルトの動作が適用されます。
ROW row-name: 各行のマップ先のエレメントの名前を指定します。オプションが指定されない場合のデフォルトのエレメント名は "row" です。
ROOT root-name: ルート・エレメント・ノードの名前を指定します。オプションが指定されない場合のデフォルトのルート・エレメント名は "rowset" です。
AS ATTRIBUTES: 各式を列名または qname-identifier (属性名としての役割を果たす) を使用して属性値にマップすることを指定します。
ORDER BY: 集約内の処理対象の、同じグループ化集合に属する行の順序を指定します。 ORDER BY 節を省略した場合や、ORDER BY が列データの ORDER BY を特定できない場合、同一のグループ化集合内の行は任意に順序付けられます。
sort-key: ソート・キーは、列名または sort-key-expression のどちらでも構いません。ソート・キーが定数の場合、ソート・キーは出力列の位置を (通常の ORDER BY 節におけるように) 参照しませんが、これは単なる定数でしかなく、ソート・キーではないことを意味することに注意してください。

規則

SELECT 節に ARRAY_AGG 関数が組み込まれている場合、同じ SELECT 節にある ARRAY_AGG、LISTAGG、XMLAGG、および XMLGROUP 関数のすべての呼び出しにおいて、同じ順序を指定するか、または順序を指定しないかのいずれかにする必要があります (SQLSTATE 428GZ)。

注

デフォルトの動作は、結果セットと XML 値の間の単純なマッピングを定義します。以下は、関数の動作に関して当てはまるいくつかの追加注意事項です。

デフォルトで、各行は "row" という名前の XML エレメントに変換され、各列はネストされたエレメントに変換されます。その際、エレメント名として列名が使用されます。
ヌル処理の動作は NULL ON NULL です。列の値が NULL の場合、そのマップ先のサブエレメントは空になります。すべての列の値が NULL の場合、行エレメントは生成されません。
BLOB および FOR BIT DATA データ・タイプのバイナリー・コード化スキームは base64Binary エンコードです。
デフォルトで、グループの行に対応するエレメントは、"rowset" という名前のルート・エレメントの子です。
ルート・エレメントの行サブエレメントの順序は、照会結果セットに行が戻される順序と同じです。
XML の結果を、単一ルートを持つ整形式 XML 文書とするために、文書ノードが暗黙的にルート・エレメントに追加されます。

例

この例は、次の表 T1 に基づいています。そこにはリレーショナル形式で格納された数値データが入っている整数列 C1 および C2 があります。

C1          C2
----------- -----------
          1           2
          -           2
          1           -
          -           -

  4 record(s) selected.

例 1: 以下の例は、XMLGroup 照会とデフォルトの動作による出力断片が示されています。表を表すために 1 つの最上位エレメントがその中で使用されています。 :
```
SELECT XMLGROUP(C1, C2)FROM T1
```
```
<rowset>
   <row>
      <C1>1</C1>
      <C2>2</C2>
   </row>
   <row>
      <C2>2</C2>
   </row>
   <row>
      <C1>1</C1>
   </row>
</rowset>

  1 record(s) selected.
```
例 2: 以下の例は、XMLGroup 照会と属性を中心としたマッピングによる出力断片を示しています。リレーショナル・データは前例のようにネストされたエレメントとして現れておらず、エレメント属性にマップされています。
```
SELECT XMLGROUP(C1, C2 OPTION AS ATTRIBUTES) FROM T1
```
```
<rowset>
   <row C1="1" C2="2"/>
   <row C2="2"/>
   <row C1="1"/>
</rowset>

  1 record(s) selected.
```
例 3: 以下の例は、XMLGroup 照会とデフォルトの <rowset> ルート・エレメントが <document> によって置き換えられ、デフォルトの <row> エレメントが <entry> によって置き換えられた出力断片を示しています。列 C1 と C2 が <column1> と <column2> エレメントで返され、戻りセットは列 C1 で順序付けられます。
```
SELECT XMLGROUP(
   C1 AS "column1", C2 AS "column2"
   ORDER BY C1 OPTION ROW "entry" ROOT "document") 
FROM T1
```
```
<document>
   <entry>
      <column1>1</column1>
      <column2>2</column2>
   </entry>
   <entry>
      <column1>1</column1>
   </entry>
   <entry>
      <column2>2</column2>
    </entry>
</document>
```