> I'll take a closer read-through shortly.
Missing file. You omitted executor/tableexpr.h from the patch, so I
can't compile.
I've expanded and copy-edited the docs. Some of it is guesswork based
on the references you sent and a glance at the code. Please check my
changes carefully. I found a few surprises, like the fact that DEFAULT
isn't a normal literal, it's an xpath expression evaluated at the same
time as the rowexpression.
Updated patch attached as XMLTABLE-v3 includes the docs changes. Note
that it's missing tableexpr.h. For convenient review or to apply to
your working tree I also attach a diff of just my docs changes as
proposed-docs-changes.diff.
Docs:
- Can you send the sample data used to generate the example output?
I'd like to include at least a cut down part of it in the docs to make
it clear how the input correlates with output, and preferably put the
whole thing in an appendix.
- How does it decide what subset of the document to iterate over?
That's presumably rowexpr, which is xpath in postgresql? (I added this
to docs).
- xmlnamespaces clause in docs needs an example for a non-default namespace.
- What effect does xmlnamespaces clause have? Does supplying it allow
you to reference qualified names in xpath? What happens if you don't
specify it for a document that has namespaces or don't define all the
namespaces? What if you reference an undefined namespace in xpath?
What about if an undefined namespace isn't referenced by xpath, but is
inside a node selected by an xpath expression?
- What are the rules for converting the matched XML node into a value?
If the matched node is not a simple text node or lacks a text node as
its single child, what happens?
- What happens if the matched has multiple text node children? This
can happen if, for example, you have something like
<matchedNode>
some text <!-- comment splits up text node --> other text
</matchedNode>
- Is there a way to get an attribute as a value? If so, an example
should show this because it's going to be a common need. Presumably
you want node/@attrname ?
- What happens if COLUMNS is not specified at all? It looks like it
returns a single column result set with the matched entries as 'xml'
type, so added to docs, please verify.
- PASSING clause isn't really defined. You can specify one PASSING
entry as a literal/colref/expression, and it's the argument xml
document, right? The external docs you referred to say that PASSING
may have a BY VALUE keyword, alias its argument with AS, and may have
expressions, e.g.
PASSING BY VALUE '<x/>' AS a, '<y/>' AS b
Neither aliases nor multiple entries are supported by the code or
grammar. Should this be documented as a restriction? Do you know if
that's an extension by the other implementation or if it's SQL/XML
standard? (I've drafted a docs update to cover this in the updated
patch).
- What does BY REF mean? Should this just be mentioned with a "see
xmlexists(...)" since it seems to be compatibility noise? Is there a
corresponding BY VALUE or similar?
- The parser definitions re-use xmlexists_argument . I don't mind
that, but it's worth noting here in case others do.
- Why do the expression arguments take c_expr (anything allowed in
a_expr or b_expr), not b_expr (restricted expression) ?
- Column definitions are underdocumented. The grammar says they can be
NOT NULL, for example, but I don't see that in any of the references
you mailed me nor in the docs. What behaviour is expected for a NOT
NULL column? I've documented my best guess (not checked closely
against the code, please verify).
-
Test suggestions:
- Coverage of multiple text() node children of an element, where split
up by comment or similar
- Coverage of xpath that matches a node with child element nodes
More to come. Please review my docs changes in the mean time. I'm
spending a lot more time on this than I expected so I might have to
get onto other things for a while too.
--
Craig Ringer http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services
From 464e8f16386c0fbfb8b5c6fdee66402c95c6ae9f Mon Sep 17 00:00:00 2001
From: Craig Ringer <cr...@2ndquadrant.com>
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 '<?xml version="1.1"?><content>abc</content>'),
</para>
</sect3>
- <sect3>
+ <sect3 id="functions-xmltable" xreflabel="XMLTABLE">
<title><literal>xmltable</literal></title>
<indexterm>
@@ -10111,7 +10111,9 @@ SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
</synopsis>
<para>
- The <function>xmltable</function> produces table based on passed XML value.
+ The <function>xmltable</function> produces a table based on the
+ passed XML value, an xpath filter to extract rows, and an
+ optional set of column definitions.
</para>
<para>
@@ -10140,11 +10142,11 @@ SELECT xmltable.*
</para>
<para>
- The optional <literal>xmlnamespaces</literal> clause allow to specify a list
- of namespaces specified by <replaceable>namespace URI</replaceable> and
- <replaceable>namespace name</replaceable> (alias>. The default namespace is
- specified by <replaceable>namespace URI</replaceable> after keyword
- <literal>DEFAULT</literal>.
+ The optional <literal>xmlnamespaces</> clause is a comma-separated list of
+ namespaces of the form <replaceable>namespace-URI</> <literal>AS</>
+ <replaceable>namespace-name</>. It specifies the XML namespaces used in
+ the document and their aliases. The default namespace is specified with
+ <literal>DEFAULT</> <replaceable>namespace-URI</>.
<screen><
0001-XMLTABLE-v3.patch.gz
Description: GNU Zip compressed data
-- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers
