From 464e8f16386c0fbfb8b5c6fdee66402c95c6ae9f Mon Sep 17 00:00:00 2001 From: Craig Ringer Date: Mon, 12 Sep 2016 12:26:14 +0800 Subject: [PATCH] Proposed docs changes --- doc/src/sgml/func.sgml | 103 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 82 insertions(+), 21 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index ca861d2..3ba492e 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -10099,7 +10099,7 @@ SELECT xmlroot(xmlparse(document 'abc'), - + <literal>xmltable</literal> @@ -10111,7 +10111,9 @@ SELECT xmlroot(xmlparse(document 'abc'), - The xmltable produces table based on passed XML value. + The xmltable produces a table based on the + passed XML value, an xpath filter to extract rows, and an + optional set of column definitions. @@ -10140,11 +10142,11 @@ SELECT xmltable.* - The optional xmlnamespaces clause allow to specify a list - of namespaces specified by namespace URI and - namespace name (alias>. The default namespace is - specified by namespace URI after keyword - DEFAULT. + The optional xmlnamespaces clause is a comma-separated list of + namespaces of the form namespace-URI AS + namespace-name. It specifies the XML namespaces used in + the document and their aliases. The default namespace is specified with + DEFAULT namespace-URI. + The required rowexpr argument is an xpath + expression that is evaluated against the supplied XML document to + obtain an ordered sequence of XML nodes. This sequence is what + xmltable transforms into output rows. + + + + + The SQL/XML standard specifies the the + xmltable construct should take an XQuery + expression as the first argument, but PostgreSQL currently only + supports XPath, which is a subset of XQuery. + + + + + The PASSING xml clause provides the + XML document to operate on. The BY REF clauses have no effect in PostgreSQL, but are allowed for SQL conformance and compatibility - with other implementations. Per SQL standard, the - first BY REF is required, the second is - optional. Also note that the SQL standard specifies - the xmlexists construct to take an XQuery - expression as first argument, but PostgreSQL currently only - supports XPath, which is a subset of XQuery. + with other implementations. Per the SQL/XML standard, the first + BY REF is required, the second is optional. + Passing BY VALUE is not supported. Multiple + comma-separated terms in the PASSING clause are not supported. + AS aliases are not supported. - The optional COLUMNS clause allow to specify a list - of colums of generated table. The column with special mark - FOR ORDINALITY ensures row numbers in this column. - When PATH is not defined, then the name of column is - used as implicit path. Only one column should be marked FOR ORDINALITY. - When path expression is empty, then possible DEFAULT value - is used. -COLUMNS clause specifies the list + of colums in the generated table. If the whole + COLUMNS list is omitted, then the result set is a + single column where each row is a field of xml type + containing the data matched by the rowexpr. + Otherwise each entry describes a single column. See the syntax + summary above for the format. The column name and type are + required; the path and not-null specifier are optional. + + + + + Column names and types are identifiers so unlike normal + function arguments they may not be specified as bind parameters, + column references, or expressions. The path and default are + ordinary values. + + + + + The PATH for a column is an xpath expression that is + evaluated for each row, relative to the result of the + rowexpr, to find the value of the column. If no + PATH is given then the column name is used as an + implicit path. + + + + If the path expression does not match for a given row but a + DEFAULT xpath expression is specified, the resulting + default value is used. If no DEFAULT is given the + field will be NULL. Note that unlike + PATH, the DEFAULT for a column is + evaluated only once, relative to the root of the + xml argument, when processing begins. + + + + Columns may be marked NOT NULL. If the xpath expression + for a NOT NULL column does not match anything and there + is no DEFAULT or the DEFAULT also evaluated + to null then the function terminates with an ERROR. + + + + A column marked with the + FOR ORDINALITY keyword will be populated with + row numbers that match the order in which the the output rows appeared + in the original input XML document. Only one column should be + marked FOR ORDINALITY. 10'); -- 2.5.5