9.14. XML 函數 · PostgreSQL 中文文檔 9.3

# 9.14\. XML 函數在本節描述的函數和像函數的表達式操作都是基于`xml`類型的值。查看[Section 8.13](#calibre_link-1460)獲取關于`xml`類型的信息。像函數表達式的`xmlparse`和`xmlserialize` 用來轉換為和從類型`xml`轉換，不在這里重復。使用這些函數需要安裝與配置了`configure --with-libxml`。 ## 9.14.1\. 生成XML內容一組函數和像函數的表達式可用于從SQL數據生成XML內容。所以它們特別適合于查詢結果格式化成在客戶端應用程序處理的XML文件。 ### 9.14.1.1\. `xmlcomment` ``` xmlcomment(_text_) ``` `xmlcomment`函數創建一個包含XML注釋的特定文本內容的值。文本中不能包含"`--`"或以"`-`" 的結束，這樣的文本是有效的XML注釋。如果參數是空，結果是空。例子： ``` SELECT xmlcomment('hello'); xmlcomment --------------  ``` ### 9.14.1.2\. `xmlconcat` ``` xmlconcat(_xml_[, ...]) ``` 函數`xmlconcat`連接一個獨立的XML值列表來創建一個包含XML內容片段的單值。忽略空值；只有當參數都為空時結果是空。例子： ``` SELECT xmlconcat('<abc/>', '<bar>foo</bar>'); xmlconcat ---------------------- <abc/><bar>foo</bar> ``` XML聲明，如果存在，結合如下。如果所有參數使用相同的XML版本聲明，則在結果中使用版本。否則不用版本。如果所有的參數值有獨立的聲明值"yes"，然后這個值在結果里使用。如果所有的參數值有獨立的聲明，并且至少有一個是"no"，然后這個值在結果里使用。否則結果將沒有獨立聲明。如果結果決定需要一個獨立的聲明，但沒有聲明版本，將使用一個帶有版本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/> ``` ### 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元素和屬性名的名稱由序列`_x``_HHHH_`_ 替換有問題的字符逃逸，這里的`_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/><xyz/></foo> ``` 將其它類型的內容格式化為有效的xml字符串數據。這意味著特殊的字符<, >, 和&將轉化為實體。二進制數據（`bytea`數據類型）將用base64或16進制編碼表示，取決于配置參數[xmlbinary](#calibre_link-2226)的設置。單個數據類型的特定行為預計將發展為了使SQL和PostgreSQL數據類型和XML架構規范一致，到時將出現更準確描述。 ### 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值的根節點屬性。如果指定一個版本，它替換根節點的版本聲明值;如果指定一個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`，除了連接發生在多行而不是發生在多個單行的表達式。請參閱[Section 9.20](#calibre_link-1641)獲取關于聚集函數的更多信息。示例： ``` 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`子句到聚合調用，描述在[Section 4.2.7](#calibre_link-1070)。示例： ``` 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\. XML Predicates 這節描述的表達式檢查`xml`值的屬性。 ### 9.14.2.1\. `IS DOCUMENT` ``` _xml_ IS DOCUMENT ``` 如果參數XML值是一個合法的XML文檔，表達式`IS DOCUMENT`返回真。否則返回假（例如，內容片段）或如果參數為空則返回空。請參閱[Section 8.13](#calibre_link-1460) 獲取關于文檔和內容片段之間的不同。 ### 9.14.2.2\. `XMLEXISTS` ``` XMLEXISTS(_text_ PASSING [BY REF] _xml_ [BY REF]) ``` 如果第一個參數中的XPath表達式返回任何節點，那么函數`xmlexists`返回真，否則返回假。（如果其他參數是null，結果是null。）示例： ``` SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY REF '<towns><town>Toronto</town><town>Ottawa</town></towns>'); xmlexists ------------ t (1 row) ``` 在PostgreSQL中，`BY REF`子句沒有影響，但是為了與SQL的一致性和其他實現的兼容性是允許的。SQL標準中，第一個`BY REF`是必須的，第二個`BY REF`是可選的。也請注意，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，返回布爾結果。 `xml_is_well_formed_document`檢查格式良好的文檔， `xml_is_well_formed_content`檢查格式良好的內容。 `xml_is_well_formed`如果[xmloption](#calibre_link-2227)參數設置為 `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) ``` 最后一個示例顯示了檢查包括命名空間是否正確匹配。 ## 9.14.3\. 處理XML PostgreSQL提供了`xpath`和`xpath_exists` 函數處理`xml`數據類型的值，計算XPath 1.0表達式的結果。 ``` xpath(_xpath_, _xml_ [, `_nsarray_`]) ``` `xpath`函數，對XML值`_xml_` 計算XPath表達式`_xpath_`（`text`值）的結果。它返回一個XML值的數組對應XPath表達式所產生的節點集。如果XPath表達式返回一個標量值而不是節點集，那么返回一個單個元素的數組。第二個參數必須是一個完整的XML文檔。特別是，它必須有一個根節點元素。該函數的第三個參數是一個命名空間的數組映射。這個數組應該是一個兩維`text`數組，第二個維的長度等于2（它應該是一個數組的數組，其中每個正好包含2個元素）。每個數組項的第一個元素是命名空間名稱的別名，第二個元素是命名空間 URI。這個數組的別名不是必須提供的，與在XML文檔本身使用的相同。（換句話說，在XML文檔和在`xpath`函數的上下文中，別名是_local_）。示例： ``` 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) ``` ## 9.14.4\. 到XML的映射表下面的函數映射關系表的內容到XML值。可以將它們認為XML導出功能： ``` table_to_xml(tbl regclass, nulls boolean, tableforest boolean, targetns text) query_to_xml(query text, nulls boolean, tableforest boolean, targetns text) cursor_to_xml(cursor refcursor, count int, nulls boolean, tableforest boolean, targetns text) ``` 每個函數的返回類型是`xml`。 `table_to_xml`映射命名表的內容，作為參數`tbl`傳遞。 `regclass`類型接受使用常用符號的字符串標識表，包括可選的模式資格和雙引號。 `query_to_xml`執行查詢，這個查詢的文本作為`query` 參數傳遞，并映射結果集。`cursor_to_xml`從參數`cursor` 指定的游標中獲取指定數量的行。如果大數據表需要映射，建議使用這個變體，因為結果值是通過每個函數在內存中構建的。如果`tableforest`是假值，則結果的XML文檔像這樣： ``` <tablename> <row> <columnname1>data</columnname1> <columnname2>data</columnname2> </row> <row> ... </row> ... </tablename> ``` 如果`tableforest`是真值，結果是一個像這樣的XML內容片段： ``` <tablename> <columnname1>data</columnname1> <columnname2>data</columnname2> </tablename> <tablename> ... </tablename> ... ``` 如果沒有可用的表名，也就是當映射一個查詢或游標時，第一個格式用字符串`table`，第二個格式用`row`。這些格式是給用戶選擇使用的。第一種格式是適當的XML文檔，在許多應用程序中比較重要。如果結果值是稍后重新組合成一個文件，則第二種格式在`cursor_to_xml` 函數中更有用。這些函數用來產生上述討論的XML內容，特別是`xmlelement`，可以用來嘗試更改結果。數據值以上面描述的函數`xmlelement`相同的方式映射。參數`nulls`取決于在輸出中是否包含空值。如果真，列中的空值表示為： ``` <columnname xsi:nil="true"/> ``` 這里的`xsi`是XML架構實例的XML命名空間前綴。將為結果值添加一個適當的命名空間聲明。如果假，包含空值的列會從輸出中簡單的省略。參數的`targetns`指定想要結果的XML命名空間。如果沒有特別想要的命名空間，應傳遞一個空字符串。下面的函數返回描述由上述相應的函數執行映射的 XML 架構文檔: ``` table_to_xmlschema(tbl regclass, nulls boolean, tableforest boolean, targetns text) query_to_xmlschema(query text, nulls boolean, tableforest boolean, targetns text) cursor_to_xmlschema(cursor refcursor, nulls boolean, tableforest boolean, targetns text) ``` 重要的是要傳遞相同的參數以獲取匹配的XML數據映射和XML架構文檔。下列函數在一個文檔（或森林）中生成XML數據映射和相應的XML架構，聯系在一起。它們在想要自我包含和自我描述結果的時候可能很有用： ``` table_to_xml_and_xmlschema(tbl regclass, nulls boolean, tableforest boolean, targetns text) query_to_xml_and_xmlschema(query text, nulls boolean, tableforest boolean, targetns text) ``` 此外，下列函數還可用于生成類似整個模式或整個當前數據庫的映射： ``` schema_to_xml(schema name, nulls boolean, tableforest boolean, targetns text) schema_to_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text) schema_to_xml_and_xmlschema(schema name, nulls boolean, tableforest boolean, targetns text) database_to_xml(nulls boolean, tableforest boolean, targetns text) database_to_xmlschema(nulls boolean, tableforest boolean, targetns text) database_to_xml_and_xmlschema(nulls boolean, tableforest boolean, targetns text) ``` 請注意這些可能產生大量的數據，是需要在內存中建立的。當請求大數據量的模式或數據庫的內容映射時，可能值得考慮映射表分別替代，可能甚至通過游標。一個模式內容映射的結果像這樣： ``` <schemaname> table1-mapping table2-mapping ... </schemaname> ``` 其中一個表映射的格式取決于上面所述的`tableforest`參數。一個數據庫內容映射的結果像這樣： ``` <dbname> <schema1name> ... </schema1name> <schema2name> ... </schema2name> ... </dbname> ``` 模式映射如上所述。使用這些函數產生的輸出作為例子，[Figure 9-1](#calibre_link-2228)顯示一個XSLT樣式表轉換 `table_to_xml_and_xmlschema`的輸出到HTML文檔，該文檔中包含了一個表數據的表格格式副本。以類似的方式，這些函數的結果可以轉換成其它基于XML的格式。 **Figure 9-1\. XSLT樣式表--將SQL/XML輸出轉換成HTML** ``` <?xml version="1.0"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.w3.org/1999/xhtml" > <xsl:output method="xml" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" doctype-public="-//W3C/DTD XHTML 1.0 Strict//EN" indent="yes"/> <xsl:template match="/*"> <xsl:variable name="schema" select="//xsd:schema"/> <xsl:variable name="tabletypename" select="$schema/xsd:element[@name=name(current())]/@type"/> <xsl:variable name="rowtypename" select="$schema/xsd:complexType[@name=$tabletypename]/xsd:sequence/xsd:element[@name='row']/@type"/> <html> <head> <title><xsl:value-of select="name(current())"/></title> </head> <body> <table> <tr> <xsl:for-each select="$schema/xsd:complexType[@name=$rowtypename]/xsd:sequence/xsd:element/@name"> <th><xsl:value-of select="."/></th> </xsl:for-each> </tr> <xsl:for-each select="row"> <tr> <xsl:for-each select="*"> <td><xsl:value-of select="."/></td> </xsl:for-each> </tr> </xsl:for-each> </table> </body> </html> </xsl:template> </xsl:stylesheet> ```