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

Commit 2d0c1d3

Browse files
tglsfdctglsfdc
committed
Documentation fixes for FILLFACTOR patch. Minor other editorialization.
1 parent 655787b commit 2d0c1d3

File tree

6 files changed

+373
-161
lines changed

6 files changed

+373
-161
lines changed

‎doc/src/sgml/ref/alter_index.sgml

Lines changed: 54 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_index.sgml,v 1.9 2006/07/02 02:23:17 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_index.sgml,v 1.10 2006/07/04 18:07:24 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -22,8 +22,8 @@ PostgreSQL documentation
2222
<synopsis>
2323
ALTER INDEX <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
2424
ALTER INDEX <replaceable class="PARAMETER">name</replaceable> SET TABLESPACE <replaceable class="PARAMETER">tablespace_name</replaceable>
25-
ALTER INDEX <replaceable class="PARAMETER">name</replaceable> SET (FILLFACTOR = <replaceable class="PARAMETER">fillfactor</replaceable>)
26-
ALTER INDEX <replaceable class="PARAMETER">name</replaceable> RESET (FILLFACTOR)
25+
ALTER INDEX <replaceable class="PARAMETER">name</replaceable> SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )
26+
ALTER INDEX <replaceable class="PARAMETER">name</replaceable> RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )
2727
</synopsis>
2828
</refsynopsisdiv>
2929

@@ -59,21 +59,28 @@ ALTER INDEX <replaceable class="PARAMETER">name</replaceable> RESET (FILLFACTOR)
5959
</varlistentry>
6060

6161
<varlistentry>
62-
<term><literal>SET (FILLFACTOR)</literal></term>
62+
<term><literal>SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )</literal></term>
6363
<listitem>
6464
<para>
65-
This form changes the index's fillfactor to the specified percentage.
66-
Index structure is not modified immediately; use <literal>REINDEX</literal>
67-
to ensure reflection of the change.
65+
This form changes one or more index-method-specific storage parameters
66+
for the index. See
67+
<xref linkend="SQL-CREATEINDEX" endterm="sql-createindex-title">
68+
for details on the available parameters. Note that the index contents
69+
will not be modified immediately by this command; depending on the
70+
parameter you may need to rebuild the index with
71+
<xref linkend="SQL-REINDEX" endterm="sql-reindex-title">
72+
to get the desired effects.
6873
</para>
6974
</listitem>
7075
</varlistentry>
7176

7277
<varlistentry>
73-
<term><literal>RESET (FILLFACTOR)</literal></term>
78+
<term><literal>RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )</literal></term>
7479
<listitem>
7580
<para>
76-
This form changes the index's fillfactor to the default value.
81+
This form resets one or more index-method-specific storage parameters to
82+
their defaults. As with <literal>SET</>, a <literal>REINDEX</literal>
83+
may be needed to update the index entirely.
7784
</para>
7885
</listitem>
7986
</varlistentry>
@@ -116,6 +123,25 @@ ALTER INDEX <replaceable class="PARAMETER">name</replaceable> RESET (FILLFACTOR)
116123
</listitem>
117124
</varlistentry>
118125

126+
<varlistentry>
127+
<term><replaceable class="PARAMETER">storage_parameter</replaceable></term>
128+
<listitem>
129+
<para>
130+
The name of an index-method-specific storage parameter.
131+
</para>
132+
</listitem>
133+
</varlistentry>
134+
135+
<varlistentry>
136+
<term><replaceable class="PARAMETER">value</replaceable></term>
137+
<listitem>
138+
<para>
139+
The new value for an index-method-specific storage parameter.
140+
This might be a number or a word depending on the parameter.
141+
</para>
142+
</listitem>
143+
</varlistentry>
144+
119145
</variablelist>
120146
</refsect1>
121147

