xmlcomment(text)

関数xmlcommentは指定のテキストを内容とするXMLコメントを含んだXML値を作成します。 結果として構築されるXMLコメントが有効になるよう、テキストは「--」を含むこと、または「-」で終結することはできません。 引数がNULLならば結果もNULLになります。

例：

SELECT xmlcomment('hello');

  xmlcomment
--------------
 <!--hello-->

xmlconcat(xml[, ...])

関数xmlconcatは、個々のXML値のリストを結合し、XMLの内容断片を含む単一の値を作成します。 NULL値は削除され、NULL以外の引数が存在しないときのみ結果はNULLになります。

例：

SELECT xmlconcat('<abc/>', '<bar>foo</bar>');

      xmlconcat
----------------------
 <abc/><bar>foo</bar>

XML宣言が提示されている場合は次のように組み合わされます。 全ての引数の値が同一のXMLversion宣言を持っていれば、そのversionが結果に使用されます。さもなければversionは使用されません。 全ての引数の値でstandaloneの宣言値が「yes」であれば、その値が結果に使用されます。 全ての引数の値にstandalone宣言値があり、その中で１つでも「no」がある場合、それが結果に使用されます。 それ以外の場合は、結果はstandalone宣言を持ちません。 standalone宣言を必要とするが、standalone宣言がないという結果になった場合には、version 1.0のversion宣言が使用されます。 これはXMLがXML宣言においてversion宣言を含むことを要求するためです。 encoding宣言は無視され、全ての場合で削除されます。

例：

SELECT xmlconcat('<?xml version="1.1"?><foo/>', '<?xml version="1.1" standalone="no"?><bar/>');

             xmlconcat
-----------------------------------
 <?xml version="1.1"?><foo/><bar/>

xmlelement(name name [, xmlattributes(value [AS attname] [, ... ])] [, content, ...])

xmlelement式は与えられた名前、属性、および内容を持つXML要素を生成します。

例：

SELECT xmlelement(name foo);

 xmlelement
------------
 <foo/>

SELECT xmlelement(name foo, xmlattributes('xyz' as bar));

    xmlelement
------------------
 <foo bar="xyz"/>

SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');

             xmlelement
-------------------------------------
 <foo bar="2007-01-26">content</foo>

有効なXML名ではない要素名と属性名は、シーケンス_xHHHH_により障害となる文字を置換することでエスケープされます。ここで、HHHHは16進数によるその文字のUnicode文字コード番号です。 例をあげます。

SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&b"));

            xmlelement
----------------------------------
 <foo_x0024_bar a_x0026_b="xyz"/>

属性値が列参照の場合、明示的な属性名を指定する必要はありません。この場合、デフォルトで列名が属性名として使用されます。 その他の場合には、属性は明示的な名前で与えられなければなりません。 従って、以下の例は有効です。

CREATE TABLE test (a xml, b xml);
SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;

しかし、以下の例は有効ではありません。

SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;

もし要素内容が指定されればそのデータ型に従って書式化されます。 もし内容そのものがxml型であれば、複合XML文書が構築されます。 例をあげます。

SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
                            xmlelement(name abc),
                            xmlcomment('test'),
                            xmlelement(name xyz));

                  xmlelement
----------------------------------------------
 <foo bar="xyz"><abc/><!--test--><xyz/></foo>

そのほかの型の内容は有効なXML文字データにフォーマットされます。 これは特に文字<、>、および&がエンティティに変換されることを意味します。 バイナリデータ（データ型はbytea）は、設定パラメータxmlbinaryの設定にしたがって、base64もしくは16進符号化方式で表現されます。 個々のデータ型に対する特定の動作は、XMLスキーマ仕様でのSQLおよびPostgreSQLデータ型に調整するため発展すると期待されます。 その時点で記述がより詳細になるでしょう。

xmlforest(content [AS name] [, ...])

xmlforest式は与えられた名前と内容を使用し、要素のXMLフォレスト（シーケンス）を生成します。

例：

SELECT xmlforest('abc' AS foo, 123 AS bar);

          xmlforest
------------------------------
 <foo>abc</foo><bar>123</bar>


SELECT xmlforest(table_name, column_name)
FROM information_schema.columns
WHERE table_schema = 'pg_catalog';

                                         xmlforest
-------------------------------------------------------------------------------------------
 <table_name>pg_authid</table_name><column_name>rolname</column_name>
 <table_name>pg_authid</table_name><column_name>rolsuper</column_name>
 ...

第２の例に見られるように、内容の値が列参照の場合、要素名は省略可能です。この時は、列名がデフォルトで使用されます。 そうでない時は、名前が指定されなければなりません。

