From 626b4416b9be9ac18faa0b441043243dd75653d3 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 2 Apr 2007 15:27:02 +0000 Subject: [PATCH] Put documentation on XML data type and functions in better positions. Add some index terms. --- doc/src/sgml/config.sgml | 4 +- doc/src/sgml/datatype.sgml | 274 ++++---- doc/src/sgml/func.sgml | 1326 ++++++++++++++++++------------------ 3 files changed, 807 insertions(+), 797 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 07d1a879b3f..57a618faa6f 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1,4 +1,4 @@ - + Server Configuration @@ -3591,7 +3591,7 @@ SELECT * FROM parent WHERE key = 2400; SET XML OPTION - XML option + XML option diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 1bf103c8780..9e95f95f011 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,4 +1,4 @@ - + Data Types @@ -3190,6 +3190,144 @@ SELECT * FROM test; + + <acronym>XML</> Type + + + XML + + + + The data type xml can be used to store XML data. Its + advantage over storing XML data in a text field is that it + checks the input values for well-formedness, and there are support + functions to perform type-safe operations on it; see . + + + + In particular, the xml type can store well-formed + documents, as defined by the XML standard, as well + as content fragments, which are defined by the + production XMLDecl? content in the XML + standard. Roughly, this means that content fragments can have + more than one top-level element or character node. The expression + xmlvalue IS DOCUMENT + can be used to evaluate whether a particular xml + value is a full document or only a content fragment. + + + + To produce a value of type xml from character data, + use the function + xmlparse:xmlparse + +XMLPARSE ( { DOCUMENT | CONTENT } value) + + Examples: +Manual...') +XMLPARSE (CONTENT 'abcbarfoo') +]]> + While this is the only way to convert character strings into XML + values according to the SQL standard, the PostgreSQL-specific + syntaxes: +bar' +'bar'::xml +]]> + can also be used. + + + + The xml type does not validate its input values + against a possibly included document type declaration + (DTD).DTD + + + + The inverse operation, producing character string type values from + xml, uses the function + xmlserialize:xmlserialize + +XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) + + type can be one of + character, character varying, or + text (or an alias name for those). Again, according + to the SQL standard, this is the only way to convert between type + xml and character types, but PostgreSQL also allows + you to simply cast the value. + + + + When character string values are cast to or from type + xml without going through XMLPARSE or + XMLSERIALIZE, respectively, the choice of + DOCUMENT versus CONTENT is + determined by the XML option + XML option + session configuration parameter, which can be set using the + standard command + +SET XML OPTION { DOCUMENT | CONTENT }; + + or the more PostgreSQL-like syntax + +SET xmloption TO { DOCUMENT | CONTENT }; + + The default is CONTENT, so all forms of XML + data are allowed. + + + + Care must be taken when dealing with multiple character encodings + on the client, server, and in the XML data passed through them. + When using the text mode to pass queries to the server and query + results to the client (which is the normal mode), PostgreSQL + converts all character data passed between the client and the + server and vice versa to the character encoding of the respective + end; see . This includes string + representations of XML values, such as in the above examples. + This would ordinarily mean that encoding declarations contained in + XML data might become invalid as the character data is converted + to other encodings while travelling between client and server, + while the embedded encoding declaration is not changed. To cope + with this behavior, an encoding declaration contained in a + character string presented for input to the xml type + is ignored, and the content is always assumed + to be in the current server encoding. Consequently, for correct + processing, such character strings of XML data must be sent off + from the client in the current client encoding. It is the + responsibility of the client to either convert the document to the + current client encoding before sending it off to the server or to + adjust the client encoding appropriately. On output, values of + type xml will not have an encoding declaration, and + clients must assume that the data is in the current client + encoding. + + + + When using the binary mode to pass query parameters to the server + and query results back the the client, no character set conversion + is performed, so the situation is different. In this case, an + encoding declaration in the XML data will be observed, and if it + is absent, the data will be assumed to be in UTF-8 (as required by + the XML standard; note that PostgreSQL does not support UTF-16 at + all). On output, data will have an encoding declaration + specifying the client encoding, unless the client encoding is + UTF-8, in which case it will be omitted. + + + + Needless to say, processing XML data with PostgreSQL will be less + error-prone and more efficient if data encoding, client encoding, + and server encoding are the same. Since XML data is internally + processed in UTF-8, computations will be most efficient if the + server encoding is also UTF-8. + + + &array; &rowtypes; @@ -3579,138 +3717,4 @@ SELECT * FROM pg_attribute - - <acronym>XML</> Type - - - XML - - - - The data type xml can be used to store XML data. Its - advantage over storing XML data in a text field is that it - checks the input values for well-formedness, and there are support - functions to perform type-safe operations on it; see . - - - - In particular, the xml type can store well-formed - documents, as defined by the XML standard, as well - as content fragments, which are defined by the - production XMLDecl? content in the XML - standard. Roughly, this means that content fragments can have - more than one top-level element or character node. The expression - xmlvalue IS DOCUMENT - can be used to evaluate whether a particular xml - value is a full document or only a content fragment. - - - - To produce a value of type xml from character data, - use the function xmlparse: - -XMLPARSE ( { DOCUMENT | CONTENT } value) - - Examples: -Manual...') -XMLPARSE (CONTENT 'abcbarfoo') -]]> - While this is the only way to convert character strings into XML - values according to the SQL standard, the PostgreSQL-specific - syntaxes: -bar' -'bar'::xml -]]> - can also be used. - - - - The xml type does not validate its input values - against a possibly included document type declaration (DTD). - - - - The inverse operation, producing character string type values from - xml, uses the function - xmlserialize: - -XMLSERIALIZE ( { DOCUMENT | CONTENT } value AS type ) - - type can be one of - character, character varying, or - text (or an alias name for those). Again, according - to the SQL standard, this is the only way to convert between type - xml and character types, but PostgreSQL also allows - you to simply cast the value. - - - - When character string values are cast to or from type - xml without going through XMLPARSE or - XMLSERIALIZE, respectively, the choice of - DOCUMENT versus CONTENT is - determined by the XML option session configuration - parameter, which can be set using the standard command - -SET XML OPTION { DOCUMENT | CONTENT }; - - or the more PostgreSQL-like syntax - -SET xmloption TO { DOCUMENT | CONTENT }; - - The default is CONTENT, so all forms of XML - data are allowed. - - - - Care must be taken when dealing with multiple character encodings - on the client, server, and in the XML data passed through them. - When using the text mode to pass queries to the server and query - results to the client (which is the normal mode), PostgreSQL - converts all character data passed between the client and the - server and vice versa to the character encoding of the respective - end; see . This includes string - representations of XML values, such as in the above examples. - This would ordinarily mean that encoding declarations contained in - XML data might become invalid as the character data is converted - to other encodings while travelling between client and server, - while the embedded encoding declaration is not changed. To cope - with this behavior, an encoding declaration contained in a - character string presented for input to the xml type - is ignored, and the content is always assumed - to be in the current server encoding. Consequently, for correct - processing, such character strings of XML data must be sent off - from the client in the current client encoding. It is the - responsibility of the client to either convert the document to the - current client encoding before sending it off to the server or to - adjust the client encoding appropriately. On output, values of - type xml will not have an encoding declaration, and - clients must assume that the data is in the current client - encoding. - - - - When using the binary mode to pass query parameters to the server - and query results back the the client, no character set conversion - is performed, so the situation is different. In this case, an - encoding declaration in the XML data will be observed, and if it - is absent, the data will be assumed to be in UTF-8 (as required by - the XML standard; note that PostgreSQL does not support UTF-16 at - all). On output, data will have an encoding declaration - specifying the client encoding, unless the client encoding is - UTF-8, in which case it will be omitted. - - - - Needless to say, processing XML data with PostgreSQL will be less - error-prone and more efficient if data encoding, client encoding, - and server encoding are the same. Since XML data is internally - processed in UTF-8, computations will be most efficient if the - server encoding is also UTF-8. - - - diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0baf1525944..cc872d8234f 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,4 +1,4 @@ - + Functions and Operators @@ -7502,6 +7502,671 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple + + 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 + + + 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) + + + + The function xmlcomment creates an XML value + containing an XML comment with the specified text as content. + The text cannot 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(xml, ...) + + + + 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 , xmlattributes(value AS attname , ... ) , content, ...) + + + + 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> + + + xmlforest + + + + xmlforest(content AS name , ...) + + + + 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> + + + xmlpi + + + + xmlpi(name target , content) + + + + The xmlpi expression creates an XML + processing instruction. The content, if present, must not + contain the character sequence ?>. + + + + Example: + +]]> + + + + + <literal>xmlroot</literal> + + + xmlroot + + + + xmlroot(xml, version text|no value , standalone yes|no|no value) + + + + 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. + + + + + + Mapping Tables to XML + + + XML export + + + + The following functions map the contents of relational tables to + XML values. They can be thought of as XML export functionality. + +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) + + The return type of each function is xml. + + + + table_to_xml maps the content of the named + table, passed as parameter tbl. The + regclass accepts strings identifying tables using the + usual notation, including optional schema qualifications and + double quotes. query_to_xml executes the + query whose text is passed as parameter + query and maps the result set. + cursor_to_xml fetches the indicated number of + rows from the cursor specified by the parameter + cursor. This variant is recommendable if + large tables have to be mapped, because the result value is built + up in memory by each function. + + + + If tableforest is false, then the resulting + XML document looks like this: + + + data + data + + + + ... + + + ... + +]]> + + If tableforest is true, the result is an + XML content fragment that looks like this: + + data + data + + + + ... + + +... +]]> + + If no table name is avaible, that is, when mapping a query or a + cursor, the string table is used in the first + format, row in the second format. + + + + The choice between these formats is up to the user. The first + format is a proper XML document, which will be important in many + applications. The second format tends to be more useful in the + cursor_to_xml function if the result values are to be + reassembled into one document later on. The functions for + producing XML content discussed above, in particular + xmlelement, can be used to alter the results + to taste. + + + + The data values are mapping in the same way as described for the + function xmlelement above. + + + + The parameter nulls determines whether null + values should be included in the output. If true, null values in + columns are represented as + +]]> + where xsi is the XML namespace prefix for XML + Schema Instance. An appropriate namespace declaration will be + added to the result value. If false, columns containing null + values are simply omitted from the output. + + + + The parameter targetns specifies the + desired XML namespace of the result. If no particular namespace + is wanted, an empty string should be passed. + + + + The following functions return XML Schema documents describing the + mappings made by the data mappings produced by the corresponding + functions above. + +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) + + It is essential that the same parameters are passed in order to + obtain matching XML data mappings and XML Schema documents. + + + + The following functions produce XML data mappings and the + corresponding XML Schema in one document (or forest), linked + together. They can be useful where self-contained and + self-describing results are wanted. + +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) + + + + + In addition, the following functions are available to produce + analogous mappings of entire schemas or the entire current + database. + +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) + + + Note that these potentially produce a lot of data, which needs to + be built up in memory. When requesting content mappings of large + schemas or databases, it may be worthwhile to consider mapping the + tables separately instead, possibly even through a cursor. + + + + The result of a schema content mapping looks like this: + + + +table1-mapping + +table2-mapping + +... + +]]> + + where the format of a table mapping depends on the + tableforest parameter as explained above. + + + + The result of a database content mapping looks like this: + + + + + ... + + + + ... + + +... + +]]> + + where the schema mapping is as above. + + + + As an example for using the output produced by these functions, + shows an XSLT stylesheet that + converts the output of + table_to_xml_and_xmlschema to an HTML + document containing a tabular rendition of the table data. In a + similar manner, the result data of these functions can be + converted into other XML-based formats. + + +
+ XSLT stylesheet for converting SQL/XML output to HTML + + + + + + + + + + + + + <xsl:value-of select="name(current())"/> + + + + + + + + + + + + + + + + +
+ + + + + +]]> +
+ + + + 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 . + + + + + 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. + + + + + + + + Sequence Manipulation Functions @@ -11141,663 +11806,4 @@ SELECT (pg_stat_file('filename')).modification; - - 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 - - - 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) - - - - The function xmlcomment creates an XML value - containing an XML comment with the specified text as content. - The text cannot 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(xml, ...) - - - - 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 , xmlattributes(value AS attname , ... ) , content, ...) - - - - 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> - - - xmlforest - - - - xmlforest(content AS name , ...) - - - - 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> - - - xmlpi - - - - xmlpi(name target , content) - - - - The xmlpi expression creates an XML - processing instruction. The content, if present, must not - contain the character sequence ?>. - - - - Example: - -]]> - - - - - <literal>xmlroot</literal> - - - xmlroot - - - - xmlroot(xml, version text|no value , standalone yes|no|no value) - - - - 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. - - - - - - Mapping Tables to XML - - - The following functions map the contents of relational tables to - XML values. They can be thought of as XML export functionality. - -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) - - The return type of each function is xml. - - - - table_to_xml maps the content of the named - table, passed as parameter tbl. The - regclass accepts strings identifying tables using the - usual notation, including optional schema qualifications and - double quotes. query_to_xml executes the - query whose text is passed as parameter - query and maps the result set. - cursor_to_xml fetches the indicated number of - rows from the cursor specified by the parameter - cursor. This variant is recommendable if - large tables have to be mapped, because the result value is built - up in memory by each function. - - - - If tableforest is false, then the resulting - XML document looks like this: - - - data - data - - - - ... - - - ... - -]]> - - If tableforest is true, the result is an - XML content fragment that looks like this: - - data - data - - - - ... - - -... -]]> - - If no table name is avaible, that is, when mapping a query or a - cursor, the string table is used in the first - format, row in the second format. - - - - The choice between these formats is up to the user. The first - format is a proper XML document, which will be important in many - applications. The second format tends to be more useful in the - cursor_to_xml function if the result values are to be - reassembled into one document later on. The functions for - producing XML content discussed above, in particular - xmlelement, can be used to alter the results - to taste. - - - - The data values are mapping in the same way as described for the - function xmlelement above. - - - - The parameter nulls determines whether null - values should be included in the output. If true, null values in - columns are represented as - -]]> - where xsi is the XML namespace prefix for XML - Schema Instance. An appropriate namespace declaration will be - added to the result value. If false, columns containing null - values are simply omitted from the output. - - - - The parameter targetns specifies the - desired XML namespace of the result. If no particular namespace - is wanted, an empty string should be passed. - - - - The following functions return XML Schema documents describing the - mappings made by the data mappings produced by the corresponding - functions above. - -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) - - It is essential that the same parameters are passed in order to - obtain matching XML data mappings and XML Schema documents. - - - - The following functions produce XML data mappings and the - corresponding XML Schema in one document (or forest), linked - together. They can be useful where self-contained and - self-describing results are wanted. - -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) - - - - - In addition, the following functions are available to produce - analogous mappings of entire schemas or the entire current - database. - -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) - - - Note that these potentially produce a lot of data, which needs to - be built up in memory. When requesting content mappings of large - schemas or databases, it may be worthwhile to consider mapping the - tables separately instead, possibly even through a cursor. - - - - The result of a schema content mapping looks like this: - - - -table1-mapping - -table2-mapping - -... - -]]> - - where the format of a table mapping depends on the - tableforest parameter as explained above. - - - - The result of a database content mapping looks like this: - - - - - ... - - - - ... - - -... - -]]> - - where the schema mapping is as above. - - - - As an example for using the output produced by these functions, - shows an XSLT stylesheet that - converts the output of - table_to_xml_and_xmlschema to an HTML - document containing a tabular rendition of the table data. In a - similar manner, the result data of these functions can be - converted into other XML-based formats. - - -
- XSLT stylesheet for converting SQL/XML output to HTML - - - - - - - - - - - - - <xsl:value-of select="name(current())"/> - - - - - - - - - - - - - - - - -
- - - - - -]]> -
- - - - 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 . - - - - - 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. - - - - - -