From 48ba3f5711aab5bd8f009aa9da8687bc465cdc21 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 29 Jan 2007 13:24:30 +0000 Subject: [PATCH] Update documentation on XML functions --- doc/src/sgml/datatype.sgml | 82 +------- doc/src/sgml/func.sgml | 412 ++++++++++++++++++++++++++++++++----- 2 files changed, 367 insertions(+), 127 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index f0ba6c32c7..10d5a34cf9 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 f433f9221c..4b03b4df14 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. + + + + - -- 2.40.0