@@ -154,6 +180,15 @@ ALTER INDEX distributors RENAME TO suppliers;
154180
To move an index to a different tablespace:
155181
<programlisting>
156182
ALTER INDEX distributors SET TABLESPACE fasttablespace;
183+
</programlisting>
184+
</para>
185+
186+
<para>
187+
To change an index's fill factor (assuming that the index method
188+
supports it):
189+
<programlisting>
190+
ALTER INDEX distributors SET (fillfactor = 75);
191+
REINDEX INDEX distributors;
157192
</programlisting>
158193
</para>
159194

@@ -167,6 +202,16 @@ ALTER INDEX distributors SET TABLESPACE fasttablespace;
167202
extension.
168203
</para>
169204
</refsect1>
205+
206+
207+
<refsect1>
208+
<title>See Also</title>
209+
210+
<simplelist type="inline">
211+
<member><xref linkend="sql-createindex" endterm="sql-createindex-title"></member>
212+
<member><xref linkend="sql-reindex" endterm="sql-reindex-title"></member>
213+
</simplelist>
214+
</refsect1>
170215
</refentry>
171216

172217
<!-- Keep this comment at the end of the file

‎doc/src/sgml/ref/alter_table.sgml

Lines changed: 75 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.86 2006/07/02 02:23:17 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.87 2006/07/04 18:07:24 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -46,8 +46,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
4646
CLUSTER ON <replaceable class="PARAMETER">index_name</replaceable>
4747
SET WITHOUT CLUSTER
4848
SET WITHOUT OIDS
49-
SET (FILLFACTOR = <replaceable class="PARAMETER">fillfactor</replaceable>)
50-
RESET (FILLFACTOR)
49+
SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )
50+
RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )
5151
INHERIT <replaceable class="PARAMETER">parent_table</replaceable>
5252
NO INHERIT <replaceable class="PARAMETER">parent_table</replaceable>
5353
OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
@@ -254,47 +254,79 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
254254
</varlistentry>
255255

256256
<varlistentry>
257-
<term><literal>INHERIT <replaceable class="PARAMETER">parent_table</replaceable></literal></term>
257+
<term><literal>SET ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] )</literal></term>
258258
<listitem>
259259
<para>
260+
This form changes one or more storage parameters for the table. See
261+
<xref linkend="SQL-CREATETABLE" endterm="sql-createtable-title">
262+
for details on the available parameters. Note that the table contents
263+
will not be modified immediately by this command; depending on the
264+
parameter you may need to rewrite the table to get the desired effects.
265+
That can be done with <xref linkend="SQL-CLUSTER"
266+
endterm="sql-cluster-title"> or one of the forms of <command>ALTER
267+
TABLE</> that forces a table rewrite.
268+
</para>
269+
270+
<note>
271+
<para>
272+
While <command>CREATE TABLE</> allows <literal>OIDS</> to be specified
273+
in the <literal>WITH (<replaceable
274+
class="PARAMETER">storage_parameter</>)</literal> syntax,
275+
<command>ALTER TABLE</> does not treat <literal>OIDS</> as a
276+
storage parameter.
277+
</para>
278+
</note>
279+
</listitem>
280+
</varlistentry>
260281

282+
<varlistentry>
283+
<term><literal>RESET ( <replaceable class="PARAMETER">storage_parameter</replaceable> [, ... ] )</literal></term>
284+
<listitem>
285+
<para>
286+
This form resets one or more storage parameters to their
287+
defaults. As with <literal>SET</>, a table rewrite may be
288+
needed to update the table entirely.
289+
</para>
290+
</listitem>
291+
</varlistentry>
292+
293+
<varlistentry>
294+
<term><literal>INHERIT <replaceable class="PARAMETER">parent_table</replaceable></literal></term>
295+
<listitem>
296+
<para>
261297
This form adds a new parent table to the table. This won't add new
262298
columns to the child table, instead all columns of the parent table must
263299
already exist in the child table. They must have matching data types,
264300
and if they have <literal>NOT NULL</literal> constraints in the parent
265301
then they must also have <literal>NOT NULL</literal> constraints in the
266302
child.
303+
</para>
267304