有効なXML名ではない要素名は上のxmlelementで説明した通りエスケープされます。 同様にして、既にxml型であるものを除き、内容データは有効なXML内容になるようにエスケープされます。

XMLフォレストは２つ以上の要素からなる場合、有効なXML文書ではないことに注意してください。 したがって、xmlelement内にxmlforest式をラップすることが有用なことがあります。

xmlpi(name target [, content])

xmlpi式はXML処理命令を作成します。 内容が存在すれば、その内容は?>文字シーケンスを含んではなりません。

例：

SELECT xmlpi(name php, 'echo "hello world";');

            xmlpi
-----------------------------
 <?php echo "hello world";?>

xmlroot(xml, version text | no value [, standalone yes|no|no value])

xmlroot式はXML値のルートノードの属性を変更します。 versionが指定されていると、ルートノードのversion宣言での値を変更し、standalone設定が指定されていると、ルートノードのstandalone宣言での値を変更します。

SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
               version '1.0', standalone yes);

                xmlroot
----------------------------------------
 <?xml version="1.0" standalone="yes"?>
 <content>abc</content>

xmlagg(xml)

ここで説明している他の関数とは異なり、xmlagg関数は集約関数です。 これはxmlconcatが行うように、入力値を連結する集約関数ですが、単一行内の複数の式にまたがった連結ではなく、複数行にまたがった連結を行います。 集約関数についての追加情報は9.20を参照してください。

例：

CREATE TABLE test (y int, x xml);
INSERT INTO test VALUES (1, '<foo>abc</foo>');
INSERT INTO test VALUES (2, '<bar/>');
SELECT xmlagg(x) FROM test;
        xmlagg
----------------------
 <foo>abc</foo><bar/>

連結の順序を決定するため、4.2.7に記述されているようにORDER BY句を集計呼び出しに追加することができます。 以下は例です。

SELECT xmlagg(x ORDER BY y DESC) FROM test;
        xmlagg
----------------------
 <bar/><foo>abc</foo>

下記は以前のバージョンで推奨されていた、非標準的な方法例です。特定のケースでは有用かもしれません。

SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
        xmlagg
----------------------
 <bar/><foo>abc</foo>

xml IS DOCUMENT

式IS DOCUMENTは引数XML値が適切なXML文書であれば真を返し、そうでなければ（つまり、内容の断片）偽を返すか、もしくは引数がNULLであればNULLを返します。 文書と内容の断片の差異については8.13を参照してください。

xml IS NOT DOCUMENT

The expression IS NOT DOCUMENT returns false if the argument XML value is a proper XML document, true if it is not (that is, it is a content fragment), or null if the argument is null.

XMLEXISTS(text PASSING [BY REF] xml [BY REF])

関数xmlexistsは第一引数のXPath式が何かしらのノードであれば真を返し、そうでなければ偽を返します。 (もしいずれの引数もNULLであった場合はNULLを返します。)

例:

SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY REF '<towns><town>Toronto</town><town>Ottawa</town></towns>');

 xmlexists
------------
 t
(1 row)

BY REF句は、PostgreSQLには何の影響も与えませんが、他の実装とのSQL互換性や順応性のため、付与することができます。 SQL標準では1つ目のBY REFを必要としており、2つ目はオプショナルです。 加えてSQL標準ではxmlexistsはXQuery式を第一引数として取る構成としていますが、PostgreSQLでは現在XQueryのサブセットにあたるXPathのみサポートしていることに注意してください。

xml_is_well_formed(text)
xml_is_well_formed_document(text)
xml_is_well_formed_content(text)

これらの関数はtext文字列が整形式かどうかをチェックし、論理値で結果を返します。 xml_is_well_formed_documentは文書が整形式かをチェックし、一方xml_is_well_formed_contentは内容が整形式かをチェックします。 xml_is_well_formedは、xmloptionパラメータ値がDOCUMENTに設定されていれば前者を、CONTENTが設定されていれば後者のチェックを実施します。 これは、xml_is_well_formedは単純なxml型へのキャストが成功するかの判断に有用であり、その他の２つの関数はXMLPARSEの対応による変換が成功するかの判断に有用であることを意味します。

例:

SET xmloption TO DOCUMENT;
SELECT xml_is_well_formed('<>');
 xml_is_well_formed 
--------------------
 f
(1 row)

SELECT xml_is_well_formed('<abc/>');
 xml_is_well_formed 
--------------------
 t
(1 row)

SET xmloption TO CONTENT;
SELECT xml_is_well_formed('abc');
 xml_is_well_formed 
--------------------
 t
(1 row)

SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuff">bar</pg:foo>');
 xml_is_well_formed_document 
