From 3963574d13383b4f377ab054e47e4af20cb75e7d Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 21 May 2007 17:10:29 +0000 Subject: XPath fixes: - Function renamed to "xpath". - Function is now strict, per discussion. - Return empty array in case when XPath expression detects nothing (previously, NULL was returned in such case), per discussion. - (bugfix) Work with fragments with prologue: select xpath('/a', ''); // now XML datum is always wrapped with dummy ..., XML prologue simply goes away (if any). - Some cleanup. Nikolay Samokhvalov Some code cleanup and documentation work by myself. --- doc/src/sgml/datatype.sgml | 46 ++++++++++++++++-- doc/src/sgml/func.sgml | 118 ++++++++++++++++++--------------------------- 2 files changed, 90 insertions(+), 74 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index e1fb7d42493..6b72e80e569 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,4 +1,4 @@ - + Data Types @@ -3213,7 +3213,7 @@ SELECT * FROM test; <acronym>UUID</acronym> Type - + UUID @@ -3289,6 +3289,8 @@ a0eebc999c0b4ef8bb6d6bb9bd380a11 value is a full document or only a content fragment. + + Creating XML Values To produce a value of type xml from character data, use the function @@ -3299,7 +3301,7 @@ XMLPARSE ( { DOCUMENT | CONTENT } value) Examples: Manual...') -XMLPARSE (CONTENT 'abcbarfoo') +XMLPARSE (CONTENT 'abcbarfoo') ]]> While this is the only way to convert character strings into XML values according to the SQL standard, the PostgreSQL-specific @@ -3351,7 +3353,10 @@ SET xmloption TO { DOCUMENT | CONTENT }; The default is CONTENT, so all forms of XML data are allowed. + + + Encoding Handling Care must be taken when dealing with multiple character encodings on the client, server, and in the XML data passed through them. @@ -3398,6 +3403,41 @@ SET xmloption TO { DOCUMENT | CONTENT }; processed in UTF-8, computations will be most efficient if the server encoding is also UTF-8. + + + + Accessing XML Values + + + The xml data type is unusual in that it does not + provide any comparison operators. This is because there is no + well-defined and universally useful comparison algorithm for XML + data. One consequence of this is that you cannot retrieve rows by + comparing an xml column against a search value. XML + values should therefore typically be accompanied by a separate key + field such as an ID. An alternative solution for comparing XML + values is to convert them to character strings first, but note + that character string comparison has little to do with a useful + XML comparison method. + + + + Since there are no comparison operators for the xml + data type, it is not possible to create an index directly on a + column of this type. If speedy searches in XML data are desired, + possible workarounds would be casting the expression to a + character string type and indexing that, or indexing an XPath + expression. The actual query would of course have to be adjusted + to search by the indexed expression. + + + + The full-text search module Tsearch2 could also be used to speed + up full-document searches in XML data. The necessary + preprocessing support is, however, not available in the PostgreSQL + distribution in this release. + + &array; diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 6c901f9cca6..9dd25928eb4 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,4 +1,4 @@ - + Functions and Operators @@ -7512,7 +7512,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple type. The function-like expressions xmlparse and xmlserialize for converting to and from type xml are not repeated here. Use of many of these - xml functions requires the installation to have been built + functions requires the installation to have been built with configure --with-libxml. @@ -7848,6 +7848,51 @@ SELECT xmlroot(xmlparse(document 'abc'), + + Processing XML + + + XPath + + + + To process values of data type xml, PostgreSQL offers + the function xpath, which evaluates XPath 1.0 + expressions. + + + +xpath(xpath, xml, nsarray) + + + + The function xpath evaluates the XPath + expression xpath against the XML value + xml. It returns an array of XML values + corresponding to the node set produced by the XPath expression. + + + + The third argument of the function is an array of namespace + mappings. This array should be a two-dimensional array with the + length of the second axis being equal to 2 (i.e., it should be an + array of arrays, each of which consists of exactly 2 elements). + The first element of each array entry is the namespace name, the + second the namespace URI. + + + + Example: +test', ARRAY[ARRAY['my', 'http://example.com']]); + xpath +-------- + {test} +(1 row) +]]> + + + Mapping Tables to XML @@ -8097,75 +8142,6 @@ table2-mapping ]]> - - - 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. - - - - - -- cgit v1.2.3