268-
</para>
269-
<para>
270-
305+
<para>
271306
There must also be matching table constraints for all
272307
<literal>CHECK</literal> table constraints of the parent. Currently
273308
<literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, and
274309
<literal>FOREIGN KEY</literal> constraints are ignored however this may
275310
change in the future.
311+
</para>
276312

277-
</para>
278-
<para>
279-
313+
<para>
280314
The easiest way to create a suitable table is to create a table using
281315
<literal>INHERITS</literal> and then remove it via <literal>NO
282316
INHERIT</literal>. Alternatively create a table using
283317
<literal>LIKE</literal> however note that <literal>LIKE</literal> does
284318
not create the necessary constraints.
285-
286319
</para>
287-
288320
</listitem>
289321
</varlistentry>
290322

291323
<varlistentry>
292324
<term><literal>NO INHERIT <replaceable class="PARAMETER">parent_table</replaceable></literal></term>
293325
<listitem>
294326
<para>
295-
This form removes a parent table from the list of parents of the table.
296-
Queries against the parent table will no longer include records drawn
297-
from the target table.
327+
This form removes a parent table from the list of parents of the table.
328+
Queries against the parent table will no longer include records drawn
329+
from the target table.
298330
</para>
299331
</listitem>
300332
</varlistentry>
@@ -323,26 +355,6 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
323355
</listitem>
324356
</varlistentry>
325357

326-
<varlistentry>
327-
<term><literal>SET (FILLFACTOR)</literal></term>
328-
<listitem>
329-
<para>
330-
This form changes the table's fillfactor to the specified percentage.
331-
Table structure is not modified immediately; use <literal>CLUSTER</literal>
332-
to ensure reflection of the change.
333-
</para>
334-
</listitem>
335-
</varlistentry>
336-
337-
<varlistentry>
338-
<term><literal>RESET</literal></term>
339-
<listitem>
340-
<para>
341-
This form changes the table's fillfactor to the default value.
342-
</para>
343-
</listitem>
344-
</varlistentry>
345-
346358
<varlistentry>
347359
<term><literal>RENAME</literal></term>
348360
<listitem>
@@ -524,6 +536,34 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
524536
</listitem>
525537
</varlistentry>
526538

539+
<varlistentry>
540+
<term><replaceable class="PARAMETER">storage_parameter</replaceable></term>
541+
<listitem>
542+
<para>
543+
The name of a table storage parameter.
544+
</para>
545+
</listitem>
546+
</varlistentry>
547+
548+
<varlistentry>
549+
<term><replaceable class="PARAMETER">value</replaceable></term>
550+
<listitem>
551+
<para>
552+
The new value for a table storage parameter.
553+
This might be a number or a word depending on the parameter.
554+
</para>
555+
</listitem>
556+
</varlistentry>
557+
558+
<varlistentry>
559+
<term><replaceable class="PARAMETER">parent_table</replaceable></term>
560+
<listitem>
561+
<para>
562+
A parent table to associate or de-associate with this table.
563+
</para>
564+
</listitem>
565+
</varlistentry>
566+
527567
<varlistentry>
528568
<term><replaceable class="PARAMETER">new_owner</replaceable></term>
529569
<listitem>

‎doc/src/sgml/ref/create_index.sgml

