xmltext ( text ) → xml

函式 xmltext 返回一個 XML 值，其中包含一個單一的文字節點，其內容是輸入引數。預定義的實體，如和號（&）、左尖括號和右尖括號（< >）以及引號（""）會被轉義。

示例：

SELECT xmltext('< foo & bar >');
         xmltext
-------------------------
 &lt; foo &amp; bar &gt;

xmlcomment ( text ) → xml

函式 xmlcomment 建立一個 XML 值，其中包含一個 XML 註釋，指定文字作為其內容。文字不能包含 “--” 或以 “-” 結尾，否則生成的結構將不是有效的 XML 註釋。如果引數為 NULL，則結果為 NULL。

示例：

SELECT xmlcomment('hello');

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

xmlconcat ( xml [, ...] ) → xml

函式 xmlconcat 將一系列單獨的 XML 值連線起來，建立一個包含 XML 內容片段的單個值。NULL 值將被忽略；僅當沒有非 NULL 引數時，結果才為 NULL。

示例：

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

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

XML 宣告（如果存在）的組合方式如下。如果所有引數值都具有相同的 XML 版本宣告，則在結果中使用該版本；否則，不使用版本。如果所有引數值都具有 “yes” 的 standalone 宣告值，則在結果中使用該值。如果所有引數值都具有 standalone 宣告值，並且至少有一個是 “no”，則在結果中使用該值。否則，結果將沒有 standalone 宣告。如果結果被確定需要 standalone 宣告但沒有版本宣告，則將使用版本 1.0 的版本宣告，因為 XML 要求 XML 宣告包含版本宣告。在所有情況下，都會忽略並刪除編碼宣告。

示例：

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 ( attvalue [ AS attname ] [, ...] ) ] [, content [, ...]] ) → xml

表示式 xmlelement 生成一個具有給定名稱、屬性和內容的 XML 元素。語法中顯示的 name 和 attname 專案是簡單的識別符號，而不是值。 attvalue 和 content 專案是表示式，它們可以產生任何 PostgreSQL 資料型別。XMLATTRIBUTES 中的引數會生成 XML 元素的屬性；content 值將被連線起來形成其內容。

示例

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 是字元的 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 型別）將以 base64 或十六進位制編碼表示，具體取決於配置引數 xmlbinary 的設定。對於各個資料型別的具體行為，預計會隨著 PostgreSQL 對映與 SQL:2006 及更高版本中指定的對映保持一致而發展，如 第 D.3.1.3 節中所述。

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

表示式 xmlforest 使用給定的名稱和內容生成一個 XML 森林（序列）的元素。與 xmlelement 一樣，每個 name 必須是簡單的識別符號，而 content 表示式可以是任何資料型別。

示例

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 文件，因此將 xmlforest 表示式包裝在 xmlelement 中可能很有用。

xmlpi ( NAME name [, content ] ) → xml

表示式 xmlpi 建立一個 XML 處理指令。與 xmlelement 一樣，name 必須是簡單的識別符號，而 content 表示式可以是任何資料型別。content（如果存在）不能包含字元序列 ?>。

示例：

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

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

xmlroot ( xml, VERSION {text|NO VALUE} [, STANDALONE {YES|NO|NO VALUE} ] ) → xml

表示式 xmlroot 修改 XML 值根節點的屬性。如果指定了版本，它將替換根節點版本宣告中的值；如果指定了 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 ) → xml

函式 xmlagg 與這裡描述的其他函式不同，它是一個聚合函式。它將輸入值連線到聚合函式呼叫，非常類似於 xmlconcat 的作用，只是連線發生在行之間，而不是發生在單行中的表示式之間。有關聚合函式的更多資訊，請參見 第 9.21 節。

示例：

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/>

要確定連線的順序，可以在聚合呼叫中新增 ORDER BY 子句，如 第 4.2.7 節中所述。例如

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 → boolean

表示式 IS DOCUMENT 在引數 XML 值是有效 XML 文件時返回 true，在不是（即是內容片段）時返回 false，在引數為 NULL 時返回 NULL。有關文件和內容片段之間的區別，請參見 第 8.13 節。

xml IS NOT DOCUMENT → boolean

表示式 IS NOT DOCUMENT 在引數 XML 值是有效 XML 文件時返回 false，在不是（即是內容片段）時返回 true，在引數為 NULL 時返回 NULL。

XMLEXISTS ( text PASSING [BY {REF|VALUE}] xml [BY {REF|VALUE}] ) → boolean

函式 xmlexists 使用作為其上下文項傳入的 XML 值來評估 XPath 1.0 表示式（第一個引數）。如果該評估的結果產生一個空節點集，函式返回 false；如果產生任何其他值，則返回 true。如果任何引數為 NULL，函式返回 NULL。作為上下文項傳入的非 NULL 值必須是 XML 文件，而不是內容片段或任何非 XML 值。

示例：

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

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

BY REF 和 BY VALUE 子句在 PostgreSQL 中被接受，但被忽略，如 第 D.3.2 節中所述。

在 SQL 標準中，函式 xmlexists 評估 XML 查詢語言中的表示式，但 PostgreSQL 只允許 XPath 1.0 表示式，如 第 D.3.1 節中所述。

xml_is_well_formed ( text ) → boolean
xml_is_well_formed_document ( text ) → boolean
xml_is_well_formed_content ( text ) → boolean

這些函式檢查 text 字串是否表示格式正確的 XML，並返回布林結果。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="https://postgres.tw/stuff">bar</pg:foo>');
 xml_is_well_formed_document
-----------------------------
 t
(1 row)

SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="https://postgres.tw/stuff">bar</my:foo>');
 xml_is_well_formed_document
-----------------------------
 f
(1 row)

最後一個示例表明，檢查包括名稱空間是否正確匹配。

xpath ( xpath text, xml xml [, nsarray text[] ] ) → xml[]

函式 xpath 針對 XML 值 xml 評估 XPath 1.0 表示式 xpath（以文字形式給出）。它返回一個與 XPath 表示式產生的節點集對應的 XML 值陣列。如果 XPath 表示式返回一個標量值而不是節點集，則返回一個單元素陣列。

第二個引數必須是一個格式正確的 XML 文件。特別是，它必須有一個單一的根節點元素。

該函式的可選第三個引數是名稱空間對映的陣列。該陣列應為二維 text 陣列，第二軸的長度等於 2（即，它應該是陣列的陣列，每個陣列恰好由 2 個元素組成）。每個陣列條目的第一個元素是名稱空間名稱（別名），第二個是名稱空間 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 text, xml xml [, nsarray text[] ] ) → boolean

函式 xpath_exists 是函式 xpath 的特化形式。它不返回滿足 XPath 1.0 表示式的單個 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|VALUE}] document_expression [BY {REF|VALUE}]
    COLUMNS name { type [PATH column_expression] [DEFAULT default_expression] [NOT NULL | NULL]
                  | FOR ORDINALITY }
            [, ...]
) → setof record

表示式 xmltable 基於 XML 值、用於提取行的 XPath 過濾器以及一組列定義來生成表。雖然在語法上類似於函式，但它只能出現在查詢的 FROM 子句中作為表。

可選的 XMLNAMESPACES 子句提供了逗號分隔的名稱空間定義列表，其中每個 namespace_uri 是 text 表示式，每個 namespace_name 是簡單的識別符號。它指定文件中使用的 XML 名稱空間及其別名。目前不支援預設名稱空間規範。

必需的 row_expression 引數是 XPath 1.0 表示式（以 text 形式給出），它透過將 XML 值 document_expression 作為其上下文項進行評估，以獲取一組 XML 節點。這些節點就是 xmltable 轉換為輸出行的內容。如果 document_expression 為 NULL，或者 row_expression 生成一個空節點集或除節點集之外的任何值，則不會產生行。

document_expression 為 row_expression 提供上下文項。它必須是一個格式正確的 XML 文件；不允許片段/森林。BY REF 和 BY VALUE 子句被接受但被忽略，如 第 D.3.2 節中所述。

在 SQL 標準中，函式 xmltable 評估 XML 查詢語言中的表示式，但 PostgreSQL 只允許 XPath 1.0 表示式，如 第 D.3.1 節中所述。

必需的 COLUMNS 子句指定將在輸出表中生成的列。有關格式，請參見上面的語法摘要。每個列都需要一個名稱，以及一個數據型別（除非指定了 FOR ORDINALITY，在這種情況下，integer 型別是隱式的）。路徑、預設值和可空性子句是可選的。

標記為 FOR ORDINALITY 的列將根據 row_expression 結果節點集的節點順序，以 1 開始的行號填充。最多隻能標記一列 FOR ORDINALITY。

列的 column_expression 是一個 XPath 1.0 表示式，它為每一行進行評估，並將 row_expression 結果中的當前節點作為其上下文項，以查詢列的值。如果未給出 column_expression，則預設使用列名作為隱式路徑。

如果列的 XPath 表示式返回一個非 XML 值（在 XPath 1.0 中僅限於字串、布林值或雙精度值），並且該列的 PostgreSQL 型別不是 xml，則該列將透過將值的字串表示分配給 PostgreSQL 型別來設定。（如果值為布林值，則當輸出列的型別類別為數值型時，其字串表示被視為 1 或 0，否則為 true 或 false。）

如果列的 XPath 表示式返回一個非空的 XML 節點集，並且列的 PostgreSQL 型別是 xml，則將為該列分配表示式結果（如果它是文件或內容形式）。^[8]

分配給 xml 輸出列的非 XML 結果會生成內容，即一個具有結果字串值的單一文字節點。分配給任何其他型別的列的 XML 結果可能不應包含多個節點，否則將引發錯誤。如果恰好有一個節點，則該列將透過將該節點的字串值（根據 XPath 1.0 string 函式的定義）分配給 PostgreSQL 型別來設定。

XML 元素的字串值是該元素及其後代中包含的所有文字節點按文件順序連線的結果。沒有後代文字節點的元素的字串值是空字串（不是 NULL）。任何 xsi:nil 屬性都將被忽略。請注意，兩個非文字元素之間的僅包含空白的 text() 節點會被保留，並且 text() 節點上的前導空白不會被展平。XPath 1.0 string 函式可以用於定義其他 XML 節點型別和非 XML 值的字串值的規則。

此處提供的轉換規則不完全符合 SQL 標準，如 第 D.3.1.3 節中所述。

如果對於給定行，路徑表示式返回一個空節點集（通常在不匹配時），則該列將被設定為 NULL，除非指定了 default_expression；然後將使用評估該表示式產生的值。

default_expression 不會在呼叫 xmltable 時立即評估，而是在每次需要該列的預設值時進行評估。如果該表示式被認為是穩定或不可變的，則可以跳過重複評估。這意味著您可以使用 nextval 這樣的易變函式在 default_expression 中。

列可以標記為 NOT NULL。如果 NOT NULL 列的 column_expression 未匹配任何內容，並且沒有 DEFAULT 或者 default_expression 也評估為 NULL，則會報告一個錯誤。

示例

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   bbbxxxCC

以下示例說明了如何使用 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)