contrib/xml2/README.xml2

   1 XML-handling functions for PostgreSQL
   2 =====================================
   3
   4 Development of this module was sponsored by Torchbox Ltd. (www.torchbox.com)
   5 It has the same BSD licence as PostgreSQL.
   6
   7 This version of the XML functions provides both XPath querying and
   8 XSLT functionality. There is also a new table function which allows
   9 the straightforward return of multiple XML results. Note that the current code
  10 doesn't take any particular care over character sets - this is
  11 something that should be fixed at some point!
  12
  13 Installation
  14 ------------
  15
  16 The current build process will only work if the files are in
  17 contrib/xml in a PostgreSQL 7.3 or 7.4 source tree which has been
  18 configured and built (If you alter the subdir value in the Makefile
  19 you can place it in a different directory in a PostgreSQL tree).
  20
  21 Before you begin, just check the Makefile, and then just 'make' and
  22 'make install'.
  23
  24 This code requires libxml to be previously installed.
  25
  26 Description of functions
  27 ------------------------
  28
  29 The first set of functions are straightforward XML parsing and XPath queries:
  30
  31 xml_valid(document) RETURNS bool
  32
  33 This parses the document text in its parameter and returns true if the
  34 document is well-formed XML.
  35
  36 xpath_string(document,query) RETURNS text
  37 xpath_number(document,query) RETURNS float4
  38 xpath_bool(document,query) RETURNS bool
  39
  40 These functions evaluate the XPath query on the supplied document, and
  41 cast the result to the specified type.
  42
  43
  44 xpath_nodeset(document,query,toptag,itemtag) RETURNS text
  45
  46 This evaluates query on document and wraps the result in XML tags. If
  47 the result is multivalued, the output will look like:
  48
  49 <toptag>
  50 <itemtag>Value 1 which could be an XML fragment</itemtag>
  51 <itemtag>Value 2....</itemtag>
  52 </toptag>
  53
  54 If either toptag or itemtag is an empty string, the relevant tag is omitted.
  55 There are also wrapper functions for this operation:
  56
  57 xpath_nodeset(document,query) RETURNS text omits both tags.
  58 xpath_nodeset(document,query,itemtag) RETURNS text omits toptag.
  59
  60
  61 xpath_list(document,query,seperator) RETURNS text
  62
  63 This function returns multiple values seperated by the specified
  64 seperator, e.g. Value 1,Value 2,Value 3 if seperator=','.
  65
  66 xpath_list(document,query) RETURNS text
  67
  68 This is a wrapper for the above function that uses ',' as the seperator.
  69
  70
  71 xpath_table
  72 -----------
  73
  74 This is a table function which evaluates a set of XPath queries on
  75 each of a set of documents and returns the results as a table. The
  76 primary key field from the original document table is returned as the
  77 first column of the result so that the resultset from xpath_table can
  78 be readily used in joins.
  79
  80 The function itself takes 5 arguments, all text.
  81
  82 xpath_table(key,document,relation,xpaths,criteria)
  83
  84 key - the name of the "key" field - this is just a field to be used as
  85 the first column of the output table i.e. it identifies the record from
  86 which each output row came.
  87
  88 document - the name of the field containing the XML document
  89
  90 relation - the name of the table or view containing the documents
  91
  92 xpaths - multiple xpath expressions separated by |
  93
  94 criteria - The contents of the where clause. This needs to be specified,
  95 so use "true" or "1=1" here if you want to process all the rows in the
  96 relation.
  97
  98 NB These parameters (except the XPath strings) are just substituted
  99 into a plain SQL SELECT statement, so you have some flexibility - the
 100 statement is
 101
 102 SELECT <key>,<document> FROM <relation> WHERE <criteria>
 103
 104 so those parameters can be *anything* valid in those particular
 105 locations. The result from this SELECT needs to return exactly two
 106 columns (which it will unless you try to list multiple fields for key
 107 or document). Beware that this simplistic approach requires that you
 108 validate any user-supplied values to avoid SQL injection attacks.
 109
 110 Using the function
 111
 112 The function has to be used in a FROM expression. This gives the following
 113 form:
 114
 115 SELECT * FROM
 116 xpath_table('article_id',
 117         'article_xml',
 118         'articles',
 119         '/article/author|/article/pages|/article/title',
 120         'date_entered > ''2003-01-01'' ')
 121 AS t(article_id integer, author text, page_count integer, title text);
 122
 123 The AS clause defines the names and types of the columns in the
 124 virtual table. If there are more XPath queries than result columns,
 125 the extra queries will be ignored. If there are more result columns
 126 than XPath queries, the extra columns will be NULL.
 127
 128 Note that I've said in this example that pages is an integer.  The
 129 function deals internally with string representations, so when you say
 130 you want an integer in the output, it will take the string
 131 representation of the XPath result and use PostgreSQL input functions
 132 to transform it into an integer (or whatever type the AS clause
 133 requests). An error will result if it can't do this - for example if
 134 the result is empty - so you may wish to just stick to 'text' as the
 135 column type if you think your data has any problems.
 136
 137 The select statement doesn't need to use * alone - it can reference the
 138 columns by name or join them to other tables. The function produces a
 139 virtual table with which you can perform any operation you wish (e.g.
 140 aggregation, joining, sorting etc). So we could also have:
 141
 142 SELECT t.title, p.fullname, p.email
 143 FROM xpath_table('article_id','article_xml','articles',
 144             '/article/title|/article/author/@id',
 145             'xpath_string(article_xml,''/article/@date'') > ''2003-03-20'' ')
 146             AS t(article_id integer, title text, author_id integer),
 147      tblPeopleInfo AS p
 148 WHERE t.author_id = p.person_id;
 149
 150 as a more complicated example. Of course, you could wrap all
 151 of this in a view for convenience.
 152
 153 XSLT functions
 154 --------------
 155
 156 The following functions are available if libxslt is installed (this is
 157 not currently detected automatically, so you will have to amend the
 158 Makefile)
 159
 160 xslt_process(document,stylesheet,paramlist) RETURNS text
 161
 162 This function appplies the XSL stylesheet to the document and returns
 163 the transformed result. The paramlist is a list of parameter
 164 assignments to be used in the transformation, specified in the form
 165 'a=1,b=2'. Note that this is also proof-of-concept code and the
 166 parameter parsing is very simple-minded (e.g. parameter values cannot
 167 contain commas!)
 168
 169 Also note that if either the document or stylesheet values do not
 170 begin with a < then they will be treated as URLs and libxslt will
 171 fetch them. It thus follows that you can use xslt_process as a means
 172 to fetch the contents of URLs - you should be aware of the security
 173 implications of this.
 174
 175 There is also a two-parameter version of xslt_process which does not
 176 pass any parameters to the transformation.
 177
 178 If you have any comments or suggestions, please do contact me at
 179 jgray@azuli.co.uk. Unfortunately, this isn't my main job, so I can't
 180 guarantee a rapid response to your query!