-----------------------------
 t
(1 row)

SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuff">bar</my:foo>');
 xml_is_well_formed_document 
-----------------------------
 f
(1 row)

最後の例は、名前空間が正しく一致しているかのチェックも含むことを示しています。

xpath(xpath, xml [, nsarray])

関数xpathは、XML値xmlに対し、XPath式xpath(ひとつのtext値)を評価します。そして、XPath式で作成されたノードセットに対応するXML値の配列を返します。 もし、XPath式がノードセットではなくスカラー値を返す場合、単一要素の配列が返されます。

2番目の引数は整形済XML文書でなければなりません。特に、単一のルートノード要素を持たなければなりません。

オプショナルな関数の３番目の引数は名前空間マッピング配列です。 この配列は、第２軸が２に等しい長さをもつ２次元text配列です（つまり、それは配列の配列で、それぞれは正確に２つの要素からなります）。 それぞれの配列のエントリの最初の要素は名前空間の名前（別名）で、２番目は名前空間のURIです。 この配列内で提供される別名がXML文書自身で使用されるものと同じであることは必要ではありません（言い換えると、XML文書内およびxpath関数の両方の文脈の中で、別名はローカルです）。

例：

SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
             ARRAY[ARRAY['my', 'http://example.com']]);

 xpath  
--------
 {test}
(1 row)

デフォルト(匿名)名前空間を取り扱うためには、以下のようなことを実施してください。

SELECT xpath('//mydefns:b/text()', '<a xmlns="http://example.com"><b>test</b></a>',
             ARRAY[ARRAY['mydefns', 'http://example.com']]);

 xpath
--------
 {test}
(1 row)

xpath_exists(xpath, xml [, nsarray])

関数xpath_existsは、xpath関数の特別な形式です。この関数は、XPathを満足する個別のXML値を返す代わりに、問い合わせがそれを満足するかどうかを論理値で返します。 この関数は、名前空間にマッピングされた引数をもサポートする点を除き、標準のXMLEXISTS述語と同じです。

例:

SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
                     ARRAY[ARRAY['my', 'http://example.com']]);

 xpath_exists  
--------------
 t
(1 row)

xmltable( [XMLNAMESPACES(namespace uri AS namespace name[, ...]), ]
          row_expression PASSING [BY REF] document_expression [BY REF]
          COLUMNS name { type [PATH column_expression] [DEFAULT default_expression] [NOT NULL | NULL]
                        | FOR ORDINALITY }
                   [, ...]
)

xmltable関数は、与えられたXML値、行を抽出するXPathフィルタ、オプションの列定義の集合に基づいてテーブルを生成します。

オプションのXMLNAMESPACES句はカンマで区切られた名前空間のリストです。 これは文書とその別名で使用されるXML名前空間を指定します。 デフォルトの名前空間指定は現在のところサポートされていません。

必須のrow_expression引数はXPath式で、指定のXML文書に対して評価され、XMLノードの順序付きシーケンスが取得されます。 このシーケンスがxmltableにより出力行に変換されます。

document_expressionは演算の対象となるXML文書を提供します。 BY REF句はPostgreSQLでは何の効果もありませんが、SQL準拠および他の実装との互換性のために受け入れられます。 引数は整形されたXMLドキュメントでなければならず、フラグメントやフォレストは受け付けられません。

必須のCOLUMNS句は、出力テーブルの列のリストを指定します。 COLUMNS句を省略した場合、結果集合の行にはxml型の列が1つだけ含まれ、そこにはrow_expressionにマッチしたデータが含まれます。 COLUMNSが指定された場合、各エントリは一つの列を表します。 形式については上記の構文サマリーを参照してください。 列名と型は必須ですが、パス、デフォルト値、NULLを許すかどうかの句は省略できます。

FOR ORDINALITYと印がつけられた列には、元の入力XMLドキュメントの中に現れた出力行の順序に対応する行番号が入ります。 FOR ORDINALITYの印が付けられるのは最大でも1列です。

列のcolumn_expressionはXPath式で、row_expressionの結果に対応する各行について評価されて、列の値を得ます。 column_expressionが与えられなかった場合は、暗示的なパスとして列名が使用されます。

列のXPath式が複数の要素を戻した場合、エラーが発生します。 式が空のタグとマッチした場合、結果は空文字列となります（NULLではありません）。 xsi:nilの属性はすべて無視されます。

column_expressionにマッチしたXMLのテキスト本体が列の値として使用されます。 要素内の複数のtext()ノードは順番に結合されます。 子要素、処理命令、コメントはすべて無視されますが、子要素のテキストコンテンツは結果に結合されます。 2つの非テキスト要素間にある空白文字のみのtext()ノードは保存されること、またtext()ノードの先頭にある空白文字は削られないことに注意してください。

