rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: improve CREATE TABLE ref page's discussion of partition bounds. 

Clarify in the syntax synopsis that partition bound values must be
exactly numeric literals or string literals; previously it
said "bound_literal" which was defined nowhere.

Replace confusing --- and, I think, incorrect in detail --- definition
of how range bounds work with a reference to row-wise comparison plus
a concrete example (which I stole from Robert Haas).

Minor copy-editing in the same area.

Discussion: https://postgr.es/m/30475.1496005465@sss.pgh.pa.us
Discussion: https://postgr.es/m/28106.1496041449@sss.pgh.pa.us
This commit is contained in:
Tom Lane 2017-06-07 17:23:38 -04:00
parent ae9bfc5d65
commit 0198c277a2
1 changed files with 44 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
doc/src/sgml/ref/create_table.sgml
View File

@ -86,8 +86,9 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<phrase>and <replaceable class="PARAMETER">partition_bound_spec</replaceable> is:</phrase>
{ IN ( { <replaceable class="PARAMETER">bound_literal</replaceable> | NULL } [, ...] ) |
FROM ( { <replaceable class="PARAMETER">bound_literal</replaceable> | UNBOUNDED } [, ...] ) TO ( { <replaceable class="PARAMETER">bound_literal</replaceable> | UNBOUNDED } [, ...] ) }
IN ( { <replaceable class="PARAMETER">numeric_literal</replaceable> | <replaceable class="PARAMETER">string_literal</replaceable> | NULL } [, ...] ) |
FROM ( { <replaceable class="PARAMETER">numeric_literal</replaceable> | <replaceable class="PARAMETER">string_literal</replaceable> | UNBOUNDED } [, ...] )
TO ( { <replaceable class="PARAMETER">numeric_literal</replaceable> | <replaceable class="PARAMETER">string_literal</replaceable> | UNBOUNDED } [, ...] )
<phrase><replaceable class="PARAMETER">index_parameters</replaceable> in <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal> constraints are:</phrase>
@ -252,44 +253,26 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<term><literal>PARTITION OF <replaceable class="PARAMETER">parent_table</replaceable> FOR VALUES <replaceable class="PARAMETER">partition_bound_spec</replaceable></literal></term>
<listitem>
<para>
Creates the table as <firstterm>partition</firstterm> of the specified
Creates the table as a <firstterm>partition</firstterm> of the specified
parent table.
</para>
<para>
The partition bound specification must correspond to the partitioning
method and partition key of the parent table, and must not overlap with
any existing partition of that parent.
The <replaceable class="PARAMETER">partition_bound_spec</replaceable>
must correspond to the partitioning method and partition key of the
parent table, and must not overlap with any existing partition of that
parent. The form with <literal>IN</> is used for list partitioning,
while the form with <literal>FROM</> and <literal>TO</> is used for
range partitioning.
</para>
<para>
Each of the values specified in the partition bound specification is
Each of the values specified in
the <replaceable class="PARAMETER">partition_bound_spec</> is
a literal, <literal>NULL</literal>, or <literal>UNBOUNDED</literal>.
A literal is either a numeric constant or a string constant that is
coercible to the corresponding partition key column's type.
</para>
<para>
When creating a range partition, the lower bound specified with
<literal>FROM</literal> is an inclusive bound, whereas the upper
bound specified with <literal>TO</literal> is an exclusive bound.
That is, the values specified in the <literal>FROM</literal> list
are accepted values of the corresponding partition key columns in a
given partition, whereas those in the <literal>TO</literal> list are
not. To be precise, this applies only to the first of the partition
key columns for which the corresponding values in the <literal>FROM</literal>
and <literal>TO</literal> lists are not equal. All rows in a given
partition contain the same values for all preceding columns, equal to
those specified in <literal>FROM</literal> and <literal>TO</literal>
lists. On the other hand, any subsequent columns are insignificant
as far as implicit partition constraint is concerned.
</para>
<para>
Specifying <literal>UNBOUNDED</literal> in <literal>FROM</literal>
signifies <literal>-infinity</literal> as the lower bound of the
corresponding column, whereas it signifies <literal>+infinity</literal>
as the upper bound when specified in <literal>TO</literal>.
Each literal value must be either a numeric constant that is coercible
to the corresponding partition key column's type, or a string literal
that is valid input for that type.
</para>
<para>
@ -300,6 +283,32 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
cannot be specified for range partitions.
</para>
<para>
When creating a range partition, the lower bound specified with
<literal>FROM</literal> is an inclusive bound, whereas the upper
bound specified with <literal>TO</literal> is an exclusive bound.
That is, the values specified in the <literal>FROM</literal> list
are valid values of the corresponding partition key columns for this
partition, whereas those in the <literal>TO</literal> list are
not. Note that this statement must be understood according to the
rules of row-wise comparison (<xref linkend="row-wise-comparison">).
For example, given <literal>PARTITION BY RANGE (x,y)</>, a partition
bound <literal>FROM (1, 2) TO (3, 4)</literal>
allows <literal>x=1</> with any <literal>y&gt;=2</>,
<literal>x=2</> with any non-null <literal>y</>,
and <literal>x=3</> with any <literal>y&lt;4</>.
</para>
<para>
Writing <literal>UNBOUNDED</literal> in <literal>FROM</literal>
signifies <literal>-infinity</literal> as the lower bound of the
corresponding column, whereas when written in <literal>TO</literal>,
it signifies <literal>+infinity</literal> as the upper bound.
All items following an <literal>UNBOUNDED</literal> item within
a <literal>FROM</literal> or <literal>TO</literal> list must also
be <literal>UNBOUNDED</literal>.
</para>
<para>
A partition must have the same column names and types as the partitioned
table to which it belongs. If the parent is specified <literal>WITH
@ -318,8 +327,9 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<para>
Rows inserted into a partitioned table will be automatically routed to
the correct partition. If no suitable partition exists, an error will
occur. Also, if updating a row in a given partition causes it to move
to another partition due to the new partition key, an error will occur.
occur. Also, if updating a row in a given partition would require it
to move to another partition due to new partition key values, an error
will occur.
</para>
<para>