projects / postgresql.git / commitdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: b39e915)
Update documentation on XML functions
authorPeter Eisentraut
Mon, 29 Jan 2007 13:24:30 +0000 (13:24 +0000)
committerPeter Eisentraut
Mon, 29 Jan 2007 13:24:30 +0000 (13:24 +0000)
doc/src/sgml/datatype.sgml patch | blob | blame | history
doc/src/sgml/func.sgml patch | blob | blame | history

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f0ba6c32c715ee3351265b8310f7fbc9d040dadd..10d5a34cf964e99311b940b06536de8b2917a701 100644 (file)
--- 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 
-    url="http://www.rpbourret.com/xml/XMLAndDatabases.htm">.
-   
-
-   
-   
-    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 f433f9221c7e127aa420596eb5a6806cc2505946..4b03b4df148c3a75f80ab5d6c234f2f2d848935d 100644 (file)
--- 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 
+   linkend="datatype-xml"> 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.
    
 
-   2>
+   3>
     <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:
+
+SELECT xmlcomment('hello');
+
+  xmlcomment
+--------------
+ 
+]]>
+    
+   
+
+   
     <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:
+
+SELECT xmlconcat('', '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:
+
+SELECT xmlconcat('', '');
+
+             xmlconcat
+-----------------------------------
+ 
+]]>
+    
+   
  
-   2>
+   3>
     <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);
+
+ xmlelement
+------------
+ 
+
+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:
+
+SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&b"));
+
+            xmlelement
+----------------------------------
+ 
+]]>
     
-    
+
+    
+     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:
+
+SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
+                            xmlelement(name abc),
+                            xmlcomment('test'),
+                            xmlelement(name xyz));
+
+                  xmlelement
+----------------------------------------------
+ 
+]]>
+
+     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.
+    
+   
  
-   2>
+   3>
     <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:
+
+SELECT xmlforest('abc' AS foo, 123 AS bar);
+
+          xmlforest
+------------------------------
+ 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.
     
-    >
+   >
  
-   2>
+   3>
     <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:
+
+SELECT xmlpi(name php, 'echo "hello world";');
+
+            xmlpi
+-----------------------------
+ 
+]]>
     
-    >
+   >
  
-   2>
+   3>
     <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.
+    
+
+    
+
+SELECT xmlroot(xmlparse(document '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 
+    url="http://www.rpbourret.com/xml/XMLAndDatabases.htm">.
+   
+
+   
+   
+    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.
+     
+    
+   
+   
   
- 
  
 
This is the main PostgreSQL git repository.