Skip to content

Commit 39ef95f

Browse files
yugo-nCommitfest Bot
yugo-n
authored and
Commitfest Bot
committed
Add documentations about Incremental View Maintenance
1 parent 6581086 commit 39ef95f

File tree

5 files changed

+583
-4
lines changed

5 files changed

+583
-4
lines changed

‎doc/src/sgml/catalogs.sgml

+9
Original file line numberDiff line numberDiff line change
@@ -2231,6 +2231,15 @@ SCRAM-SHA-256$<replaceable>&lt;iteration count&gt;</replaceable>:<replaceable>&l
22312231
</para></entry>
22322232
</row>
22332233

2234+
<row>
2235+
<entry role="catalog_table_entry"><para role="column_definition">
2236+
<structfield>relisivm</structfield> <type>bool</type>
2237+
</para>
2238+
<para>
2239+
True if relation is incrementally maintainable materialized view
2240+
</para></entry>
2241+
</row>
2242+
22342243
<row>
22352244
<entry role="catalog_table_entry"><para role="column_definition">
22362245
<structfield>relrewrite</structfield> <type>oid</type>

‎doc/src/sgml/ref/create_materialized_view.sgml

+122-2
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ PostgreSQL documentation
2121

2222
<refsynopsisdiv>
2323
<synopsis>
24-
CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
24+
CREATE [ INCREMENTAL ] MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
2525
[ (<replaceable>column_name</replaceable> [, ...] ) ]
2626
[ USING <replaceable class="parameter">method</replaceable> ]
2727
[ WITH ( <replaceable class="parameter">storage_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] ) ]
@@ -60,6 +60,125 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
6060
<title>Parameters</title>
6161

6262
<variablelist>
63+
<varlistentry>
64+
<term><literal>INCREMENTAL</literal></term>
65+
<listitem>
66+
<para>
67+
If specified, some triggers are automatically created so that the rows
68+
of the materialized view are immediately updated when base tables of the
69+
materialized view are updated. In general, this allows faster update of
70+
the materialized view at a price of slower update of the base tables
71+
because the triggers will be invoked. We call this form of materialized
72+
view as "Incrementally Maintainable Materialized View" (IMMV).
73+
</para>
74+
<para>
75+
When <acronym>IMMV</acronym> is defined without using <command>WITH NO DATA</command>,
76+
a unique index is created on the view automatically if possible. If the view
77+
definition query has a GROUP BY clause, a unique index is created on the columns
78+
of GROUP BY expressions. Also, if the view has DISTINCT clause, a unique index
79+
is created on all columns in the target list. Otherwise, if the view contains all
80+
primary key attritubes of its base tables in the target list, a unique index is
81+
created on these attritubes. In other cases, no index is created.
82+
</para>
83+
<para>
84+
There are restrictions of query definitions allowed to use this
85+
option. The following are supported in query definitions for IMMV:
86+
<itemizedlist>
87+
88+
<listitem>
89+
<para>
90+
Inner joins (including self-joins).
91+
</para>
92+
</listitem>
93+
94+
<listitem>
95+
<para>
96+
Some built-in aggregate functions (count, sum, avg, min, max) without a HAVING
97+
clause.
98+
</para>
99+
</listitem>
100+
</itemizedlist>
101+
102+
Unsupported queries with this option include the following:
103+
104+
<itemizedlist>
105+
<listitem>
106+
<para>
107+
Outer joins.
108+
</para>
109+
</listitem>
110+
111+
<listitem>
112+
<para>
113+
Sub-queries.
114+
</para>
115+
</listitem>
116+
117+
<listitem>
118+
<para>
119+
Aggregate functions other than built-in count, sum, avg, min and max.
120+
</para>
121+
</listitem>
122+
<listitem>
123+
<para>
124+
Aggregate functions with a HAVING clause.
125+
</para>
126+
</listitem>
127+
<listitem>
128+
<para>
129+
DISTINCT ON, WINDOW, VALUES, LIMIT and OFFSET clause.
130+
</para>
131+
</listitem>
132+
</itemizedlist>
133+
134+
Other restrictions include:
135+
<itemizedlist>
136+
137+
<listitem>
138+
<para>
139+
IMMVs must be based on simple base tables. It's not supported to
140+
create them on top of views or materialized views.
141+
</para>
142+
</listitem>
143+
144+
<listitem>
145+
<para>
146+
It is not supported to include system columns in an IMMV.
147+
<programlisting>
148+
CREATE INCREMENTAL MATERIALIZED VIEW mv_ivm02 AS SELECT i,j FROM mv_base_a WHERE xmin = '610';
149+
ERROR: system column is not supported with IVM
150+
</programlisting>
151+
</para>
152+
</listitem>
153+
154+
<listitem>
155+
<para>
156+
Non-immutable functions are not supported.
157+
<programlisting>
158+
CREATE INCREMENTAL MATERIALIZED VIEW mv_ivm12 AS SELECT i,j FROM mv_base_a WHERE i = random()::int;
159+
ERROR: functions in IMMV must be marked IMMUTABLE
160+
</programlisting>
161+
</para>
162+
</listitem>
163+
164+
<listitem>
165+
<para>
166+
IMMVs do not support expressions that contains aggregates
167+
</para>
168+
</listitem>
169+
170+
<listitem>
171+
<para>
172+
Logical replication does not support IMMVs.
173+
</para>
174+
</listitem>
175+
176+
</itemizedlist>
177+
178+
</para>
179+
</listitem>
180+
</varlistentry>
181+
63182
<varlistentry>
64183
<term><literal>IF NOT EXISTS</literal></term>
65184
<listitem>
@@ -155,7 +274,8 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
155274
This clause specifies whether or not the materialized view should be
156275
populated at creation time. If not, the materialized view will be
157276
flagged as unscannable and cannot be queried until <command>REFRESH
158-
MATERIALIZED VIEW</command> is used.
277+
MATERIALIZED VIEW</command> is used. Also, if the view is IMMV,
278+
triggers for maintaining the view are not created.
159279
</para>
160280
</listitem>
161281
</varlistentry>

‎doc/src/sgml/ref/refresh_materialized_view.sgml

+6-2
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,13 @@ REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] <replaceable class="parameter">name</
3636
privilege on the materialized view. The old contents are discarded. If
3737
<literal>WITH DATA</literal> is specified (or defaults) the backing query
3838
is executed to provide the new data, and the materialized view is left in a
39-
scannable state. If <literal>WITH NO DATA</literal> is specified no new
39+
scannable state. If the view is an incrementally maintainable materialized
40+
view (IMMV) and was unpopulated, triggers for maintaining the view are
41+
created. Also, a unique index is created for IMMV if it is possible and the
42+
view doesn't have that yet.
43+
If <literal>WITH NO DATA</literal> is specified no new
4044
data is generated and the materialized view is left in an unscannable
41-
state.
45+
state. If the view is IMMV, the triggers are dropped.
4246
</para>
4347
<para>
4448
<literal>CONCURRENTLY</literal> and <literal>WITH NO DATA</literal> may not

0 commit comments

Comments
 (0)