Skip to content

P
Postgres FD Implementation
Commit c30446b9 authored by Tom Lane's avatar Tom Lane
Browse files
Options

Proofreading for Bruce's recent round of documentation proofreading. 

Most of those changes were good, but some not so good ...
parent e8d78d35
Show whitespace changes
Inline Side-by-side
Showing with 514 additions and 440 deletions
doc/src/sgml/advanced.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.58 2009/04/27 16:27:35 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.59 2009/06/17 21:58:48 tgl Exp $ -->
<chapter id="tutorial-advanced"> <chapter id="tutorial-advanced">
<title>Advanced Features</title> <title>Advanced Features</title>
...@@ -19,7 +19,7 @@ ...@@ -19,7 +19,7 @@
<para> <para>
This chapter will on occasion refer to examples found in <xref This chapter will on occasion refer to examples found in <xref
linkend="tutorial-sql"> to change or improve them, so it will be linkend="tutorial-sql"> to change or improve them, so it will be
good if you have read that chapter. Some examples from useful to have read that chapter. Some examples from
this chapter can also be found in this chapter can also be found in
<filename>advanced.sql</filename> in the tutorial directory. This <filename>advanced.sql</filename> in the tutorial directory. This
file also contains some sample data to load, which is not file also contains some sample data to load, which is not
...@@ -173,7 +173,7 @@ UPDATE branches SET balance = balance + 100.00 ...@@ -173,7 +173,7 @@ UPDATE branches SET balance = balance + 100.00
</para> </para>
<para> <para>
The details of these commands are not important; the important The details of these commands are not important here; the important
point is that there are several separate updates involved to accomplish point is that there are several separate updates involved to accomplish
this rather simple operation. Our bank's officers will want to be this rather simple operation. Our bank's officers will want to be
assured that either all these updates happen, or none of them happen. assured that either all these updates happen, or none of them happen.
......
doc/src/sgml/array.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.69 2009/04/27 16:27:35 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.70 2009/06/17 21:58:48 tgl Exp $ -->
<sect1 id="arrays"> <sect1 id="arrays">
<title>Arrays</title> <title>Arrays</title>
...@@ -60,18 +60,17 @@ CREATE TABLE tictactoe ( ...@@ -60,18 +60,17 @@ CREATE TABLE tictactoe (
</para> </para>
<para> <para>
In addition, the current implementation does not enforce the declared The current implementation does not enforce the declared
number of dimensions either. Arrays of a particular element type are number of dimensions either. Arrays of a particular element type are
all considered to be of the same type, regardless of size or number all considered to be of the same type, regardless of size or number
of dimensions. So, declaring the number of dimensions or sizes in of dimensions. So, declaring the array size or number of dimensions in
<command>CREATE TABLE</command> is simply documentation, it does not <command>CREATE TABLE</command> is simply documentation; it does not
affect run-time behavior. affect run-time behavior.
</para> </para>
<para> <para>
An alternative syntax, which conforms to the SQL standard by using An alternative syntax, which conforms to the SQL standard by using
they keyword <literal>ARRAY</>, can the keyword <literal>ARRAY</>, can be used for one-dimensional arrays.
be used for one-dimensional arrays;
<structfield>pay_by_quarter</structfield> could have been defined <structfield>pay_by_quarter</structfield> could have been defined
as: as:
<programlisting> <programlisting>
...@@ -109,7 +108,7 @@ CREATE TABLE tictactoe ( ...@@ -109,7 +108,7 @@ CREATE TABLE tictactoe (
for the type, as recorded in its <literal>pg_type</literal> entry. for the type, as recorded in its <literal>pg_type</literal> entry.
Among the standard data types provided in the Among the standard data types provided in the
<productname>PostgreSQL</productname> distribution, all use a comma <productname>PostgreSQL</productname> distribution, all use a comma
(<literal>,</>), except for the type <literal>box</> which uses a semicolon (<literal>,</>), except for type <type>box</> which uses a semicolon
(<literal>;</>). Each <replaceable>val</replaceable> is (<literal>;</>). Each <replaceable>val</replaceable> is
either a constant of the array element type, or a subarray. An example either a constant of the array element type, or a subarray. An example
of an array constant is: of an array constant is:
...@@ -121,7 +120,7 @@ CREATE TABLE tictactoe ( ...@@ -121,7 +120,7 @@ CREATE TABLE tictactoe (
</para> </para>
<para> <para>
To set an element of an array to NULL, write <literal>NULL</> To set an element of an array constant to NULL, write <literal>NULL</>
for the element value. (Any upper- or lower-case variant of for the element value. (Any upper- or lower-case variant of
<literal>NULL</> will do.) If you want an actual string value <literal>NULL</> will do.) If you want an actual string value
<quote>NULL</>, you must put double quotes around it. <quote>NULL</>, you must put double quotes around it.
...@@ -417,14 +416,14 @@ SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]]; ...@@ -417,14 +416,14 @@ SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
</para> </para>
<para> <para>
The concatenation operator allows a single element to be pushed to the The concatenation operator allows a single element to be pushed onto the
beginning or end of a one-dimensional array. It also accepts two beginning or end of a one-dimensional array. It also accepts two
<replaceable>N</>-dimensional arrays, or an <replaceable>N</>-dimensional <replaceable>N</>-dimensional arrays, or an <replaceable>N</>-dimensional
and an <replaceable>N+1</>-dimensional array. and an <replaceable>N+1</>-dimensional array.
</para> </para>
<para> <para>
When a single element is pushed to either the beginning or end of a When a single element is pushed onto either the beginning or end of a
one-dimensional array, the result is an array with the same lower bound one-dimensional array, the result is an array with the same lower bound
subscript as the array operand. For example: subscript as the array operand. For example:
<programlisting> <programlisting>
...@@ -463,7 +462,7 @@ SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]); ...@@ -463,7 +462,7 @@ SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]);
</para> </para>
<para> <para>
When an <replaceable>N</>-dimensional array is pushed to the beginning When an <replaceable>N</>-dimensional array is pushed onto the beginning
or end of an <replaceable>N+1</>-dimensional array, the result is or end of an <replaceable>N+1</>-dimensional array, the result is
analogous to the element-array case above. Each <replaceable>N</>-dimensional analogous to the element-array case above. Each <replaceable>N</>-dimensional
sub-array is essentially an element of the <replaceable>N+1</>-dimensional sub-array is essentially an element of the <replaceable>N+1</>-dimensional
...@@ -601,9 +600,9 @@ SELECT * FROM ...@@ -601,9 +600,9 @@ SELECT * FROM
around the array value plus delimiter characters between adjacent items. around the array value plus delimiter characters between adjacent items.
The delimiter character is usually a comma (<literal>,</>) but can be The delimiter character is usually a comma (<literal>,</>) but can be
something else: it is determined by the <literal>typdelim</> setting something else: it is determined by the <literal>typdelim</> setting
for the array's element type. (Among the standard data types provided for the array's element type. Among the standard data types provided
in the <productname>PostgreSQL</productname> distribution, all in the <productname>PostgreSQL</productname> distribution, all use a comma,
use a comma, except for <literal>box</>, which uses a semicolon (<literal>;</>).) except for type <type>box</>, which uses a semicolon (<literal>;</>).
In a multidimensional array, each dimension (row, plane, In a multidimensional array, each dimension (row, plane,
cube, etc.) gets its own level of curly braces, and delimiters cube, etc.) gets its own level of curly braces, and delimiters
must be written between adjacent curly-braced entities of the same level. must be written between adjacent curly-braced entities of the same level.
...@@ -657,7 +656,7 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 ...@@ -657,7 +656,7 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
As shown previously, when writing an array value you can use double As shown previously, when writing an array value you can use double
quotes around any individual array element. You <emphasis>must</> do so quotes around any individual array element. You <emphasis>must</> do so
if the element value would otherwise confuse the array-value parser. if the element value would otherwise confuse the array-value parser.
For example, elements containing curly braces, commas (or the matching For example, elements containing curly braces, commas (or the data type's
delimiter character), double quotes, backslashes, or leading or trailing delimiter character), double quotes, backslashes, or leading or trailing
whitespace must be double-quoted. Empty strings and strings matching the whitespace must be double-quoted. Empty strings and strings matching the
word <literal>NULL</> must be quoted, too. To put a double quote or word <literal>NULL</> must be quoted, too. To put a double quote or
...@@ -668,7 +667,7 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2 ...@@ -668,7 +667,7 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
</para> </para>
<para> <para>
You can use whitespace before a left brace or after a right You can add whitespace before a left brace or after a right
brace. You can also add whitespace before or after any individual item brace. You can also add whitespace before or after any individual item
string. In all of these cases the whitespace will be ignored. However, string. In all of these cases the whitespace will be ignored. However,
whitespace within double-quoted elements, or surrounded on both sides by whitespace within double-quoted elements, or surrounded on both sides by
......
doc/src/sgml/config.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.219 2009/06/03 20:34:29 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.220 2009/06/17 21:58:48 tgl Exp $ -->
<chapter Id="runtime-config"> <chapter Id="runtime-config">
<title>Server Configuration</title> <title>Server Configuration</title>
...@@ -1252,8 +1252,8 @@ SET ENABLE_SEQSCAN TO OFF; ...@@ -1252,8 +1252,8 @@ SET ENABLE_SEQSCAN TO OFF;
Asynchronous I/O depends on an effective <function>posix_fadvise</> Asynchronous I/O depends on an effective <function>posix_fadvise</>
function, which some operating systems lack. If the function is not function, which some operating systems lack. If the function is not
present then setting this parameter to anything but zero will result present then setting this parameter to anything but zero will result
in an error. On some operating systems the function is present but in an error. On some operating systems (e.g., Solaris), the function
does not actually do anything (e.g., Solaris). is present but does not actually do anything.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
......
doc/src/sgml/datatype.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.238 2009/06/10 20:25:41 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.239 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="datatype"> <chapter id="datatype">
<title id="datatype-title">Data Types</title> <title id="datatype-title">Data Types</title>
...@@ -290,7 +290,7 @@ ...@@ -290,7 +290,7 @@
to <productname>PostgreSQL</productname>, such as geometric to <productname>PostgreSQL</productname>, such as geometric
paths, or have several possible formats, such as the date paths, or have several possible formats, such as the date
and time types. and time types.
Some of the input and output functions are not invertible, i.e. Some of the input and output functions are not invertible, i.e.,
the result of an output function might lose accuracy when compared to the result of an output function might lose accuracy when compared to
the original input. the original input.
</para> </para>
...@@ -441,11 +441,11 @@ ...@@ -441,11 +441,11 @@
<para> <para>
On very minimal operating systems the <type>bigint</type> type On very minimal operating systems the <type>bigint</type> type
might not function correctly because it relies on compiler support might not function correctly, because it relies on compiler support
for eight-byte integers. On such machines, <type>bigint</type> for eight-byte integers. On such machines, <type>bigint</type>
acts the same as <type>integer</type> (but still takes up eight acts the same as <type>integer</type>, but still takes up eight
bytes of storage). (We are not aware of any bytes of storage. (We are not aware of any modern
platform where this is true.) platform where this is the case.)
</para> </para>
<para> <para>
...@@ -453,7 +453,7 @@ ...@@ -453,7 +453,7 @@
<type>integer</type> (or <type>int</type>), <type>integer</type> (or <type>int</type>),
<type>smallint</type>, and <type>bigint</type>. The <type>smallint</type>, and <type>bigint</type>. The
type names <type>int2</type>, <type>int4</type>, and type names <type>int2</type>, <type>int4</type>, and
<type>int8</type> are extensions, which are also used by <type>int8</type> are extensions, which are also used by some
other <acronym>SQL</acronym> database systems. other <acronym>SQL</acronym> database systems.
</para> </para>
...@@ -481,7 +481,7 @@ ...@@ -481,7 +481,7 @@
especially recommended for storing monetary amounts and other especially recommended for storing monetary amounts and other
quantities where exactness is required. However, arithmetic on quantities where exactness is required. However, arithmetic on
<type>numeric</type> values is very slow compared to the integer <type>numeric</type> values is very slow compared to the integer
and floating-point types described in the next section. types, or to the floating-point types described in the next section.
</para> </para>
<para> <para>
...@@ -681,7 +681,7 @@ NUMERIC ...@@ -681,7 +681,7 @@ NUMERIC
<quote>not-a-number</quote>, respectively. (On a machine whose <quote>not-a-number</quote>, respectively. (On a machine whose
floating-point arithmetic does not follow IEEE 754, these values floating-point arithmetic does not follow IEEE 754, these values
will probably not work as expected.) When writing these values will probably not work as expected.) When writing these values
as constants in a SQL command, you must put quotes around them, as constants in an SQL command, you must put quotes around them,
for example <literal>UPDATE table SET x = 'Infinity'</>. On input, for example <literal>UPDATE table SET x = 'Infinity'</>. On input,
these strings are recognized in a case-insensitive manner. these strings are recognized in a case-insensitive manner.
</para> </para>
...@@ -785,7 +785,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab ...@@ -785,7 +785,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
Thus, we have created an integer column and arranged for its default Thus, we have created an integer column and arranged for its default
values to be assigned from a sequence generator. A <literal>NOT NULL</> values to be assigned from a sequence generator. A <literal>NOT NULL</>
constraint is applied to ensure that a null value cannot be explicitly constraint is applied to ensure that a null value cannot be
inserted. (In most cases you would also want to attach a inserted. (In most cases you would also want to attach a
<literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint to prevent <literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint to prevent
duplicate values from being inserted by accident, but this is duplicate values from being inserted by accident, but this is
...@@ -798,7 +798,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab ...@@ -798,7 +798,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
Prior to <productname>PostgreSQL</productname> 7.3, <type>serial</type> Prior to <productname>PostgreSQL</productname> 7.3, <type>serial</type>
implied <literal>UNIQUE</literal>. This is no longer automatic. If implied <literal>UNIQUE</literal>. This is no longer automatic. If
you wish a serial column to have a unique constraint or be a you wish a serial column to have a unique constraint or be a
primary key, it must now be specified just like primary key, it must now be specified, just like
any other data type. any other data type.
</para> </para>
</note> </note>
...@@ -837,15 +837,15 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab ...@@ -837,15 +837,15 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
<para> <para>
The <type>money</type> type stores a currency amount with a fixed The <type>money</type> type stores a currency amount with a fixed
fractional precision; see <xref fractional precision; see <xref
linkend="datatype-money-table">. The fractional precision linkend="datatype-money-table">. The fractional precision is
is controlled by the database locale. determined by the database's <xref linkend="guc-lc-monetary"> setting.
Input is accepted in a variety of formats, including integer and Input is accepted in a variety of formats, including integer and
floating-point literals, as well as typical floating-point literals, as well as typical
currency formatting, such as <literal>'$1,000.00'</literal>. currency formatting, such as <literal>'$1,000.00'</literal>.
Output is generally in the latter form but depends on the locale. Output is generally in the latter form but depends on the locale.
Non-quoted numeric values can be converted to <type>money</type> by Non-quoted numeric values can be converted to <type>money</type> by
casting the numeric value to <type>text</type> and then casting the numeric value to <type>text</type> and then
<type>money</type>: <type>money</type>, for example:
<programlisting> <programlisting>
SELECT 1234::text::money; SELECT 1234::text::money;
</programlisting> </programlisting>
...@@ -961,7 +961,7 @@ SELECT regexp_replace('52093.89'::money::text, '[$,]', '', 'g')::numeric; ...@@ -961,7 +961,7 @@ SELECT regexp_replace('52093.89'::money::text, '[$,]', '', 'g')::numeric;
<type>character varying(<replaceable>n</>)</type> and <type>character varying(<replaceable>n</>)</type> and
<type>character(<replaceable>n</>)</type>, where <replaceable>n</> <type>character(<replaceable>n</>)</type>, where <replaceable>n</>
is a positive integer. Both of these types can store strings up to is a positive integer. Both of these types can store strings up to
<replaceable>n</> characters in length (not bytes). An attempt to store a <replaceable>n</> characters (not bytes) in length. An attempt to store a
longer string into a column of these types will result in an longer string into a column of these types will result in an
error, unless the excess characters are all spaces, in which case error, unless the excess characters are all spaces, in which case
the string will be truncated to the maximum length. (This somewhat the string will be truncated to the maximum length. (This somewhat
...@@ -1033,13 +1033,15 @@ SELECT regexp_replace('52093.89'::money::text, '[$,]', '', 'g')::numeric; ...@@ -1033,13 +1033,15 @@ SELECT regexp_replace('52093.89'::money::text, '[$,]', '', 'g')::numeric;
<tip> <tip>
<para> <para>
There is no performance difference between these three types, There is no performance difference among these three types,
apart from increased storage space when using the blank-padded apart from increased storage space when using the blank-padded
type, and a few extra CPU cycles to check the length when storing into type, and a few extra CPU cycles to check the length when storing into
a length-constrained column. While a length-constrained column. While
<type>character(<replaceable>n</>)</type> has performance <type>character(<replaceable>n</>)</type> has performance
advantages in some other database systems, there is no such advantage in advantages in some other database systems, there is no such advantage in
<productname>PostgreSQL</productname>. In most situations <productname>PostgreSQL</productname>; in fact
<type>character(<replaceable>n</>)</type> is usually the slowest of
the three because of its additional storage costs. In most situations
<type>text</type> or <type>character varying</type> should be used <type>text</type> or <type>character varying</type> should be used
instead. instead.
</para> </para>
...@@ -1583,7 +1585,8 @@ SELECT b, char_length(b) FROM test2; ...@@ -1583,7 +1585,8 @@ SELECT b, char_length(b) FROM test2;
<synopsis> <synopsis>
<replaceable>type</replaceable> [ (<replaceable>p</replaceable>) ] '<replaceable>value</replaceable>' <replaceable>type</replaceable> [ (<replaceable>p</replaceable>) ] '<replaceable>value</replaceable>'
</synopsis> </synopsis>
where <replaceable>p</replaceable> is an optional precision corresponding to the number of where <replaceable>p</replaceable> is an optional precision
specification giving the number of
fractional digits in the seconds field. Precision can be fractional digits in the seconds field. Precision can be
specified for <type>time</type>, <type>timestamp</type>, and specified for <type>time</type>, <type>timestamp</type>, and
<type>interval</type> types. The allowed values are mentioned <type>interval</type> types. The allowed values are mentioned
...@@ -1705,7 +1708,7 @@ SELECT b, char_length(b) FROM test2; ...@@ -1705,7 +1708,7 @@ SELECT b, char_length(b) FROM test2;
The time-of-day types are <type>time [ The time-of-day types are <type>time [
(<replaceable>p</replaceable>) ] without time zone</type> and (<replaceable>p</replaceable>) ] without time zone</type> and
<type>time [ (<replaceable>p</replaceable>) ] with time <type>time [ (<replaceable>p</replaceable>) ] with time
zone</type>; <type>time</type> is equivalent to zone</type>. <type>time</type> alone is equivalent to
<type>time without time zone</type>. <type>time without time zone</type>.
</para> </para>
...@@ -1752,7 +1755,7 @@ SELECT b, char_length(b) FROM test2; ...@@ -1752,7 +1755,7 @@ SELECT b, char_length(b) FROM test2;
</row> </row>
<row> <row>
<entry><literal>04:05 AM</literal></entry> <entry><literal>04:05 AM</literal></entry>
<entry>same as 04:05 (AM ignored)</entry> <entry>same as 04:05; AM does not affect value</entry>
</row> </row>
<row> <row>
<entry><literal>04:05 PM</literal></entry> <entry><literal>04:05 PM</literal></entry>
...@@ -1878,14 +1881,15 @@ January 8 04:05:06 1999 PST ...@@ -1878,14 +1881,15 @@ January 8 04:05:06 1999 PST
</para> </para>
<para> <para>
The <acronym>SQL</acronym> standard differentiates <type>timestamp without time zone</type> The <acronym>SQL</acronym> standard differentiates
<type>timestamp without time zone</type>
and <type>timestamp with time zone</type> literals by the presence of a and <type>timestamp with time zone</type> literals by the presence of a
<quote>+</quote> or <quote>-</quote> symbol after the time <quote>+</quote> or <quote>-</quote> symbol and time zone offset after
indicating the time zone offset. Hence, according to the standard: the time. Hence, according to the standard,
<programlisting>TIMESTAMP '2004-10-19 10:23:54'</programlisting> <programlisting>TIMESTAMP '2004-10-19 10:23:54'</programlisting>
is a <type>timestamp without time zone</type>, while: is a <type>timestamp without time zone</type>, while
<programlisting>TIMESTAMP '2004-10-19 10:23:54+02'</programlisting> <programlisting>TIMESTAMP '2004-10-19 10:23:54+02'</programlisting>
...@@ -2048,15 +2052,15 @@ January 8 04:05:06 1999 PST ...@@ -2048,15 +2052,15 @@ January 8 04:05:06 1999 PST
</indexterm> </indexterm>
<para> <para>
The output format of the date/time types can one of the four The output format of the date/time types can be set to one of the four
styles: ISO 8601, styles ISO 8601,
<acronym>SQL</acronym> (Ingres), traditional <productname>POSTGRES</> <acronym>SQL</acronym> (Ingres), traditional <productname>POSTGRES</>
(Unix <application>date</> format), and (Unix <application>date</> format), or
German. It can be set using the <literal>SET datestyle</literal> command. The default German. The default
is the <acronym>ISO</acronym> format. (The is the <acronym>ISO</acronym> format. (The
<acronym>SQL</acronym> standard requires the use of the ISO 8601 <acronym>SQL</acronym> standard requires the use of the ISO 8601
format. The name of the <literal>SQL</> output format poorly format. The name of the <quote>SQL</quote> output format is a
chosen and an historical accident.) <xref historical accident.) <xref
linkend="datatype-datetime-output-table"> shows examples of each linkend="datatype-datetime-output-table"> shows examples of each
output style. The output of the <type>date</type> and output style. The output of the <type>date</type> and
<type>time</type> types is of course only the date or time part <type>time</type> types is of course only the date or time part
...@@ -2273,7 +2277,7 @@ January 8 04:05:06 1999 PST ...@@ -2273,7 +2277,7 @@ January 8 04:05:06 1999 PST
</listitem> </listitem>
</itemizedlist> </itemizedlist>
In summary, there is a difference between abbreviations In short, this is the difference between abbreviations
and full names: abbreviations always represent a fixed offset from and full names: abbreviations always represent a fixed offset from
UTC, whereas most of the full names imply a local daylight-savings time UTC, whereas most of the full names imply a local daylight-savings time
rule, and so have two possible UTC offsets. rule, and so have two possible UTC offsets.
...@@ -2358,7 +2362,7 @@ January 8 04:05:06 1999 PST ...@@ -2358,7 +2362,7 @@ January 8 04:05:06 1999 PST
</indexterm> </indexterm>
<para> <para>
<type>interval</type> values can be written using the following: <type>interval</type> values can be written using the following
verbose syntax: verbose syntax:
<synopsis> <synopsis>
...@@ -2708,9 +2712,10 @@ P <optional> <replaceable>years</>-<replaceable>months</>-<replaceable>days</> < ...@@ -2708,9 +2712,10 @@ P <optional> <replaceable>years</>-<replaceable>months</>-<replaceable>days</> <
<member><literal>'off'</literal></member> <member><literal>'off'</literal></member>
<member><literal>'0'</literal></member> <member><literal>'0'</literal></member>
</simplelist> </simplelist>
Leading and trailing whitespace and case are ignored. The key words Leading or trailing whitespace is ignored, and case does not matter.
<literal>TRUE</literal> and <literal>FALSE</literal> is the preferred The key words
usage (and <acronym>SQL</acronym>-compliant). <literal>TRUE</literal> and <literal>FALSE</literal> are the preferred
(<acronym>SQL</acronym>-compliant) usage.
</para> </para>
<example id="datatype-boolean-example"> <example id="datatype-boolean-example">
...@@ -3072,8 +3077,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays ...@@ -3072,8 +3077,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
</para> </para>
<para> <para>
Boxes are output using the first syntax. Any two opposite corners Boxes are output using the first syntax.
can be supplied; the corners are reordered on input to store the Any two opposite corners can be supplied on input, but the values
will be reordered as needed to store the
upper right and lower left corners. upper right and lower left corners.
</para> </para>
</sect2> </sect2>
...@@ -3111,7 +3117,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays ...@@ -3111,7 +3117,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
</para> </para>
<para> <para>
Paths are output using the first appropriate syntax. Paths are output using the first or second syntax, as appropriate.
</para> </para>
</sect2> </sect2>
...@@ -3190,7 +3196,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays ...@@ -3190,7 +3196,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC <productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC
addresses, as shown in <xref linkend="datatype-net-types-table">. It addresses, as shown in <xref linkend="datatype-net-types-table">. It
is better to use these types instead of plain text types to store is better to use these types instead of plain text types to store
network addresses because network addresses, because
these types offer input error checking and specialized these types offer input error checking and specialized
operators and functions (see <xref linkend="functions-net">). operators and functions (see <xref linkend="functions-net">).
</para> </para>
...@@ -3266,7 +3272,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays ...@@ -3266,7 +3272,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<replaceable class="parameter">y</replaceable> <replaceable class="parameter">y</replaceable>
is the number of bits in the netmask. If the is the number of bits in the netmask. If the
<replaceable class="parameter">/y</replaceable> <replaceable class="parameter">/y</replaceable>
is missing, the portion is missing, the
netmask is 32 for IPv4 and 128 for IPv6, so the value represents netmask is 32 for IPv4 and 128 for IPv6, so the value represents
just a single host. On display, the just a single host. On display, the
<replaceable class="parameter">/y</replaceable> <replaceable class="parameter">/y</replaceable>
...@@ -3560,8 +3566,8 @@ SELECT * FROM test; ...@@ -3560,8 +3566,8 @@ SELECT * FROM test;
are designed to support full text search, which is the activity of are designed to support full text search, which is the activity of
searching through a collection of natural-language <firstterm>documents</> searching through a collection of natural-language <firstterm>documents</>
to locate those that best match a <firstterm>query</>. to locate those that best match a <firstterm>query</>.
The <type>tsvector</type> type represents a document stored in a form optimized The <type>tsvector</type> type represents a document in a form optimized
for text search; <type>tsquery</type> type similarly represents for text search; the <type>tsquery</type> type similarly represents
a text query. a text query.
<xref linkend="textsearch"> provides a detailed explanation of this <xref linkend="textsearch"> provides a detailed explanation of this
facility, and <xref linkend="functions-textsearch"> summarizes the facility, and <xref linkend="functions-textsearch"> summarizes the
...@@ -3577,7 +3583,7 @@ SELECT * FROM test; ...@@ -3577,7 +3583,7 @@ SELECT * FROM test;
<para> <para>
A <type>tsvector</type> value is a sorted list of distinct A <type>tsvector</type> value is a sorted list of distinct
<firstterm>lexemes</>, which are words which have been <firstterm>lexemes</>, which are words that have been
<firstterm>normalized</> to merge different variants of the same word <firstterm>normalized</> to merge different variants of the same word
(see <xref linkend="textsearch"> for details). Sorting and (see <xref linkend="textsearch"> for details). Sorting and
duplicate-elimination are done automatically during input, as shown in duplicate-elimination are done automatically during input, as shown in
...@@ -3687,7 +3693,7 @@ SELECT to_tsvector('english', 'The Fat Rats'); ...@@ -3687,7 +3693,7 @@ SELECT to_tsvector('english', 'The Fat Rats');
<para> <para>
A <type>tsquery</type> value stores lexemes that are to be A <type>tsquery</type> value stores lexemes that are to be
searched for, and combines them by honoring the boolean operators searched for, and combines them honoring the boolean operators
<literal>&amp;</literal> (AND), <literal>|</literal> (OR), and <literal>&amp;</literal> (AND), <literal>|</literal> (OR), and
<literal>!</> (NOT). Parentheses can be used to enforce grouping <literal>!</> (NOT). Parentheses can be used to enforce grouping
of the operators: of the operators:
...@@ -3825,8 +3831,8 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11 ...@@ -3825,8 +3831,8 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
<para> <para>
The <type>xml</type> data type can be used to store XML data. Its The <type>xml</type> data type can be used to store XML data. Its
advantage over storing XML data in a <type>text</type> field is that it advantage over storing XML data in a <type>text</type> field is that it
checks the input values for well-formedness, and support checks the input values for well-formedness, and there are support
functions can perform type-safe operations on it; see <xref functions to perform type-safe operations on it; see <xref
linkend="functions-xml">. Use of this data type requires the linkend="functions-xml">. Use of this data type requires the
installation to have been built with <command>configure installation to have been built with <command>configure
--with-libxml</>. --with-libxml</>.
...@@ -3870,8 +3876,9 @@ xml '<foo>bar</foo>' ...@@ -3870,8 +3876,9 @@ xml '<foo>bar</foo>'
<para> <para>
The <type>xml</type> type does not validate input values The <type>xml</type> type does not validate input values
against an optionally-supplied document type declaration against a document type declaration
(DTD).<indexterm><primary>DTD</primary></indexterm> (DTD),<indexterm><primary>DTD</primary></indexterm>
even when the input value specifies a DTD.
</para> </para>
<para> <para>
...@@ -3883,7 +3890,7 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <repla ...@@ -3883,7 +3890,7 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <repla
</synopsis> </synopsis>
<replaceable>type</replaceable> can be <replaceable>type</replaceable> can be
<type>character</type>, <type>character varying</type>, or <type>character</type>, <type>character varying</type>, or
<type>text</type> (or an alias name for those). Again, according <type>text</type> (or an alias for one of those). Again, according
to the SQL standard, this is the only way to convert between type to the SQL standard, this is the only way to convert between type
<type>xml</type> and character types, but PostgreSQL also allows <type>xml</type> and character types, but PostgreSQL also allows
you to simply cast the value. you to simply cast the value.
...@@ -3923,7 +3930,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; ...@@ -3923,7 +3930,7 @@ SET xmloption TO { DOCUMENT | CONTENT };
representations of XML values, such as in the above examples. representations of XML values, such as in the above examples.
This would ordinarily mean that encoding declarations contained in This would ordinarily mean that encoding declarations contained in
XML data can become invalid as the character data is converted XML data can become invalid as the character data is converted
to other encodings while travelling between client and server to other encodings while travelling between client and server,
because the embedded encoding declaration is not changed. To cope because the embedded encoding declaration is not changed. To cope
with this behavior, encoding declarations contained in with this behavior, encoding declarations contained in
character strings presented for input to the <type>xml</type> type character strings presented for input to the <type>xml</type> type
...@@ -3932,7 +3939,7 @@ SET xmloption TO { DOCUMENT | CONTENT }; ...@@ -3932,7 +3939,7 @@ SET xmloption TO { DOCUMENT | CONTENT };
processing, character strings of XML data must be sent processing, character strings of XML data must be sent
from the client in the current client encoding. It is the from the client in the current client encoding. It is the
responsibility of the client to either convert documents to the responsibility of the client to either convert documents to the
current client encoding before sending them to the server or to current client encoding before sending them to the server, or to
adjust the client encoding appropriately. On output, values of adjust the client encoding appropriately. On output, values of
type <type>xml</type> will not have an encoding declaration, and type <type>xml</type> will not have an encoding declaration, and
clients should assume all data is in the current client clients should assume all data is in the current client
......
doc/src/sgml/ddl.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.86 2009/04/27 16:27:35 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.87 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="ddl"> <chapter id="ddl">
<title>Data Definition</title> <title>Data Definition</title>
...@@ -557,8 +557,8 @@ CREATE TABLE products ( ...@@ -557,8 +557,8 @@ CREATE TABLE products (
comparison. That means even in the presence of a comparison. That means even in the presence of a
unique constraint it is possible to store duplicate unique constraint it is possible to store duplicate
rows that contain a null value in at least one of the constrained rows that contain a null value in at least one of the constrained
columns. This behavior conforms to the SQL standard, but there columns. This behavior conforms to the SQL standard, but we have
might be other SQL databases might not follow this rule. So be heard that other SQL databases might not follow this rule. So be
careful when developing applications that are intended to be careful when developing applications that are intended to be
portable. portable.
</para> </para>
...@@ -1802,7 +1802,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC; ...@@ -1802,7 +1802,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
such names, to ensure that you won't suffer a conflict if some such names, to ensure that you won't suffer a conflict if some
future version defines a system table named the same as your future version defines a system table named the same as your
table. (With the default search path, an unqualified reference to table. (With the default search path, an unqualified reference to
your table name would be resolved as a system table instead.) your table name would then be resolved as the system table instead.)
System tables will continue to follow the convention of having System tables will continue to follow the convention of having
names beginning with <literal>pg_</>, so that they will not names beginning with <literal>pg_</>, so that they will not
conflict with unqualified user-table names so long as users avoid conflict with unqualified user-table names so long as users avoid
...@@ -2709,9 +2709,9 @@ SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01'; ...@@ -2709,9 +2709,9 @@ SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
Without constraint exclusion, the above query would scan each of Without constraint exclusion, the above query would scan each of
the partitions of the <structname>measurement</> table. With constraint the partitions of the <structname>measurement</> table. With constraint
exclusion enabled, the planner will examine the constraints of each exclusion enabled, the planner will examine the constraints of each
partition and try to determine which partitions need not partition and try to prove that the partition need not
be scanned because they cannot not contain any rows meeting the query's be scanned because it could not contain any rows meeting the query's
<literal>WHERE</> clause. When the planner can determine this, it <literal>WHERE</> clause. When the planner can prove this, it
excludes the partition from the query plan. excludes the partition from the query plan.
</para> </para>
...@@ -2906,7 +2906,7 @@ ANALYZE measurement; ...@@ -2906,7 +2906,7 @@ ANALYZE measurement;
<listitem> <listitem>
<para> <para>
Keep the partitioning constraints simple or else the planner may not be Keep the partitioning constraints simple, else the planner may not be
able to prove that partitions don't need to be visited. Use simple able to prove that partitions don't need to be visited. Use simple
equality conditions for list partitioning, or simple equality conditions for list partitioning, or simple
range tests for range partitioning, as illustrated in the preceding range tests for range partitioning, as illustrated in the preceding
......
doc/src/sgml/dml.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.18 2009/04/27 16:27:35 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.19 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="dml"> <chapter id="dml">
<title>Data Manipulation</title> <title>Data Manipulation</title>
...@@ -248,10 +248,7 @@ DELETE FROM products WHERE price = 10; ...@@ -248,10 +248,7 @@ DELETE FROM products WHERE price = 10;
<programlisting> <programlisting>
DELETE FROM products; DELETE FROM products;
</programlisting> </programlisting>
then all rows in the table will be deleted! (<xref then all rows in the table will be deleted! Caveat programmer.
linkend="sql-truncate" endterm="sql-truncate-title"> can also be used
to delete all rows.)
Caveat programmer.
</para> </para>
</sect1> </sect1>
</chapter> </chapter>
doc/src/sgml/docguide.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.75 2009/04/27 16:27:35 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.76 2009/06/17 21:58:49 tgl Exp $ -->
<appendix id="docguide"> <appendix id="docguide">
<title>Documentation</title> <title>Documentation</title>
...@@ -358,7 +358,7 @@ CATALOG "dsssl/catalog" ...@@ -358,7 +358,7 @@ CATALOG "dsssl/catalog"
Create the directory Create the directory
<filename>/usr/local/share/sgml/docbook-4.2</filename> and change <filename>/usr/local/share/sgml/docbook-4.2</filename> and change
to it. (The exact location is irrelevant, but this one is to it. (The exact location is irrelevant, but this one is
reasonable within the layout we are following here.): reasonable within the layout we are following here.)
<screen> <screen>
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput> <prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook-4.2</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput> <prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook-4.2</userinput>
...@@ -421,7 +421,7 @@ perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat ...@@ -421,7 +421,7 @@ perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
To install the style sheets, unzip and untar the distribution and To install the style sheets, unzip and untar the distribution and
move it to a suitable place, for example move it to a suitable place, for example
<filename>/usr/local/share/sgml</filename>. (The archive will <filename>/usr/local/share/sgml</filename>. (The archive will
automatically create a subdirectory.): automatically create a subdirectory.)
<screen> <screen>
<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput> <prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput> <prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
......
doc/src/sgml/func.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.481 2009/05/26 17:36:05 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.482 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="functions"> <chapter id="functions">
<title>Functions and Operators</title> <title>Functions and Operators</title>
...@@ -268,8 +268,9 @@ ...@@ -268,8 +268,9 @@
<synopsis> <synopsis>
<replaceable>a</replaceable> &gt;= <replaceable>x</replaceable> AND <replaceable>a</replaceable> &lt;= <replaceable>y</replaceable> <replaceable>a</replaceable> &gt;= <replaceable>x</replaceable> AND <replaceable>a</replaceable> &lt;= <replaceable>y</replaceable>
</synopsis> </synopsis>
Note <token>BETWEEN</token> is inclusive in comparing the endpoint Notice that <token>BETWEEN</token> treats the endpoint values as included
values. <literal>NOT BETWEEN</literal> does the opposite comparison: in the range.
<literal>NOT BETWEEN</literal> does the opposite comparison:
<synopsis> <synopsis>
<replaceable>a</replaceable> NOT BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable> <replaceable>a</replaceable> NOT BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
</synopsis> </synopsis>
...@@ -280,9 +281,11 @@ ...@@ -280,9 +281,11 @@
<indexterm> <indexterm>
<primary>BETWEEN SYMMETRIC</primary> <primary>BETWEEN SYMMETRIC</primary>
</indexterm> </indexterm>
<token>BETWEEN SYMMETRIC</> is the same as <literal>BETWEEN</> <literal>BETWEEN SYMMETRIC</> is the same as <literal>BETWEEN</>
except there is no requirement that the argument to the left of <literal>AND</> be less than except there is no requirement that the argument to the left of
or equal to the argument on the right; the proper range is automatically determined. <literal>AND</> be less than or equal to the argument on the right.
If it is not, those two arguments are automatically swapped, so that
a nonempty range is always implied.
</para> </para>
<para> <para>
...@@ -322,7 +325,7 @@ ...@@ -322,7 +325,7 @@
<tip> <tip>
<para> <para>
Some applications might expect Some applications might expect that
<literal><replaceable>expression</replaceable> = NULL</literal> <literal><replaceable>expression</replaceable> = NULL</literal>
returns true if <replaceable>expression</replaceable> evaluates to returns true if <replaceable>expression</replaceable> evaluates to
the null value. It is highly recommended that these applications the null value. It is highly recommended that these applications
...@@ -358,11 +361,11 @@ ...@@ -358,11 +361,11 @@
<indexterm> <indexterm>
<primary>IS NOT DISTINCT FROM</primary> <primary>IS NOT DISTINCT FROM</primary>
</indexterm> </indexterm>
Ordinary comparison operators yield null (signifying <quote>unknown</>) Ordinary comparison operators yield null (signifying <quote>unknown</>),
when either input is null, not true or false, e.g., <literal>7 = not true or false, when either input is null. For example,
NULL</> yields null. <literal>7 = NULL</> yields null. When this behavior is not suitable,
Another way to do comparisons is with the use the
<literal>IS <optional> NOT </> DISTINCT FROM</literal> construct: <literal>IS <optional> NOT </> DISTINCT FROM</literal> constructs:
<synopsis> <synopsis>
<replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable> <replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable>
<replaceable>expression</replaceable> IS NOT DISTINCT FROM <replaceable>expression</replaceable> <replaceable>expression</replaceable> IS NOT DISTINCT FROM <replaceable>expression</replaceable>
...@@ -440,8 +443,8 @@ ...@@ -440,8 +443,8 @@
<para> <para>
Mathematical operators are provided for many Mathematical operators are provided for many
<productname>PostgreSQL</productname> types. For types that support <productname>PostgreSQL</productname> types. For types without
only limited mathematical operations standard mathematical conventions
(e.g., date/time types) we (e.g., date/time types) we
describe the actual behavior in subsequent sections. describe the actual behavior in subsequent sections.
</para> </para>
...@@ -1010,11 +1013,13 @@ ...@@ -1010,11 +1013,13 @@
</para> </para>
<para> <para>
<acronym>SQL</acronym> defines some string functions with a special syntax <acronym>SQL</acronym> defines some string functions that use
wherein certain key words rather than commas are used to separate the key words, rather than commas, to separate
arguments. Details are in <xref linkend="functions-string-sql">. arguments. Details are in
These functions are also implemented using the regular syntax for <xref linkend="functions-string-sql">.
function invocation. (See <xref linkend="functions-string-other">.) <productname>PostgreSQL</> also provides versions of these functions
that use the regular function invocation syntax
(see <xref linkend="functions-string-other">).
</para> </para>
<note> <note>
...@@ -1795,8 +1800,8 @@ ...@@ -1795,8 +1800,8 @@
<para> <para>
The conversion names follow a standard naming scheme: The The conversion names follow a standard naming scheme: The
official name of the source encoding with all official name of the source encoding with all
non-alphanumeric characters replaced by underscores followed non-alphanumeric characters replaced by underscores, followed
by <literal>_to_</literal> followed by similarly by <literal>_to_</literal>, followed by the similarly processed
destination encoding name. Therefore, the names might deviate destination encoding name. Therefore, the names might deviate
from the customary encoding names. from the customary encoding names.
</para> </para>
...@@ -2598,12 +2603,12 @@ ...@@ -2598,12 +2603,12 @@
<para> <para>
<acronym>SQL</acronym> defines some string functions that use <acronym>SQL</acronym> defines some string functions that use
a key word syntax, rather than commas to separate key words, rather than commas, to separate
arguments. Details are in arguments. Details are in
<xref linkend="functions-binarystring-sql">. <xref linkend="functions-binarystring-sql">.
Such functions are also implemented using the regular syntax for <productname>PostgreSQL</> also provides versions of these functions
function invocation. that use the regular function invocation syntax
(See <xref linkend="functions-binarystring-other">.) (see <xref linkend="functions-binarystring-other">).
</para> </para>
<table id="functions-binarystring-sql"> <table id="functions-binarystring-sql">
...@@ -2999,7 +3004,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> ...@@ -2999,7 +3004,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
</synopsis> </synopsis>
<para> <para>
The <function>LIKE</function> expression returns true if The <function>LIKE</function> expression returns true if the
<replaceable>string</replaceable> matches the supplied <replaceable>string</replaceable> matches the supplied
<replaceable>pattern</replaceable>. (As <replaceable>pattern</replaceable>. (As
expected, the <function>NOT LIKE</function> expression returns expected, the <function>NOT LIKE</function> expression returns
...@@ -3011,11 +3016,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> ...@@ -3011,11 +3016,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para> <para>
If <replaceable>pattern</replaceable> does not contain percent If <replaceable>pattern</replaceable> does not contain percent
signs or underscore, then the pattern only represents the string signs or underscores, then the pattern only represents the string
itself; in that case <function>LIKE</function> acts like the itself; in that case <function>LIKE</function> acts like the
equals operator. An underscore (<literal>_</literal>) in equals operator. An underscore (<literal>_</literal>) in
<replaceable>pattern</replaceable> stands for (matches) any single <replaceable>pattern</replaceable> stands for (matches) any single
character; a percent sign (<literal>%</literal>) matches any string character; a percent sign (<literal>%</literal>) matches any sequence
of zero or more characters. of zero or more characters.
</para> </para>
...@@ -3036,7 +3041,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> ...@@ -3036,7 +3041,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
</para> </para>
<para> <para>
To match only a literal underscore or percent sign without matching To match a literal underscore or percent sign without matching
other characters, the respective character in other characters, the respective character in
<replaceable>pattern</replaceable> must be <replaceable>pattern</replaceable> must be
preceded by the escape character. The default escape preceded by the escape character. The default escape
...@@ -3053,8 +3058,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> ...@@ -3053,8 +3058,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
actually matches a literal backslash means writing four backslashes in the actually matches a literal backslash means writing four backslashes in the
statement. You can avoid this by selecting a different escape character statement. You can avoid this by selecting a different escape character
with <literal>ESCAPE</literal>; then a backslash is not special to with <literal>ESCAPE</literal>; then a backslash is not special to
<function>LIKE</function> anymore. (But backslash is still special to the string <function>LIKE</function> anymore. (But backslash is still special to the
literal parser, so you still need two of them.) string literal parser, so you still need two of them to match a backslash.)
</para> </para>
<para> <para>
...@@ -3163,9 +3168,9 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation> ...@@ -3163,9 +3168,9 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
Notice that bounded repetition (<literal>?</> and <literal>{...}</>) Notice that bounded repetition operators (<literal>?</> and
is not provided, though they exist in POSIX. Also, the period (<literal>.</>) <literal>{...}</>) are not provided, though they exist in POSIX.
is not a metacharacter. Also, the period (<literal>.</>) is not a metacharacter.
</para> </para>
<para> <para>
...@@ -3295,7 +3300,7 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat ...@@ -3295,7 +3300,7 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat
expression. As with <function>LIKE</function>, pattern characters expression. As with <function>LIKE</function>, pattern characters
match string characters exactly unless they are special characters match string characters exactly unless they are special characters
in the regular expression language &mdash; but regular expressions use in the regular expression language &mdash; but regular expressions use
different special characters than <function>LIKE</function>. different special characters than <function>LIKE</function> does.
Unlike <function>LIKE</function> patterns, a Unlike <function>LIKE</function> patterns, a
regular expression is allowed to match anywhere within a string, unless regular expression is allowed to match anywhere within a string, unless
the regular expression is explicitly anchored to the beginning or the regular expression is explicitly anchored to the beginning or
...@@ -3562,7 +3567,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -3562,7 +3567,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<para> <para>
A branch is zero or more <firstterm>quantified atoms</> or A branch is zero or more <firstterm>quantified atoms</> or
<firstterm>constraints</>, concatenated. <firstterm>constraints</>, concatenated.
It tries a match of the first, followed by a match for the second, etc; It matches a match for the first, followed by a match for the second, etc;
an empty branch matches the empty string. an empty branch matches the empty string.
</para> </para>
...@@ -3579,7 +3584,8 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -3579,7 +3584,8 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<para> <para>
A <firstterm>constraint</> matches an empty string, but matches only when A <firstterm>constraint</> matches an empty string, but matches only when
specific conditions are met. A constraint cannot be followed by a quantifier. specific conditions are met. A constraint can be used where an atom
could be used, except it cannot be followed by a quantifier.
The simple constraints are shown in The simple constraints are shown in
<xref linkend="posix-constraints-table">; <xref linkend="posix-constraints-table">;
some more constraints are described later. some more constraints are described later.
...@@ -3788,12 +3794,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -3788,12 +3794,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<tbody> <tbody>
<row> <row>
<entry> <literal>^</> </entry> <entry> <literal>^</> </entry>
<entry> matches the beginning of the string </entry> <entry> matches at the beginning of the string </entry>
</row> </row>
<row> <row>
<entry> <literal>$</> </entry> <entry> <literal>$</> </entry>
<entry> matches the end of the string </entry> <entry> matches at the end of the string </entry>
</row> </row>
<row> <row>
...@@ -3842,12 +3848,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -3842,12 +3848,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<para> <para>
To include a literal <literal>]</literal> in the list, make it the To include a literal <literal>]</literal> in the list, make it the
first character (possibly following a <literal>^</literal>). To first character (after <literal>^</literal>, if that is used). To
include a literal <literal>-</literal>, make it the first or last include a literal <literal>-</literal>, make it the first or last
character, or the second endpoint of a range. To use a literal character, or the second endpoint of a range. To use a literal
<literal>-</literal> as the start of a range, enclose it <literal>-</literal> as the first endpoint of a range, enclose it
in <literal>[.</literal> and <literal>.]</literal> to make it a in <literal>[.</literal> and <literal>.]</literal> to make it a
collating element (see below). With the exception of these characters and collating element (see below). With the exception of these characters,
some combinations using <literal>[</literal> some combinations using <literal>[</literal>
(see next paragraphs), and escapes (AREs only), all other special (see next paragraphs), and escapes (AREs only), all other special
characters lose their special significance within a bracket expression. characters lose their special significance within a bracket expression.
...@@ -3945,7 +3951,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -3945,7 +3951,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<para> <para>
<firstterm>Character-entry escapes</> exist to make it easier to specify <firstterm>Character-entry escapes</> exist to make it easier to specify
non-printing and inconvenient characters in REs. They are non-printing and other inconvenient characters in REs. They are
shown in <xref linkend="posix-character-entry-escapes-table">. shown in <xref linkend="posix-character-entry-escapes-table">.
</para> </para>
...@@ -4050,7 +4056,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -4050,7 +4056,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<entry> <literal>\u</><replaceable>wxyz</> </entry> <entry> <literal>\u</><replaceable>wxyz</> </entry>
<entry> (where <replaceable>wxyz</> is exactly four hexadecimal digits) <entry> (where <replaceable>wxyz</> is exactly four hexadecimal digits)
the UTF16 (Unicode, 16-bit) character <literal>U+</><replaceable>wxyz</> the UTF16 (Unicode, 16-bit) character <literal>U+</><replaceable>wxyz</>
in the local byte encoding</entry> in the local byte ordering </entry>
</row> </row>
<row> <row>
...@@ -4067,11 +4073,11 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -4067,11 +4073,11 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
</row> </row>
<row> <row>
<entry> <literal>\x</><replaceable>###</> </entry> <entry> <literal>\x</><replaceable>hhh</> </entry>
<entry> (where <replaceable>###</> is any sequence of hexadecimal <entry> (where <replaceable>hhh</> is any sequence of hexadecimal
digits) digits)
the character whose hexadecimal value is the character whose hexadecimal value is
<literal>0x</><replaceable>###</> <literal>0x</><replaceable>hhh</>
(a single character no matter how many hexadecimal digits are used) (a single character no matter how many hexadecimal digits are used)
</entry> </entry>
</row> </row>
...@@ -4082,19 +4088,19 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -4082,19 +4088,19 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
</row> </row>
<row> <row>
<entry> <literal>\</><replaceable>##</> </entry> <entry> <literal>\</><replaceable>xy</> </entry>
<entry> (where <replaceable>##</> is exactly two octal digits, <entry> (where <replaceable>xy</> is exactly two octal digits,
and is not a <firstterm>back reference</>) and is not a <firstterm>back reference</>)
the character whose octal value is the character whose octal value is
<literal>0</><replaceable>##</> </entry> <literal>0</><replaceable>xy</> </entry>
</row> </row>
<row> <row>
<entry> <literal>\</><replaceable>###</> </entry> <entry> <literal>\</><replaceable>xyz</> </entry>
<entry> (where <replaceable>###</> is exactly three octal digits, <entry> (where <replaceable>xyz</> is exactly three octal digits,
and is not a <firstterm>back reference</>) and is not a <firstterm>back reference</>)
the character whose octal value is the character whose octal value is
<literal>0</><replaceable>###</> </entry> <literal>0</><replaceable>xyz</> </entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
...@@ -4258,12 +4264,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo; ...@@ -4258,12 +4264,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<note> <note>
<para> <para>
There is an inherent ambiguity between octal character-entry There is an inherent ambiguity between octal character-entry
escapes and back references, which is resolved by heuristics, escapes and back references, which is resolved by the following heuristics,
as hinted at above. as hinted at above.
A leading zero always indicates an octal escape. A leading zero always indicates an octal escape.
A single non-zero digit, not followed by another digit, A single non-zero digit, not followed by another digit,
is always taken as a back reference. is always taken as a back reference.
A multidigit sequence not starting with a zero is taken as a back A multi-digit sequence not starting with a zero is taken as a back
reference if it comes after a suitable subexpression reference if it comes after a suitable subexpression
(i.e., the number is in the legal range for a back reference), (i.e., the number is in the legal range for a back reference),
and otherwise is taken as octal. and otherwise is taken as octal.
...@@ -4817,7 +4823,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -4817,7 +4823,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row> <row>
<entry><literal><function>to_timestamp</function>(<type>double precision</type>)</literal></entry> <entry><literal><function>to_timestamp</function>(<type>double precision</type>)</literal></entry>
<entry><type>timestamp with time zone</type></entry> <entry><type>timestamp with time zone</type></entry>
<entry>convert UNIX epoch to time stamp</entry> <entry>convert Unix epoch to time stamp</entry>
<entry><literal>to_timestamp(1284352323)</literal></entry> <entry><literal>to_timestamp(1284352323)</literal></entry>
</row> </row>
</tbody> </tbody>
...@@ -4825,11 +4831,12 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -4825,11 +4831,12 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</table> </table>
<para> <para>
In a <function>to_char</> output template string, there are certain patterns that are In a <function>to_char</> output template string, there are certain
recognized and replaced with appropriately-formatted data based on the value. patterns that are recognized and replaced with appropriately-formatted
Any text that is not a template pattern is simply data based on the given value. Any text that is not a template pattern is
copied verbatim. Similarly, in an input template string (anything but <function>to_char</>), template patterns simply copied verbatim. Similarly, in an input template string (for the
identify the values to be supplied by the input data string. other functions), template patterns identify the values to be supplied by
the input data string.
</para> </para>
<para> <para>
...@@ -5033,11 +5040,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5033,11 +5040,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row> </row>
<row> <row>
<entry><literal>RM</literal></entry> <entry><literal>RM</literal></entry>
<entry>uppercase month in Roman numerals (I-XII; I=January)</entry> <entry>month in uppercase Roman numerals (I-XII; I=January)</entry>
</row> </row>
<row> <row>
<entry><literal>rm</literal></entry> <entry><literal>rm</literal></entry>
<entry>lowercase month in Roman numerals (i-xii; i=January)</entry> <entry>month in lowercase Roman numerals (i-xii; i=January)</entry>
</row> </row>
<row> <row>
<entry><literal>TZ</literal></entry> <entry><literal>TZ</literal></entry>
...@@ -5073,7 +5080,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5073,7 +5080,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<tbody> <tbody>
<row> <row>
<entry><literal>FM</literal> prefix</entry> <entry><literal>FM</literal> prefix</entry>
<entry>fill mode (suppress padding of blanks and zeroes)</entry> <entry>fill mode (suppress padding blanks and zeroes)</entry>
<entry><literal>FMMonth</literal></entry> <entry><literal>FMMonth</literal></entry>
</row> </row>
<row> <row>
...@@ -5099,7 +5106,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5099,7 +5106,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row> </row>
<row> <row>
<entry><literal>SP</literal> suffix</entry> <entry><literal>SP</literal> suffix</entry>
<entry>spell mode (not supported)</entry> <entry>spell mode (not implemented)</entry>
<entry><literal>DDSP</literal></entry> <entry><literal>DDSP</literal></entry>
</row> </row>
</tbody> </tbody>
...@@ -5127,8 +5134,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5127,8 +5134,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem> <listitem>
<para> <para>
<function>to_timestamp</function> and <function>to_date</function> <function>to_timestamp</function> and <function>to_date</function>
skip multiple blank spaces in the input string unless the <literal>FX</literal> option skip multiple blank spaces in the input string unless the
is used. For example, <literal>FX</literal> option is used. For example,
<literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'YYYY MON')</literal> works, but <literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'YYYY MON')</literal> works, but
<literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'FXYYYY MON')</literal> returns an error <literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'FXYYYY MON')</literal> returns an error
because <function>to_timestamp</function> expects one space only. because <function>to_timestamp</function> expects one space only.
...@@ -5177,8 +5184,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5177,8 +5184,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem> <listitem>
<para> <para>
In conversions from string to <type>timestamp</type> or In conversions from string to <type>timestamp</type> or
<type>date</type>, the <literal>CC</literal> field (century) is ignored if there <type>date</type>, the <literal>CC</literal> (century) field is ignored
is a <literal>YYY</literal>, <literal>YYYY</literal> or if there is a <literal>YYY</literal>, <literal>YYYY</literal> or
<literal>Y,YYY</literal> field. If <literal>CC</literal> is used with <literal>Y,YYY</literal> field. If <literal>CC</literal> is used with
<literal>YY</literal> or <literal>Y</literal> then the year is computed <literal>YY</literal> or <literal>Y</literal> then the year is computed
as <literal>(CC-1)*100+YY</literal>. as <literal>(CC-1)*100+YY</literal>.
...@@ -5220,7 +5227,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5220,7 +5227,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem> <listitem>
<para> <para>
In a conversion from string to <type>timestamp</type>, millisecond In a conversion from string to <type>timestamp</type>, millisecond
(<literal>MS</literal>) and microsecond (<literal>US</literal>) (<literal>MS</literal>) or microsecond (<literal>US</literal>)
values are used as the values are used as the
seconds digits after the decimal point. For example seconds digits after the decimal point. For example
<literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds, <literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds,
...@@ -5251,7 +5258,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5251,7 +5258,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</listitem> </listitem>
<listitem> <listitem>
<para><function>to_char(interval)</function> formats <literal>HH</> and <para>
<function>to_char(interval)</function> formats <literal>HH</> and
<literal>HH12</> as hours in a single day, while <literal>HH24</> <literal>HH12</> as hours in a single day, while <literal>HH24</>
can output hours exceeding a single day, e.g., &gt;24. can output hours exceeding a single day, e.g., &gt;24.
</para> </para>
...@@ -5392,8 +5400,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); ...@@ -5392,8 +5400,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<replaceable>n</replaceable> is the number of digits following <replaceable>n</replaceable> is the number of digits following
<literal>V</literal>. <literal>V</literal>.
<function>to_char</function> does not support the use of <function>to_char</function> does not support the use of
<literal>V</literal> with non-integer values. <literal>V</literal> combined with a decimal point
(e.g., <literal>99.9V99</literal> is not allowed.) (e.g., <literal>99.9V99</literal> is not allowed).
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -6129,7 +6137,7 @@ EXTRACT(<replaceable>field</replaceable> FROM <replaceable>source</replaceable>) ...@@ -6129,7 +6137,7 @@ EXTRACT(<replaceable>field</replaceable> FROM <replaceable>source</replaceable>)
<term><literal>century</literal></term> <term><literal>century</literal></term>
<listitem> <listitem>
<para> <para>
The century: The century
</para> </para>
<screen> <screen>
...@@ -6225,7 +6233,7 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); ...@@ -6225,7 +6233,7 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
<listitem> <listitem>
<para> <para>
For <type>date</type> and <type>timestamp</type> values, the For <type>date</type> and <type>timestamp</type> values, the
number of seconds since 1970-01-01 00:00:00-00 GMT (can be negative); number of seconds since 1970-01-01 00:00:00 UTC (can be negative);
for <type>interval</type> values, the total number for <type>interval</type> values, the total number
of seconds in the interval of seconds in the interval
</para> </para>
...@@ -6778,6 +6786,9 @@ now() ...@@ -6778,6 +6786,9 @@ now()
</para> </para>
<para> <para>
<function>transaction_timestamp()</> is equivalent to
<function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect
what it returns.
<function>statement_timestamp()</> returns the start time of the current <function>statement_timestamp()</> returns the start time of the current
statement (more specifically, the time of receipt of the latest command statement (more specifically, the time of receipt of the latest command
message from the client). message from the client).
...@@ -6792,10 +6803,7 @@ now() ...@@ -6792,10 +6803,7 @@ now()
but as a formatted <type>text</> string rather than a <type>timestamp but as a formatted <type>text</> string rather than a <type>timestamp
with time zone</> value. with time zone</> value.
<function>now()</> is a traditional <productname>PostgreSQL</productname> <function>now()</> is a traditional <productname>PostgreSQL</productname>
equivalent to <function>CURRENT_TIMESTAMP</function>. equivalent to <function>transaction_timestamp()</function>.
<function>transaction_timestamp()</> is likewise equivalent to
<function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect
what it returns.
</para> </para>
<para> <para>
...@@ -7428,7 +7436,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ...@@ -7428,7 +7436,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
<para> <para>
It is possible to access the two component numbers of a <type>point</> It is possible to access the two component numbers of a <type>point</>
as though they were an array with indices 0 and 1. For example, if as though the point were an array with indexes 0 and 1. For example, if
<literal>t.p</> is a <type>point</> column then <literal>t.p</> is a <type>point</> column then
<literal>SELECT p[0] FROM t</> retrieves the X coordinate and <literal>SELECT p[0] FROM t</> retrieves the X coordinate and
<literal>UPDATE t SET p[1] = ...</> changes the Y coordinate. <literal>UPDATE t SET p[1] = ...</> changes the Y coordinate.
...@@ -8235,7 +8243,7 @@ SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test; ...@@ -8235,7 +8243,7 @@ SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
<para> <para>
Element content, if specified, will be formatted according to Element content, if specified, will be formatted according to
the data type. If the content is itself of type <type>xml</type>, its data type. If the content is itself of type <type>xml</type>,
complex XML documents can be constructed. For example: complex XML documents can be constructed. For example:
<screen><![CDATA[ <screen><![CDATA[
SELECT xmlelement(name foo, xmlattributes('xyz' as bar), SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
...@@ -8360,9 +8368,9 @@ SELECT xmlpi(name php, 'echo "hello world";'); ...@@ -8360,9 +8368,9 @@ SELECT xmlpi(name php, 'echo "hello world";');
<para> <para>
The <function>xmlroot</function> expression alters the properties The <function>xmlroot</function> expression alters the properties
of the root node of an XML value. If a version is specified, of the root node of an XML value. If a version is specified,
this replaces the value in the version declaration; if a it replaces the value in the root node's version declaration; if a
standalone value is specified, this replaces the value in the standalone setting is specified, it replaces the value in the
standalone declaration. root node's standalone declaration.
</para> </para>
<para> <para>
...@@ -8967,7 +8975,7 @@ SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</> wi ...@@ -8967,7 +8975,7 @@ SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</> wi
<para> <para>
If a sequence object has been created with default parameters, If a sequence object has been created with default parameters,
<function>nextval</function> will return successive values successive <function>nextval</function> calls will return successive values
beginning with 1. Other behaviors can be obtained by using beginning with 1. Other behaviors can be obtained by using
special parameters in the <xref linkend="sql-createsequence" endterm="sql-createsequence-title"> command; special parameters in the <xref linkend="sql-createsequence" endterm="sql-createsequence-title"> command;
see its command reference page for more information. see its command reference page for more information.
...@@ -9028,16 +9036,17 @@ END ...@@ -9028,16 +9036,17 @@ END
</synopsis> </synopsis>
<token>CASE</token> clauses can be used wherever <token>CASE</token> clauses can be used wherever
an expression is valid. <replaceable>condition</replaceable> is an an expression is valid. Each <replaceable>condition</replaceable> is an
expression that returns a <type>boolean</type> result. If the result is true expression that returns a <type>boolean</type> result. If the condition's
the value of the <token>CASE</token> expression is the result is true, the value of the <token>CASE</token> expression is the
<replaceable>result</replaceable> that follows the condition. If the result is false <replaceable>result</replaceable> that follows the condition, and the
subsequent <token>WHEN</token> clauses are searched in the same remainder of the <token>CASE</token> expression is not processed. If the
manner. If no <token>WHEN</token> condition's result is not true, any subsequent <token>WHEN</token> clauses
<replaceable>condition</replaceable> is true then the value of the are examined in the same manner. If no <token>WHEN</token>
case expression is the <replaceable>result</replaceable> of the <replaceable>condition</replaceable> yields true, the value of the
<token>CASE</> expression is the <replaceable>result</replaceable> of the
<token>ELSE</token> clause. If the <token>ELSE</token> clause is <token>ELSE</token> clause. If the <token>ELSE</token> clause is
omitted and no condition matches, the result is null. omitted and no condition is true, the result is null.
</para> </para>
<para> <para>
...@@ -9074,8 +9083,8 @@ SELECT a, ...@@ -9074,8 +9083,8 @@ SELECT a,
</para> </para>
<para> <para>
The following <token>CASE</token> expression is a There is a <quote>simple</> form of <token>CASE</token> expression
variant of the general form above: that is a variant of the general form above:
<synopsis> <synopsis>
CASE <replaceable>expression</replaceable> CASE <replaceable>expression</replaceable>
...@@ -9085,10 +9094,10 @@ CASE <replaceable>expression</replaceable> ...@@ -9085,10 +9094,10 @@ CASE <replaceable>expression</replaceable>
END END
</synopsis> </synopsis>
The The first
<replaceable>expression</replaceable> is computed and compared to <replaceable>expression</replaceable> is computed, then compared to
all the <replaceable>value</replaceable>s in the each of the <replaceable>value</replaceable> expressions in the
<token>WHEN</token> clauses until one is found that is equal. If <token>WHEN</token> clauses until one is found that is equal to it. If
no match is found, the <replaceable>result</replaceable> of the no match is found, the <replaceable>result</replaceable> of the
<token>ELSE</token> clause (or a null value) is returned. This is similar <token>ELSE</token> clause (or a null value) is returned. This is similar
to the <function>switch</function> statement in C. to the <function>switch</function> statement in C.
...@@ -9114,8 +9123,8 @@ SELECT a, ...@@ -9114,8 +9123,8 @@ SELECT a,
</para> </para>
<para> <para>
A <token>CASE</token> expression evaluates any subexpressions A <token>CASE</token> expression does not evaluate any subexpressions
that are needed to determine the result. For example, this is a that are not needed to determine the result. For example, this is a
possible way of avoiding a division-by-zero failure: possible way of avoiding a division-by-zero failure:
<programlisting> <programlisting>
SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END; SELECT ... WHERE CASE WHEN x &lt;&gt; 0 THEN y/x &gt; 1.5 ELSE false END;
...@@ -9154,7 +9163,7 @@ SELECT COALESCE(description, short_description, '(none)') ... ...@@ -9154,7 +9163,7 @@ SELECT COALESCE(description, short_description, '(none)') ...
<para> <para>
Like a <token>CASE</token> expression, <function>COALESCE</function> only Like a <token>CASE</token> expression, <function>COALESCE</function> only
evaluates arguments that are needed to determine the result; evaluates the arguments that are needed to determine the result;
that is, arguments to the right of the first non-null argument are that is, arguments to the right of the first non-null argument are
not evaluated. This SQL-standard function provides capabilities similar not evaluated. This SQL-standard function provides capabilities similar
to <function>NVL</> and <function>IFNULL</>, which are used in some other to <function>NVL</> and <function>IFNULL</>, which are used in some other
...@@ -9813,8 +9822,9 @@ SELECT NULLIF(value, '(none)') ... ...@@ -9813,8 +9822,9 @@ SELECT NULLIF(value, '(none)') ...
<programlisting> <programlisting>
SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...; SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
</programlisting> </programlisting>
Here <function>ANY</function> can be considered as leading either Here <function>ANY</function> can be considered either as introducing
to a subquery or to an aggregate, if the select expression returns one row. a subquery, or as being an aggregate function, if the sub-select
returns one row with a boolean value.
Thus the standard name cannot be given to these aggregates. Thus the standard name cannot be given to these aggregates.
</para> </para>
</note> </note>
...@@ -9829,7 +9839,7 @@ SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...; ...@@ -9829,7 +9839,7 @@ SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
SELECT count(*) FROM sometable; SELECT count(*) FROM sometable;
</programlisting> </programlisting>
will be executed by <productname>PostgreSQL</productname> using a will be executed by <productname>PostgreSQL</productname> using a
sequential scan of an entire table. sequential scan of the entire table.
</para> </para>
</note> </note>
...@@ -10882,7 +10892,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2); ...@@ -10882,7 +10892,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
The forms involving array subexpressions are The forms involving array subexpressions are
<productname>PostgreSQL</productname> extensions; the rest are <productname>PostgreSQL</productname> extensions; the rest are
<acronym>SQL</acronym>-compliant. <acronym>SQL</acronym>-compliant.
All of the expressions documented in this section return All of the expression forms documented in this section return
Boolean (true/false) results. Boolean (true/false) results.
</para> </para>
...@@ -11594,8 +11604,8 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, .. ...@@ -11594,8 +11604,8 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<para> <para>
<function>pg_my_temp_schema</function> returns the OID of the current <function>pg_my_temp_schema</function> returns the OID of the current
session's temporary schema, or 0 if it has none (because no session's temporary schema, or zero if it has none (because it has not
temporary tables have been created). created any temporary tables).
<function>pg_is_other_temp_schema</function> returns true if the <function>pg_is_other_temp_schema</function> returns true if the
given OID is the OID of another session's temporary schema. given OID is the OID of another session's temporary schema.
(This can be useful, for example, to exclude other sessions' temporary (This can be useful, for example, to exclude other sessions' temporary
...@@ -11891,7 +11901,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION') ...@@ -11891,7 +11901,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para> <para>
<function>has_any_column_privilege</function> checks whether a user can <function>has_any_column_privilege</function> checks whether a user can
access any column of a table in a particular way; its argument possibilities access any column of a table in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</>, are analogous to <function>has_table_privilege</>,
except that the desired access privilege type must evaluate to some except that the desired access privilege type must evaluate to some
combination of combination of
...@@ -11908,7 +11919,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION') ...@@ -11908,7 +11919,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para> <para>
<function>has_column_privilege</function> checks whether a user <function>has_column_privilege</function> checks whether a user
can access a column in a particular way; its argument possibilities can access a column in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>, are analogous to <function>has_table_privilege</function>,
with the addition that the column can be specified either by name with the addition that the column can be specified either by name
or attribute number. or attribute number.
...@@ -11922,7 +11934,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION') ...@@ -11922,7 +11934,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para> <para>
<function>has_database_privilege</function> checks whether a user <function>has_database_privilege</function> checks whether a user
can access a database in a particular way; its argument possibilities can access a database in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to some combination of The desired access privilege type must evaluate to some combination of
<literal>CREATE</literal>, <literal>CREATE</literal>,
...@@ -11934,7 +11947,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION') ...@@ -11934,7 +11947,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para> <para>
<function>has_function_privilege</function> checks whether a user <function>has_function_privilege</function> checks whether a user
can access a function in a particular way; its argument possibilities can access a function in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
When specifying a function by a text string rather than by OID, When specifying a function by a text string rather than by OID,
the allowed input is the same as for the <type>regprocedure</> data type the allowed input is the same as for the <type>regprocedure</> data type
...@@ -11949,7 +11963,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); ...@@ -11949,7 +11963,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para> <para>
<function>has_foreign_data_wrapper_privilege</function> checks whether a user <function>has_foreign_data_wrapper_privilege</function> checks whether a user
can access a foreign-data wrapper in a particular way; its argument possibilities can access a foreign-data wrapper in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to The desired access privilege type must evaluate to
<literal>USAGE</literal>. <literal>USAGE</literal>.
...@@ -11957,7 +11972,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); ...@@ -11957,7 +11972,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para> <para>
<function>has_language_privilege</function> checks whether a user <function>has_language_privilege</function> checks whether a user
can access a procedural language in a particular way; its argument possibilities can access a procedural language in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to The desired access privilege type must evaluate to
<literal>USAGE</literal>. <literal>USAGE</literal>.
...@@ -11965,7 +11981,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); ...@@ -11965,7 +11981,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para> <para>
<function>has_schema_privilege</function> checks whether a user <function>has_schema_privilege</function> checks whether a user
can access a schema in a particular way; its argument possibilities can access a schema in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to some combination of The desired access privilege type must evaluate to some combination of
<literal>CREATE</literal> or <literal>CREATE</literal> or
...@@ -11974,7 +11991,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); ...@@ -11974,7 +11991,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para> <para>
<function>has_server_privilege</function> checks whether a user <function>has_server_privilege</function> checks whether a user
can access a foreign server in a particular way; its argument possibilities can access a foreign server in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to The desired access privilege type must evaluate to
<literal>USAGE</literal>. <literal>USAGE</literal>.
...@@ -11982,7 +12000,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); ...@@ -11982,7 +12000,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para> <para>
<function>has_tablespace_privilege</function> checks whether a user <function>has_tablespace_privilege</function> checks whether a user
can access a tablespace in a particular way; its argument possibilities can access a tablespace in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to The desired access privilege type must evaluate to
<literal>CREATE</literal>. <literal>CREATE</literal>.
...@@ -11990,7 +12009,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); ...@@ -11990,7 +12009,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para> <para>
<function>pg_has_role</function> checks whether a user <function>pg_has_role</function> checks whether a user
can access a role in a particular way; its argument possibilities can access a role in a particular way.
Its argument possibilities
are analogous to <function>has_table_privilege</function>. are analogous to <function>has_table_privilege</function>.
The desired access privilege type must evaluate to some combination of The desired access privilege type must evaluate to some combination of
<literal>MEMBER</literal> or <literal>MEMBER</literal> or
...@@ -12305,7 +12325,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); ...@@ -12305,7 +12325,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry> <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry>
</row> </row>
<row> <row>
<entry><literal><function>pg_get_userbyid</function>(<parameter>roleid</parameter>)</literal></entry> <entry><literal><function>pg_get_userbyid</function>(<parameter>role_oid</parameter>)</literal></entry>
<entry><type>name</type></entry> <entry><type>name</type></entry>
<entry>get role name with given OID</entry> <entry>get role name with given OID</entry>
</row> </row>
...@@ -12559,7 +12579,7 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33); ...@@ -12559,7 +12579,7 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
<para> <para>
The functions shown in <xref linkend="functions-txid-snapshot"> The functions shown in <xref linkend="functions-txid-snapshot">
export server transaction information. The main provide server transaction information in an exportable form. The main
use of these functions is to determine which transactions were committed use of these functions is to determine which transactions were committed
between two snapshots. between two snapshots.
</para> </para>
...@@ -12641,8 +12661,8 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33); ...@@ -12641,8 +12661,8 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
<row> <row>
<entry><type>xmax</type></entry> <entry><type>xmax</type></entry>
<entry> <entry>
First as-yet-unassigned txid. All txids later than this are First as-yet-unassigned txid. All txids greater than or equal to this
not yet started as of the time of the snapshot, and thus invisible. are not yet started as of the time of the snapshot, and thus invisible.
</entry> </entry>
</row> </row>
...@@ -12652,7 +12672,7 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33); ...@@ -12652,7 +12672,7 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
Active txids at the time of the snapshot. The list Active txids at the time of the snapshot. The list
includes only those active txids between <literal>xmin</> includes only those active txids between <literal>xmin</>
and <literal>xmax</>; there might be active txids higher and <literal>xmax</>; there might be active txids higher
than xmax. A txid that is <literal>xmin &lt;= txid &lt; than <literal>xmax</>. A txid that is <literal>xmin &lt;= txid &lt;
xmax</literal> and not in this list was already completed xmax</literal> and not in this list was already completed
at the time of the snapshot, and thus either visible or at the time of the snapshot, and thus either visible or
dead according to its commit status. The list does not dead according to its commit status. The list does not
...@@ -12834,9 +12854,9 @@ SELECT set_config('log_statement_stats', 'off', false); ...@@ -12834,9 +12854,9 @@ SELECT set_config('log_statement_stats', 'off', false);
The process ID of an active backend can be found from The process ID of an active backend can be found from
the <structfield>procpid</structfield> column of the the <structfield>procpid</structfield> column of the
<structname>pg_stat_activity</structname> view, or by listing the <structname>pg_stat_activity</structname> view, or by listing the
<command>postgres</command> processes on the server using <command>postgres</command> processes on the server (using
<application>ps</> on Unix or the <application>Task <application>ps</> on Unix or the <application>Task
Manager</> on <productname>Windows</>. Manager</> on <productname>Windows</>).
</para> </para>
<para> <para>
...@@ -12904,7 +12924,7 @@ SELECT set_config('log_statement_stats', 'off', false); ...@@ -12904,7 +12924,7 @@ SELECT set_config('log_statement_stats', 'off', false);
<literal><function>pg_stop_backup</function>()</literal> <literal><function>pg_stop_backup</function>()</literal>
</entry> </entry>
<entry><type>text</type></entry> <entry><type>text</type></entry>
<entry>Finalize after performing on-line backup</entry> <entry>Finish performing on-line backup</entry>
</row> </row>
<row> <row>
<entry> <entry>
...@@ -12991,7 +13011,7 @@ postgres=# select pg_start_backup('label_goes_here'); ...@@ -12991,7 +13011,7 @@ postgres=# select pg_start_backup('label_goes_here');
<para> <para>
<function>pg_current_xlog_location</> displays the current transaction log write <function>pg_current_xlog_location</> displays the current transaction log write
location in the format used by the above functions. Similarly, location in the same format used by the above functions. Similarly,
<function>pg_current_xlog_insert_location</> displays the current transaction log <function>pg_current_xlog_insert_location</> displays the current transaction log
insertion point. The insertion point is the <quote>logical</> end insertion point. The insertion point is the <quote>logical</> end
of the transaction log of the transaction log
...@@ -13086,9 +13106,9 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); ...@@ -13086,9 +13106,9 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
</entry> </entry>
<entry><type>bigint</type></entry> <entry><type>bigint</type></entry>
<entry> <entry>
Disk space used by the specified fork, <literal>'main'</literal> or Disk space used by the specified fork (<literal>'main'</literal>,
<literal>'fsm'</literal>, of a table or index with the specified OID <literal>'fsm'</literal> or <literal>'vm'</>)
or name; the table name can be schema-qualified. of the table or index with the specified OID or name
</entry> </entry>
</row> </row>
<row> <row>
...@@ -13128,8 +13148,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); ...@@ -13128,8 +13148,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<entry><type>bigint</type></entry> <entry><type>bigint</type></entry>
<entry> <entry>
Total disk space used by the table with the specified OID or name, Total disk space used by the table with the specified OID or name,
including indexes and <acronym>TOAST</> data; the table name can be including indexes and <acronym>TOAST</> data
schema-qualified.
</entry> </entry>
</row> </row>
</tbody> </tbody>
...@@ -13154,6 +13173,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); ...@@ -13154,6 +13173,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
size of the main data fork of the relation. Specifying size of the main data fork of the relation. Specifying
<literal>'fsm'</literal> returns the size of the <literal>'fsm'</literal> returns the size of the
Free Space Map (see <xref linkend="storage-fsm">) associated with the Free Space Map (see <xref linkend="storage-fsm">) associated with the
relation. Specifying <literal>'vm'</literal> returns the size of the
Visibility Map (see <xref linkend="storage-vm">) associated with the
relation. relation.
</para> </para>
...@@ -13240,7 +13261,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup()); ...@@ -13240,7 +13261,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
size, last accessed time stamp, last modified time stamp, size, last accessed time stamp, last modified time stamp,
last file status change time stamp (Unix platforms only), last file status change time stamp (Unix platforms only),
file creation time stamp (Windows only), and a <type>boolean</type> file creation time stamp (Windows only), and a <type>boolean</type>
indicating if it is a directory. Typical usage include: indicating if it is a directory. Typical usages include:
<programlisting> <programlisting>
SELECT * FROM pg_stat_file('filename'); SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification; SELECT (pg_stat_file('filename')).modification;
...@@ -13426,7 +13447,7 @@ SELECT (pg_stat_file('filename')).modification; ...@@ -13426,7 +13447,7 @@ SELECT (pg_stat_file('filename')).modification;
<para> <para>
<function>pg_advisory_unlock_shared</> works the same as <function>pg_advisory_unlock_shared</> works the same as
<function>pg_advisory_unlock</>, <function>pg_advisory_unlock</>,
except is releases a shared advisory lock. except it releases a shared advisory lock.
</para> </para>
<indexterm> <indexterm>
...@@ -13435,7 +13456,7 @@ SELECT (pg_stat_file('filename')).modification; ...@@ -13435,7 +13456,7 @@ SELECT (pg_stat_file('filename')).modification;
<para> <para>
<function>pg_advisory_unlock_all</> will release all advisory locks <function>pg_advisory_unlock_all</> will release all advisory locks
held by the current session. (This function is implicitly invoked held by the current session. (This function is implicitly invoked
at session end, even if the client disconnects abruptly.) at session end, even if the client disconnects ungracefully.)
</para> </para>
</sect1> </sect1>
......
doc/src/sgml/indices.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.77 2009/04/27 16:27:35 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.78 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="indexes"> <chapter id="indexes">
<title id="indexes-title">Indexes</title> <title id="indexes-title">Indexes</title>
...@@ -36,7 +36,7 @@ SELECT content FROM test1 WHERE id = <replaceable>constant</replaceable>; ...@@ -36,7 +36,7 @@ SELECT content FROM test1 WHERE id = <replaceable>constant</replaceable>;
matching entries. If there are many rows in matching entries. If there are many rows in
<structname>test1</structname> and only a few rows (perhaps zero <structname>test1</structname> and only a few rows (perhaps zero
or one) that would be returned by such a query, this is clearly an or one) that would be returned by such a query, this is clearly an
inefficient method. But if the system maintains an inefficient method. But if the system has been instructed to maintain an
index on the <structfield>id</structfield> column, it can use a more index on the <structfield>id</structfield> column, it can use a more
efficient method for locating matching rows. For instance, it efficient method for locating matching rows. For instance, it
might only have to walk a few levels deep into a search tree. might only have to walk a few levels deep into a search tree.
...@@ -73,7 +73,7 @@ CREATE INDEX test1_id_index ON test1 (id); ...@@ -73,7 +73,7 @@ CREATE INDEX test1_id_index ON test1 (id);
<para> <para>
Once an index is created, no further intervention is required: the Once an index is created, no further intervention is required: the
system will update the index when the table is modified, and it will system will update the index when the table is modified, and it will
use the index in queries when it thinks it would be more efficient use the index in queries when it thinks doing so would be more efficient
than a sequential table scan. But you might have to run the than a sequential table scan. But you might have to run the
<command>ANALYZE</command> command regularly to update <command>ANALYZE</command> command regularly to update
statistics to allow the query planner to make educated decisions. statistics to allow the query planner to make educated decisions.
...@@ -294,7 +294,7 @@ CREATE TABLE test2 ( ...@@ -294,7 +294,7 @@ CREATE TABLE test2 (
<programlisting> <programlisting>
SELECT name FROM test2 WHERE major = <replaceable>constant</replaceable> AND minor = <replaceable>constant</replaceable>; SELECT name FROM test2 WHERE major = <replaceable>constant</replaceable> AND minor = <replaceable>constant</replaceable>;
</programlisting> </programlisting>
then it might be appropriate to define an index on columns then it might be appropriate to define an index on the columns
<structfield>major</structfield> and <structfield>major</structfield> and
<structfield>minor</structfield> together, e.g.: <structfield>minor</structfield> together, e.g.:
<programlisting> <programlisting>
...@@ -384,16 +384,16 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor); ...@@ -384,16 +384,16 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor);
<para> <para>
The planner will consider satisfying an <literal>ORDER BY</> specification The planner will consider satisfying an <literal>ORDER BY</> specification
by either scanning an available index that matches the specification, either by scanning an available index that matches the specification,
or by scanning the table in physical order and doing an explicit or by scanning the table in physical order and doing an explicit
sort. For a query that requires scanning a large fraction of the sort. For a query that requires scanning a large fraction of the
table, the explicit sort is likely to be faster than using an index table, an explicit sort is likely to be faster than using an index
because it requires because it requires
less disk I/O due to a sequential access pattern. Indexes are less disk I/O due to following a sequential access pattern. Indexes are
more useful when only a few rows need be fetched. An important more useful when only a few rows need be fetched. An important
special case is <literal>ORDER BY</> in combination with special case is <literal>ORDER BY</> in combination with
<literal>LIMIT</> <replaceable>n</>: an explicit sort will have to process <literal>LIMIT</> <replaceable>n</>: an explicit sort will have to process
all data to identify the first <replaceable>n</> rows, but if there is all the data to identify the first <replaceable>n</> rows, but if there is
an index matching the <literal>ORDER BY</>, the first <replaceable>n</> an index matching the <literal>ORDER BY</>, the first <replaceable>n</>
rows can be retrieved directly, without scanning the remainder at all. rows can be retrieved directly, without scanning the remainder at all.
</para> </para>
...@@ -433,14 +433,14 @@ CREATE INDEX test3_desc_index ON test3 (id DESC NULLS LAST); ...@@ -433,14 +433,14 @@ CREATE INDEX test3_desc_index ON test3 (id DESC NULLS LAST);
<literal>ORDER BY x DESC, y DESC</> if we scan backward. <literal>ORDER BY x DESC, y DESC</> if we scan backward.
But it might be that the application frequently needs to use But it might be that the application frequently needs to use
<literal>ORDER BY x ASC, y DESC</>. There is no way to get that <literal>ORDER BY x ASC, y DESC</>. There is no way to get that
ordering from a simpler index, but it is possible if the index is defined ordering from a plain index, but it is possible if the index is defined
as <literal>(x ASC, y DESC)</> or <literal>(x DESC, y ASC)</>. as <literal>(x ASC, y DESC)</> or <literal>(x DESC, y ASC)</>.
</para> </para>
<para> <para>
Obviously, indexes with non-default sort orderings are a fairly Obviously, indexes with non-default sort orderings are a fairly
specialized feature, but sometimes they can produce tremendous specialized feature, but sometimes they can produce tremendous
speedups for certain queries. Whether it's worth creating such an speedups for certain queries. Whether it's worth maintaining such an
index depends on how often you use queries that require a special index depends on how often you use queries that require a special
sort ordering. sort ordering.
</para> </para>
...@@ -584,9 +584,9 @@ CREATE UNIQUE INDEX <replaceable>name</replaceable> ON <replaceable>table</repla ...@@ -584,9 +584,9 @@ CREATE UNIQUE INDEX <replaceable>name</replaceable> ON <replaceable>table</repla
</indexterm> </indexterm>
<para> <para>
An index column need not be just a column of an underlying table, An index column need not be just a column of the underlying table,
but can be a function or scalar expression computed from one or but can be a function or scalar expression computed from one or
more columns of a table. This feature is useful to obtain fast more columns of the table. This feature is useful to obtain fast
access to tables based on the results of computations. access to tables based on the results of computations.
</para> </para>
...@@ -666,8 +666,8 @@ CREATE INDEX people_names ON people ((first_name || ' ' || last_name)); ...@@ -666,8 +666,8 @@ CREATE INDEX people_names ON people ((first_name || ' ' || last_name));
values. Since a query searching for a common value (one that values. Since a query searching for a common value (one that
accounts for more than a few percent of all the table rows) will not accounts for more than a few percent of all the table rows) will not
use the index anyway, there is no point in keeping those rows in the use the index anyway, there is no point in keeping those rows in the
index. A partial index reduces the size of the index, which speeds index at all. This reduces the size of the index, which will speed
up queries that use the index. It will also speed up many table up those queries that do use the index. It will also speed up many table
update operations because the index does not need to be update operations because the index does not need to be
updated in all cases. <xref linkend="indexes-partial-ex1"> shows a updated in all cases. <xref linkend="indexes-partial-ex1"> shows a
possible application of this idea. possible application of this idea.
...@@ -724,14 +724,14 @@ WHERE client_ip = inet '192.168.100.23'; ...@@ -724,14 +724,14 @@ WHERE client_ip = inet '192.168.100.23';
<para> <para>
Observe that this kind of partial index requires that the common Observe that this kind of partial index requires that the common
values be predetermined, so such partial indexes are best used for values be predetermined, so such partial indexes are best used for
data distribution that do not change. The indexes can be recreated data distributions that do not change. The indexes can be recreated
occasionally to adjust for new data distributions, but this adds occasionally to adjust for new data distributions, but this adds
maintenance overhead. maintenance effort.
</para> </para>
</example> </example>
<para> <para>
Another possible use for partial indexes is to exclude values from the Another possible use for a partial index is to exclude values from the
index that the index that the
typical query workload is not interested in; this is shown in <xref typical query workload is not interested in; this is shown in <xref
linkend="indexes-partial-ex2">. This results in the same linkend="indexes-partial-ex2">. This results in the same
......
doc/src/sgml/installation.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.323 2009/06/12 15:53:32 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.324 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="installation"> <chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]> <title><![%standalone-include[<productname>PostgreSQL</>]]>
...@@ -85,7 +85,7 @@ su - postgres ...@@ -85,7 +85,7 @@ su - postgres
<listitem> <listitem>
<para> <para>
You need an <acronym>ISO</>/<acronym>ANSI</> C compiler (minimum You need an <acronym>ISO</>/<acronym>ANSI</> C compiler (at least
C89-compliant). Recent C89-compliant). Recent
versions of <productname>GCC</> are recommendable, but versions of <productname>GCC</> are recommendable, but
<productname>PostgreSQL</> is known to build using a wide variety <productname>PostgreSQL</> is known to build using a wide variety
...@@ -118,7 +118,7 @@ su - postgres ...@@ -118,7 +118,7 @@ su - postgres
command you type, and allows you to use arrow keys to recall and command you type, and allows you to use arrow keys to recall and
edit previous commands. This is very helpful and is strongly edit previous commands. This is very helpful and is strongly
recommended. If you don't want to use it then you must specify recommended. If you don't want to use it then you must specify
the <option>--without-readline</option> option of the <option>--without-readline</option> option to
<filename>configure</>. As an alternative, you can often use the <filename>configure</>. As an alternative, you can often use the
BSD-licensed <filename>libedit</filename> library, originally BSD-licensed <filename>libedit</filename> library, originally
developed on <productname>NetBSD</productname>. The developed on <productname>NetBSD</productname>. The
...@@ -422,11 +422,10 @@ su - postgres ...@@ -422,11 +422,10 @@ su - postgres
On systems that have <productname>PostgreSQL</> started at boot time, On systems that have <productname>PostgreSQL</> started at boot time,
there is probably a start-up file that will accomplish the same thing. For there is probably a start-up file that will accomplish the same thing. For
example, on a <systemitem class="osname">Red Hat Linux</> system one example, on a <systemitem class="osname">Red Hat Linux</> system one
might find that: might find that this works:
<screen> <screen>
<userinput>/etc/rc.d/init.d/postgresql stop</userinput> <userinput>/etc/rc.d/init.d/postgresql stop</userinput>
</screen> </screen>
works.
</para> </para>
</step> </step>
...@@ -471,7 +470,7 @@ su - postgres ...@@ -471,7 +470,7 @@ su - postgres
<step> <step>
<para> <para>
Start the database server, again the special database user Start the database server, again using the special database user
account: account:
<programlisting> <programlisting>
<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</> <userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
...@@ -1648,7 +1647,7 @@ All of PostgreSQL is successfully made. Ready to install. ...@@ -1648,7 +1647,7 @@ All of PostgreSQL is successfully made. Ready to install.
later on. To reset the source tree to the state in which it was later on. To reset the source tree to the state in which it was
distributed, use <command>gmake distclean</>. If you are going to distributed, use <command>gmake distclean</>. If you are going to
build for several platforms within the same source tree you must do build for several platforms within the same source tree you must do
this and rebuild for each platform. (Alternatively, use this and re-configure for each platform. (Alternatively, use
a separate build tree for each platform, so that the source tree a separate build tree for each platform, so that the source tree
remains unmodified.) remains unmodified.)
</para> </para>
...@@ -1675,7 +1674,7 @@ All of PostgreSQL is successfully made. Ready to install. ...@@ -1675,7 +1674,7 @@ All of PostgreSQL is successfully made. Ready to install.
</indexterm> </indexterm>
<para> <para>
On several systems with shared libraries On some systems with shared libraries
you need to tell the system how to find the newly installed you need to tell the system how to find the newly installed
shared libraries. The systems on which this is shared libraries. The systems on which this is
<emphasis>not</emphasis> necessary include <systemitem <emphasis>not</emphasis> necessary include <systemitem
......
doc/src/sgml/monitoring.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.69 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.70 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="monitoring"> <chapter id="monitoring">
<title>Monitoring Database Activity</title> <title>Monitoring Database Activity</title>
...@@ -929,7 +929,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re ...@@ -929,7 +929,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<function>read()</> calls issued for the table, index, or <function>read()</> calls issued for the table, index, or
database; the number of actual physical reads is usually database; the number of actual physical reads is usually
lower due to kernel-level buffering. The <literal>*_blks_read</> lower due to kernel-level buffering. The <literal>*_blks_read</>
statistics columns uses this subtraction, i.e., fetched minus hit. statistics columns use this subtraction, i.e., fetched minus hit.
</para> </para>
</note> </note>
......
doc/src/sgml/mvcc.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.71 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.72 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="mvcc"> <chapter id="mvcc">
<title>Concurrency Control</title> <title>Concurrency Control</title>
...@@ -246,7 +246,7 @@ ...@@ -246,7 +246,7 @@
committed before the query began; it never sees either uncommitted committed before the query began; it never sees either uncommitted
data or changes committed during query execution by concurrent data or changes committed during query execution by concurrent
transactions. In effect, a <command>SELECT</command> query sees transactions. In effect, a <command>SELECT</command> query sees
a snapshot of the database at the instant the query begins to a snapshot of the database as of the instant the query begins to
run. However, <command>SELECT</command> does see the effects run. However, <command>SELECT</command> does see the effects
of previous updates executed within its own transaction, even of previous updates executed within its own transaction, even
though they are not yet committed. Also note that two successive though they are not yet committed. Also note that two successive
...@@ -260,7 +260,7 @@ ...@@ -260,7 +260,7 @@
FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands
behave the same as <command>SELECT</command> behave the same as <command>SELECT</command>
in terms of searching for target rows: they will only find target rows in terms of searching for target rows: they will only find target rows
that were committed before the command start time. However, such a target that were committed as of the command start time. However, such a target
row might have already been updated (or deleted or locked) by row might have already been updated (or deleted or locked) by
another concurrent transaction by the time it is found. In this case, the another concurrent transaction by the time it is found. In this case, the
would-be updater will wait for the first updating transaction to commit or would-be updater will wait for the first updating transaction to commit or
...@@ -367,16 +367,17 @@ COMMIT; ...@@ -367,16 +367,17 @@ COMMIT;
transaction began; it never sees either uncommitted data or changes transaction began; it never sees either uncommitted data or changes
committed committed
during transaction execution by concurrent transactions. (However, during transaction execution by concurrent transactions. (However,
<command>SELECT</command> does see the effects of previous updates the query does see the effects of previous updates
executed within its own transaction, even though they are not yet executed within its own transaction, even though they are not yet
committed.) This is different from Read Committed in that committed.) This is different from Read Committed in that
<command>SELECT</command> in a serializable transaction a query in a serializable transaction
sees a snapshot as of the start of the <emphasis>transaction</>, not as of the start sees a snapshot as of the start of the <emphasis>transaction</>,
not as of the start
of the current query within the transaction. Thus, successive of the current query within the transaction. Thus, successive
<command>SELECT</command> commands within a <emphasis>single</> <command>SELECT</command> commands within a <emphasis>single</>
transaction see the same data, i.e. they never see changes made by transaction see the same data, i.e., they do not see changes made by
transactions that committed after its own transaction started. (This other transactions that committed after their own transaction started.
behavior can be ideal for reporting applications.) (This behavior can be ideal for reporting applications.)
</para> </para>
<para> <para>
...@@ -384,7 +385,7 @@ COMMIT; ...@@ -384,7 +385,7 @@ COMMIT;
FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands
behave the same as <command>SELECT</command> behave the same as <command>SELECT</command>
in terms of searching for target rows: they will only find target rows in terms of searching for target rows: they will only find target rows
that were committed before the transaction start time. However, such a that were committed as of the transaction start time. However, such a
target target
row might have already been updated (or deleted or locked) by row might have already been updated (or deleted or locked) by
another concurrent transaction by the time it is found. In this case, the another concurrent transaction by the time it is found. In this case, the
...@@ -666,9 +667,10 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -666,9 +667,10 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term> </term>
<listitem> <listitem>
<para> <para>
Conflicts all lock modes except <literal>ACCESS SHARE</literal>, Conflicts with the <literal>ROW EXCLUSIVE</literal>,
<literal>ROW SHARE</literal>, and <literal>SHARE</literal> (it <literal>SHARE UPDATE EXCLUSIVE</literal>, <literal>SHARE ROW
does not conflict with itself). EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
<literal>ACCESS EXCLUSIVE</literal> lock modes.
This mode protects a table against concurrent data changes. This mode protects a table against concurrent data changes.
</para> </para>
...@@ -685,8 +687,11 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -685,8 +687,11 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term> </term>
<listitem> <listitem>
<para> <para>
Conflicts all lock modes except <literal>ACCESS SHARE</literal> Conflicts with the <literal>ROW EXCLUSIVE</literal>,
and <literal>ROW SHARE</literal>. <literal>SHARE UPDATE EXCLUSIVE</literal>,
<literal>SHARE</literal>, <literal>SHARE ROW
EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
<literal>ACCESS EXCLUSIVE</literal> lock modes.
</para> </para>
<para> <para>
...@@ -702,7 +707,11 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -702,7 +707,11 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term> </term>
<listitem> <listitem>
<para> <para>
Conflicts all lock modes except <literal>ACCESS SHARE</literal>. Conflicts with the <literal>ROW SHARE</literal>, <literal>ROW
EXCLUSIVE</literal>, <literal>SHARE UPDATE
EXCLUSIVE</literal>, <literal>SHARE</literal>, <literal>SHARE
ROW EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
<literal>ACCESS EXCLUSIVE</literal> lock modes.
This mode allows only concurrent <literal>ACCESS SHARE</literal> locks, This mode allows only concurrent <literal>ACCESS SHARE</literal> locks,
i.e., only reads from the table can proceed in parallel with a i.e., only reads from the table can proceed in parallel with a
transaction holding this lock mode. transaction holding this lock mode.
...@@ -711,7 +720,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -711,7 +720,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
<para> <para>
This lock mode is not automatically acquired on user tables by any This lock mode is not automatically acquired on user tables by any
<productname>PostgreSQL</productname> command. However it is <productname>PostgreSQL</productname> command. However it is
acquired during certain internal system catalogs operations. acquired on certain system catalogs in some operations.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -722,7 +731,12 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -722,7 +731,12 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term> </term>
<listitem> <listitem>
<para> <para>
Conflicts with all lock modes. Conflicts with locks of all modes (<literal>ACCESS
SHARE</literal>, <literal>ROW SHARE</literal>, <literal>ROW
EXCLUSIVE</literal>, <literal>SHARE UPDATE
EXCLUSIVE</literal>, <literal>SHARE</literal>, <literal>SHARE
ROW EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
<literal>ACCESS EXCLUSIVE</literal>).
This mode guarantees that the This mode guarantees that the
holder is the only transaction accessing the table in any way. holder is the only transaction accessing the table in any way.
</para> </para>
...@@ -749,7 +763,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -749,7 +763,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
<para> <para>
Once acquired, a lock is normally held till end of transaction. But if a Once acquired, a lock is normally held till end of transaction. But if a
lock is acquired after establishing a savepoint, the lock is released lock is acquired after establishing a savepoint, the lock is released
immediately if the savepoint is rolled back. This is consistent with immediately if the savepoint is rolled back to. This is consistent with
the principle that <command>ROLLBACK</> cancels all effects of the the principle that <command>ROLLBACK</> cancels all effects of the
commands since the savepoint. The same holds for locks acquired within a commands since the savepoint. The same holds for locks acquired within a
<application>PL/pgSQL</> exception block: an error escape from the block <application>PL/pgSQL</> exception block: an error escape from the block
...@@ -882,8 +896,8 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -882,8 +896,8 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
can be exclusive or shared locks. An exclusive row-level lock on a can be exclusive or shared locks. An exclusive row-level lock on a
specific row is automatically acquired when the row is updated or specific row is automatically acquired when the row is updated or
deleted. The lock is held until the transaction commits or rolls deleted. The lock is held until the transaction commits or rolls
back, like table-level locks. Row-level locks do back, just like table-level locks. Row-level locks do
not affect data querying; they only block <emphasis>writers to the same not affect data querying; they block only <emphasis>writers to the same
row</emphasis>. row</emphasis>.
</para> </para>
...@@ -918,7 +932,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2; ...@@ -918,7 +932,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
used to control read/write access to table pages in the shared buffer used to control read/write access to table pages in the shared buffer
pool. These locks are released immediately after a row is fetched or pool. These locks are released immediately after a row is fetched or
updated. Application developers normally need not be concerned with updated. Application developers normally need not be concerned with
page-level locks, but they are mentioned for completeness. page-level locks, but they are mentioned here for completeness.
</para> </para>
</sect2> </sect2>
...@@ -1100,7 +1114,7 @@ SELECT pg_advisory_lock(q.id) FROM ...@@ -1100,7 +1114,7 @@ SELECT pg_advisory_lock(q.id) FROM
after the current query began). The row might have been modified or after the current query began). The row might have been modified or
deleted by an already-committed transaction that committed after deleted by an already-committed transaction that committed after
the <command>SELECT</command> started. the <command>SELECT</command> started.
Even if the row is still valid <emphasis>now</>, it could be changed or Even if the row is still valid <quote>now</>, it could be changed or
deleted deleted
before the current transaction does a commit or rollback. before the current transaction does a commit or rollback.
</para> </para>
...@@ -1121,7 +1135,7 @@ SELECT pg_advisory_lock(q.id) FROM ...@@ -1121,7 +1135,7 @@ SELECT pg_advisory_lock(q.id) FROM
concurrent updates one must use <command>SELECT FOR UPDATE</command>, concurrent updates one must use <command>SELECT FOR UPDATE</command>,
<command>SELECT FOR SHARE</command>, or an appropriate <command>LOCK <command>SELECT FOR SHARE</command>, or an appropriate <command>LOCK
TABLE</command> statement. (<command>SELECT FOR UPDATE</command> TABLE</command> statement. (<command>SELECT FOR UPDATE</command>
or <command>SELECT FOR SHARE</command> lock just the and <command>SELECT FOR SHARE</command> lock just the
returned rows against concurrent updates, while <command>LOCK returned rows against concurrent updates, while <command>LOCK
TABLE</command> locks the whole table.) This should be taken into TABLE</command> locks the whole table.) This should be taken into
account when porting applications to account when porting applications to
...@@ -1151,9 +1165,9 @@ SELECT pg_advisory_lock(q.id) FROM ...@@ -1151,9 +1165,9 @@ SELECT pg_advisory_lock(q.id) FROM
</para> </para>
<para> <para>
Note also that if one is Note also that if one is relying on explicit locking to prevent concurrent
relying on explicit locking to prevent concurrent changes, one should use changes, one should either use Read Committed mode, or in Serializable
either Read Committed mode, or in Serializable mode be careful to obtain mode be careful to obtain
locks before performing queries. A lock obtained by a locks before performing queries. A lock obtained by a
serializable transaction guarantees that no other transactions modifying serializable transaction guarantees that no other transactions modifying
the table are still running, but if the snapshot seen by the the table are still running, but if the snapshot seen by the
...@@ -1162,7 +1176,7 @@ SELECT pg_advisory_lock(q.id) FROM ...@@ -1162,7 +1176,7 @@ SELECT pg_advisory_lock(q.id) FROM
frozen at the start of its first query or data-modification command frozen at the start of its first query or data-modification command
(<literal>SELECT</>, <literal>INSERT</>, (<literal>SELECT</>, <literal>INSERT</>,
<literal>UPDATE</>, or <literal>DELETE</>), so <literal>UPDATE</>, or <literal>DELETE</>), so
it is often desirable to obtain locks explicitly before the snapshot is it is possible to obtain locks explicitly before the snapshot is
frozen. frozen.
</para> </para>
</sect1> </sect1>
...@@ -1178,7 +1192,7 @@ SELECT pg_advisory_lock(q.id) FROM ...@@ -1178,7 +1192,7 @@ SELECT pg_advisory_lock(q.id) FROM
<para> <para>
Though <productname>PostgreSQL</productname> Though <productname>PostgreSQL</productname>
provides nonblocking read/write access to table provides nonblocking read/write access to table
data, nonblocking read/write access is currently not offered for every data, nonblocking read/write access is not currently offered for every
index access method implemented index access method implemented
in <productname>PostgreSQL</productname>. in <productname>PostgreSQL</productname>.
The various index types are handled as follows: The various index types are handled as follows:
...@@ -1221,8 +1235,8 @@ SELECT pg_advisory_lock(q.id) FROM ...@@ -1221,8 +1235,8 @@ SELECT pg_advisory_lock(q.id) FROM
<para> <para>
Short-term share/exclusive page-level locks are used for Short-term share/exclusive page-level locks are used for
read/write access. Locks are released immediately after each read/write access. Locks are released immediately after each
index row is fetched or inserted. But note insertion of a GIN-indexed index row is fetched or inserted. But note that insertion of a
value usually produces several index key insertions GIN-indexed value usually produces several index key insertions
per row, so GIN might do substantial work for a single value's per row, so GIN might do substantial work for a single value's
insertion. insertion.
</para> </para>
......
doc/src/sgml/perform.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.70 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.71 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="performance-tips"> <chapter id="performance-tips">
<title>Performance Tips</title> <title>Performance Tips</title>
...@@ -45,8 +45,9 @@ ...@@ -45,8 +45,9 @@
table access methods: sequential scans, index scans, and bitmap index table access methods: sequential scans, index scans, and bitmap index
scans. If the query requires joining, aggregation, sorting, or other scans. If the query requires joining, aggregation, sorting, or other
operations on the raw rows, then there will be additional nodes operations on the raw rows, then there will be additional nodes
above the scan nodes to perform these operations. Other nodes types above the scan nodes to perform these operations. Again,
are also supported. The output there is usually more than one possible way to do these operations,
so different node types can appear here too. The output
of <command>EXPLAIN</command> has one line for each node in the plan of <command>EXPLAIN</command> has one line for each node in the plan
tree, showing the basic node type plus the cost estimates that the planner tree, showing the basic node type plus the cost estimates that the planner
made for the execution of that plan node. The first line (topmost node) made for the execution of that plan node. The first line (topmost node)
...@@ -83,24 +84,24 @@ EXPLAIN SELECT * FROM tenk1; ...@@ -83,24 +84,24 @@ EXPLAIN SELECT * FROM tenk1;
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Estimated start-up cost, e.g., time expended before the output scan can start, Estimated start-up cost (time expended before the output scan can start,
time to do the sorting in a sort node e.g., time to do the sorting in a sort node)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Estimated total cost if all rows were to be retrieved (though they might Estimated total cost (if all rows are retrieved, though they might
not be, e.g., a query with a <literal>LIMIT</> clause will stop not be; e.g., a query with a <literal>LIMIT</> clause will stop
short of paying the total cost of the <literal>Limit</> node's short of paying the total cost of the <literal>Limit</> plan node's
input node) input node)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Estimated number of rows output by this plan node (Again, only if Estimated number of rows output by this plan node (again, only if
executed to completion.) executed to completion)
</para> </para>
</listitem> </listitem>
...@@ -129,18 +130,18 @@ EXPLAIN SELECT * FROM tenk1; ...@@ -129,18 +130,18 @@ EXPLAIN SELECT * FROM tenk1;
the cost only reflects things that the planner cares about. the cost only reflects things that the planner cares about.
In particular, the cost does not consider the time spent transmitting In particular, the cost does not consider the time spent transmitting
result rows to the client, which could be an important result rows to the client, which could be an important
factor in the total elapsed time; but the planner ignores it because factor in the real elapsed time; but the planner ignores it because
it cannot change it by altering the plan. (Every correct plan will it cannot change it by altering the plan. (Every correct plan will
output the same row set, we trust.) output the same row set, we trust.)
</para> </para>
<para> <para>
The <command>EXPLAIN</command> <literal>rows=</> value is a little tricky The <literal>rows</> value is a little tricky
because it is <emphasis>not</emphasis> the because it is <emphasis>not</emphasis> the
number of rows processed or scanned by the plan node. It is usually less, number of rows processed or scanned by the plan node. It is usually less,
reflecting the estimated selectivity of any <literal>WHERE</>-clause reflecting the estimated selectivity of any <literal>WHERE</>-clause
conditions that are being conditions that are being
applied to the node. Ideally the top-level rows estimate will applied at the node. Ideally the top-level rows estimate will
approximate the number of rows actually returned, updated, or deleted approximate the number of rows actually returned, updated, or deleted
by the query. by the query.
</para> </para>
...@@ -197,7 +198,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 7000; ...@@ -197,7 +198,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 7000;
</para> </para>
<para> <para>
The actual number of rows this query would select is 7000, but the <literal>rows=</> The actual number of rows this query would select is 7000, but the <literal>rows</>
estimate is only approximate. If you try to duplicate this experiment, estimate is only approximate. If you try to duplicate this experiment,
you will probably get a slightly different estimate; moreover, it will you will probably get a slightly different estimate; moreover, it will
change after each <command>ANALYZE</command> command, because the change after each <command>ANALYZE</command> command, because the
...@@ -234,7 +235,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100; ...@@ -234,7 +235,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100;
<para> <para>
If the <literal>WHERE</> condition is selective enough, the planner might If the <literal>WHERE</> condition is selective enough, the planner might
switch to a <emphasis>simple</> index scan plan: switch to a <quote>simple</> index scan plan:
<programlisting> <programlisting>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3; EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3;
...@@ -248,8 +249,8 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3; ...@@ -248,8 +249,8 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3;
In this case the table rows are fetched in index order, which makes them In this case the table rows are fetched in index order, which makes them
even more expensive to read, but there are so few that the extra cost even more expensive to read, but there are so few that the extra cost
of sorting the row locations is not worth it. You'll most often see of sorting the row locations is not worth it. You'll most often see
this plan type in queries that fetch just a single row, and for queries this plan type for queries that fetch just a single row, and for queries
with an <literal>ORDER BY</> condition that matches the index that have an <literal>ORDER BY</> condition that matches the index
order. order.
</para> </para>
...@@ -320,7 +321,7 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2; ...@@ -320,7 +321,7 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
</para> </para>
<para> <para>
In this nested-loop join, the outer scan (upper) is the same bitmap index scan we In this nested-loop join, the outer (upper) scan is the same bitmap index scan we
saw earlier, and so its cost and row count are the same because we are saw earlier, and so its cost and row count are the same because we are
applying the <literal>WHERE</> clause <literal>unique1 &lt; 100</literal> applying the <literal>WHERE</> clause <literal>unique1 &lt; 100</literal>
at that node. at that node.
...@@ -409,7 +410,7 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2; ...@@ -409,7 +410,7 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
</screen> </screen>
Note that the <quote>actual time</quote> values are in milliseconds of Note that the <quote>actual time</quote> values are in milliseconds of
real time, whereas the <literal>cost=</> estimates are expressed in real time, whereas the <literal>cost</> estimates are expressed in
arbitrary units; so they are unlikely to match up. arbitrary units; so they are unlikely to match up.
The thing to pay attention to is whether the ratios of actual time and The thing to pay attention to is whether the ratios of actual time and
estimated costs are consistent. estimated costs are consistent.
...@@ -419,11 +420,11 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2; ...@@ -419,11 +420,11 @@ WHERE t1.unique1 &lt; 100 AND t1.unique2 = t2.unique2;
In some query plans, it is possible for a subplan node to be executed more In some query plans, it is possible for a subplan node to be executed more
than once. For example, the inner index scan is executed once per outer than once. For example, the inner index scan is executed once per outer
row in the above nested-loop plan. In such cases, the row in the above nested-loop plan. In such cases, the
<literal>loops=</> value reports the <literal>loops</> value reports the
total number of executions of the node, and the actual time and rows total number of executions of the node, and the actual time and rows
values shown are averages per-execution. This is done to make the numbers values shown are averages per-execution. This is done to make the numbers
comparable with the way that the cost estimates are shown. Multiply by comparable with the way that the cost estimates are shown. Multiply by
the <literal>loops=</> value to get the total time actually spent in the <literal>loops</> value to get the total time actually spent in
the node. the node.
</para> </para>
...@@ -780,7 +781,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse; ...@@ -780,7 +781,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
</indexterm> </indexterm>
<para> <para>
When doing <command>INSERT</>s, turn off autocommit and just do When using multiple <command>INSERT</>s, turn off autocommit and just do
one commit at the end. (In plain one commit at the end. (In plain
SQL, this means issuing <command>BEGIN</command> at the start and SQL, this means issuing <command>BEGIN</command> at the start and
<command>COMMIT</command> at the end. Some client libraries might <command>COMMIT</command> at the end. Some client libraries might
...@@ -824,7 +825,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse; ...@@ -824,7 +825,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<para> <para>
Note that loading a large number of rows using Note that loading a large number of rows using
<command>COPY</command> is almost always faster than using <command>COPY</command> is almost always faster than using
<command>INSERT</command>, even if the <command>PREPARE ... INSERT</> is used and <command>INSERT</command>, even if <command>PREPARE</> is used and
multiple insertions are batched into a single transaction. multiple insertions are batched into a single transaction.
</para> </para>
......
doc/src/sgml/postgres.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.87 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.88 2009/06/17 21:58:49 tgl Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
...@@ -134,7 +134,7 @@ ...@@ -134,7 +134,7 @@
The first few chapters are written so they can be understood The first few chapters are written so they can be understood
without prerequisite knowledge, so new users who need to set without prerequisite knowledge, so new users who need to set
up their own server can begin their exploration with this part. up their own server can begin their exploration with this part.
The rest of this part is about tuning and management; the material The rest of this part is about tuning and management; that material
assumes that the reader is familiar with the general use of assumes that the reader is familiar with the general use of
the <productname>PostgreSQL</> database system. Readers are the <productname>PostgreSQL</> database system. Readers are
encouraged to look at <xref linkend="tutorial"> and <xref encouraged to look at <xref linkend="tutorial"> and <xref
......
doc/src/sgml/queries.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.54 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.55 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="queries"> <chapter id="queries">
<title>Queries</title> <title>Queries</title>
...@@ -133,8 +133,8 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r ...@@ -133,8 +133,8 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
When a table reference names a table that is the parent of a When a table reference names a table that is the parent of a
table inheritance hierarchy, the table reference produces rows table inheritance hierarchy, the table reference produces rows of
not only of that table but all of its descendant tables, unless the not only that table but all of its descendant tables, unless the
key word <literal>ONLY</> precedes the table name. However, the key word <literal>ONLY</> precedes the table name. However, the
reference produces only the columns that appear in the named table reference produces only the columns that appear in the named table
&mdash; any columns added in subtables are ignored. &mdash; any columns added in subtables are ignored.
...@@ -174,12 +174,12 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r ...@@ -174,12 +174,12 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
</synopsis> </synopsis>
<para> <para>
Produce every possible combination of rows from For every possible combination of rows from
<replaceable>T1</replaceable> and <replaceable>T1</replaceable> and
<replaceable>T2</replaceable> (i.e., a Cartesian product), <replaceable>T2</replaceable> (i.e., a Cartesian product),
with output columns consisting of the joined table will contain a
all <replaceable>T1</replaceable> columns row consisting of all columns in <replaceable>T1</replaceable>
followed by all <replaceable>T2</replaceable> columns. If followed by all columns in <replaceable>T2</replaceable>. If
the tables have N and M rows respectively, the joined the tables have N and M rows respectively, the joined
table will have N * M rows. table will have N * M rows.
</para> </para>
...@@ -245,7 +245,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r ...@@ -245,7 +245,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
equality of each of these pairs of columns. Furthermore, the equality of each of these pairs of columns. Furthermore, the
output of <literal>JOIN USING</> has one column for each of output of <literal>JOIN USING</> has one column for each of
the equated pairs of input columns, followed by the the equated pairs of input columns, followed by the
other columns from each table. Thus, <literal>USING (a, b, remaining columns from each table. Thus, <literal>USING (a, b,
c)</literal> is equivalent to <literal>ON (t1.a = t2.a AND c)</literal> is equivalent to <literal>ON (t1.a = t2.a AND
t1.b = t2.b AND t1.c = t2.c)</literal> with the exception that t1.b = t2.b AND t1.c = t2.c)</literal> with the exception that
if <literal>ON</> is used there will be two columns if <literal>ON</> is used there will be two columns
...@@ -300,7 +300,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r ...@@ -300,7 +300,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
First, an inner join is performed. Then, for each row in First, an inner join is performed. Then, for each row in
T1 that does not satisfy the join condition with any row in T1 that does not satisfy the join condition with any row in
T2, a row is added with null values in columns of T2, a joined row is added with null values in columns of
T2. Thus, the joined table always has at least T2. Thus, the joined table always has at least
one row for each row in T1. one row for each row in T1.
</para> </para>
...@@ -323,7 +323,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r ...@@ -323,7 +323,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
First, an inner join is performed. Then, for each row in First, an inner join is performed. Then, for each row in
T2 that does not satisfy the join condition with any row in T2 that does not satisfy the join condition with any row in
T1, a row is added with null values in columns of T1, a joined row is added with null values in columns of
T1. This is the converse of a left join: the result table T1. This is the converse of a left join: the result table
will always have a row for each row in T2. will always have a row for each row in T2.
</para> </para>
...@@ -337,9 +337,9 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r ...@@ -337,9 +337,9 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para> <para>
First, an inner join is performed. Then, for each row in First, an inner join is performed. Then, for each row in
T1 that does not satisfy the join condition with any row in T1 that does not satisfy the join condition with any row in
T2, a row is added with null values in columns of T2, a joined row is added with null values in columns of
T2. Also, for each row of T2 that does not satisfy the T2. Also, for each row of T2 that does not satisfy the
join condition with any row in T1, a row with null join condition with any row in T1, a joined row with null
values in the columns of T1 is added. values in the columns of T1 is added.
</para> </para>
</listitem> </listitem>
...@@ -575,7 +575,7 @@ FROM <replaceable>table_reference</replaceable> <optional>AS</optional> <replace ...@@ -575,7 +575,7 @@ FROM <replaceable>table_reference</replaceable> <optional>AS</optional> <replace
<para> <para>
When an alias is applied to the output of a <literal>JOIN</> When an alias is applied to the output of a <literal>JOIN</>
clause, the alias hides the original clause, the alias hides the original
name referenced in the <literal>JOIN</>. For example: name(s) within the <literal>JOIN</>. For example:
<programlisting> <programlisting>
SELECT a.* FROM my_table AS a JOIN your_table AS b ON ... SELECT a.* FROM my_table AS a JOIN your_table AS b ON ...
</programlisting> </programlisting>
...@@ -686,8 +686,7 @@ SELECT * FROM vw_getfoo; ...@@ -686,8 +686,7 @@ SELECT * FROM vw_getfoo;
In some cases it is useful to define table functions that can In some cases it is useful to define table functions that can
return different column sets depending on how they are invoked. return different column sets depending on how they are invoked.
To support this, the table function can be declared as returning To support this, the table function can be declared as returning
the pseudotype <type>record</>, rather than <literal>SET OF</>. the pseudotype <type>record</>. When such a function is used in
When such a function is used in
a query, the expected row structure must be specified in the a query, the expected row structure must be specified in the
query itself, so that the system can know how to parse and plan query itself, so that the system can know how to parse and plan
the query. Consider this example: the query. Consider this example:
...@@ -757,11 +756,11 @@ FROM a NATURAL JOIN b WHERE b.val &gt; 5 ...@@ -757,11 +756,11 @@ FROM a NATURAL JOIN b WHERE b.val &gt; 5
probably not as portable to other SQL database management systems, probably not as portable to other SQL database management systems,
even though it is in the SQL standard. For even though it is in the SQL standard. For
outer joins there is no choice: they must be done in outer joins there is no choice: they must be done in
the <literal>FROM</> clause. The <literal>ON</>/<literal>USING</> the <literal>FROM</> clause. The <literal>ON</> or <literal>USING</>
clause of an outer join is <emphasis>not</> equivalent to a clause of an outer join is <emphasis>not</> equivalent to a
<literal>WHERE</> condition, because it affects the addition <literal>WHERE</> condition, because it results in the addition
of rows (for unmatched input rows) as well as the removal of rows of rows (for unmatched input rows) as well as the removal of rows
from the final result. in the final result.
</para> </para>
</note> </note>
...@@ -780,7 +779,7 @@ SELECT ... FROM fdt WHERE c1 BETWEEN (SELECT c3 FROM t2 WHERE c2 = fdt.c1 + 10) ...@@ -780,7 +779,7 @@ SELECT ... FROM fdt WHERE c1 BETWEEN (SELECT c3 FROM t2 WHERE c2 = fdt.c1 + 10)
SELECT ... FROM fdt WHERE EXISTS (SELECT c1 FROM t2 WHERE c2 &gt; fdt.c1) SELECT ... FROM fdt WHERE EXISTS (SELECT c1 FROM t2 WHERE c2 &gt; fdt.c1)
</programlisting> </programlisting>
<literal>fdt</literal> is the table used in the <literal>fdt</literal> is the table derived in the
<literal>FROM</> clause. Rows that do not meet the search <literal>FROM</> clause. Rows that do not meet the search
condition of the <literal>WHERE</> clause are eliminated from condition of the <literal>WHERE</> clause are eliminated from
<literal>fdt</literal>. Notice the use of scalar subqueries as <literal>fdt</literal>. Notice the use of scalar subqueries as
...@@ -860,7 +859,7 @@ SELECT <replaceable>select_list</replaceable> ...@@ -860,7 +859,7 @@ SELECT <replaceable>select_list</replaceable>
<para> <para>
In general, if a table is grouped, columns that are not In general, if a table is grouped, columns that are not
the same in the group cannot be referenced except in aggregate listed in <literal>GROUP BY</> cannot be referenced except in aggregate
expressions. An example with aggregate expressions is: expressions. An example with aggregate expressions is:
<screen> <screen>
<prompt>=&gt;</> <userinput>SELECT x, sum(y) FROM test1 GROUP BY x;</> <prompt>=&gt;</> <userinput>SELECT x, sum(y) FROM test1 GROUP BY x;</>
...@@ -880,7 +879,7 @@ SELECT <replaceable>select_list</replaceable> ...@@ -880,7 +879,7 @@ SELECT <replaceable>select_list</replaceable>
<tip> <tip>
<para> <para>
Grouping without aggregate expressions effectively calculates the Grouping without aggregate expressions effectively calculates the
set of distinct values in a column. This can more clearly be achieved set of distinct values in a column. This can also be achieved
using the <literal>DISTINCT</> clause (see <xref using the <literal>DISTINCT</> clause (see <xref
linkend="queries-distinct">). linkend="queries-distinct">).
</para> </para>
...@@ -1088,7 +1087,7 @@ SELECT tbl1.*, tbl2.a FROM ... ...@@ -1088,7 +1087,7 @@ SELECT tbl1.*, tbl2.a FROM ...
the row's values substituted for any column references. But the the row's values substituted for any column references. But the
expressions in the select list do not have to reference any expressions in the select list do not have to reference any
columns in the table expression of the <literal>FROM</> clause; columns in the table expression of the <literal>FROM</> clause;
they can be constant arithmetic expressions as well. they can be constant arithmetic expressions, for instance.
</para> </para>
</sect2> </sect2>
...@@ -1101,8 +1100,8 @@ SELECT tbl1.*, tbl2.a FROM ... ...@@ -1101,8 +1100,8 @@ SELECT tbl1.*, tbl2.a FROM ...
</indexterm> </indexterm>
<para> <para>
The entries in the select list can be assigned names for further The entries in the select list can be assigned names for subsequent
processing, perhaps for reference in an <literal>ORDER BY</> clause processing, such as for use in an <literal>ORDER BY</> clause
or for display by the client application. For example: or for display by the client application. For example:
<programlisting> <programlisting>
SELECT a AS value, b + c AS sum FROM ... SELECT a AS value, b + c AS sum FROM ...
...@@ -1141,7 +1140,7 @@ SELECT a "value", b + c AS sum FROM ... ...@@ -1141,7 +1140,7 @@ SELECT a "value", b + c AS sum FROM ...
The naming of output columns here is different from that done in The naming of output columns here is different from that done in
the <literal>FROM</> clause (see <xref the <literal>FROM</> clause (see <xref
linkend="queries-table-aliases">). It is possible linkend="queries-table-aliases">). It is possible
to rename the same column twice, but the name used in to rename the same column twice, but the name assigned in
the select list is the one that will be passed on. the select list is the one that will be passed on.
</para> </para>
</note> </note>
...@@ -1346,9 +1345,9 @@ SELECT a, b FROM table1 ORDER BY a + b, c; ...@@ -1346,9 +1345,9 @@ SELECT a, b FROM table1 ORDER BY a + b, c;
<para> <para>
The <literal>NULLS FIRST</> and <literal>NULLS LAST</> options can be The <literal>NULLS FIRST</> and <literal>NULLS LAST</> options can be
used to determine whether nulls appear before or after non-null values used to determine whether nulls appear before or after non-null values
in the sort ordering. The default behavior is for null values sort as in the sort ordering. By default, null values sort as if larger than any
if larger than all non-null values (<literal>NULLS FIRST</>), except non-null value; that is, <literal>NULLS FIRST</> is the default for
in <literal>DESC</> ordering, where <literal>NULLS LAST</> is the default. <literal>DESC</> order, and <literal>NULLS LAST</> otherwise.
</para> </para>
<para> <para>
...@@ -1366,7 +1365,7 @@ SELECT a + b AS sum, c FROM table1 ORDER BY sum; ...@@ -1366,7 +1365,7 @@ SELECT a + b AS sum, c FROM table1 ORDER BY sum;
SELECT a, max(b) FROM table1 GROUP BY a ORDER BY 1; SELECT a, max(b) FROM table1 GROUP BY a ORDER BY 1;
</programlisting> </programlisting>
both of which sort by the first output column. Note that an output both of which sort by the first output column. Note that an output
column name has to stand alone, e.g., it cannot be used in an expression column name has to stand alone, that is, it cannot be used in an expression
&mdash; for example, this is <emphasis>not</> correct: &mdash; for example, this is <emphasis>not</> correct:
<programlisting> <programlisting>
SELECT a + b AS sum, c FROM table1 ORDER BY sum + c; -- wrong SELECT a + b AS sum, c FROM table1 ORDER BY sum + c; -- wrong
...@@ -1429,10 +1428,10 @@ SELECT <replaceable>select_list</replaceable> ...@@ -1429,10 +1428,10 @@ SELECT <replaceable>select_list</replaceable>
<para> <para>
When using <literal>LIMIT</>, it is important to use an When using <literal>LIMIT</>, it is important to use an
<literal>ORDER BY</> clause that constrains the result rows in a <literal>ORDER BY</> clause that constrains the result rows into a
unique order. Otherwise you will get an unpredictable subset of unique order. Otherwise you will get an unpredictable subset of
the query's rows. You might be asking for the tenth through the query's rows. You might be asking for the tenth through
twentieth rows, but tenth through twentieth using what ordering? The twentieth rows, but tenth through twentieth in what ordering? The
ordering is unknown, unless you specified <literal>ORDER BY</>. ordering is unknown, unless you specified <literal>ORDER BY</>.
</para> </para>
...@@ -1472,7 +1471,7 @@ SELECT <replaceable>select_list</replaceable> ...@@ -1472,7 +1471,7 @@ SELECT <replaceable>select_list</replaceable>
<synopsis> <synopsis>
VALUES ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) [, ...] VALUES ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) [, ...]
</synopsis> </synopsis>
Each parenthesized list of expressions generates a row in the table expression. Each parenthesized list of expressions generates a row in the table.
The lists must all have the same number of elements (i.e., the number The lists must all have the same number of elements (i.e., the number
of columns in the table), and corresponding entries in each list must of columns in the table), and corresponding entries in each list must
have compatible data types. The actual data type assigned to each column have compatible data types. The actual data type assigned to each column
......
doc/src/sgml/query.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.52 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.53 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="tutorial-sql"> <chapter id="tutorial-sql">
<title>The <acronym>SQL</acronym> Language</title> <title>The <acronym>SQL</acronym> Language</title>
...@@ -53,7 +53,7 @@ ...@@ -53,7 +53,7 @@
</screen> </screen>
The <literal>\i</literal> command reads in commands from the The <literal>\i</literal> command reads in commands from the
specified file. The <command>psql</command> <literal>-s</> option puts you in specified file. <command>psql</command>'s <literal>-s</> option puts you in
single step mode which pauses before sending each statement to the single step mode which pauses before sending each statement to the
server. The commands used in this section are in the file server. The commands used in this section are in the file
<filename>basics.sql</filename>. <filename>basics.sql</filename>.
...@@ -150,7 +150,7 @@ CREATE TABLE weather ( ...@@ -150,7 +150,7 @@ CREATE TABLE weather (
<type>int</type> is the normal integer type. <type>real</type> is <type>int</type> is the normal integer type. <type>real</type> is
a type for storing single precision floating-point numbers. a type for storing single precision floating-point numbers.
<type>date</type> should be self-explanatory. (Yes, the column of <type>date</type> should be self-explanatory. (Yes, the column of
type <type>date</type> is also named <literal>date</literal>. type <type>date</type> is also named <structfield>date</structfield>.
This might be convenient or confusing &mdash; you choose.) This might be convenient or confusing &mdash; you choose.)
</para> </para>
...@@ -165,7 +165,7 @@ CREATE TABLE weather ( ...@@ -165,7 +165,7 @@ CREATE TABLE weather (
and a rich set of geometric types. and a rich set of geometric types.
<productname>PostgreSQL</productname> can be customized with an <productname>PostgreSQL</productname> can be customized with an
arbitrary number of user-defined data types. Consequently, type arbitrary number of user-defined data types. Consequently, type
names are not special key words in the syntax except where required to names are not key words in the syntax, except where required to
support special cases in the <acronym>SQL</acronym> standard. support special cases in the <acronym>SQL</acronym> standard.
</para> </para>
...@@ -291,7 +291,7 @@ COPY weather FROM '/home/user/weather.txt'; ...@@ -291,7 +291,7 @@ COPY weather FROM '/home/user/weather.txt';
tables from which to retrieve the data), and an optional tables from which to retrieve the data), and an optional
qualification (the part that specifies any restrictions). For qualification (the part that specifies any restrictions). For
example, to retrieve all the rows of table example, to retrieve all the rows of table
<classname>weather</classname>, type: <structname>weather</structname>, type:
<programlisting> <programlisting>
SELECT * FROM weather; SELECT * FROM weather;
</programlisting> </programlisting>
...@@ -450,9 +450,10 @@ SELECT DISTINCT city ...@@ -450,9 +450,10 @@ SELECT DISTINCT city
of the same or different tables at one time is called a of the same or different tables at one time is called a
<firstterm>join</firstterm> query. As an example, say you wish to <firstterm>join</firstterm> query. As an example, say you wish to
list all the weather records together with the location of the list all the weather records together with the location of the
associated city. To do that, we need to compare the city column of associated city. To do that, we need to compare the <structfield>city</>
each row of the <literal>weather</> table with the name column of all rows in column of each row of the <structname>weather</> table with the
the <literal>cities</> table, and select the pairs of rows where these values match. <structfield>name</> column of all rows in the <structname>cities</>
table, and select the pairs of rows where these values match.
<note> <note>
<para> <para>
This is only a conceptual model. The join is usually performed This is only a conceptual model. The join is usually performed
...@@ -485,8 +486,8 @@ SELECT * ...@@ -485,8 +486,8 @@ SELECT *
<para> <para>
There is no result row for the city of Hayward. This is There is no result row for the city of Hayward. This is
because there is no matching entry in the because there is no matching entry in the
<classname>cities</classname> table for Hayward, so the join <structname>cities</structname> table for Hayward, so the join
ignores the unmatched rows in the <literal>weather</> table. We will see ignores the unmatched rows in the <structname>weather</> table. We will see
shortly how this can be fixed. shortly how this can be fixed.
</para> </para>
</listitem> </listitem>
...@@ -494,9 +495,9 @@ SELECT * ...@@ -494,9 +495,9 @@ SELECT *
<listitem> <listitem>
<para> <para>
There are two columns containing the city name. This is There are two columns containing the city name. This is
correct because the columns from the correct because the lists of columns from the
<classname>weather</classname> and the <structname>weather</structname> and
<classname>cities</classname> tables are concatenated. In <structname>cities</structname> tables are concatenated. In
practice this is undesirable, though, so you will probably want practice this is undesirable, though, so you will probably want
to list the output columns explicitly rather than using to list the output columns explicitly rather than using
<literal>*</literal>: <literal>*</literal>:
...@@ -556,10 +557,10 @@ SELECT * ...@@ -556,10 +557,10 @@ SELECT *
Now we will figure out how we can get the Hayward records back in. Now we will figure out how we can get the Hayward records back in.
What we want the query to do is to scan the What we want the query to do is to scan the
<classname>weather</classname> table and for each row to find the <structname>weather</structname> table and for each row to find the
matching <classname>cities</classname> row(s). If no matching row is matching <structname>cities</structname> row(s). If no matching row is
found we want some <quote>empty values</quote> to be substituted found we want some <quote>empty values</quote> to be substituted
for the <classname>cities</classname> table's columns. This kind for the <structname>cities</structname> table's columns. This kind
of query is called an <firstterm>outer join</firstterm>. (The of query is called an <firstterm>outer join</firstterm>. (The
joins we have seen so far are inner joins.) The command looks joins we have seen so far are inner joins.) The command looks
like this: like this:
...@@ -603,10 +604,10 @@ SELECT * ...@@ -603,10 +604,10 @@ SELECT *
to find all the weather records that are in the temperature range to find all the weather records that are in the temperature range
of other weather records. So we need to compare the of other weather records. So we need to compare the
<structfield>temp_lo</> and <structfield>temp_hi</> columns of <structfield>temp_lo</> and <structfield>temp_hi</> columns of
each <classname>weather</classname> row to the each <structname>weather</structname> row to the
<structfield>temp_lo</structfield> and <structfield>temp_lo</structfield> and
<structfield>temp_hi</structfield> columns of all other <structfield>temp_hi</structfield> columns of all other
<classname>weather</classname> rows. We can do this with the <structname>weather</structname> rows. We can do this with the
following query: following query:
<programlisting> <programlisting>
...@@ -756,7 +757,7 @@ SELECT city, max(temp_lo) ...@@ -756,7 +757,7 @@ SELECT city, max(temp_lo)
</screen> </screen>
which gives us the same results for only the cities that have all which gives us the same results for only the cities that have all
<literal>temp_lo</> values below 40. Finally, if we only care about <structfield>temp_lo</> values below 40. Finally, if we only care about
cities whose cities whose
names begin with <quote><literal>S</literal></quote>, we might do: names begin with <quote><literal>S</literal></quote>, we might do:
......
doc/src/sgml/rowtypes.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.10 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.11 2009/06/17 21:58:49 tgl Exp $ -->
<sect1 id="rowtypes"> <sect1 id="rowtypes">
<title>Composite Types</title> <title>Composite Types</title>
...@@ -41,7 +41,7 @@ CREATE TYPE inventory_item AS ( ...@@ -41,7 +41,7 @@ CREATE TYPE inventory_item AS (
NULL</>) can presently be included. Note that the <literal>AS</> keyword NULL</>) can presently be included. Note that the <literal>AS</> keyword
is essential; without it, the system will think a different kind is essential; without it, the system will think a different kind
of <command>CREATE TYPE</> command is meant, and you will get odd syntax of <command>CREATE TYPE</> command is meant, and you will get odd syntax
error. errors.
</para> </para>
<para> <para>
...@@ -68,8 +68,8 @@ SELECT price_extension(item, 10) FROM on_hand; ...@@ -68,8 +68,8 @@ SELECT price_extension(item, 10) FROM on_hand;
</para> </para>
<para> <para>
Whenever you create a table, a composite type is automatically Whenever you create a table, a composite type is also automatically
created also, with the same name as the table, to represent the table's created, with the same name as the table, to represent the table's
row type. For example, had we said: row type. For example, had we said:
<programlisting> <programlisting>
CREATE TABLE inventory_item ( CREATE TABLE inventory_item (
...@@ -250,7 +250,7 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); ...@@ -250,7 +250,7 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
The external text representation of a composite value consists of items that The external text representation of a composite value consists of items that
are interpreted according to the I/O conversion rules for the individual are interpreted according to the I/O conversion rules for the individual
field types, plus decoration that indicates the composite structure. field types, plus decoration that indicates the composite structure.
The decoration consists of parentheses The decoration consists of parentheses (<literal>(</> and <literal>)</>)
around the whole value, plus commas (<literal>,</>) between adjacent around the whole value, plus commas (<literal>,</>) between adjacent
items. Whitespace outside the parentheses is ignored, but within the items. Whitespace outside the parentheses is ignored, but within the
parentheses it is considered part of the field value, and might or might not be parentheses it is considered part of the field value, and might or might not be
...@@ -264,7 +264,7 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2); ...@@ -264,7 +264,7 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
</para> </para>
<para> <para>
As shown previously, when writing a composite value you can use double As shown previously, when writing a composite value you can write double
quotes around any individual field value. quotes around any individual field value.
You <emphasis>must</> do so if the field value would otherwise You <emphasis>must</> do so if the field value would otherwise
confuse the composite-value parser. In particular, fields containing confuse the composite-value parser. In particular, fields containing
......
doc/src/sgml/start.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.49 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.50 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="tutorial-start"> <chapter id="tutorial-start">
<title>Getting Started</title> <title>Getting Started</title>
...@@ -74,7 +74,7 @@ ...@@ -74,7 +74,7 @@
<para> <para>
A server process, which manages the database files, accepts A server process, which manages the database files, accepts
connections to the database from client applications, and connections to the database from client applications, and
performs database actions on the behalf of the clients. The performs database actions on behalf of the clients. The
database server program is called database server program is called
<filename>postgres</filename>. <filename>postgres</filename>.
<indexterm><primary>postgres</primary></indexterm> <indexterm><primary>postgres</primary></indexterm>
...@@ -164,8 +164,8 @@ ...@@ -164,8 +164,8 @@
createdb: command not found createdb: command not found
</screen> </screen>
then <productname>PostgreSQL</> was not installed properly. Either it was not then <productname>PostgreSQL</> was not installed properly. Either it was not
installed at all or your shell's search path was not set correctly. Try installed at all or your shell's search path was not set to include it.
calling the command with an absolute path instead: Try calling the command with an absolute path instead:
<screen> <screen>
<prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb mydb</userinput> <prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb mydb</userinput>
</screen> </screen>
...@@ -177,8 +177,7 @@ createdb: command not found ...@@ -177,8 +177,7 @@ createdb: command not found
<para> <para>
Another response could be this: Another response could be this:
<screen> <screen>
createdb: could not connect to database postgres: could not connect createdb: could not connect to database postgres: could not connect to server: No such file or directory
to server: No such file or directory
Is the server running locally and accepting Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"? connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
</screen> </screen>
......
doc/src/sgml/storage.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.28 2009/05/16 22:03:53 tgl Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.29 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="storage"> <chapter id="storage">
...@@ -135,8 +135,9 @@ main file (a/k/a main fork), each table and index has a <firstterm>free space ...@@ -135,8 +135,9 @@ main file (a/k/a main fork), each table and index has a <firstterm>free space
map</> (see <xref linkend="storage-fsm">), which stores information about free map</> (see <xref linkend="storage-fsm">), which stores information about free
space available in the relation. The free space map is stored in a file named space available in the relation. The free space map is stored in a file named
with the filenode number plus the suffix <literal>_fsm</>. Tables also have a with the filenode number plus the suffix <literal>_fsm</>. Tables also have a
visibility map fork, with the suffix <literal>_vm</>, to track which pages are <firstterm>visibility map</>, stored in a fork with the suffix
known to have no dead tuples and therefore need no vacuuming. <literal>_vm</>, to track which pages are known to have no dead tuples.
The visibility map is described further in <xref linkend="storage-vm">.
</para> </para>
<caution> <caution>
...@@ -417,6 +418,38 @@ information stored in free space maps (see <xref linkend="pgfreespacemap">). ...@@ -417,6 +418,38 @@ information stored in free space maps (see <xref linkend="pgfreespacemap">).
</sect1> </sect1>
<sect1 id="storage-vm">
<title>Visibility Map</title>
<indexterm>
<primary>Visibility Map</primary>
</indexterm>
<indexterm><primary>VM</><see>Visibility Map</></indexterm>
<para>
Each heap relation has a Visibility Map
(VM) to keep track of which pages contain only tuples that are known to be
visible to all active transactions. It's stored
alongside the main relation data in a separate relation fork, named after the
filenode number of the relation, plus a <literal>_vm</> suffix. For example,
if the filenode of a relation is 12345, the VM is stored in a file called
<filename>12345_vm</>, in the same directory as the main relation file.
Note that indexes do not have VMs.
</para>
<para>
The visibility map simply stores one bit per heap page. A set bit means
that all tuples on the page are known to be visible to all transactions.
This means that the page does not contain any tuples that need to be vacuumed;
in future it might also be used to avoid visiting the page for visibility
checks. The map is conservative in the sense that we
make sure that whenever a bit is set, we know the condition is true, but if
a bit is not set, it might or might not be true.
</para>
</sect1>
<sect1 id="storage-page-layout"> <sect1 id="storage-page-layout">
<title>Database Page Layout</title> <title>Database Page Layout</title>
......
doc/src/sgml/syntax.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.132 2009/05/05 18:32:17 petere Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.133 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="sql-syntax"> <chapter id="sql-syntax">
<title>SQL Syntax</title> <title>SQL Syntax</title>
...@@ -442,7 +442,7 @@ SELECT 'foo' 'bar'; ...@@ -442,7 +442,7 @@ SELECT 'foo' 'bar';
</caution> </caution>
<para> <para>
The zero-byte (null byte) character cannot be in a string constant. The character with the code zero cannot be in a string constant.
</para> </para>
</sect3> </sect3>
...@@ -929,8 +929,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> ) ...@@ -929,8 +929,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
</para> </para>
<para> <para>
Comment are removed from the input stream before further syntax A comment is removed from the input stream before further syntax
analysis and are effectively replaced by whitespace. analysis and is effectively replaced by whitespace.
</para> </para>
</sect2> </sect2>
...@@ -1244,9 +1244,9 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; ...@@ -1244,9 +1244,9 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
<listitem> <listitem>
<para> <para>
Another value expression in parentheses, useful to group Another value expression in parentheses (used to group
subexpressions and override subexpressions and override
precedence.<indexterm><primary>parenthesis</></> precedence<indexterm><primary>parenthesis</></>)
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -1725,7 +1725,7 @@ CAST ( <replaceable>expression</replaceable> AS <replaceable>type</replaceable> ...@@ -1725,7 +1725,7 @@ CAST ( <replaceable>expression</replaceable> AS <replaceable>type</replaceable>
casts that are marked <quote>OK to apply implicitly</> casts that are marked <quote>OK to apply implicitly</>
in the system catalogs. Other casts must be invoked with in the system catalogs. Other casts must be invoked with
explicit casting syntax. This restriction is intended to prevent explicit casting syntax. This restriction is intended to prevent
surprising conversions from being silently applied. surprising conversions from being applied silently.
</para> </para>
<para> <para>
...@@ -1805,7 +1805,7 @@ SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name) ...@@ -1805,7 +1805,7 @@ SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name)
<para> <para>
An array constructor is an expression that builds an An array constructor is an expression that builds an
array using values for its member elements. A simple array array value using values for its member elements. A simple array
constructor constructor
consists of the key word <literal>ARRAY</literal>, a left square bracket consists of the key word <literal>ARRAY</literal>, a left square bracket
<literal>[</>, a list of expressions (separated by commas) for the <literal>[</>, a list of expressions (separated by commas) for the
...@@ -1936,7 +1936,7 @@ SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%'); ...@@ -1936,7 +1936,7 @@ SELECT ARRAY(SELECT oid FROM pg_proc WHERE proname LIKE 'bytea%');
</indexterm> </indexterm>
<para> <para>
A row constructor is an expression that builds a row (also A row constructor is an expression that builds a row value (also
called a composite value) using values called a composite value) using values
for its member fields. A row constructor consists of the key word for its member fields. A row constructor consists of the key word
<literal>ROW</literal>, a left parenthesis, zero or more <literal>ROW</literal>, a left parenthesis, zero or more
......
doc/src/sgml/textsearch.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/textsearch.sgml,v 1.51 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/textsearch.sgml,v 1.52 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="textsearch"> <chapter id="textsearch">
<title id="textsearch-title">Full Text Search</title> <title id="textsearch-title">Full Text Search</title>
...@@ -389,7 +389,7 @@ text @@ text ...@@ -389,7 +389,7 @@ text @@ text
<para> <para>
Text search parsers and templates are built from low-level C functions; Text search parsers and templates are built from low-level C functions;
therefore C programming ability is required to develop new ones, and therefore it requires C programming ability to develop new ones, and
superuser privileges to install one into a database. (There are examples superuser privileges to install one into a database. (There are examples
of add-on parsers and templates in the <filename>contrib/</> area of the of add-on parsers and templates in the <filename>contrib/</> area of the
<productname>PostgreSQL</> distribution.) Since dictionaries and <productname>PostgreSQL</> distribution.) Since dictionaries and
...@@ -519,7 +519,7 @@ CREATE INDEX pgweb_idx ON pgweb USING gin(to_tsvector(config_name, body)); ...@@ -519,7 +519,7 @@ CREATE INDEX pgweb_idx ON pgweb USING gin(to_tsvector(config_name, body));
recording which configuration was used for each index entry. This recording which configuration was used for each index entry. This
would be useful, for example, if the document collection contained would be useful, for example, if the document collection contained
documents in different languages. Again, documents in different languages. Again,
queries that wish to use the index must be phrased to match, e.g., queries that are meant to use the index must be phrased to match, e.g.,
<literal>WHERE to_tsvector(config_name, body) @@ 'a &amp; b'</>. <literal>WHERE to_tsvector(config_name, body) @@ 'a &amp; b'</>.
</para> </para>
...@@ -860,7 +860,8 @@ SELECT plainto_tsquery('english', 'The Fat &amp; Rats:C'); ...@@ -860,7 +860,8 @@ SELECT plainto_tsquery('english', 'The Fat &amp; Rats:C');
<term> <term>
<synopsis> <synopsis>
ts_rank(<optional> <replaceable class="PARAMETER">weights</replaceable> <type>float4[]</>, </optional> <replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>, <replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">normalization</replaceable> <type>integer</> </optional>) returns <type>float4</> ts_rank(<optional> <replaceable class="PARAMETER">weights</replaceable> <type>float4[]</>, </optional> <replaceable class="PARAMETER">vector</replaceable> <type>tsvector</>,
<replaceable class="PARAMETER">query</replaceable> <type>tsquery</> <optional>, <replaceable class="PARAMETER">normalization</replaceable> <type>integer</> </optional>) returns <type>float4</>
</synopsis> </synopsis>
</term> </term>
...@@ -1042,7 +1043,7 @@ LIMIT 10; ...@@ -1042,7 +1043,7 @@ LIMIT 10;
Ranking can be expensive since it requires consulting the Ranking can be expensive since it requires consulting the
<type>tsvector</type> of each matching document, which can be I/O bound and <type>tsvector</type> of each matching document, which can be I/O bound and
therefore slow. Unfortunately, it is almost impossible to avoid since therefore slow. Unfortunately, it is almost impossible to avoid since
practical queries often result in a large number of matches. practical queries often result in large numbers of matches.
</para> </para>
</sect2> </sect2>
...@@ -1068,7 +1069,7 @@ LIMIT 10; ...@@ -1068,7 +1069,7 @@ LIMIT 10;
<para> <para>
<function>ts_headline</function> accepts a document along <function>ts_headline</function> accepts a document along
with a query, and returns an excerpt of with a query, and returns an excerpt from
the document in which terms from the query are highlighted. The the document in which terms from the query are highlighted. The
configuration to be used to parse the document can be specified by configuration to be used to parse the document can be specified by
<replaceable>config</replaceable>; if <replaceable>config</replaceable> <replaceable>config</replaceable>; if <replaceable>config</replaceable>
...@@ -1085,8 +1086,8 @@ LIMIT 10; ...@@ -1085,8 +1086,8 @@ LIMIT 10;
<itemizedlist spacing="compact" mark="bullet"> <itemizedlist spacing="compact" mark="bullet">
<listitem> <listitem>
<para> <para>
<literal>StartSel</>, <literal>StopSel</literal>: the strings to delimit <literal>StartSel</>, <literal>StopSel</literal>: the strings with
query words appearing in the document, to distinguish which to delimit query words appearing in the document, to distinguish
them from other excerpted words. You must double-quote these strings them from other excerpted words. You must double-quote these strings
if they contain spaces or commas. if they contain spaces or commas.
</para> </para>
...@@ -1678,9 +1679,9 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title &amp; body'); ...@@ -1678,9 +1679,9 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title &amp; body');
</para> </para>
<para> <para>
A limitation of built-in triggers is that they treat all the A limitation of these built-in triggers is that they treat all the
input columns alike. To process columns differently &mdash; for input columns alike. To process columns differently &mdash; for
example, to weigh title differently from body &mdash; it is necessary example, to weight title differently from body &mdash; it is necessary
to write a custom trigger. Here is an example using to write a custom trigger. Here is an example using
<application>PL/pgSQL</application> as the trigger language: <application>PL/pgSQL</application> as the trigger language:
...@@ -1722,8 +1723,8 @@ ON messages FOR EACH ROW EXECUTE PROCEDURE messages_trigger(); ...@@ -1722,8 +1723,8 @@ ON messages FOR EACH ROW EXECUTE PROCEDURE messages_trigger();
</para> </para>
<synopsis> <synopsis>
ts_stat(<replaceable class="PARAMETER">sqlquery</replaceable> <type>text</>, <optional> <replaceable class="PARAMETER">weights</replaceable> <type>text</>, ts_stat(<replaceable class="PARAMETER">sqlquery</replaceable> <type>text</>, <optional> <replaceable class="PARAMETER">weights</replaceable> <type>text</>, </optional>
</optional> OUT <replaceable class="PARAMETER">word</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">ndoc</replaceable> <type>integer</>, OUT <replaceable class="PARAMETER">word</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">ndoc</replaceable> <type>integer</>,
OUT <replaceable class="PARAMETER">nentry</replaceable> <type>integer</>) returns <type>setof record</> OUT <replaceable class="PARAMETER">nentry</replaceable> <type>integer</>) returns <type>setof record</>
</synopsis> </synopsis>
...@@ -2087,7 +2088,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h ...@@ -2087,7 +2088,7 @@ SELECT alias, description, token FROM ts_debug('http://example.com/stuff/index.h
by the parser, each dictionary in the list is consulted in turn, by the parser, each dictionary in the list is consulted in turn,
until some dictionary recognizes it as a known word. If it is identified until some dictionary recognizes it as a known word. If it is identified
as a stop word, or if no dictionary recognizes the token, it will be as a stop word, or if no dictionary recognizes the token, it will be
discarded and not indexed or searched. discarded and not indexed or searched for.
The general rule for configuring a list of dictionaries The general rule for configuring a list of dictionaries
is to place first the most narrow, most specific dictionary, then the more is to place first the most narrow, most specific dictionary, then the more
general dictionaries, finishing with a very general dictionary, like general dictionaries, finishing with a very general dictionary, like
...@@ -2679,9 +2680,9 @@ CREATE TEXT SEARCH DICTIONARY english_stem ( ...@@ -2679,9 +2680,9 @@ CREATE TEXT SEARCH DICTIONARY english_stem (
</para> </para>
<para> <para>
As an example, we will create a configuration As an example we will create a configuration
<literal>pg</literal> by duplicating the built-in <literal>pg</literal>, starting by duplicating the built-in
<literal>english</> configuration. <literal>english</> configuration:
<programlisting> <programlisting>
CREATE TEXT SEARCH CONFIGURATION public.pg ( COPY = pg_catalog.english ); CREATE TEXT SEARCH CONFIGURATION public.pg ( COPY = pg_catalog.english );
...@@ -3137,7 +3138,7 @@ SELECT plainto_tsquery('supernovae stars'); ...@@ -3137,7 +3138,7 @@ SELECT plainto_tsquery('supernovae stars');
</indexterm> </indexterm>
<para> <para>
There are two kinds of indexes which can be used to speed up full text There are two kinds of indexes that can be used to speed up full text
searches. searches.
Note that indexes are not mandatory for full text searching, but in Note that indexes are not mandatory for full text searching, but in
cases where a column is searched on a regular basis, an index is cases where a column is searched on a regular basis, an index is
...@@ -3204,7 +3205,7 @@ SELECT plainto_tsquery('supernovae stars'); ...@@ -3204,7 +3205,7 @@ SELECT plainto_tsquery('supernovae stars');
to check the actual table row to eliminate such false matches. to check the actual table row to eliminate such false matches.
(<productname>PostgreSQL</productname> does this automatically when needed.) (<productname>PostgreSQL</productname> does this automatically when needed.)
GiST indexes are lossy because each document is represented in the GiST indexes are lossy because each document is represented in the
index using a fixed-length signature. The signature is generated by hashing index by a fixed-length signature. The signature is generated by hashing
each word into a random bit in an n-bit string, with all these bits OR-ed each word into a random bit in an n-bit string, with all these bits OR-ed
together to produce an n-bit document signature. When two words hash to together to produce an n-bit document signature. When two words hash to
the same bit position there will be a false match. If all words in the same bit position there will be a false match. If all words in
......
doc/src/sgml/typeconv.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.59 2009/04/27 16:27:36 momjian Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.60 2009/06/17 21:58:49 tgl Exp $ -->
<chapter Id="typeconv"> <chapter Id="typeconv">
<title>Type Conversion</title> <title>Type Conversion</title>
...@@ -161,7 +161,7 @@ categories</firstterm>, including <type>boolean</type>, <type>numeric</type>, ...@@ -161,7 +161,7 @@ categories</firstterm>, including <type>boolean</type>, <type>numeric</type>,
user-defined. (For a list see <xref linkend="catalog-typcategory-table">; user-defined. (For a list see <xref linkend="catalog-typcategory-table">;
but note it is also possible to create custom type categories.) Within each but note it is also possible to create custom type categories.) Within each
category there can be one or more <firstterm>preferred types</firstterm>, which category there can be one or more <firstterm>preferred types</firstterm>, which
are selected when there is ambiguity. With careful selection are preferred when there is a choice of possible types. With careful selection
of preferred types and available implicit casts, it is possible to ensure that of preferred types and available implicit casts, it is possible to ensure that
ambiguous expressions (those with multiple candidate parsing solutions) can be ambiguous expressions (those with multiple candidate parsing solutions) can be
resolved in a useful way. resolved in a useful way.
...@@ -189,7 +189,7 @@ calls in the query. ...@@ -189,7 +189,7 @@ calls in the query.
<para> <para>
Additionally, if a query usually requires an implicit conversion for a function, and Additionally, if a query usually requires an implicit conversion for a function, and
if then the user defines a new function with the correct argument types, the parser if then the user defines a new function with the correct argument types, the parser
should use this new function and no longer do implicit conversion using the old function. should use this new function and no longer do implicit conversion to use the old function.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -206,10 +206,12 @@ should use this new function and no longer do implicit conversion using the old ...@@ -206,10 +206,12 @@ should use this new function and no longer do implicit conversion using the old
</indexterm> </indexterm>
<para> <para>
The specific operator invoked is determined by the following The specific operator that is referenced by an operator expression
steps. Note that this procedure is affected is determined using the following procedure.
by the precedence of the involved operators. See <xref Note that this procedure is indirectly affected
linkend="sql-precedence"> for more information. by the precedence of the involved operators, since that will determine
which sub-expressions are taken to be the inputs of which operators.
See <xref linkend="sql-precedence"> for more information.
</para> </para>
<procedure> <procedure>
...@@ -220,7 +222,7 @@ should use this new function and no longer do implicit conversion using the old ...@@ -220,7 +222,7 @@ should use this new function and no longer do implicit conversion using the old
Select the operators to be considered from the Select the operators to be considered from the
<classname>pg_operator</classname> system catalog. If a non-schema-qualified <classname>pg_operator</classname> system catalog. If a non-schema-qualified
operator name was used (the usual case), the operators operator name was used (the usual case), the operators
considered are those with a matching name and argument count that are considered are those with the matching name and argument count that are
visible in the current search path (see <xref linkend="ddl-schemas-path">). visible in the current search path (see <xref linkend="ddl-schemas-path">).
If a qualified operator name was given, only operators in the specified If a qualified operator name was given, only operators in the specified
schema are considered. schema are considered.
...@@ -250,8 +252,8 @@ operators considered), use it. ...@@ -250,8 +252,8 @@ operators considered), use it.
<para> <para>
If one argument of a binary operator invocation is of the <type>unknown</type> type, If one argument of a binary operator invocation is of the <type>unknown</type> type,
then assume it is the same type as the other argument for this check. then assume it is the same type as the other argument for this check.
Cases involving two <type>unknown</type> types will never find a match at Invocations involving two <type>unknown</type> inputs, or a unary operator
this step. with an <type>unknown</type> input, will never find a match at this step.
</para> </para>
</step> </step>
</substeps> </substeps>
...@@ -390,9 +392,9 @@ In this case there is no initial hint for which type to use, since no types ...@@ -390,9 +392,9 @@ In this case there is no initial hint for which type to use, since no types
are specified in the query. So, the parser looks for all candidate operators are specified in the query. So, the parser looks for all candidate operators
and finds that there are candidates accepting both string-category and and finds that there are candidates accepting both string-category and
bit-string-category inputs. Since string category is preferred when available, bit-string-category inputs. Since string category is preferred when available,
that category is selected, and the that category is selected, and then the
preferred type for strings, <type>text</type>, is used as the specific preferred type for strings, <type>text</type>, is used as the specific
type to resolve the unknown literals. type to resolve the unknown literals as.
</para> </para>
</example> </example>
...@@ -459,8 +461,8 @@ SELECT ~ CAST('20' AS int8) AS "negation"; ...@@ -459,8 +461,8 @@ SELECT ~ CAST('20' AS int8) AS "negation";
</indexterm> </indexterm>
<para> <para>
The specific function to be invoked is determined The specific function that is referenced by a function call
according to the following steps. is determined using the following procedure.
</para> </para>
<procedure> <procedure>
...@@ -471,7 +473,7 @@ SELECT ~ CAST('20' AS int8) AS "negation"; ...@@ -471,7 +473,7 @@ SELECT ~ CAST('20' AS int8) AS "negation";
Select the functions to be considered from the Select the functions to be considered from the
<classname>pg_proc</classname> system catalog. If a non-schema-qualified <classname>pg_proc</classname> system catalog. If a non-schema-qualified
function name was used, the functions function name was used, the functions
considered are those with a matching name and argument count that are considered are those with the matching name and argument count that are
visible in the current search path (see <xref linkend="ddl-schemas-path">). visible in the current search path (see <xref linkend="ddl-schemas-path">).
If a qualified function name was given, only functions in the specified If a qualified function name was given, only functions in the specified
schema are considered. schema are considered.
...@@ -554,7 +556,7 @@ Look for the best match. ...@@ -554,7 +556,7 @@ Look for the best match.
<substeps> <substeps>
<step performance="required"> <step performance="required">
<para> <para>
Discard candidate functions in which the input types do not match Discard candidate functions for which the input types do not match
and cannot be converted (using an implicit conversion) to match. and cannot be converted (using an implicit conversion) to match.
<type>unknown</type> literals are <type>unknown</type> literals are
assumed to be convertible to anything for this purpose. If only one assumed to be convertible to anything for this purpose. If only one
...@@ -615,9 +617,10 @@ Some examples follow. ...@@ -615,9 +617,10 @@ Some examples follow.
<title>Rounding Function Argument Type Resolution</title> <title>Rounding Function Argument Type Resolution</title>
<para> <para>
There is only one <function>round</function> function which takes two There is only one <function>round</function> function that takes two
arguments; it takes a first argument of <type>numeric</type> and arguments; it takes a first argument of type <type>numeric</type> and
a second argument of <type>integer</type>. So the following query automatically converts a second argument of type <type>integer</type>.
So the following query automatically converts
the first argument of type <type>integer</type> to the first argument of type <type>integer</type> to
<type>numeric</type>: <type>numeric</type>:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment