Skip to content

Commit c6736ff

Browse files
alvherrealvherre
committed
doc: move PARTITION OF stanza to just below PARTITION BY
It's more logical this way, since the new ordering matches the way the tables are created; but in any case, the previous location of PARTITION OF did not appear carefully chosen anyway (since it didn't match the location in which it appears in the synopsys either, which is what we normally do.) In the PARTITION BY stanza, add a link to the partitioning section in the DDL chapter, too. Suggested-by: David G. Johnston Discussion: https://postgr.es/m/CAKFQuwY4Ld7ecxL_KAmaxwt0FUu5VcPPN2L4dh+3BeYbrdBa5g@mail.gmail.com
1 parent 1c04d4b commit c6736ff

File tree

1 file changed

+139
-134
lines changed

1 file changed

+139
-134
lines changed

‎doc/src/sgml/ref/create_table.sgml‎

Lines changed: 139 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -251,6 +251,145 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
251251
</listitem>
252252
</varlistentry>
253253

254+
<varlistentry>
255+
<term><replaceable class="parameter">column_name</replaceable></term>
256+
<listitem>
257+
<para>
258+
The name of a column to be created in the new table.
259+
</para>
260+
</listitem>
261+
</varlistentry>
262+
263+
<varlistentry>
264+
<term><replaceable class="parameter">data_type</replaceable></term>
265+
<listitem>
266+
<para>
267+
The data type of the column. This can include array
268+
specifiers. For more information on the data types supported by
269+
<productname>PostgreSQL</productname>, refer to <xref
270+
linkend="datatype"/>.
271+
</para>
272+
</listitem>
273+
</varlistentry>
274+
275+
<varlistentry>
276+
<term><literal>COLLATE <replaceable>collation</replaceable></literal></term>
277+
<listitem>
278+
<para>
279+
The <literal>COLLATE</literal> clause assigns a collation to
280+
the column (which must be of a collatable data type).
281+
If not specified, the column data type's default collation is used.
282+
</para>
283+
</listitem>
284+
</varlistentry>
285+
286+
<varlistentry>
287+
<term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term>
288+
<listitem>
289+
<para>
290+
The optional <literal>INHERITS</literal> clause specifies a list of
291+
tables from which the new table automatically inherits all
292+
columns. Parent tables can be plain tables or foreign tables.
293+
</para>
294+
295+
<para>
296+
Use of <literal>INHERITS</literal> creates a persistent relationship
297+
between the new child table and its parent table(s). Schema
298+
modifications to the parent(s) normally propagate to children
299+
as well, and by default the data of the child table is included in
300+
scans of the parent(s).
301+
</para>
302+
303+
<para>
304+
If the same column name exists in more than one parent
305+
table, an error is reported unless the data types of the columns
306+
match in each of the parent tables. If there is no conflict,
307+
then the duplicate columns are merged to form a single column in
308+
the new table. If the column name list of the new table
309+
contains a column name that is also inherited, the data type must
310+
likewise match the inherited column(s), and the column
311+
definitions are merged into one. If the
312+
new table explicitly specifies a default value for the column,
313+
this default overrides any defaults from inherited declarations
314+
of the column. Otherwise, any parents that specify default
315+
values for the column must all specify the same default, or an
316+
error will be reported.
317+
</para>
318+
319+
<para>
320+
<literal>CHECK</literal> constraints are merged in essentially the same way as
321+
columns: if multiple parent tables and/or the new table definition
322+
contain identically-named <literal>CHECK</literal> constraints, these
323+
constraints must all have the same check expression, or an error will be
324+
reported. Constraints having the same name and expression will
325+
be merged into one copy. A constraint marked <literal>NO INHERIT</literal> in a
326+
parent will not be considered. Notice that an unnamed <literal>CHECK</literal>
327+
constraint in the new table will never be merged, since a unique name
328+
will always be chosen for it.
329+
</para>
330+
331+
<para>
332+
Column <literal>STORAGE</literal> settings are also copied from parent tables.
333+
</para>
334+
335+
<para>
336+
If a column in the parent table is an identity column, that property is
337+
not inherited. A column in the child table can be declared identity
338+
column if desired.
339+
</para>
340+
</listitem>
341+
</varlistentry>
342+
343+
<varlistentry>
344+
<term><literal>PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] ) </literal></term>
345+
<listitem>
346+
<para>
347+
The optional <literal>PARTITION BY</literal> clause specifies a strategy
348+
of partitioning the table. The table thus created is called a
349+
<firstterm>partitioned</firstterm> table. The parenthesized list of
350+
columns or expressions forms the <firstterm>partition key</firstterm>
351+
for the table. When using range or hash partitioning, the partition key
352+
can include multiple columns or expressions (up to 32, but this limit can
353+
be altered when building <productname>PostgreSQL</productname>), but for
354+
list partitioning, the partition key must consist of a single column or
355+
expression.
356+
</para>
357+
358+
<para>
359+
Range and list partitioning require a btree operator class, while hash
360+
partitioning requires a hash operator class. If no operator class is
361+
specified explicitly, the default operator class of the appropriate
362+
type will be used; if no default operator class exists, an error will
363+
be raised. When hash partitioning is used, the operator class used
364+
must implement support function 2 (see <xref linkend="xindex-support"/>
365+
for details).
366+
</para>
367+
368+
<para>
369+
A partitioned table is divided into sub-tables (called partitions),
370+
which are created using separate <literal>CREATE TABLE</literal> commands.
371+
The partitioned table is itself empty. A data row inserted into the
372+
table is routed to a partition based on the value of columns or
373+
expressions in the partition key. If no existing partition matches
374+
the values in the new row, an error will be reported.
375+
</para>
376+
377+
<para>
378+
Partitioned tables do not support <literal>EXCLUDE</literal> constraints;
379+
however, you can define these constraints on individual partitions.
380+
Also, while it's possible to define <literal>PRIMARY KEY</literal>
381+
constraints on partitioned tables, creating foreign keys that
382+
reference a partitioned table is not yet supported.
383+
</para>
384+
385+
<para>
386+
See <xref linkend="ddl-partitioning"/> for more discussion on table
387+
partitioning.
388+
</para>
389+
390+
</listitem>
391+
</varlistentry>
392+
254393
<varlistentry id="sql-createtable-partition">
255394
<term><literal>PARTITION OF <replaceable class="parameter">parent_table</replaceable> { FOR VALUES <replaceable class="parameter">partition_bound_spec</replaceable> | DEFAULT }</literal></term>
256395
<listitem>
@@ -421,140 +560,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
421560
</listitem>
422561
</varlistentry>
423562

424-
<varlistentry>
425-
<term><replaceable class="parameter">column_name</replaceable></term>
426-
<listitem>
427-
<para>
428-
The name of a column to be created in the new table.
429-
</para>
430-
</listitem>
431-
</varlistentry>
432-
433-
<varlistentry>
434-
<term><replaceable class="parameter">data_type</replaceable></term>
435-
<listitem>
436-
<para>
437-
The data type of the column. This can include array
438-
specifiers. For more information on the data types supported by
439-
<productname>PostgreSQL</productname>, refer to <xref
440-
linkend="datatype"/>.
441-
</para>
442-
</listitem>
443-
</varlistentry>
444-
445-
<varlistentry>
446-
<term><literal>COLLATE <replaceable>collation</replaceable></literal></term>
447-
<listitem>
448-
<para>
449-
The <literal>COLLATE</literal> clause assigns a collation to
450-
the column (which must be of a collatable data type).
451-
If not specified, the column data type's default collation is used.
452-
</para>
453-
</listitem>
454-
</varlistentry>
455-
456-
<varlistentry>
457-
<term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term>
458-
<listitem>
459-
<para>
460-
The optional <literal>INHERITS</literal> clause specifies a list of
461-
tables from which the new table automatically inherits all
462-
columns. Parent tables can be plain tables or foreign tables.
463-
</para>
464-
465-
<para>
466-
Use of <literal>INHERITS</literal> creates a persistent relationship
467-
between the new child table and its parent table(s). Schema
468-
modifications to the parent(s) normally propagate to children
469-
as well, and by default the data of the child table is included in
470-
scans of the parent(s).
471-
</para>
472-
473-
<para>
474-
If the same column name exists in more than one parent
475-
table, an error is reported unless the data types of the columns
476-
match in each of the parent tables. If there is no conflict,
477-
then the duplicate columns are merged to form a single column in
478-
the new table. If the column name list of the new table
479-
contains a column name that is also inherited, the data type must
480-
likewise match the inherited column(s), and the column
481-
definitions are merged into one. If the
482-
new table explicitly specifies a default value for the column,
483-
this default overrides any defaults from inherited declarations
484-
of the column. Otherwise, any parents that specify default
485-
values for the column must all specify the same default, or an
486-
error will be reported.
487-
</para>
488-
489-
<para>
490-
<literal>CHECK</literal> constraints are merged in essentially the same way as
491-
columns: if multiple parent tables and/or the new table definition
492-
contain identically-named <literal>CHECK</literal> constraints, these
493-
constraints must all have the same check expression, or an error will be
494-
reported. Constraints having the same name and expression will
495-
be merged into one copy. A constraint marked <literal>NO INHERIT</literal> in a
496-
parent will not be considered. Notice that an unnamed <literal>CHECK</literal>
497-
constraint in the new table will never be merged, since a unique name
498-
will always be chosen for it.
499-
</para>
500-
501-
<para>
502-
Column <literal>STORAGE</literal> settings are also copied from parent tables.
503-
</para>
504-
505-
<para>
506-
If a column in the parent table is an identity column, that property is
507-
not inherited. A column in the child table can be declared identity
508-
column if desired.
509-
</para>
510-
</listitem>
511-
</varlistentry>
512-
513-
<varlistentry>
514-
<term><literal>PARTITION BY { RANGE | LIST | HASH } ( { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] ) </literal></term>
515-
<listitem>
516-
<para>
517-
The optional <literal>PARTITION BY</literal> clause specifies a strategy
518-
of partitioning the table. The table thus created is called a
519-
<firstterm>partitioned</firstterm> table. The parenthesized list of
520-
columns or expressions forms the <firstterm>partition key</firstterm>
521-
for the table. When using range or hash partitioning, the partition key
522-
can include multiple columns or expressions (up to 32, but this limit can
523-
be altered when building <productname>PostgreSQL</productname>), but for
524-
list partitioning, the partition key must consist of a single column or
525-
expression.
526-
</para>
527-
528-
<para>
529-
Range and list partitioning require a btree operator class, while hash
530-
partitioning requires a hash operator class. If no operator class is
531-
specified explicitly, the default operator class of the appropriate
532-
type will be used; if no default operator class exists, an error will
533-
be raised. When hash partitioning is used, the operator class used
534-
must implement support function 2 (see <xref linkend="xindex-support"/>
535-
for details).
536-
</para>
537-
538-
<para>
539-
A partitioned table is divided into sub-tables (called partitions),
540-
which are created using separate <literal>CREATE TABLE</literal> commands.
541-
The partitioned table is itself empty. A data row inserted into the
542-
table is routed to a partition based on the value of columns or
543-
expressions in the partition key. If no existing partition matches
544-
the values in the new row, an error will be reported.
545-
</para>
546-
547-
<para>
548-
Partitioned tables do not support <literal>EXCLUDE</literal> constraints;
549-
however, you can define these constraints on individual partitions.
550-
Also, while it's possible to define <literal>PRIMARY KEY</literal>
551-
constraints on partitioned tables, creating foreign keys that
552-
reference a partitioned table is not yet supported.
553-
</para>
554-
555-
</listitem>
556-
</varlistentry>
557-
558563
<varlistentry>
559564
<term><literal>LIKE <replaceable>source_table</replaceable> [ <replaceable>like_option</replaceable> ... ]</literal></term>
560565
<listitem>

0 commit comments

Comments
 (0)