Lines changed: 57 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.53 2006/07/02 02:23:17 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.54 2006/07/04 18:07:24 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -22,7 +22,7 @@ PostgreSQL documentation
2222
<synopsis>
2323
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <replaceable class="parameter">table</replaceable> [ USING <replaceable class="parameter">method</replaceable> ]
2424
( { <replaceable class="parameter">column</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [ <replaceable class="parameter">opclass</replaceable> ] [, ...] )
25-
[ WITH (FILLFACTOR = <replaceable>fillfactor</replaceable>) ]
25+
[ WITH ( <replaceable class="PARAMETER">storage_parameter</replaceable> = <replaceable class="PARAMETER">value</replaceable> [, ... ] ) ]
2626
[ TABLESPACE <replaceable class="parameter">tablespace</replaceable> ]
2727
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
2828
</synopsis>
@@ -56,7 +56,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
5656

5757
<para>
5858
<productname>PostgreSQL</productname> provides the index methods
59-
B-tree, hash, and GiST. Users can also define their own index
59+
B-tree, hash, GiST, and GIN. Users can also define their own index
6060
methods, but that is fairly complicated.
6161
</para>
6262

@@ -136,7 +136,7 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
136136
<para>
137137
The name of the index method to be used. Choices are
138138
<literal>btree</literal>, <literal>hash</literal>,
139-
and <literal>gist</literal>. The
139+
<literal>gist</literal>, and <literal>gin</>. The
140140
default method is <literal>btree</literal>.
141141
</para>
142142
</listitem>
@@ -173,10 +173,11 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
173173
</varlistentry>
174174

175175
<varlistentry>
176-
<term><replaceable class="parameter">fillfactor</replaceable></term>
176+
<term><replaceable class="parameter">storage_parameter</replaceable></term>
177177
<listitem>
178178
<para>
179-
The index's fillfactor in percentage.
179+
The name of an index-method-specific storage parameter. See
180+
below for details.
180181
</para>
181182
</listitem>
182183
</varlistentry>
@@ -203,6 +204,41 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">name</replaceable> ON <re
203204
</varlistentry>
204205

205206
</variablelist>
207+
208+
<refsect2 id="SQL-CREATEINDEX-storage-parameters">
209+
<title id="SQL-CREATEINDEX-storage-parameters-title">Index Storage Parameters</title>
210+
211+
<para>
212+
The <literal>WITH</> clause can specify <firstterm>storage parameters</>
213+
for indexes. Each index method can have its own set of allowed storage
214+
parameters. The built-in index methods all accept a single parameter:
215+
</para>
216+
217+
<variablelist>
218+
219+
<varlistentry>
220+
<term><literal>FILLFACTOR</></term>
221+
<listitem>
222+
<para>
223+
The fillfactor for an index is a percentage that determines how full
224+
the index method will try to pack index pages. For B-trees, pages
225+
are filled to this percentage during initial index build, and also
226+
when extending the index at the right (largest key values). If pages
227+
subsequently become completely full, they will be split, leading to
228+
gradual degradation in the index's efficiency. B-trees use a default
229+
fillfactor of 90, but any value from 70 to 100 can be selected.
230+
If the table is static then fillfactor 100 is best to minimize the
231+
index's physical size, but for heavily updated tables a smaller
232+
fillfactor is better to minimize the need for page splits. The
233+
other index methods use fillfactor in different but roughly analogous
234+
ways; the default fillfactor and allowed range varies.
235+
</para>
236+
</listitem>
237+
</varlistentry>
238+
239+
</variablelist>
240+
241+
</refsect2>
206242
</refsect1>
207243

208244
<refsect1>
@@ -271,6 +307,21 @@ CREATE UNIQUE INDEX title_idx ON films (title);
271307
</programlisting>
272308
</para>
273309

310+
<para>
311+
To create an index on the expression <literal>lower(title)</>,
312+
allowing efficient case-insensitive searches:
313+
<programlisting>
314+
CREATE INDEX lower_title_idx ON films ((lower(title)));
315+
</programlisting>
316+
</para>
317+
318+
<para>
319+
To create an index with non-default fill factor:
320+
<programlisting>
321+
CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70);
322+
</programlisting>
323+
</para>
324+
274325
<para>
275326
To create an index on the column <literal>code</> in the table
276327
<literal>films</> and have the index reside in the tablespace

0 commit comments

Comments
 (0)