Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit a1a4459

Browse files
committed
doc: Improve documentation related to table partitioning feature.
Commit f0e4475 implemented table partitioning, but failed to mention the "no row movement" restriction in the documentation. Fix that and a few other issues. Amit Langote, with some additional wordsmithing by me.
1 parent 3856cf9 commit a1a4459

File tree

4 files changed

+34
-14
lines changed

4 files changed

+34
-14
lines changed

doc/src/sgml/ref/alter_table.sgml

+2-2
Original file line numberDiff line numberDiff line change
@@ -715,7 +715,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
715715
</varlistentry>
716716

717717
<varlistentry>
718-
<term><literal>ATTACH PARTITION</literal> <replaceable class="PARAMETER">partition_name</replaceable> <replaceable class="PARAMETER">partition_bound_spec</replaceable></term>
718+
<term><literal>ATTACH PARTITION</literal> <replaceable class="PARAMETER">partition_name</replaceable> FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable></term>
719719
<listitem>
720720
<para>
721721
This form attaches an existing table (which might itself be partitioned)
@@ -1332,7 +1332,7 @@ ALTER TABLE measurement
13321332
Attach a partition to list partitioned table:
13331333
<programlisting>
13341334
ALTER TABLE cities
1335-
ATTACH PARTITION cities_west FOR VALUES IN ('Los Angeles', 'San Francisco');
1335+
ATTACH PARTITION cities_ab FOR VALUES IN ('a', 'b');
13361336
</programlisting></para>
13371337

13381338
<para>

doc/src/sgml/ref/create_table.sgml

+13-12
Original file line numberDiff line numberDiff line change
@@ -248,7 +248,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
248248
</varlistentry>
249249

250250
<varlistentry>
251-
<term><literal>PARTITION OF <replaceable class="PARAMETER">parent_table</replaceable></literal></term>
251+
<term><literal>PARTITION OF <replaceable class="PARAMETER">parent_table</replaceable></literal> FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable></term>
252252
<listitem>
253253
<para>
254254
Creates the table as <firstterm>partition</firstterm> of the specified
@@ -275,7 +275,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
275275
<para>
276276
Rows inserted into a partitioned table will be automatically routed to
277277
the correct partition. If no suitable partition exists, an error will
278-
occur.
278+
occur. Also, if updating a row in a given partition causes it to move
279+
to another partition due to the new partition key, an error will occur.
279280
</para>
280281

281282
<para>
@@ -1477,7 +1478,6 @@ CREATE TABLE employees OF employee_type (
14771478
Create a range partitioned table:
14781479
<programlisting>
14791480
CREATE TABLE measurement (
1480-
city_id int not null,
14811481
logdate date not null,
14821482
peaktemp int,
14831483
unitsales int
@@ -1488,40 +1488,41 @@ CREATE TABLE measurement (
14881488
Create a list partitioned table:
14891489
<programlisting>
14901490
CREATE TABLE cities (
1491+
city_id bigserial not null,
14911492
name text not null,
1492-
population int,
1493-
) PARTITION BY LIST (initcap(name));
1493+
population bigint,
1494+
) PARTITION BY LIST (left(lower(name), 1));
14941495
</programlisting></para>
14951496

14961497
<para>
14971498
Create partition of a range partitioned table:
14981499
<programlisting>
14991500
CREATE TABLE measurement_y2016m07
15001501
PARTITION OF measurement (
1501-
unitsales WITH OPTIONS DEFAULT 0
1502+
unitsales DEFAULT 0
15021503
) FOR VALUES FROM ('2016-07-01') TO ('2016-08-01');
15031504
</programlisting></para>
15041505

15051506
<para>
15061507
Create partition of a list partitioned table:
15071508
<programlisting>
1508-
CREATE TABLE cities_west
1509+
CREATE TABLE cities_ab
15091510
PARTITION OF cities (
15101511
CONSTRAINT city_id_nonzero CHECK (city_id != 0)
1511-
) FOR VALUES IN ('Los Angeles', 'San Francisco');
1512+
) FOR VALUES IN ('a', 'b');
15121513
</programlisting></para>
15131514

15141515
<para>
15151516
Create partition of a list partitioned table that is itself further
15161517
partitioned and then add a partition to it:
15171518
<programlisting>
1518-
CREATE TABLE cities_west
1519+
CREATE TABLE cities_ab
15191520
PARTITION OF cities (
15201521
CONSTRAINT city_id_nonzero CHECK (city_id != 0)
1521-
) FOR VALUES IN ('Los Angeles', 'San Francisco') PARTITION BY RANGE (population);
1522+
) FOR VALUES IN ('a', 'b') PARTITION BY RANGE (population);
15221523

1523-
CREATE TABLE cities_west_10000_to_100000
1524-
PARTITION OF cities_west FOR VALUES FROM (10000) TO (100000);
1524+
CREATE TABLE cities_ab_10000_to_100000
1525+
PARTITION OF cities_ab FOR VALUES FROM (10000) TO (100000);
15251526
</programlisting></para>
15261527
</refsect1>
15271528

doc/src/sgml/ref/insert.sgml

+11
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,17 @@ INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</repl
526526
updated by the command.
527527
</para>
528528
</refsect1>
529+
530+
<refsect1>
531+
<title>Notes</title>
532+
533+
<para>
534+
If the specified table is a partitioned table, each row is routed to
535+
the appropriate partition and inserted into it. If the specified table
536+
is a partition, an error will occur if one of the input rows violates
537+
the partition constraint.
538+
</para>
539+
</refsect1>
529540

530541
<refsect1>
531542
<title>Examples</title>

doc/src/sgml/ref/update.sgml

+8
Original file line numberDiff line numberDiff line change
@@ -279,6 +279,14 @@ UPDATE <replaceable class="parameter">count</replaceable>
279279
sub-selects is safer, though often harder to read and slower than
280280
using a join.
281281
</para>
282+
283+
<para>
284+
In the case of a partitioned table, updating a row might cause it to no
285+
longer satisfy the partition constraint. Since there is no provision to
286+
move the row to the partition appropriate to the new value of its
287+
partitioning key, an error will occur in this case. This can also happen
288+
when updating a partition directly.
289+
</para>
282290
</refsect1>
283291

284292
<refsect1>

0 commit comments

Comments
 (0)