Skip to content

Commit fcec6ca

Browse files
alvherrealvherre
committed
Support XMLTABLE query expression
XMLTABLE is defined by the SQL/XML standard as a feature that allows turning XML-formatted data into relational form, so that it can be used as a <table primary> in the FROM clause of a query. This new construct provides significant simplicity and performance benefit for XML data processing; what in a client-side custom implementation was reported to take 20 minutes can be executed in 400ms using XMLTABLE. (The same functionality was said to take 10 seconds using nested PostgreSQL XPath function calls, and 5 seconds using XMLReader under PL/Python). The implemented syntax deviates slightly from what the standard requires. First, the standard indicates that the PASSING clause is optional and that multiple XML input documents may be given to it; we make it mandatory and accept a single document only. Second, we don't currently support a default namespace to be specified. This implementation relies on a new executor node based on a hardcoded method table. (Because the grammar is fixed, there is no extensibility in the current approach; further constructs can be implemented on top of this such as JSON_TABLE, but they require changes to core code.) Author: Pavel Stehule, Álvaro Herrera Extensively reviewed by: Craig Ringer Discussion: https://postgr.es/m/CAFj8pRAgfzMD-LoSmnMGybD0WsEznLHWap8DO79+-GTRAPR4qA@mail.gmail.com
1 parent 270d7dd commit fcec6ca

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+4606
-50
lines changed

