diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f0ba6c32c71..10d5a34cf96 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-
+
Data Types
@@ -3538,86 +3538,6 @@ SET xmloption TO { DOCUMENT | CONTENT };
processed in UTF-8, computations will be most efficient if the
server encoding is also UTF-8.
-
-
- XML (Extensible Markup Language) support is not
- just the existance of an xml data type, but a
- variety of features supported by a database system. These
- capabilities include import/export, indexing, searching,
- transforming, and XML to SQL mapping.
- PostgreSQL supports some but not all of these
- XML capabilities. For an overview of XML
- use in databases, see .
-
-
-
-
- Import/Export
-
-
-
- There is no facility for mapping XML to relational
- tables. An external tool must be used for this. One simple way to
- export XML is to use psql in
- HTML mode (\pset format html), and convert
- the XHTML output to XML using an external tool.
-
-
-
-
-
- Indexing
-
-
-
- /contrib/xml2 functions can be used in expression
- indexes to index specific XML fields. To index the
- full contents of XML documents, the full-text indexing
- tool /contrib/tsearch2 can be used. Of course,
- Tsearch2 indexes have no XML awareness so additional
- /contrib/xml2 checks should be added to queries.
-
-
-
-
-
- Searching
-
-
-
- XPath searches are implemented using /contrib/xml2.
- It processes XML text documents and returns results
- based on the requested query.
-
-
-
-
-
- Transforming
-
-
-
- /contrib/xml2 supports XSLT (Extensible
- Stylesheet Language Transformation).
-
-
-
-
-
- XML to SQL Mapping
-
-
-
- This involves converting XML data to and from
- relational structures. PostgreSQL has no internal
- support for such mapping, and relies on external tools to do such
- conversions.
-
-
-
-
-
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index f433f9221c7..4b03b4df148 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-
+
Functions and Operators
@@ -10752,65 +10752,215 @@ SELECT (pg_stat_file('filename')).modification;
-
- XML Functions
+
+ XML Functions
+
+
+ The functions and function-like expressions described in this
+ section operate on values of type xml. Check for information about the xml
+ type. The function-like expressions xmlparse
+ and xmlserialize for converting to and from
+ type xml are not repeated here.
+
+
+
+ Producing XML Content
- The functions and function-like expressions described in this
- section operate on values of type xml.
+ A set of functions and function-like expressions are available for
+ producing XML content from SQL data. As such, they are
+ particularly suitable for formatting query results into XML
+ documents for processing in client applications.
-
+
<literal>xmlcomment</literal>
-
-
- xmlcomment
-
-
-
- xmlcomment(text)
-
-
+
+
+ xmlcomment
+
+
+
+xmlcomment(text)
+
+
- Creates an XML comment.
+ The function xmlcomment creates an XML value
+ containing an XML comment with the specified text as content.
+ The text may not contain -- or end with a
+ - so that the resulting construct is a valid
+ XML comment. If the argument is null, the result is null.
-
-
-
+
+
+ Example:
+
+]]>
+
+
+
+
<literal>xmlconcat</literal>
-
-
- xmlconcat
-
-
+
+
+ xmlconcat
+
+
- xmlconcat(xml, xml, ...)
+ xmlconcat(xml, ...)
- Combines a list of individual XML values to create a
- single value containing an XML forest.
+ The function xmlconcat concatenates a list
+ of individual XML values to create a single value containing an
+ XML content fragment. Null values are omitted; the result is
+ only null if there are no nonnull arguments.
-
+
+
+ Example:
+', 'foo');
+
+ xmlconcat
+----------------------
+ foo
+]]>
+
+
+
+ XML declarations, if present are combined as follows. If all
+ argument values have the same XML version declaration, that
+ version is used in the result, else no version is used. If all
+ argument values have the standalone declaration value
+ yes
, then that value is used in the result. If
+ all argument values have a standalone declaration value and at
+ least one is no
, then that is used in the result.
+ Else the result will have no standalone declaration. If the
+ result is determined to require a standalone declaration but no
+ version declaration, a version declaration with version 1.0 will
+ be used because XML requires an XML declaration to contain a
+ version declaration. Encoding declarations are ignored and
+ removed in all cases.
+
+
+
+ Example:
+', '');
+
+ xmlconcat
+-----------------------------------
+
+]]>
+
+
-
+
<literal>xmlelement</literal>
xmlelement
-
- xmlelement(name name, xmlattribytes(value AS label, ... )
- , content, ...)
+
+ xmlelement(name name , xmlattributes(value AS attname , ... ) , content, ...)
- Creates an XML element, allowing the name to be specified.
+ The xmlelement expression produces an XML
+ element with the given name, attributes, and content.
-
+
+
+ Examples:
+
+
+SELECT xmlelement(name foo, xmlattributes('xyz' as bar));
+
+ xmlelement
+------------------
+
+
+SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');
+
+ xmlelement
+-------------------------------------
+ content
+]]>
+
+
+
+ Element and attribute names that are not valid XML names are
+ escaped by replacing the offending characters by the sequence
+ _xHHHH_, where
+ HHHH is the character's Unicode
+ codepoint in hexadecimal notation. For example:
+
+]]>
+
+
+
+ An explicit attribute name need not be specified if the attribute
+ value is a column reference, in which case the column's name will
+ be used as attribute name by default. In any other case, the
+ attribute must be given an explicit name. So this example is
+ valid:
+
+CREATE TABLE test (a xml, b xml);
+SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
+
+ But these are not:
+
+SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
+SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
+
+
+
+
+ Element content, if specified, will be formatted according to
+ data type. If the content is itself of type xml,
+ complex XML documents can be constructed. For example:
+
+]]>
+
+ Content of other types will be formatted into valid XML character
+ data. This means in particular that the characters <, >,
+ and & will be converted to entities. Binary data (data type
+ bytea) will be represented in base64 or hex
+ encoding, depending on the setting of the configuration parameter
+ . The particular behavior for
+ individual data types is expected evolve in order to align the
+ SQL and PostgreSQL data types with the XML Schema specification,
+ at which point a more precise description will appear.
+
+
-
+
<literal>xmlforest</literal>
@@ -10818,16 +10968,54 @@ SELECT (pg_stat_file('filename')).modification;
- xmlforest(value AS label, ...)
+ xmlforest(content AS name , ...)
- Creates XML elements from columns, using the name of each
- column as the name of the corresponding element.
+ The xmlforest expression produces an XML
+ forest (sequence) of elements using the given names and content.
-
+
+
+ Examples:
+abc123
+
+
+SELECT xmlforest(table_name, column_name) FROM information_schema.columns WHERE table_schema = 'pg_catalog';
+
+ xmlforest
+-------------------------------------------------------------------------------------------
+ pg_authidrolname
+ pg_authidrolsuper
+ ...
+]]>
+
+ As seen in the second example, the element name can be omitted if
+ the content value is a column reference, in which case the column
+ name is used by default. Otherwise, a name must be specified.
+
+
+
+ Element names that are not valid XML names are escaped as shown
+ for xmlelement above. Similarly, content
+ data is escaped to make valid XML content, unless it is already
+ of type xml.
+
+
+
+ Note that XML forests are not valid XML documents if they consist
+ of more than one element. So it might be useful to wrap
+ xmlforest expressions in
+ xmlelement.
+
+
-
+
<literal>xmlpi</literal>
@@ -10839,11 +11027,24 @@ SELECT (pg_stat_file('filename')).modification;
- Creates an XML processing instruction.
+ The xmlpi expression creates an XML
+ processing instruction. The content, if present, must not
+ contain the character sequence ?<.
-
+
+
+ Example:
+
+]]>
+
+
-
+
<literal>xmlroot</literal>
@@ -10851,13 +11052,132 @@ SELECT (pg_stat_file('filename')).modification;
- xmlroot(xml, version text , standalone yes|no|no value)
+ xmlroot(xml, version text|no value , standalone yes|no|no value)
- Creates the root node of an XML document.
+ The xmlroot expression alters the properties
+ of the root node of an XML value. If a version is specified,
+ this replaces the value in the version declaration, if a
+ standalone value is specified, this replaces the value in the
+ standalone declaration.
+
+
+abc'), version '1.0', standalone yes);
+
+ xmlroot
+----------------------------------------
+
+ abc
+]]>
+
+
+
+
+ XML Predicates
+
+
+ IS DOCUMENT
+
+
+
+xml IS DOCUMENT
+
+
+
+ The expression IS DOCUMENT returns true if the
+ argument XML value is a proper XML document, false if it is not
+ (that is, it is a content fragment), or null if the argument is
+ null. See about the difference
+ between documents and content fragments.
+
+
+
+
+
+ Processing XML
+
+
+ XML support is not just the existence of an
+ xml data type, but a variety of features supported by
+ a database system. These capabilities include import/export,
+ indexing, searching, transforming, and XML to
+ SQL mapping. PostgreSQL supports some
+ but not all of these XML capabilities. For an
+ overview of XML use in databases, see .
+
+
+
+
+ Import/Export
+
+
+
+ There is no facility for mapping XML to relational
+ tables. An external tool must be used for this. One simple way
+ to export XML is to use psql in
+ HTML mode (\pset format html), and
+ convert the XHTML output to XML using an external
+ tool.
+
+
+
+
+
+ Indexing
+
+
+
+ contrib/xml2/ functions can be used in expression
+ indexes to index specific XML fields. To index the
+ full contents of XML documents, the full-text
+ indexing tool contrib/tsearch2/ can be used. Of
+ course, Tsearch2 indexes have no XML awareness so
+ additional contrib/xml2/ checks should be added to
+ queries.
+
+
+
+
+
+ Searching
+
+
+
+ XPath searches are implemented using contrib/xml2/.
+ It processes XML text documents and returns results
+ based on the requested query.
+
+
+
+
+
+ Transforming
+
+
+
+ contrib/xml2/ supports XSLT (Extensible
+ Stylesheet Language Transformation).
+
+
+
+
+
+ XML to SQL Mapping
+
+
+
+ This involves converting XML data to and from
+ relational structures. PostgreSQL has no
+ internal support for such mapping, and relies on external tools
+ to do such conversions.
+
+
+
+
-