9.14. XML関数

9.14.1.1. xmlcomment

xmlcomment(text)

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

例：

SELECT xmlcomment('hello');

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

9.14.1.2. xmlconcat

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宣言がない場合には、XMLはversion宣言を含むXML宣言を要求するため、version 1.0のversion宣言が使用されます。 encoding宣言は無視され、全ての場合で削除されます。

例：

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

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

9.14.1.3. xmlelement

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データ型に調整するため展開されると期待されます。この時点でより詳細な記述が出現します。

9.14.1.4. xmlforest

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式をラップすることが有用なことがあります。

9.14.1.5. xmlpi

xmlpi(name target [, content])

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

例：

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

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

9.14.1.6. xmlroot

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>

9.14.1.7. xmlagg

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>

9.14.2.1. IS DOCUMENT

xml IS DOCUMENT

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

9.14.2.2. XMLEXISTS

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標準では最初にBY REFを必要としており、2つ目の引数以降はオプショナルです。加えてSQL標準ではxmlexistsはXQueryを第一引数として取る構成としていますが、 PostgreSQLでは現在XQueryのサブセットにあたるXpathのみサポートしていることに注意してください。

9.14.2.3. xml_is_well_formed

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)

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