‎contrib/pg_stat_statements/pg_stat_statements.c‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2400,6 +2400,9 @@ JumbleRangeTable(pgssJumbleState *jstate, List *rtable)
24002400
case RTE_FUNCTION:
24012401
JumbleExpr(jstate, (Node *) rte->functions);
24022402
break;
2403+
case RTE_TABLEFUNC:
2404+
JumbleExpr(jstate, (Node *) rte->tablefunc);
2405+
break;
24032406
case RTE_VALUES:
24042407
JumbleExpr(jstate, (Node *) rte->values_lists);
24052408
break;
@@ -2868,6 +2871,15 @@ JumbleExpr(pgssJumbleState *jstate, Node *node)
28682871
JumbleExpr(jstate, rtfunc->funcexpr);
28692872
}
28702873
break;
2874+
case T_TableFunc:
2875+
{
2876+
TableFunc *tablefunc = (TableFunc *) node;
2877+
2878+
JumbleExpr(jstate, tablefunc->docexpr);
2879+
JumbleExpr(jstate, tablefunc->rowexpr);
2880+
JumbleExpr(jstate, (Node *) tablefunc->colexprs);
2881+
}
2882+
break;
28712883
case T_TableSampleClause:
28722884
{
28732885
TableSampleClause *tsc = (TableSampleClause *) node;

‎doc/src/sgml/func.sgml‎

Lines changed: 202 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10332,7 +10332,8 @@ SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuf
1033210332
To process values of data type <type>xml</type>, PostgreSQL offers
1033310333
the functions <function>xpath</function> and
1033410334
<function>xpath_exists</function>, which evaluate XPath 1.0
10335-
expressions.
10335+
expressions, and the <function>XMLTABLE</function>
10336+
table function.
1033610337
</para>
1033710338

1033810339
<sect3 id="functions-xml-processing-xpath">
@@ -10430,6 +10431,206 @@ SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</m
1043010431
--------------
1043110432
t
1043210433
(1 row)
10434+
]]></screen>
10435+
</para>
10436+
</sect3>
10437+
10438+
<sect3 id="functions-xml-processing-xmltable">
10439+
<title><literal>xmltable</literal></title>
10440+
10441+
<indexterm>
10442+
<primary>xmltable</primary>
10443+
</indexterm>
10444+
10445+
<indexterm zone="functions-xml-processing-xmltable">
10446+
<primary>table function</primary>
10447+
<secondary>XMLTABLE</secondary>
10448+
</indexterm>
10449+
10450+
<synopsis>
10451+
<function>xmltable</function>( <optional>XMLNAMESPACES(<replaceable>namespace uri</replaceable> AS <replaceable>namespace name</replaceable><optional>, ...</optional>)</optional>
10452+
<replaceable>row_expression</replaceable> PASSING <optional>BY REF</optional> <replaceable>document_expression</replaceable> <optional>BY REF</optional>
10453+
COLUMNS <replaceable>name</replaceable> { <replaceable>type</replaceable> <optional>PATH <replaceable>column_expression</replaceable></optional> <optional>DEFAULT <replaceable>default_expression</replaceable></optional> <optional>NOT NULL | NULL</optional>
10454+
| FOR ORDINALITY }
10455+
<optional>, ...</optional>
10456+
)
10457+
</synopsis>
10458+
10459+
<para>
10460+
The <function>xmltable</function> function produces a table based
10461+
on the given XML value, an XPath filter to extract rows, and an
10462+
optional set of column definitions.
10463+
</para>
10464+
10465+
<para>
10466+
The optional <literal>XMLNAMESPACES</> clause is a comma-separated
10467+
list of namespaces. It specifies the XML namespaces used in
10468+
the document and their aliases. A default namespace specification
10469+
is not currently supported.
10470+
</para>
10471+
10472+
<para>
10473+
The required <replaceable>row_expression</> argument is an XPath
10474+
expression that is evaluated against the supplied XML document to
10475+
obtain an ordered sequence of XML nodes. This sequence is what
10476+
<function>xmltable</> transforms into output rows.
10477+
</para>
10478+
10479+
<para>
10480+
<replaceable>document_expression</> provides the XML document to
10481+
operate on.
10482+
The <literal>BY REF</literal> clauses have no effect in PostgreSQL,
10483+
but are allowed for SQL conformance and compatibility with other
10484+
implementations.
10485+
The argument must be a well-formed XML document; fragments/forests
10486+
are not accepted.
10487+
</para>
10488+
10489+
<para>
10490+
The mandatory <literal>COLUMNS</literal> clause specifies the list
10491+
of columns in the output table.
10492+
If the <literal>COLUMNS</> clause is omitted, the rows in the result
10493+
set contain a single column of type <literal>xml</> containing the
10494+
data matched by <replaceable>row_expression</>.
10495+
If <literal>COLUMNS</literal> is specified, each entry describes a
10496+
single column.
10497+
See the syntax summary above for the format.
10498+
The column name and type are required; the path, default and
10499+
nullability clauses are optional.
10500+
</para>
10501+
10502+
<para>
10503+
A column marked <literal>FOR ORDINALITY</literal> will be populated
10504+
with row numbers matching the order in which the
10505+
output rows appeared in the original input XML document.
10506+
At most one column may be marked <literal>FOR ORDINALITY</literal>.
10507+
</para>
10508+
10509+
<para>
10510+
The <literal>column_expression</> for a column is an XPath expression
10511+
that is evaluated for each row, relative to the result of the
10512+
<replaceable>row_expression</>, to find the value of the column.
10513+
If no <literal>column_expression</> is given, then the column name
10514+
is used as an implicit path.
10515+
</para>
10516+
10517+
<para>
10518+
If a column's XPath expression returns multiple elements, an error
10519+
is raised.
10520+
If the expression matches an empty tag, the result is an
10521+
empty string (not <literal>NULL</>).
10522+
Any <literal>xsi:nil</> attributes are ignored.
10523+
</para>
10524+
10525+
<para>
10526+
The text body of the XML matched by the <replaceable>column_expression</>
10527+
is used as the column value. Multiple <literal>text()</literal> nodes
10528+
within an element are concatenated in order. Any child elements,
10529+
processing instructions, and comments are ignored, but the text contents
10530+
of child elements are concatenated to the result.
10531+
Note that the whitespace-only <literal>text()</> node between two non-text
10532+
elements is preserved, and that leading whitespace on a <literal>text()</>
10533+
node is not flattened.
10534+
</para>
10535+
10536+
<para>
10537+
If the path expression does not match for a given row but
10538+
<replaceable>default_expression</> is specified, the value resulting
10539+
from evaluating that expression is used.
10540+
If no <literal>DEFAULT</> clause is given for the column,
10541+
the field will be set to <literal>NULL</>.
10542+
It is possible for a <replaceable>default_expression</> to reference
10543+
the value of output columns that appear prior to it in the column list,
10544+
so the default of one column may be based on the value of another
10545+
column.
10546+
</para>
10547+
10548+
<para>
10549+
Columns may be marked <literal>NOT NULL</>. If the
10550+
<replaceable>column_expression</> for a <literal>NOT NULL</> column
10551+
does not match anything and there is no <literal>DEFAULT</> or the
10552+
<replaceable>default_expression</> also evaluates to null, an error
10553+
is reported.
10554+
</para>
10555+
10556+
<para>
10557+
Unlike regular PostgreSQL functions, <replaceable>column_expression</>
10558+
and <replaceable>default_expression</> are not evaluated to a simple
10559+
value before calling the function.
10560+
<replaceable>column_expression</> is normally evaluated
10561+
exactly once per input row, and <replaceable>default_expression</>
10562+
is evaluated each time a default is needed for a field.
10563+
If the expression qualifies as stable or immutable the repeat
10564+
evaluation may be skipped.
10565+
Effectively <function>xmltable</> behaves more like a subquery than a
10566+
function call.
10567+
This means that you can usefully use volatile functions like
10568+
<function>nextval</> in <replaceable>default_expression</>, and
10569+
<replaceable>column_expression</> may depend on other parts of the
10570+
XML document.
10571+
</para>
10572+
10573+
<para>
10574+
Examples:
10575+
<screen><![CDATA[
10576+
CREATE TABLE xmldata AS SELECT
10577+
xml $$
10578+
<ROWS>
10579+
<ROW id="1">
10580+
<COUNTRY_ID>AU</COUNTRY_ID>
10581+
<COUNTRY_NAME>Australia</COUNTRY_NAME>
10582+
</ROW>
10583+
<ROW id="5">
10584+
<COUNTRY_ID>JP</COUNTRY_ID>
10585+
<COUNTRY_NAME>Japan</COUNTRY_NAME>
10586+
<PREMIER_NAME>Shinzo Abe</PREMIER_NAME>
10587+
<SIZE unit="sq_mi">145935</SIZE>
10588+
</ROW>
10589+
<ROW id="6">
10590+
<COUNTRY_ID>SG</COUNTRY_ID>
10591+
<COUNTRY_NAME>Singapore</COUNTRY_NAME>
10592+
<SIZE unit="sq_km">697</SIZE>
10593+
</ROW>
10594+
</ROWS>
10595+
$$ AS data;
10596+
10597+
SELECT xmltable.*
10598+
FROM xmldata,
10599+
XMLTABLE('//ROWS/ROW'
10600+
PASSING data
10601+
COLUMNS id int PATH '@id',
10602+
ordinality FOR ORDINALITY,
10603+
"COUNTRY_NAME" text,
10604+
country_id text PATH 'COUNTRY_ID',
10605+
size_sq_km float PATH 'SIZE[@unit = "sq_km"]',
10606+
size_other text PATH
10607+
'concat(SIZE[@unit!="sq_km"], " ", SIZE[@unit!="sq_km"]/@unit)',
10608+
premier_name text PATH 'PREMIER_NAME' DEFAULT 'not specified') ;
10609+
10610+
id | ordinality | COUNTRY_NAME | country_id | size_sq_km | size_other | premier_name
10611+
----+------------+--------------+------------+------------+--------------+---------------
10612+
1 | 1 | Australia | AU | | | not specified
10613+
5 | 2 | Japan | JP | | 145935 sq_mi | Shinzo Abe
10614+
6 | 3 | Singapore | SG | 697 | | not specified
10615+
]]></screen>
10616+
10617+
The following example shows concatenation of multiple text() nodes,
10618+
usage of the column name as XPath filter, and the treatment of whitespace,
10619+
XML comments and processing instructions:
10620+
10621+
<screen><![CDATA[
10622+
CREATE TABLE xmlelements AS SELECT
10623+
xml $$
10624+
<root>
10625+
<element> Hello<!-- xyxxz -->2a2<?aaaaa?> <!--x--> bbb<x>xxx</x>CC </element>
10626+
</root>
10627+
$$ AS data;
10628+
10629+
SELECT xmltable.*
10630+
FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
10631+
element
10632+
----------------------
10633+
Hello2a2 bbbCC
1043310634
]]></screen>
1043410635
</para>
1043510636
</sect3>

‎src/backend/commands/explain.c‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -781,6 +781,7 @@ ExplainPreScanNode(PlanState *planstate, Bitmapset **rels_used)
781781
case T_TidScan:
782782
case T_SubqueryScan:
783783
case T_FunctionScan:
784+
case T_TableFuncScan:
784785
case T_ValuesScan:
785786
case T_CteScan:
786787
case T_WorkTableScan:
@@ -926,6 +927,9 @@ ExplainNode(PlanState *planstate, List *ancestors,
926927
case T_FunctionScan:
927928
pname = sname = "Function Scan";
928929
break;
930+
case T_TableFuncScan:
931+
pname = sname = "Table Function Scan";
932+
break;
929933
case T_ValuesScan:
930934
pname = sname = "Values Scan";
931935
break;
@@ -1103,6 +1107,7 @@ ExplainNode(PlanState *planstate, List *ancestors,
11031107
case T_TidScan:
11041108
case T_SubqueryScan:
11051109
case T_FunctionScan:
1110+
case T_TableFuncScan:
11061111
case T_ValuesScan:
11071112
case T_CteScan:
11081113
case T_WorkTableScan:
@@ -1416,6 +1421,20 @@ ExplainNode(PlanState *planstate, List *ancestors,
14161421
show_instrumentation_count("Rows Removed by Filter", 1,
14171422
planstate, es);
14181423
break;
1424+
case T_TableFuncScan:
1425+
if (es->verbose)
1426+
{
1427+
TableFunc *tablefunc = ((TableFuncScan *) plan)->tablefunc;
1428+
1429+
show_expression((Node *) tablefunc,
1430+
"Table Function Call", planstate, ancestors,
1431+
es->verbose, es);
1432+
}
1433+
show_scan_qual(plan->qual, "Filter", planstate, ancestors, es);
1434+
if (plan->qual)
1435+
show_instrumentation_count("Rows Removed by Filter", 1,
1436+
planstate, es);
1437+
break;
14191438
case T_TidScan:
14201439
{
14211440
/*
@@ -2593,6 +2612,11 @@ ExplainTargetRel(Plan *plan, Index rti, ExplainState *es)
25932612
objecttag = "Function Name";
25942613
}
25952614
break;
2615+
case T_TableFuncScan:
2616+
Assert(rte->rtekind == RTE_TABLEFUNC);
2617+
objectname = "xmltable";
2618+
objecttag = "Table Function Name";
2619+
break;
25962620
case T_ValuesScan:
25972621
Assert(rte->rtekind == RTE_VALUES);
25982622
break;

‎src/backend/executor/Makefile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ OBJS = execAmi.o execCurrent.o execGrouping.o execIndexing.o execJunk.o \
2626
nodeSamplescan.o nodeSeqscan.o nodeSetOp.o nodeSort.o nodeUnique.o \
2727
nodeValuesscan.o nodeCtescan.o nodeWorktablescan.o \
2828
nodeGroup.o nodeSubplan.o nodeSubqueryscan.o nodeTidscan.o \
29-
nodeForeignscan.o nodeWindowAgg.o tstoreReceiver.o tqueue.o spi.o
29+
nodeForeignscan.o nodeWindowAgg.o tstoreReceiver.o tqueue.o spi.o \
30+
nodeTableFuncscan.o
3031

3132
include $(top_srcdir)/src/backend/common.mk

‎src/backend/executor/execAmi.c‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848
#include "executor/nodeSort.h"
4949
#include "executor/nodeSubplan.h"
5050
#include "executor/nodeSubqueryscan.h"
51+
#include "executor/nodeTableFuncscan.h"
5152
#include "executor/nodeTidscan.h"
5253
#include "executor/nodeUnique.h"
5354
#include "executor/nodeValuesscan.h"
@@ -198,6 +199,10 @@ ExecReScan(PlanState *node)
198199
ExecReScanFunctionScan((FunctionScanState *) node);
199200
break;
200201

202+
case T_TableFuncScanState:
203+
ExecReScanTableFuncScan((TableFuncScanState *) node);
204+
break;
205+
201206
case T_ValuesScanState:
202207
ExecReScanValuesScan((ValuesScanState *) node);
203208
break;
@@ -564,6 +569,7 @@ ExecMaterializesOutput(NodeTag plantype)
564569
{
565570
case T_Material:
566571
case T_FunctionScan:
572+
case T_TableFuncScan:
567573
case T_CteScan:
568574
case T_WorkTableScan:
569575
case T_Sort:

‎src/backend/executor/execProcnode.c‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@
110110
#include "executor/nodeSort.h"
111111
#include "executor/nodeSubplan.h"
112112
#include "executor/nodeSubqueryscan.h"
113+
#include "executor/nodeTableFuncscan.h"
113114
#include "executor/nodeTidscan.h"
114115
#include "executor/nodeUnique.h"
115116
#include "executor/nodeValuesscan.h"
@@ -239,6 +240,11 @@ ExecInitNode(Plan *node, EState *estate, int eflags)
239240
estate, eflags);
240241
break;
241242

243+
case T_TableFuncScan:
244+
result = (PlanState *) ExecInitTableFuncScan((TableFuncScan *) node,
245+
estate, eflags);
246+
break;
247+
242248
case T_ValuesScan:
243249
result = (PlanState *) ExecInitValuesScan((ValuesScan *) node,
244250
estate, eflags);
@@ -459,6 +465,10 @@ ExecProcNode(PlanState *node)
459465
result = ExecFunctionScan((FunctionScanState *) node);
460466
break;
461467

468+
case T_TableFuncScanState:
469+
result = ExecTableFuncScan((TableFuncScanState *) node);
470+
break;
471+
462472
case T_ValuesScanState:
463473
result = ExecValuesScan((ValuesScanState *) node);
464474
break;
@@ -715,6 +725,10 @@ ExecEndNode(PlanState *node)
715725
ExecEndFunctionScan((FunctionScanState *) node);
716726
break;
717727

728+
case T_TableFuncScanState:
729+
ExecEndTableFuncScan((TableFuncScanState *) node);
730+
break;
731+
718732
case T_ValuesScanState:
719733
ExecEndValuesScan((ValuesScanState *) node);
720734
break;

0 commit comments

Comments
 (0)