パス式が行とマッチせず、default_expressionが指定されている場合は、その式を評価した結果の値が使用されます。 その列にDEFAULT句が指定されていない場合は、そのフィールドはNULLに設定されます。 default_expressionは列リスト内でそれより前に現れる出力列の値を参照して、ある列のデフォルト値を他の列の値に基づくものにすることができます。

列にはNOT NULLの印をつけることができます。 NOT NULLの列のcolumn_expressionが何にもマッチせず、DEFAULTがない、あるいはdefault_expressionの評価結果もNULLになるという場合はエラーが報告されます。

PostgreSQLの通常の関数とは異なり、column_expressionとdefault_expressionは関数を呼び出す前には単純な値に評価されません。 column_expressionは通常は一つの入力行に対してちょうど一度だけ評価され、default_expressionはフィールドにデフォルト値が必要になる度に評価されます。 式が安定（stable）または不変（immutable）とみなされる場合、評価は繰り返し行われないかもしれません。 実際上、xmltableは関数呼び出しとしてよりも、副問合せのように動作します。 これはdefault_expressionの中でnextvalのような揮発性（volatile）の関数を有効に使用できること、またcolumn_expressionはXML文書の他の部分に依存するかもしれないということを意味します。

例：

CREATE TABLE xmldata AS SELECT
xml $$
<ROWS>
  <ROW id="1">
    <COUNTRY_ID>AU</COUNTRY_ID>
    <COUNTRY_NAME>Australia</COUNTRY_NAME>
  </ROW>
  <ROW id="5">
    <COUNTRY_ID>JP</COUNTRY_ID>
    <COUNTRY_NAME>Japan</COUNTRY_NAME>
    <PREMIER_NAME>Shinzo Abe</PREMIER_NAME>
    <SIZE unit="sq_mi">145935</SIZE>
  </ROW>
  <ROW id="6">
    <COUNTRY_ID>SG</COUNTRY_ID>
    <COUNTRY_NAME>Singapore</COUNTRY_NAME>
    <SIZE unit="sq_km">697</SIZE>
  </ROW>
</ROWS>
$$ AS data;

SELECT xmltable.*
  FROM xmldata,
       XMLTABLE('//ROWS/ROW'
                PASSING data
                COLUMNS id int PATH '@id',
                        ordinality FOR ORDINALITY,
                        "COUNTRY_NAME" text,
                        country_id text PATH 'COUNTRY_ID',
                        size_sq_km float PATH 'SIZE[@unit = "sq_km"]',
                        size_other text PATH
                             'concat(SIZE[@unit!="sq_km"], " ", SIZE[@unit!="sq_km"]/@unit)',
                        premier_name text PATH 'PREMIER_NAME' DEFAULT 'not specified') ;

 id | ordinality | COUNTRY_NAME | country_id | size_sq_km |  size_other  | premier_name  
----+------------+--------------+------------+------------+--------------+---------------
  1 |          1 | Australia    | AU         |            |              | not specified
  5 |          2 | Japan        | JP         |            | 145935 sq_mi | Shinzo Abe
  6 |          3 | Singapore    | SG         |        697 |              | not specified

以下の例では、複数のtext()ノードの結合、列名のXPathフィルターとしての使用、空白文字、XMLコメント、処理命令の取扱いを示します。

CREATE TABLE xmlelements AS SELECT
xml $$
  <root>
   <element>  Hello<!-- xyxxz -->2a2<?aaaaa?> <!--x-->  bbb<x>xxx</x>CC  </element>
  </root>
$$ AS data;

SELECT xmltable.*
  FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
       element        
----------------------
   Hello2a2   bbbCC  

以下の例では、XMLNAMESPACES句を使ってXMLドキュメントやXPath式で使われる追加の名前空間のリストを指定する方法を示します。

WITH xmldata(data) AS (VALUES ('
<example xmlns="http://example.com/myns" xmlns:B="http://example.com/b">
 <item foo="1" B:bar="2"/>
 <item foo="3" B:bar="4"/>
 <item foo="4" B:bar="5"/>
</example>'::xml)
)
SELECT xmltable.*
  FROM XMLTABLE(XMLNAMESPACES('http://example.com/myns' AS x,
                              'http://example.com/b' AS "B"),
             '/x:example/x:item'
                PASSING (SELECT data FROM xmldata)
                COLUMNS foo int PATH '@foo',
                  bar int PATH '@B:bar');
 foo | bar
-----+-----
   1 |   2
   3 |   4
   4 |   5
(3 rows)