diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index 305ce9cc57de54a4ce36d1d943c4433c47413208..5ae2f59baeafc8036e719005fc5fd40729ae3ba3 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Advanced Features</title>
@@ -19,7 +19,7 @@
<para>
This chapter will on occasion refer to examples found in <xref
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
<filename>advanced.sql</filename> in the tutorial directory. This
file also contains some sample data to load, which is not
@@ -173,7 +173,7 @@ UPDATE branches SET balance = balance + 100.00
</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
this rather simple operation. Our bank's officers will want to be
assured that either all these updates happen, or none of them happen.
diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 6e731e1448e4ee0cac24d6d75fa272f11a8f7892..bfc373ac052d0f01d1ac9416d78d458ef9e2110f 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Arrays</title>
@@ -60,18 +60,17 @@ CREATE TABLE tictactoe (
</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
all considered to be of the same type, regardless of size or number
- of dimensions. So, declaring the number of dimensions or sizes in
- <command>CREATE TABLE</command> is simply documentation, it does not
+ of dimensions. So, declaring the array size or number of dimensions in
+ <command>CREATE TABLE</command> is simply documentation; it does not
affect run-time behavior.
</para>
<para>
An alternative syntax, which conforms to the SQL standard by using
- they keyword <literal>ARRAY</>, can
- be used for one-dimensional arrays;
+ the keyword <literal>ARRAY</>, can be used for one-dimensional arrays.
<structfield>pay_by_quarter</structfield> could have been defined
as:
<programlisting>
@@ -109,7 +108,7 @@ CREATE TABLE tictactoe (
for the type, as recorded in its <literal>pg_type</literal> entry.
Among the standard data types provided in the
<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
either a constant of the array element type, or a subarray. An example
of an array constant is:
@@ -121,7 +120,7 @@ CREATE TABLE tictactoe (
</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
<literal>NULL</> will do.) If you want an actual string value
<quote>NULL</>, you must put double quotes around it.
@@ -211,7 +210,7 @@ INSERT INTO sal_emp
First, we show how to access a single element of an array.
This query retrieves the names of the employees whose pay changed in
the second quarter:
-
+
<programlisting>
SELECT name FROM sal_emp WHERE pay_by_quarter[1] <> pay_by_quarter[2];
@@ -230,7 +229,7 @@ SELECT name FROM sal_emp WHERE pay_by_quarter[1] <> pay_by_quarter[2];
<para>
This query retrieves the third quarter pay of all employees:
-
+
<programlisting>
SELECT pay_by_quarter[3] FROM sal_emp;
@@ -248,7 +247,7 @@ SELECT pay_by_quarter[3] FROM sal_emp;
<literal><replaceable>lower-bound</replaceable>:<replaceable>upper-bound</replaceable></literal>
for one or more array dimensions. For example, this query retrieves the first
item on Bill's schedule for the first two days of the week:
-
+
<programlisting>
SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill';
@@ -417,14 +416,14 @@ SELECT ARRAY[5,6] || ARRAY[[1,2],[3,4]];
</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
<replaceable>N</>-dimensional arrays, or an <replaceable>N</>-dimensional
and an <replaceable>N+1</>-dimensional array.
</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
subscript as the array operand. For example:
<programlisting>
@@ -463,7 +462,7 @@ SELECT array_dims(ARRAY[[1,2],[3,4]] || ARRAY[[5,6],[7,8],[9,0]]);
</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
analogous to the element-array case above. Each <replaceable>N</>-dimensional
sub-array is essentially an element of the <replaceable>N+1</>-dimensional
@@ -601,9 +600,9 @@ SELECT * FROM
around the array value plus delimiter characters between adjacent items.
The delimiter character is usually a comma (<literal>,</>) but can be
something else: it is determined by the <literal>typdelim</> setting
- for the array's element type. (Among the standard data types provided
- in the <productname>PostgreSQL</productname> distribution, all
- use a comma, except for <literal>box</>, which uses a semicolon (<literal>;</>).)
+ for the array's element type. Among the standard data types provided
+ in the <productname>PostgreSQL</productname> distribution, all use a comma,
+ except for type <type>box</>, which uses a semicolon (<literal>;</>).
In a multidimensional array, each dimension (row, plane,
cube, etc.) gets its own level of curly braces, and delimiters
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
As shown previously, when writing an array value you can use double
quotes around any individual array element. You <emphasis>must</> do so
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
whitespace must be double-quoted. Empty strings and strings matching the
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
</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
string. In all of these cases the whitespace will be ignored. However,
whitespace within double-quoted elements, or surrounded on both sides by
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 89f7ab35db3d221d54705a020ac6c600ddacd4fa..dbdd0a0dbc46bf32000c46e9be8bd9a1703260a8 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Server Configuration</title>
@@ -1252,8 +1252,8 @@ SET ENABLE_SEQSCAN TO OFF;
Asynchronous I/O depends on an effective <function>posix_fadvise</>
function, which some operating systems lack. If the function is not
present then setting this parameter to anything but zero will result
- in an error. On some operating systems the function is present but
- does not actually do anything (e.g., Solaris).
+ in an error. On some operating systems (e.g., Solaris), the function
+ is present but does not actually do anything.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 4844fd63b5192ca9c9a84b8fb8d92b759e687c1d..763a114e7f7d2b2cd21489275a7d4f30ac772aaf 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title id="datatype-title">Data Types</title>
@@ -290,7 +290,7 @@
to <productname>PostgreSQL</productname>, such as geometric
paths, or have several possible formats, such as the date
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 original input.
</para>
@@ -441,11 +441,11 @@
<para>
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>
- acts the same as <type>integer</type> (but still takes up eight
- bytes of storage). (We are not aware of any
- platform where this is true.)
+ acts the same as <type>integer</type>, but still takes up eight
+ bytes of storage. (We are not aware of any modern
+ platform where this is the case.)
</para>
<para>
@@ -453,7 +453,7 @@
<type>integer</type> (or <type>int</type>),
<type>smallint</type>, and <type>bigint</type>. The
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.
</para>
@@ -481,7 +481,7 @@
especially recommended for storing monetary amounts and other
quantities where exactness is required. However, arithmetic on
<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>
@@ -681,7 +681,7 @@ NUMERIC
<quote>not-a-number</quote>, respectively. (On a machine whose
floating-point arithmetic does not follow IEEE 754, 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,
these strings are recognized in a case-insensitive manner.
</para>
@@ -785,7 +785,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
Thus, we have created an integer column and arranged for its default
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
<literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint to prevent
duplicate values from being inserted by accident, but this is
@@ -798,7 +798,7 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
Prior to <productname>PostgreSQL</productname> 7.3, <type>serial</type>
implied <literal>UNIQUE</literal>. This is no longer automatic. If
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.
</para>
</note>
@@ -837,15 +837,15 @@ ALTER SEQUENCE <replaceable class="parameter">tablename</replaceable>_<replaceab
<para>
The <type>money</type> type stores a currency amount with a fixed
fractional precision; see <xref
- linkend="datatype-money-table">. The fractional precision
- is controlled by the database locale.
+ linkend="datatype-money-table">. The fractional precision is
+ determined by the database's <xref linkend="guc-lc-monetary"> setting.
Input is accepted in a variety of formats, including integer and
floating-point literals, as well as typical
currency formatting, such as <literal>'$1,000.00'</literal>.
Output is generally in the latter form but depends on the locale.
Non-quoted numeric values can be converted to <type>money</type> by
casting the numeric value to <type>text</type> and then
- <type>money</type>:
+ <type>money</type>, for example:
<programlisting>
SELECT 1234::text::money;
</programlisting>
@@ -961,7 +961,7 @@ SELECT regexp_replace('52093.89'::money::text, '[$,]', '', 'g')::numeric;
<type>character varying(<replaceable>n</>)</type> and
<type>character(<replaceable>n</>)</type>, where <replaceable>n</>
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
error, unless the excess characters are all spaces, in which case
the string will be truncated to the maximum length. (This somewhat
@@ -1033,13 +1033,15 @@ SELECT regexp_replace('52093.89'::money::text, '[$,]', '', 'g')::numeric;
<tip>
<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
type, and a few extra CPU cycles to check the length when storing into
a length-constrained column. While
<type>character(<replaceable>n</>)</type> has performance
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
instead.
</para>
@@ -1583,7 +1585,8 @@ SELECT b, char_length(b) FROM test2;
<synopsis>
<replaceable>type</replaceable> [ (<replaceable>p</replaceable>) ] '<replaceable>value</replaceable>'
</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
specified for <type>time</type>, <type>timestamp</type>, and
<type>interval</type> types. The allowed values are mentioned
@@ -1705,7 +1708,7 @@ SELECT b, char_length(b) FROM test2;
The time-of-day types are <type>time [
(<replaceable>p</replaceable>) ] without time zone</type> and
<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>.
</para>
@@ -1752,7 +1755,7 @@ SELECT b, char_length(b) FROM test2;
</row>
<row>
<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>
<entry><literal>04:05 PM</literal></entry>
@@ -1878,14 +1881,15 @@ January 8 04:05:06 1999 PST
</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
- <quote>+</quote> or <quote>-</quote> symbol after the time
- indicating the time zone offset. Hence, according to the standard:
+ <quote>+</quote> or <quote>-</quote> symbol and time zone offset after
+ the time. Hence, according to the standard,
<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>
@@ -2048,15 +2052,15 @@ January 8 04:05:06 1999 PST
</indexterm>
<para>
- The output format of the date/time types can one of the four
- styles: ISO 8601,
+ The output format of the date/time types can be set to one of the four
+ styles ISO 8601,
<acronym>SQL</acronym> (Ingres), traditional <productname>POSTGRES</>
- (Unix <application>date</> format), and
- German. It can be set using the <literal>SET datestyle</literal> command. The default
+ (Unix <application>date</> format), or
+ German. The default
is the <acronym>ISO</acronym> format. (The
<acronym>SQL</acronym> standard requires the use of the ISO 8601
- format. The name of the <literal>SQL</> output format poorly
- chosen and an historical accident.) <xref
+ format. The name of the <quote>SQL</quote> output format is a
+ historical accident.) <xref
linkend="datatype-datetime-output-table"> shows examples of each
output style. The output of the <type>date</type> and
<type>time</type> types is of course only the date or time part
@@ -2273,7 +2277,7 @@ January 8 04:05:06 1999 PST
</listitem>
</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
UTC, whereas most of the full names imply a local daylight-savings time
rule, and so have two possible UTC offsets.
@@ -2358,7 +2362,7 @@ January 8 04:05:06 1999 PST
</indexterm>
<para>
- <type>interval</type> values can be written using the following:
+ <type>interval</type> values can be written using the following
verbose syntax:
<synopsis>
@@ -2708,9 +2712,10 @@ P <optional> <replaceable>years</>-<replaceable>months</>-<replaceable>days</> <
<member><literal>'off'</literal></member>
<member><literal>'0'</literal></member>
</simplelist>
- Leading and trailing whitespace and case are ignored. The key words
- <literal>TRUE</literal> and <literal>FALSE</literal> is the preferred
- usage (and <acronym>SQL</acronym>-compliant).
+ Leading or trailing whitespace is ignored, and case does not matter.
+ The key words
+ <literal>TRUE</literal> and <literal>FALSE</literal> are the preferred
+ (<acronym>SQL</acronym>-compliant) usage.
</para>
<example id="datatype-boolean-example">
@@ -3072,8 +3077,9 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
</para>
<para>
- Boxes are output using the first syntax. Any two opposite corners
- can be supplied; the corners are reordered on input to store the
+ Boxes are output using the first syntax.
+ 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.
</para>
</sect2>
@@ -3111,7 +3117,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
</para>
<para>
- Paths are output using the first appropriate syntax.
+ Paths are output using the first or second syntax, as appropriate.
</para>
</sect2>
@@ -3190,7 +3196,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC
addresses, as shown in <xref linkend="datatype-net-types-table">. It
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
operators and functions (see <xref linkend="functions-net">).
</para>
@@ -3266,7 +3272,7 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
<replaceable class="parameter">y</replaceable>
is the number of bits in the netmask. If the
<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
just a single host. On display, the
<replaceable class="parameter">/y</replaceable>
@@ -3560,8 +3566,8 @@ SELECT * FROM test;
are designed to support full text search, which is the activity of
searching through a collection of natural-language <firstterm>documents</>
to locate those that best match a <firstterm>query</>.
- The <type>tsvector</type> type represents a document stored in a form optimized
- for text search; <type>tsquery</type> type similarly represents
+ The <type>tsvector</type> type represents a document in a form optimized
+ for text search; the <type>tsquery</type> type similarly represents
a text query.
<xref linkend="textsearch"> provides a detailed explanation of this
facility, and <xref linkend="functions-textsearch"> summarizes the
@@ -3577,7 +3583,7 @@ SELECT * FROM test;
<para>
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
(see <xref linkend="textsearch"> for details). Sorting and
duplicate-elimination are done automatically during input, as shown in
@@ -3687,7 +3693,7 @@ SELECT to_tsvector('english', 'The Fat Rats');
<para>
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>&</literal> (AND), <literal>|</literal> (OR), and
<literal>!</> (NOT). Parentheses can be used to enforce grouping
of the operators:
@@ -3825,8 +3831,8 @@ a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
<para>
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
- checks the input values for well-formedness, and support
- functions can perform type-safe operations on it; see <xref
+ checks the input values for well-formedness, and there are support
+ functions to perform type-safe operations on it; see <xref
linkend="functions-xml">. Use of this data type requires the
installation to have been built with <command>configure
--with-libxml</>.
@@ -3870,8 +3876,9 @@ xml '<foo>bar</foo>'
<para>
The <type>xml</type> type does not validate input values
- against an optionally-supplied document type declaration
- (DTD).<indexterm><primary>DTD</primary></indexterm>
+ against a document type declaration
+ (DTD),<indexterm><primary>DTD</primary></indexterm>
+ even when the input value specifies a DTD.
</para>
<para>
@@ -3883,7 +3890,7 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <repla
</synopsis>
<replaceable>type</replaceable> can be
<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
<type>xml</type> and character types, but PostgreSQL also allows
you to simply cast the value.
@@ -3923,7 +3930,7 @@ SET xmloption TO { DOCUMENT | CONTENT };
representations of XML values, such as in the above examples.
This would ordinarily mean that encoding declarations contained in
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
with this behavior, encoding declarations contained in
character strings presented for input to the <type>xml</type> type
@@ -3932,7 +3939,7 @@ SET xmloption TO { DOCUMENT | CONTENT };
processing, character strings of XML data must be sent
from the client in the current client encoding. It is 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
type <type>xml</type> will not have an encoding declaration, and
clients should assume all data is in the current client
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index caf4cfd025688c4d6176d180122ab6deaa99ea7b..406a521ff05c9eb497cfea4b4be022283c34c57f 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Data Definition</title>
@@ -557,8 +557,8 @@ CREATE TABLE products (
comparison. That means even in the presence of a
unique constraint it is possible to store duplicate
rows that contain a null value in at least one of the constrained
- columns. This behavior conforms to the SQL standard, but there
- might be other SQL databases might not follow this rule. So be
+ columns. This behavior conforms to the SQL standard, but we have
+ heard that other SQL databases might not follow this rule. So be
careful when developing applications that are intended to be
portable.
</para>
@@ -1802,7 +1802,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
such names, to ensure that you won't suffer a conflict if some
future version defines a system table named the same as your
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
names beginning with <literal>pg_</>, so that they will not
conflict with unqualified user-table names so long as users avoid
@@ -2571,14 +2571,14 @@ CREATE TRIGGER insert_measurement_trigger
CREATE OR REPLACE FUNCTION measurement_insert_trigger()
RETURNS TRIGGER AS $$
BEGIN
- IF ( NEW.logdate >= DATE '2006-02-01' AND
+ IF ( NEW.logdate >= DATE '2006-02-01' AND
NEW.logdate < DATE '2006-03-01' ) THEN
INSERT INTO measurement_y2006m02 VALUES (NEW.*);
- ELSIF ( NEW.logdate >= DATE '2006-03-01' AND
+ ELSIF ( NEW.logdate >= DATE '2006-03-01' AND
NEW.logdate < DATE '2006-04-01' ) THEN
INSERT INTO measurement_y2006m03 VALUES (NEW.*);
...
- ELSIF ( NEW.logdate >= DATE '2008-01-01' AND
+ ELSIF ( NEW.logdate >= DATE '2008-01-01' AND
NEW.logdate < DATE '2008-02-01' ) THEN
INSERT INTO measurement_y2008m01 VALUES (NEW.*);
ELSE
@@ -2709,9 +2709,9 @@ SELECT count(*) FROM measurement WHERE logdate >= DATE '2008-01-01';
Without constraint exclusion, the above query would scan each of
the partitions of the <structname>measurement</> table. With constraint
exclusion enabled, the planner will examine the constraints of each
- partition and try to determine which partitions need not
- be scanned because they cannot not contain any rows meeting the query's
- <literal>WHERE</> clause. When the planner can determine this, it
+ partition and try to prove that the partition need not
+ be scanned because it could not contain any rows meeting the query's
+ <literal>WHERE</> clause. When the planner can prove this, it
excludes the partition from the query plan.
</para>
@@ -2906,7 +2906,7 @@ ANALYZE measurement;
<listitem>
<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
equality conditions for list partitioning, or simple
range tests for range partitioning, as illustrated in the preceding
diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml
index 08fd5b763012918d8bca8d4c4d0d2dd1c038f4ed..eb114263a5f2b02c02d07125a8119e084f0271a6 100644
--- a/doc/src/sgml/dml.sgml
+++ b/doc/src/sgml/dml.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Data Manipulation</title>
@@ -248,10 +248,7 @@ DELETE FROM products WHERE price = 10;
<programlisting>
DELETE FROM products;
</programlisting>
- then all rows in the table will be deleted! (<xref
- linkend="sql-truncate" endterm="sql-truncate-title"> can also be used
- to delete all rows.)
- Caveat programmer.
+ then all rows in the table will be deleted! Caveat programmer.
</para>
</sect1>
</chapter>
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index e37eac587e977f3b824abcecb69ef7ded4196b08..4aafc4e2a0212ba501814695425f24af911d01b6 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Documentation</title>
@@ -358,7 +358,7 @@ CATALOG "dsssl/catalog"
Create the directory
<filename>/usr/local/share/sgml/docbook-4.2</filename> and change
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>
<prompt>$ </prompt><userinput>mkdir /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
To install the style sheets, unzip and untar the distribution and
move it to a suitable place, for example
<filename>/usr/local/share/sgml</filename>. (The archive will
- automatically create a subdirectory.):
+ automatically create a subdirectory.)
<screen>
<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>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index a594a12ed7b11a4b15685b667968344ed7c6feb2..cbadf0f99a11e4f56d989cb3b963ba57421a61fb 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Functions and Operators</title>
@@ -268,8 +268,9 @@
<synopsis>
<replaceable>a</replaceable> >= <replaceable>x</replaceable> AND <replaceable>a</replaceable> <= <replaceable>y</replaceable>
</synopsis>
- Note <token>BETWEEN</token> is inclusive in comparing the endpoint
- values. <literal>NOT BETWEEN</literal> does the opposite comparison:
+ Notice that <token>BETWEEN</token> treats the endpoint values as included
+ in the range.
+ <literal>NOT BETWEEN</literal> does the opposite comparison:
<synopsis>
<replaceable>a</replaceable> NOT BETWEEN <replaceable>x</replaceable> AND <replaceable>y</replaceable>
</synopsis>
@@ -280,9 +281,11 @@
<indexterm>
<primary>BETWEEN SYMMETRIC</primary>
</indexterm>
- <token>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
- or equal to the argument on the right; the proper range is automatically determined.
+ <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 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>
@@ -322,7 +325,7 @@
<tip>
<para>
- Some applications might expect
+ Some applications might expect that
<literal><replaceable>expression</replaceable> = NULL</literal>
returns true if <replaceable>expression</replaceable> evaluates to
the null value. It is highly recommended that these applications
@@ -358,11 +361,11 @@
<indexterm>
<primary>IS NOT DISTINCT FROM</primary>
</indexterm>
- Ordinary comparison operators yield null (signifying <quote>unknown</>)
- when either input is null, not true or false, e.g., <literal>7 =
- NULL</> yields null.
- Another way to do comparisons is with the
- <literal>IS <optional> NOT </> DISTINCT FROM</literal> construct:
+ Ordinary comparison operators yield null (signifying <quote>unknown</>),
+ not true or false, when either input is null. For example,
+ <literal>7 = NULL</> yields null. When this behavior is not suitable,
+ use the
+ <literal>IS <optional> NOT </> DISTINCT FROM</literal> constructs:
<synopsis>
<replaceable>expression</replaceable> IS DISTINCT FROM <replaceable>expression</replaceable>
<replaceable>expression</replaceable> IS NOT DISTINCT FROM <replaceable>expression</replaceable>
@@ -440,8 +443,8 @@
<para>
Mathematical operators are provided for many
- <productname>PostgreSQL</productname> types. For types that support
- only limited mathematical operations
+ <productname>PostgreSQL</productname> types. For types without
+ standard mathematical conventions
(e.g., date/time types) we
describe the actual behavior in subsequent sections.
</para>
@@ -1010,11 +1013,13 @@
</para>
<para>
- <acronym>SQL</acronym> defines some string functions with a special syntax
- wherein certain key words rather than commas are used to separate the
- arguments. Details are in <xref linkend="functions-string-sql">.
- These functions are also implemented using the regular syntax for
- function invocation. (See <xref linkend="functions-string-other">.)
+ <acronym>SQL</acronym> defines some string functions that use
+ key words, rather than commas, to separate
+ arguments. Details are in
+ <xref linkend="functions-string-sql">.
+ <productname>PostgreSQL</> also provides versions of these functions
+ that use the regular function invocation syntax
+ (see <xref linkend="functions-string-other">).
</para>
<note>
@@ -1795,8 +1800,8 @@
<para>
The conversion names follow a standard naming scheme: The
official name of the source encoding with all
- non-alphanumeric characters replaced by underscores followed
- by <literal>_to_</literal> followed by similarly
+ non-alphanumeric characters replaced by underscores, followed
+ by <literal>_to_</literal>, followed by the similarly processed
destination encoding name. Therefore, the names might deviate
from the customary encoding names.
</para>
@@ -2598,12 +2603,12 @@
<para>
<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
<xref linkend="functions-binarystring-sql">.
- Such functions are also implemented using the regular syntax for
- function invocation.
- (See <xref linkend="functions-binarystring-other">.)
+ <productname>PostgreSQL</> also provides versions of these functions
+ that use the regular function invocation syntax
+ (see <xref linkend="functions-binarystring-other">).
</para>
<table id="functions-binarystring-sql">
@@ -2999,7 +3004,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
</synopsis>
<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>pattern</replaceable>. (As
expected, the <function>NOT LIKE</function> expression returns
@@ -3011,11 +3016,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para>
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
equals operator. An underscore (<literal>_</literal>) in
<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.
</para>
@@ -3028,7 +3033,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
'abc' LIKE 'c' <lineannotation>false</lineannotation>
</programlisting>
</para>
-
+
<para>
<function>LIKE</function> pattern matching always covers the entire
string. Therefore, to match a sequence anywhere within a string, the
@@ -3036,9 +3041,9 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
</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
- <replaceable>pattern</replaceable> must be
+ <replaceable>pattern</replaceable> must be
preceded by the escape character. The default escape
character is the backslash but a different one can be selected by
using the <literal>ESCAPE</literal> clause. To match the escape
@@ -3053,8 +3058,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
actually matches a literal backslash means writing four backslashes in the
statement. You can avoid this by selecting a different escape character
with <literal>ESCAPE</literal>; then a backslash is not special to
- <function>LIKE</function> anymore. (But backslash is still special to the string
- literal parser, so you still need two of them.)
+ <function>LIKE</function> anymore. (But backslash is still special to the
+ string literal parser, so you still need two of them to match a backslash.)
</para>
<para>
@@ -3163,9 +3168,9 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
</listitem>
</itemizedlist>
- Notice that bounded repetition (<literal>?</> and <literal>{...}</>)
- is not provided, though they exist in POSIX. Also, the period (<literal>.</>)
- is not a metacharacter.
+ Notice that bounded repetition operators (<literal>?</> and
+ <literal>{...}</>) are not provided, though they exist in POSIX.
+ Also, the period (<literal>.</>) is not a metacharacter.
</para>
<para>
@@ -3295,7 +3300,7 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat
expression. As with <function>LIKE</function>, pattern characters
match string characters exactly unless they are special characters
in the regular expression language — 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
regular expression is allowed to match anywhere within a string, unless
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;
<para>
A branch is zero or more <firstterm>quantified atoms</> or
<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.
</para>
@@ -3579,7 +3584,8 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<para>
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
<xref linkend="posix-constraints-table">;
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;
<tbody>
<row>
<entry> <literal>^</> </entry>
- <entry> matches the beginning of the string </entry>
+ <entry> matches at the beginning of the string </entry>
</row>
<row>
<entry> <literal>$</> </entry>
- <entry> matches the end of the string </entry>
+ <entry> matches at the end of the string </entry>
</row>
<row>
@@ -3842,12 +3848,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<para>
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
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
- 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>
(see next paragraphs), and escapes (AREs only), all other special
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;
<para>
<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">.
</para>
@@ -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> (where <replaceable>wxyz</> is exactly four hexadecimal digits)
the UTF16 (Unicode, 16-bit) character <literal>U+</><replaceable>wxyz</>
- in the local byte encoding</entry>
+ in the local byte ordering </entry>
</row>
<row>
@@ -4058,7 +4064,7 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<entry> (where <replaceable>stuvwxyz</> is exactly eight hexadecimal
digits)
reserved for a hypothetical Unicode extension to 32 bits
- </entry>
+ </entry>
</row>
<row>
@@ -4067,11 +4073,11 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
</row>
<row>
- <entry> <literal>\x</><replaceable>###</> </entry>
- <entry> (where <replaceable>###</> is any sequence of hexadecimal
+ <entry> <literal>\x</><replaceable>hhh</> </entry>
+ <entry> (where <replaceable>hhh</> is any sequence of hexadecimal
digits)
the character whose hexadecimal value is
- <literal>0x</><replaceable>###</>
+ <literal>0x</><replaceable>hhh</>
(a single character no matter how many hexadecimal digits are used)
</entry>
</row>
@@ -4082,19 +4088,19 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
</row>
<row>
- <entry> <literal>\</><replaceable>##</> </entry>
- <entry> (where <replaceable>##</> is exactly two octal digits,
+ <entry> <literal>\</><replaceable>xy</> </entry>
+ <entry> (where <replaceable>xy</> is exactly two octal digits,
and is not a <firstterm>back reference</>)
the character whose octal value is
- <literal>0</><replaceable>##</> </entry>
+ <literal>0</><replaceable>xy</> </entry>
</row>
<row>
- <entry> <literal>\</><replaceable>###</> </entry>
- <entry> (where <replaceable>###</> is exactly three octal digits,
+ <entry> <literal>\</><replaceable>xyz</> </entry>
+ <entry> (where <replaceable>xyz</> is exactly three octal digits,
and is not a <firstterm>back reference</>)
the character whose octal value is
- <literal>0</><replaceable>###</> </entry>
+ <literal>0</><replaceable>xyz</> </entry>
</row>
</tbody>
</tgroup>
@@ -4258,12 +4264,12 @@ SELECT foo FROM regexp_split_to_table('the quick brown fox', E'\\s*') AS foo;
<note>
<para>
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.
A leading zero always indicates an octal escape.
A single non-zero digit, not followed by another digit,
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
(i.e., the number is in the legal range for a back reference),
and otherwise is taken as octal.
@@ -4749,7 +4755,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<type>double precision</type> argument and converts from Unix epoch
(seconds since 1970-01-01 00:00:00+00) to
<type>timestamp with time zone</type>.
- (<type>Integer</type> Unix epochs are implicitly cast to
+ (<type>Integer</type> Unix epochs are implicitly cast to
<type>double precision</type>.)
</para>
@@ -4817,7 +4823,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<row>
<entry><literal><function>to_timestamp</function>(<type>double precision</type>)</literal></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>
</row>
</tbody>
@@ -4825,11 +4831,12 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</table>
<para>
- In a <function>to_char</> output template string, there are certain patterns that are
- recognized and replaced with appropriately-formatted data based on the value.
- Any text that is not a template pattern is simply
- copied verbatim. Similarly, in an input template string (anything but <function>to_char</>), template patterns
- identify the values to be supplied by the input data string.
+ In a <function>to_char</> output template string, there are certain
+ patterns that are recognized and replaced with appropriately-formatted
+ data based on the given value. Any text that is not a template pattern is
+ simply copied verbatim. Similarly, in an input template string (for the
+ other functions), template patterns identify the values to be supplied by
+ the input data string.
</para>
<para>
@@ -5033,11 +5040,11 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row>
<row>
<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>
<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>
<entry><literal>TZ</literal></entry>
@@ -5073,7 +5080,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<tbody>
<row>
<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>
</row>
<row>
@@ -5099,7 +5106,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</row>
<row>
<entry><literal>SP</literal> suffix</entry>
- <entry>spell mode (not supported)</entry>
+ <entry>spell mode (not implemented)</entry>
<entry><literal>DDSP</literal></entry>
</row>
</tbody>
@@ -5127,8 +5134,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem>
<para>
<function>to_timestamp</function> and <function>to_date</function>
- skip multiple blank spaces in the input string unless the <literal>FX</literal> option
- is used. For example,
+ skip multiple blank spaces in the input string unless the
+ <literal>FX</literal> option is used. For example,
<literal>to_timestamp('2000 JUN', 'YYYY MON')</literal> works, but
<literal>to_timestamp('2000 JUN', 'FXYYYY MON')</literal> returns an error
because <function>to_timestamp</function> expects one space only.
@@ -5177,8 +5184,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem>
<para>
In conversions from string to <type>timestamp</type> or
- <type>date</type>, the <literal>CC</literal> field (century) is ignored if there
- is a <literal>YYY</literal>, <literal>YYYY</literal> or
+ <type>date</type>, the <literal>CC</literal> (century) field is ignored
+ if there is a <literal>YYY</literal>, <literal>YYYY</literal> or
<literal>Y,YYY</literal> field. If <literal>CC</literal> is used with
<literal>YY</literal> or <literal>Y</literal> then the year is computed
as <literal>(CC-1)*100+YY</literal>.
@@ -5220,7 +5227,7 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem>
<para>
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
seconds digits after the decimal point. For example
<literal>to_timestamp('12:3', 'SS:MS')</literal> is not 3 milliseconds,
@@ -5251,7 +5258,8 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
</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</>
can output hours exceeding a single day, e.g., >24.
</para>
@@ -5390,14 +5398,14 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
multiplies the input values by
<literal>10^<replaceable>n</replaceable></literal>, where
<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
- <literal>V</literal> with non-integer values.
- (e.g., <literal>99.9V99</literal> is not allowed.)
+ <literal>V</literal> combined with a decimal point
+ (e.g., <literal>99.9V99</literal> is not allowed).
</para>
</listitem>
</itemizedlist>
- </para>
+ </para>
<para>
Certain modifiers can be applied to any template pattern to alter its
@@ -6129,7 +6137,7 @@ EXTRACT(<replaceable>field</replaceable> FROM <replaceable>source</replaceable>)
<term><literal>century</literal></term>
<listitem>
<para>
- The century:
+ The century
</para>
<screen>
@@ -6225,7 +6233,7 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40');
<listitem>
<para>
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
of seconds in the interval
</para>
@@ -6778,6 +6786,9 @@ now()
</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
statement (more specifically, the time of receipt of the latest command
message from the client).
@@ -6792,10 +6803,7 @@ now()
but as a formatted <type>text</> string rather than a <type>timestamp
with time zone</> value.
<function>now()</> is a traditional <productname>PostgreSQL</productname>
- equivalent to <function>CURRENT_TIMESTAMP</function>.
- <function>transaction_timestamp()</> is likewise equivalent to
- <function>CURRENT_TIMESTAMP</function>, but is named to clearly reflect
- what it returns.
+ equivalent to <function>transaction_timestamp()</function>.
</para>
<para>
@@ -7428,7 +7436,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
<para>
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>SELECT p[0] FROM t</> retrieves the X coordinate and
<literal>UPDATE t SET p[1] = ...</> changes the Y coordinate.
@@ -8235,7 +8243,7 @@ SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
<para>
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:
<screen><![CDATA[
SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
@@ -8360,9 +8368,9 @@ SELECT xmlpi(name php, 'echo "hello world";');
<para>
The <function>xmlroot</function> expression alters the properties
of the root node of an XML value. If a version is specified,
- this replaces the value in the version declaration; if a
- standalone value is specified, this replaces the value in the
- standalone declaration.
+ it replaces the value in the root node's version declaration; if a
+ standalone setting is specified, it replaces the value in the
+ root node's standalone declaration.
</para>
<para>
@@ -8967,7 +8975,7 @@ SELECT setval('foo', 42, false); <lineannotation>Next <function>nextval</> wi
<para>
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
special parameters in the <xref linkend="sql-createsequence" endterm="sql-createsequence-title"> command;
see its command reference page for more information.
@@ -9028,16 +9036,17 @@ END
</synopsis>
<token>CASE</token> clauses can be used wherever
- an expression is valid. <replaceable>condition</replaceable> is an
- expression that returns a <type>boolean</type> result. If 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
- subsequent <token>WHEN</token> clauses are searched in the same
- manner. If no <token>WHEN</token>
- <replaceable>condition</replaceable> is true then the value of the
- case expression is the <replaceable>result</replaceable> of the
+ an expression is valid. Each <replaceable>condition</replaceable> is an
+ expression that returns a <type>boolean</type> result. If the condition's
+ result is true, the value of the <token>CASE</token> expression is the
+ <replaceable>result</replaceable> that follows the condition, and the
+ remainder of the <token>CASE</token> expression is not processed. If the
+ condition's result is not true, any subsequent <token>WHEN</token> clauses
+ are examined in the same manner. If no <token>WHEN</token>
+ <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
- omitted and no condition matches, the result is null.
+ omitted and no condition is true, the result is null.
</para>
<para>
@@ -9074,8 +9083,8 @@ SELECT a,
</para>
<para>
- The following <token>CASE</token> expression is a
- variant of the general form above:
+ There is a <quote>simple</> form of <token>CASE</token> expression
+ that is a variant of the general form above:
<synopsis>
CASE <replaceable>expression</replaceable>
@@ -9085,10 +9094,10 @@ CASE <replaceable>expression</replaceable>
END
</synopsis>
- The
- <replaceable>expression</replaceable> is computed and compared to
- all the <replaceable>value</replaceable>s in the
- <token>WHEN</token> clauses until one is found that is equal. If
+ The first
+ <replaceable>expression</replaceable> is computed, then compared to
+ each of the <replaceable>value</replaceable> expressions in the
+ <token>WHEN</token> clauses until one is found that is equal to it. If
no match is found, the <replaceable>result</replaceable> of the
<token>ELSE</token> clause (or a null value) is returned. This is similar
to the <function>switch</function> statement in C.
@@ -9114,8 +9123,8 @@ SELECT a,
</para>
<para>
- A <token>CASE</token> expression evaluates any subexpressions
- that are needed to determine the result. For example, this is a
+ A <token>CASE</token> expression does not evaluate any subexpressions
+ that are not needed to determine the result. For example, this is a
possible way of avoiding a division-by-zero failure:
<programlisting>
SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END;
@@ -9154,7 +9163,7 @@ SELECT COALESCE(description, short_description, '(none)') ...
<para>
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
not evaluated. This SQL-standard function provides capabilities similar
to <function>NVL</> and <function>IFNULL</>, which are used in some other
@@ -9804,17 +9813,18 @@ SELECT NULLIF(value, '(none)') ...
<primary>SOME</primary>
</indexterm>
<para>
- Boolean aggregates <function>bool_and</function> and
+ Boolean aggregates <function>bool_and</function> and
<function>bool_or</function> correspond to standard SQL aggregates
<function>every</function> and <function>any</function> or
- <function>some</function>.
- As for <function>any</function> and <function>some</function>,
+ <function>some</function>.
+ As for <function>any</function> and <function>some</function>,
it seems that there is an ambiguity built into the standard syntax:
<programlisting>
SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
</programlisting>
- Here <function>ANY</function> can be considered as leading either
- to a subquery or to an aggregate, if the select expression returns one row.
+ Here <function>ANY</function> can be considered either as introducing
+ 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.
</para>
</note>
@@ -9829,7 +9839,7 @@ SELECT b1 = ANY((SELECT b2 FROM t2 ...)) FROM t1 ...;
SELECT count(*) FROM sometable;
</programlisting>
will be executed by <productname>PostgreSQL</productname> using a
- sequential scan of an entire table.
+ sequential scan of the entire table.
</para>
</note>
@@ -10533,7 +10543,7 @@ EXISTS (<replaceable>subquery</replaceable>)
or <firstterm>subquery</firstterm>. The
subquery is evaluated to determine whether it returns any rows.
If it returns at least one row, the result of <token>EXISTS</token> is
- <quote>true</>; if the subquery returns no rows, the result of <token>EXISTS</token>
+ <quote>true</>; if the subquery returns no rows, the result of <token>EXISTS</token>
is <quote>false</>.
</para>
@@ -10882,7 +10892,7 @@ WHERE EXISTS (SELECT 1 FROM tab2 WHERE col2 = tab1.col2);
The forms involving array subexpressions are
<productname>PostgreSQL</productname> extensions; the rest are
<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.
</para>
@@ -11594,8 +11604,8 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<para>
<function>pg_my_temp_schema</function> returns the OID of the current
- session's temporary schema, or 0 if it has none (because no
- temporary tables have been created).
+ session's temporary schema, or zero if it has none (because it has not
+ created any temporary tables).
<function>pg_is_other_temp_schema</function> returns true if the
given OID is the OID of another session's temporary schema.
(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')
<para>
<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</>,
except that the desired access privilege type must evaluate to some
combination of
@@ -11908,7 +11919,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para>
<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>,
with the addition that the column can be specified either by name
or attribute number.
@@ -11922,7 +11934,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para>
<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>.
The desired access privilege type must evaluate to some combination of
<literal>CREATE</literal>,
@@ -11934,7 +11947,8 @@ SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION')
<para>
<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>.
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
@@ -11949,7 +11963,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<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>.
The desired access privilege type must evaluate to
<literal>USAGE</literal>.
@@ -11957,7 +11972,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<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>.
The desired access privilege type must evaluate to
<literal>USAGE</literal>.
@@ -11965,7 +11981,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<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>.
The desired access privilege type must evaluate to some combination of
<literal>CREATE</literal> or
@@ -11974,7 +11991,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<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>.
The desired access privilege type must evaluate to
<literal>USAGE</literal>.
@@ -11982,7 +12000,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<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>.
The desired access privilege type must evaluate to
<literal>CREATE</literal>.
@@ -11990,7 +12009,8 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
<para>
<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>.
The desired access privilege type must evaluate to some combination of
<literal>MEMBER</literal> or
@@ -12305,7 +12325,7 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
<entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</> command for trigger</entry>
</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>get role name with given OID</entry>
</row>
@@ -12559,7 +12579,7 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
<para>
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
between two snapshots.
</para>
@@ -12641,8 +12661,8 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
<row>
<entry><type>xmax</type></entry>
<entry>
- First as-yet-unassigned txid. All txids later than this are
- not yet started as of the time of the snapshot, and thus invisible.
+ First as-yet-unassigned txid. All txids greater than or equal to this
+ are not yet started as of the time of the snapshot, and thus invisible.
</entry>
</row>
@@ -12652,7 +12672,7 @@ SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
Active txids at the time of the snapshot. The list
includes only those active txids between <literal>xmin</>
and <literal>xmax</>; there might be active txids higher
- than xmax. A txid that is <literal>xmin <= txid <
+ than <literal>xmax</>. A txid that is <literal>xmin <= txid <
xmax</literal> and not in this list was already completed
at the time of the snapshot, and thus either visible or
dead according to its commit status. The list does not
@@ -12834,9 +12854,9 @@ SELECT set_config('log_statement_stats', 'off', false);
The process ID of an active backend can be found from
the <structfield>procpid</structfield> column of 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
- Manager</> on <productname>Windows</>.
+ Manager</> on <productname>Windows</>).
</para>
<para>
@@ -12904,7 +12924,7 @@ SELECT set_config('log_statement_stats', 'off', false);
<literal><function>pg_stop_backup</function>()</literal>
</entry>
<entry><type>text</type></entry>
- <entry>Finalize after performing on-line backup</entry>
+ <entry>Finish performing on-line backup</entry>
</row>
<row>
<entry>
@@ -12991,7 +13011,7 @@ postgres=# select pg_start_backup('label_goes_here');
<para>
<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
insertion point. The insertion point is the <quote>logical</> end
of the transaction log
@@ -13086,9 +13106,9 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
</entry>
<entry><type>bigint</type></entry>
<entry>
- Disk space used by the specified fork, <literal>'main'</literal> or
- <literal>'fsm'</literal>, of a table or index with the specified OID
- or name; the table name can be schema-qualified.
+ Disk space used by the specified fork (<literal>'main'</literal>,
+ <literal>'fsm'</literal> or <literal>'vm'</>)
+ of the table or index with the specified OID or name
</entry>
</row>
<row>
@@ -13128,8 +13148,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
<entry><type>bigint</type></entry>
<entry>
Total disk space used by the table with the specified OID or name,
- including indexes and <acronym>TOAST</> data; the table name can be
- schema-qualified.
+ including indexes and <acronym>TOAST</> data
</entry>
</row>
</tbody>
@@ -13154,6 +13173,8 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
size of the main data fork of the relation. Specifying
<literal>'fsm'</literal> returns the size of 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.
</para>
@@ -13240,7 +13261,7 @@ postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
size, last accessed time stamp, last modified time stamp,
last file status change time stamp (Unix platforms only),
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>
SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;
@@ -13425,8 +13446,8 @@ SELECT (pg_stat_file('filename')).modification;
</indexterm>
<para>
<function>pg_advisory_unlock_shared</> works the same as
- <function>pg_advisory_unlock</>,
- except is releases a shared advisory lock.
+ <function>pg_advisory_unlock</>,
+ except it releases a shared advisory lock.
</para>
<indexterm>
@@ -13435,7 +13456,7 @@ SELECT (pg_stat_file('filename')).modification;
<para>
<function>pg_advisory_unlock_all</> will release all advisory locks
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>
</sect1>
diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index e40724df177aa62afb1b5c066aaba18f61928c3a..974e1415f658733349a74f333766108f0f628356 100644
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title id="indexes-title">Indexes</title>
@@ -36,7 +36,7 @@ SELECT content FROM test1 WHERE id = <replaceable>constant</replaceable>;
matching entries. If there are many rows in
<structname>test1</structname> and only a few rows (perhaps zero
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
efficient method for locating matching rows. For instance, it
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);
<para>
Once an index is created, no further intervention is required: the
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
<command>ANALYZE</command> command regularly to update
statistics to allow the query planner to make educated decisions.
@@ -294,7 +294,7 @@ CREATE TABLE test2 (
<programlisting>
SELECT name FROM test2 WHERE major = <replaceable>constant</replaceable> AND minor = <replaceable>constant</replaceable>;
</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>minor</structfield> together, e.g.:
<programlisting>
@@ -384,16 +384,16 @@ CREATE INDEX test2_mm_idx ON test2 (major, minor);
<para>
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
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
- 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
special case is <literal>ORDER BY</> in combination with
<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</>
rows can be retrieved directly, without scanning the remainder at all.
</para>
@@ -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.
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
- 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)</>.
</para>
<para>
Obviously, indexes with non-default sort orderings are a fairly
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
sort ordering.
</para>
@@ -584,9 +584,9 @@ CREATE UNIQUE INDEX <replaceable>name</replaceable> ON <replaceable>table</repla
</indexterm>
<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
- 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.
</para>
@@ -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
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
- index. A partial index reduces the size of the index, which speeds
- up queries that use the index. It will also speed up many table
+ index at all. This reduces the size of the index, which will speed
+ 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
updated in all cases. <xref linkend="indexes-partial-ex1"> shows a
possible application of this idea.
@@ -701,7 +701,7 @@ CREATE TABLE access_log (
such as this:
<programlisting>
CREATE INDEX access_log_client_ip_ix ON access_log (client_ip)
-WHERE NOT (client_ip > inet '192.168.100.0' AND
+WHERE NOT (client_ip > inet '192.168.100.0' AND
client_ip < inet '192.168.100.255');
</programlisting>
</para>
@@ -724,14 +724,14 @@ WHERE client_ip = inet '192.168.100.23';
<para>
Observe that this kind of partial index requires that the common
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
- maintenance overhead.
+ maintenance effort.
</para>
</example>
<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
typical query workload is not interested in; this is shown in <xref
linkend="indexes-partial-ex2">. This results in the same
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index c214374fcab32162e6afdc5514b1e8a67ef17fbf..f6f5166adac54f73047e645795d40922aab62a0a 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -85,7 +85,7 @@ su - postgres
<listitem>
<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
versions of <productname>GCC</> are recommendable, but
<productname>PostgreSQL</> is known to build using a wide variety
@@ -118,7 +118,7 @@ su - postgres
command you type, and allows you to use arrow keys to recall and
edit previous commands. This is very helpful and is strongly
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
BSD-licensed <filename>libedit</filename> library, originally
developed on <productname>NetBSD</productname>. The
@@ -422,11 +422,10 @@ su - postgres
On systems that have <productname>PostgreSQL</> started at boot time,
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
- might find that:
+ might find that this works:
<screen>
<userinput>/etc/rc.d/init.d/postgresql stop</userinput>
</screen>
- works.
</para>
</step>
@@ -471,7 +470,7 @@ su - postgres
<step>
<para>
- Start the database server, again the special database user
+ Start the database server, again using the special database user
account:
<programlisting>
<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
@@ -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
distributed, use <command>gmake distclean</>. If you are going to
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
remains unmodified.)
</para>
@@ -1675,7 +1674,7 @@ All of PostgreSQL is successfully made. Ready to install.
</indexterm>
<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
shared libraries. The systems on which this is
<emphasis>not</emphasis> necessary include <systemitem
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index ae36d078324583c5668a2be8e45fd75ef878820f..f5dce009fff35e18641a832912415bd6c0c3409d 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Monitoring Database Activity</title>
@@ -929,7 +929,7 @@ postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <re
<function>read()</> calls issued for the table, index, or
database; the number of actual physical reads is usually
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>
</note>
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index 4637f0ae28e489352dcd8f4ee03cd4a7f153f78e..4213216cc47dbd0f6e203aa02ac2c2c06753056f 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Concurrency Control</title>
@@ -246,7 +246,7 @@
committed before the query began; it never sees either uncommitted
data or changes committed during query execution by concurrent
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
of previous updates executed within its own transaction, even
though they are not yet committed. Also note that two successive
@@ -260,7 +260,7 @@
FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands
behave the same as <command>SELECT</command>
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
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
@@ -367,16 +367,17 @@ COMMIT;
transaction began; it never sees either uncommitted data or changes
committed
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
committed.) This is different from Read Committed in that
- <command>SELECT</command> in a serializable transaction
- sees a snapshot as of the start of the <emphasis>transaction</>, not as of the start
+ a query in a serializable transaction
+ 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
<command>SELECT</command> commands within a <emphasis>single</>
- transaction see the same data, i.e. they never see changes made by
- transactions that committed after its own transaction started. (This
- behavior can be ideal for reporting applications.)
+ transaction see the same data, i.e., they do not see changes made by
+ other transactions that committed after their own transaction started.
+ (This behavior can be ideal for reporting applications.)
</para>
<para>
@@ -384,7 +385,7 @@ COMMIT;
FOR UPDATE</command>, and <command>SELECT FOR SHARE</command> commands
behave the same as <command>SELECT</command>
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
row might have already been updated (or deleted or locked) by
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;
</term>
<listitem>
<para>
- Conflicts all lock modes except <literal>ACCESS SHARE</literal>,
- <literal>ROW SHARE</literal>, and <literal>SHARE</literal> (it
- does not conflict with itself).
+ Conflicts with the <literal>ROW EXCLUSIVE</literal>,
+ <literal>SHARE UPDATE EXCLUSIVE</literal>, <literal>SHARE ROW
+ EXCLUSIVE</literal>, <literal>EXCLUSIVE</literal>, and
+ <literal>ACCESS EXCLUSIVE</literal> lock modes.
This mode protects a table against concurrent data changes.
</para>
@@ -685,8 +687,11 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term>
<listitem>
<para>
- Conflicts all lock modes except <literal>ACCESS SHARE</literal>
- and <literal>ROW SHARE</literal>.
+ Conflicts with the <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.
</para>
<para>
@@ -702,7 +707,11 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term>
<listitem>
<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,
i.e., only reads from the table can proceed in parallel with a
transaction holding this lock mode.
@@ -711,7 +720,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
<para>
This lock mode is not automatically acquired on user tables by any
<productname>PostgreSQL</productname> command. However it is
- acquired during certain internal system catalogs operations.
+ acquired on certain system catalogs in some operations.
</para>
</listitem>
</varlistentry>
@@ -722,7 +731,12 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
</term>
<listitem>
<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
holder is the only transaction accessing the table in any way.
</para>
@@ -749,7 +763,7 @@ SELECT SUM(value) FROM mytab WHERE class = 2;
<para>
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
- 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
commands since the savepoint. The same holds for locks acquired within a
<application>PL/pgSQL</> exception block: an error escape from the block
@@ -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
specific row is automatically acquired when the row is updated or
deleted. The lock is held until the transaction commits or rolls
- back, like table-level locks. Row-level locks do
- not affect data querying; they only block <emphasis>writers to the same
+ back, just like table-level locks. Row-level locks do
+ not affect data querying; they block only <emphasis>writers to the same
row</emphasis>.
</para>
@@ -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
pool. These locks are released immediately after a row is fetched or
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>
</sect2>
@@ -1100,7 +1114,7 @@ SELECT pg_advisory_lock(q.id) FROM
after the current query began). The row might have been modified or
deleted by an already-committed transaction that committed after
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
before the current transaction does a commit or rollback.
</para>
@@ -1121,7 +1135,7 @@ SELECT pg_advisory_lock(q.id) FROM
concurrent updates one must use <command>SELECT FOR UPDATE</command>,
<command>SELECT FOR SHARE</command>, or an appropriate <command>LOCK
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
TABLE</command> locks the whole table.) This should be taken into
account when porting applications to
@@ -1151,9 +1165,9 @@ SELECT pg_advisory_lock(q.id) FROM
</para>
<para>
- Note also that if one is
- relying on explicit locking to prevent concurrent changes, one should use
- either Read Committed mode, or in Serializable mode be careful to obtain
+ Note also that if one is relying on explicit locking to prevent concurrent
+ changes, one should either use Read Committed mode, or in Serializable
+ mode be careful to obtain
locks before performing queries. A lock obtained by a
serializable transaction guarantees that no other transactions modifying
the table are still running, but if the snapshot seen by the
@@ -1162,7 +1176,7 @@ SELECT pg_advisory_lock(q.id) FROM
frozen at the start of its first query or data-modification command
(<literal>SELECT</>, <literal>INSERT</>,
<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.
</para>
</sect1>
@@ -1178,7 +1192,7 @@ SELECT pg_advisory_lock(q.id) FROM
<para>
Though <productname>PostgreSQL</productname>
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
in <productname>PostgreSQL</productname>.
The various index types are handled as follows:
@@ -1221,8 +1235,8 @@ SELECT pg_advisory_lock(q.id) FROM
<para>
Short-term share/exclusive page-level locks are used for
read/write access. Locks are released immediately after each
- index row is fetched or inserted. But note insertion of a GIN-indexed
- value usually produces several index key insertions
+ index row is fetched or inserted. But note that insertion of a
+ GIN-indexed value usually produces several index key insertions
per row, so GIN might do substantial work for a single value's
insertion.
</para>
diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 8744a5cb315a5141cf27d0ec9d1487d852bbf1de..1a631d3d91f2cc0de5962206227fb00992f30bb3 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Performance Tips</title>
@@ -45,8 +45,9 @@
table access methods: sequential scans, index scans, and bitmap index
scans. If the query requires joining, aggregation, sorting, or other
operations on the raw rows, then there will be additional nodes
- above the scan nodes to perform these operations. Other nodes types
- are also supported. The output
+ above the scan nodes to perform these operations. Again,
+ 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
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)
@@ -83,24 +84,24 @@ EXPLAIN SELECT * FROM tenk1;
<itemizedlist>
<listitem>
<para>
- Estimated start-up cost, e.g., time expended before the output scan can start,
- time to do the sorting in a sort node
+ Estimated start-up cost (time expended before the output scan can start,
+ e.g., time to do the sorting in a sort node)
</para>
</listitem>
<listitem>
<para>
- Estimated total cost if all rows were to be retrieved (though they might
- 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
+ Estimated total cost (if all rows are retrieved, though they might
+ not be; e.g., a query with a <literal>LIMIT</> clause will stop
+ short of paying the total cost of the <literal>Limit</> plan node's
input node)
</para>
</listitem>
<listitem>
<para>
- Estimated number of rows output by this plan node (Again, only if
- executed to completion.)
+ Estimated number of rows output by this plan node (again, only if
+ executed to completion)
</para>
</listitem>
@@ -129,18 +130,18 @@ EXPLAIN SELECT * FROM tenk1;
the cost only reflects things that the planner cares about.
In particular, the cost does not consider the time spent transmitting
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
output the same row set, we trust.)
</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
number of rows processed or scanned by the plan node. It is usually less,
reflecting the estimated selectivity of any <literal>WHERE</>-clause
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
by the query.
</para>
@@ -197,7 +198,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 7000;
</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,
you will probably get a slightly different estimate; moreover, it will
change after each <command>ANALYZE</command> command, because the
@@ -234,7 +235,7 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 100;
<para>
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>
EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 3;
@@ -248,8 +249,8 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 3;
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
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
- with an <literal>ORDER BY</> condition that matches the index
+ this plan type for queries that fetch just a single row, and for queries
+ that have an <literal>ORDER BY</> condition that matches the index
order.
</para>
@@ -320,7 +321,7 @@ WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2;
</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
applying the <literal>WHERE</> clause <literal>unique1 < 100</literal>
at that node.
@@ -409,7 +410,7 @@ WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2;
</screen>
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.
The thing to pay attention to is whether the ratios of actual time and
estimated costs are consistent.
@@ -419,11 +420,11 @@ WHERE t1.unique1 < 100 AND t1.unique2 = t2.unique2;
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
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
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
- 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.
</para>
@@ -780,7 +781,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
</indexterm>
<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
SQL, this means issuing <command>BEGIN</command> at the start and
<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;
<para>
Note that loading a large number of rows 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.
</para>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 296ad5bb947e303bde903de99ad16996c34fee25..19c76b8ec74199b6a3440cc434aafbc5d457d9c6 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,4 +1,4 @@
-<!-- $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" [
@@ -134,7 +134,7 @@
The first few chapters are written so they can be understood
without prerequisite knowledge, so new users who need to set
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
the <productname>PostgreSQL</> database system. Readers are
encouraged to look at <xref linkend="tutorial"> and <xref
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index 2fc3b92f8de10e91b745c059d8be758e87362aba..21a3a8d1a6c1061586f54c2bac8eca0be425ddbf 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Queries</title>
@@ -133,8 +133,8 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para>
When a table reference names a table that is the parent of a
- table inheritance hierarchy, the table reference produces rows
- not only of that table but all of its descendant tables, unless the
+ table inheritance hierarchy, the table reference produces rows of
+ not only that table but all of its descendant tables, unless the
key word <literal>ONLY</> precedes the table name. However, the
reference produces only the columns that appear in the named table
— any columns added in subtables are ignored.
@@ -174,12 +174,12 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
</synopsis>
<para>
- Produce every possible combination of rows from
+ For every possible combination of rows from
<replaceable>T1</replaceable> and
<replaceable>T2</replaceable> (i.e., a Cartesian product),
- with output columns consisting of
- all <replaceable>T1</replaceable> columns
- followed by all <replaceable>T2</replaceable> columns. If
+ the joined table will contain a
+ row consisting of all columns in <replaceable>T1</replaceable>
+ followed by all columns in <replaceable>T2</replaceable>. If
the tables have N and M rows respectively, the joined
table will have N * M rows.
</para>
@@ -245,7 +245,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
equality of each of these pairs of columns. Furthermore, the
output of <literal>JOIN USING</> has one column for each of
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
t1.b = t2.b AND t1.c = t2.c)</literal> with the exception that
if <literal>ON</> is used there will be two columns
@@ -300,7 +300,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para>
First, an inner join is performed. Then, for each 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
one row for each row in T1.
</para>
@@ -323,7 +323,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para>
First, an inner join is performed. Then, for each 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
will always have a row for each row in T2.
</para>
@@ -337,9 +337,9 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para>
First, an inner join is performed. Then, for each 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
- 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.
</para>
</listitem>
@@ -575,7 +575,7 @@ FROM <replaceable>table_reference</replaceable> <optional>AS</optional> <replace
<para>
When an alias is applied to the output of a <literal>JOIN</>
clause, the alias hides the original
- name referenced in the <literal>JOIN</>. For example:
+ name(s) within the <literal>JOIN</>. For example:
<programlisting>
SELECT a.* FROM my_table AS a JOIN your_table AS b ON ...
</programlisting>
@@ -686,8 +686,7 @@ SELECT * FROM vw_getfoo;
In some cases it is useful to define table functions that can
return different column sets depending on how they are invoked.
To support this, the table function can be declared as returning
- the pseudotype <type>record</>, rather than <literal>SET OF</>.
- When such a function is used in
+ the pseudotype <type>record</>. When such a function is used in
a query, the expected row structure must be specified in the
query itself, so that the system can know how to parse and plan
the query. Consider this example:
@@ -757,11 +756,11 @@ FROM a NATURAL JOIN b WHERE b.val > 5
probably not as portable to other SQL database management systems,
even though it is in the SQL standard. For
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
- <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
- from the final result.
+ in the final result.
</para>
</note>
@@ -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 > fdt.c1)
</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
condition of the <literal>WHERE</> clause are eliminated from
<literal>fdt</literal>. Notice the use of scalar subqueries as
@@ -860,7 +859,7 @@ SELECT <replaceable>select_list</replaceable>
<para>
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:
<screen>
<prompt>=></> <userinput>SELECT x, sum(y) FROM test1 GROUP BY x;</>
@@ -880,7 +879,7 @@ SELECT <replaceable>select_list</replaceable>
<tip>
<para>
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
linkend="queries-distinct">).
</para>
@@ -1088,7 +1087,7 @@ SELECT tbl1.*, tbl2.a FROM ...
the row's values substituted for any column references. But the
expressions in the select list do not have to reference any
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>
</sect2>
@@ -1101,8 +1100,8 @@ SELECT tbl1.*, tbl2.a FROM ...
</indexterm>
<para>
- The entries in the select list can be assigned names for further
- processing, perhaps for reference in an <literal>ORDER BY</> clause
+ The entries in the select list can be assigned names for subsequent
+ processing, such as for use in an <literal>ORDER BY</> clause
or for display by the client application. For example:
<programlisting>
SELECT a AS 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 <literal>FROM</> clause (see <xref
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.
</para>
</note>
@@ -1346,9 +1345,9 @@ SELECT a, b FROM table1 ORDER BY a + b, c;
<para>
The <literal>NULLS FIRST</> and <literal>NULLS LAST</> options can be
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
- if larger than all non-null values (<literal>NULLS FIRST</>), except
- in <literal>DESC</> ordering, where <literal>NULLS LAST</> is the default.
+ in the sort ordering. By default, null values sort as if larger than any
+ non-null value; that is, <literal>NULLS FIRST</> is the default for
+ <literal>DESC</> order, and <literal>NULLS LAST</> otherwise.
</para>
<para>
@@ -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;
</programlisting>
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
— for example, this is <emphasis>not</> correct:
<programlisting>
SELECT a + b AS sum, c FROM table1 ORDER BY sum + c; -- wrong
@@ -1429,10 +1428,10 @@ SELECT <replaceable>select_list</replaceable>
<para>
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
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</>.
</para>
@@ -1472,7 +1471,7 @@ SELECT <replaceable>select_list</replaceable>
<synopsis>
VALUES ( <replaceable class="PARAMETER">expression</replaceable> [, ...] ) [, ...]
</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
of columns in the table), and corresponding entries in each list must
have compatible data types. The actual data type assigned to each column
diff --git a/doc/src/sgml/query.sgml b/doc/src/sgml/query.sgml
index c81c321134b8523f9cdb7212bb7402e9c31033f5..49a1221ea0f58891c432507073b7d73f2b87416f 100644
--- a/doc/src/sgml/query.sgml
+++ b/doc/src/sgml/query.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>The <acronym>SQL</acronym> Language</title>
@@ -53,7 +53,7 @@
</screen>
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
server. The commands used in this section are in the file
<filename>basics.sql</filename>.
@@ -150,7 +150,7 @@ CREATE TABLE weather (
<type>int</type> is the normal integer type. <type>real</type> is
a type for storing single precision floating-point numbers.
<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 — you choose.)
</para>
@@ -165,7 +165,7 @@ CREATE TABLE weather (
and a rich set of geometric types.
<productname>PostgreSQL</productname> can be customized with an
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.
</para>
@@ -291,7 +291,7 @@ COPY weather FROM '/home/user/weather.txt';
tables from which to retrieve the data), and an optional
qualification (the part that specifies any restrictions). For
example, to retrieve all the rows of table
- <classname>weather</classname>, type:
+ <structname>weather</structname>, type:
<programlisting>
SELECT * FROM weather;
</programlisting>
@@ -450,9 +450,10 @@ SELECT DISTINCT city
of the same or different tables at one time is called a
<firstterm>join</firstterm> query. As an example, say you wish to
list all the weather records together with the location of the
- associated city. To do that, we need to compare the city column of
- each row of the <literal>weather</> table with the name column of all rows in
- the <literal>cities</> table, and select the pairs of rows where these values match.
+ associated city. To do that, we need to compare the <structfield>city</>
+ column of each row of the <structname>weather</> table with the
+ <structfield>name</> column of all rows in the <structname>cities</>
+ table, and select the pairs of rows where these values match.
<note>
<para>
This is only a conceptual model. The join is usually performed
@@ -485,8 +486,8 @@ SELECT *
<para>
There is no result row for the city of Hayward. This is
because there is no matching entry in the
- <classname>cities</classname> table for Hayward, so the join
- ignores the unmatched rows in the <literal>weather</> table. We will see
+ <structname>cities</structname> table for Hayward, so the join
+ ignores the unmatched rows in the <structname>weather</> table. We will see
shortly how this can be fixed.
</para>
</listitem>
@@ -494,9 +495,9 @@ SELECT *
<listitem>
<para>
There are two columns containing the city name. This is
- correct because the columns from the
- <classname>weather</classname> and the
- <classname>cities</classname> tables are concatenated. In
+ correct because the lists of columns from the
+ <structname>weather</structname> and
+ <structname>cities</structname> tables are concatenated. In
practice this is undesirable, though, so you will probably want
to list the output columns explicitly rather than using
<literal>*</literal>:
@@ -556,10 +557,10 @@ SELECT *
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
- <classname>weather</classname> table and for each row to find the
- matching <classname>cities</classname> row(s). If no matching row is
+ <structname>weather</structname> table and for each row to find the
+ matching <structname>cities</structname> row(s). If no matching row is
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
joins we have seen so far are inner joins.) The command looks
like this:
@@ -603,10 +604,10 @@ SELECT *
to find all the weather records that are in the temperature range
of other weather records. So we need to compare the
<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_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:
<programlisting>
@@ -756,7 +757,7 @@ SELECT city, max(temp_lo)
</screen>
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
names begin with <quote><literal>S</literal></quote>, we might do:
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index d699c39f4aaae38f8b5da201226c2d8d27e8d2a0..a95f4c583dddf1eaaefbaf030092a98d0a86138d 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Composite Types</title>
@@ -41,7 +41,7 @@ CREATE TYPE inventory_item AS (
NULL</>) can presently be included. Note that the <literal>AS</> keyword
is essential; without it, the system will think a different kind
of <command>CREATE TYPE</> command is meant, and you will get odd syntax
- error.
+ errors.
</para>
<para>
@@ -68,8 +68,8 @@ SELECT price_extension(item, 10) FROM on_hand;
</para>
<para>
- Whenever you create a table, a composite type is automatically
- created also, with the same name as the table, to represent the table's
+ Whenever you create a table, a composite type is also automatically
+ created, with the same name as the table, to represent the table's
row type. For example, had we said:
<programlisting>
CREATE TABLE inventory_item (
@@ -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
are interpreted according to the I/O conversion rules for the individual
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
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
@@ -264,7 +264,7 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
</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.
You <emphasis>must</> do so if the field value would otherwise
confuse the composite-value parser. In particular, fields containing
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 11bd7895d1e482bf10eae1bb093af026a079dc73..863011a9dddde2451c63b51b5e9d2bf203787058 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Getting Started</title>
@@ -74,7 +74,7 @@
<para>
A server process, which manages the database files, accepts
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
<filename>postgres</filename>.
<indexterm><primary>postgres</primary></indexterm>
@@ -164,8 +164,8 @@
createdb: command not found
</screen>
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
- calling the command with an absolute path instead:
+ installed at all or your shell's search path was not set to include it.
+ Try calling the command with an absolute path instead:
<screen>
<prompt>$</prompt> <userinput>/usr/local/pgsql/bin/createdb mydb</userinput>
</screen>
@@ -177,8 +177,7 @@ createdb: command not found
<para>
Another response could be this:
<screen>
-createdb: could not connect to database postgres: could not connect
-to server: No such file or directory
+createdb: could not connect to database postgres: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5432"?
</screen>
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 8e4df1bdfff9a29bca6a4a9582eb55a82106ed28..ee7f814ea89434a0a2e95862cf048c3a30a22733 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
@@ -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
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
-visibility map fork, with the suffix <literal>_vm</>, to track which pages are
-known to have no dead tuples and therefore need no vacuuming.
+<firstterm>visibility map</>, stored in a fork with the suffix
+<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>
<caution>
@@ -417,6 +418,38 @@ information stored in free space maps (see <xref linkend="pgfreespacemap">).
</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">
<title>Database Page Layout</title>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index cf929f0b72e86004c803ec9f9406c2466ae4be15..bc562e1f97be8f294a9843cf369171d11e6b556b 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>SQL Syntax</title>
@@ -442,7 +442,7 @@ SELECT 'foo' 'bar';
</caution>
<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>
</sect3>
@@ -929,8 +929,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
</para>
<para>
- Comment are removed from the input stream before further syntax
- analysis and are effectively replaced by whitespace.
+ A comment is removed from the input stream before further syntax
+ analysis and is effectively replaced by whitespace.
</para>
</sect2>
@@ -1244,9 +1244,9 @@ SELECT 3 OPERATOR(pg_catalog.+) 4;
<listitem>
<para>
- Another value expression in parentheses, useful to group
+ Another value expression in parentheses (used to group
subexpressions and override
- precedence.<indexterm><primary>parenthesis</></>
+ precedence<indexterm><primary>parenthesis</></>)
</para>
</listitem>
</itemizedlist>
@@ -1725,7 +1725,7 @@ CAST ( <replaceable>expression</replaceable> AS <replaceable>type</replaceable>
casts that are marked <quote>OK to apply implicitly</>
in the system catalogs. Other casts must be invoked with
explicit casting syntax. This restriction is intended to prevent
- surprising conversions from being silently applied.
+ surprising conversions from being applied silently.
</para>
<para>
@@ -1805,7 +1805,7 @@ SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name)
<para>
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
consists of the key word <literal>ARRAY</literal>, a left square bracket
<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%');
</indexterm>
<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
for its member fields. A row constructor consists of the key word
<literal>ROW</literal>, a left parenthesis, zero or more
diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml
index d3e7a148ea5ef1623b02f7132b5859dcca941eef..547c0153ac8be831491f799155702f55d7c4f400 100644
--- a/doc/src/sgml/textsearch.sgml
+++ b/doc/src/sgml/textsearch.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title id="textsearch-title">Full Text Search</title>
@@ -389,7 +389,7 @@ text @@ text
<para>
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
of add-on parsers and templates in the <filename>contrib/</> area of the
<productname>PostgreSQL</> distribution.) Since dictionaries and
@@ -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
would be useful, for example, if the document collection contained
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 & b'</>.
</para>
@@ -860,7 +860,8 @@ SELECT plainto_tsquery('english', 'The Fat & Rats:C');
<term>
<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>
</term>
@@ -1042,7 +1043,7 @@ LIMIT 10;
Ranking can be expensive since it requires consulting the
<type>tsvector</type> of each matching document, which can be I/O bound and
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>
</sect2>
@@ -1068,7 +1069,7 @@ LIMIT 10;
<para>
<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
configuration to be used to parse the document can be specified by
<replaceable>config</replaceable>; if <replaceable>config</replaceable>
@@ -1085,8 +1086,8 @@ LIMIT 10;
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
- <literal>StartSel</>, <literal>StopSel</literal>: the strings to delimit
- query words appearing in the document, to distinguish
+ <literal>StartSel</>, <literal>StopSel</literal>: the strings with
+ which to delimit query words appearing in the document, to distinguish
them from other excerpted words. You must double-quote these strings
if they contain spaces or commas.
</para>
@@ -1188,7 +1189,7 @@ SELECT id, ts_headline(body, q), rank
FROM (SELECT id, body, q, ts_rank_cd(ti, q) AS rank
FROM apod, to_tsquery('stars') q
WHERE ti @@ q
- ORDER BY rank DESC
+ ORDER BY rank DESC
LIMIT 10) AS foo;
</programlisting>
</para>
@@ -1678,9 +1679,9 @@ SELECT title, body FROM messages WHERE tsv @@ to_tsquery('title & body');
</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 — for
- example, to weigh title differently from body — it is necessary
+ example, to weight title differently from body — it is necessary
to write a custom trigger. Here is an example using
<application>PL/pgSQL</application> as the trigger language:
@@ -1722,8 +1723,8 @@ ON messages FOR EACH ROW EXECUTE PROCEDURE messages_trigger();
</para>
<synopsis>
- ts_stat(<replaceable class="PARAMETER">sqlquery</replaceable> <type>text</>, <optional> <replaceable class="PARAMETER">weights</replaceable> <type>text</>,
- </optional> OUT <replaceable class="PARAMETER">word</replaceable> <type>text</>, OUT <replaceable class="PARAMETER">ndoc</replaceable> <type>integer</>,
+ ts_stat(<replaceable class="PARAMETER">sqlquery</replaceable> <type>text</>, <optional> <replaceable class="PARAMETER">weights</replaceable> <type>text</>, </optional>
+ 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</>
</synopsis>
@@ -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,
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
- discarded and not indexed or searched.
+ discarded and not indexed or searched for.
The general rule for configuring a list of dictionaries
is to place first the most narrow, most specific dictionary, then the more
general dictionaries, finishing with a very general dictionary, like
@@ -2439,7 +2440,7 @@ CREATE TEXT SEARCH DICTIONARY thesaurus_simple (
<programlisting>
ALTER TEXT SEARCH CONFIGURATION russian
- ALTER MAPPING FOR asciiword, asciihword, hword_asciipart
+ ALTER MAPPING FOR asciiword, asciihword, hword_asciipart
WITH thesaurus_simple;
</programlisting>
</para>
@@ -2679,9 +2680,9 @@ CREATE TEXT SEARCH DICTIONARY english_stem (
</para>
<para>
- As an example, we will create a configuration
- <literal>pg</literal> by duplicating the built-in
- <literal>english</> configuration.
+ As an example we will create a configuration
+ <literal>pg</literal>, starting by duplicating the built-in
+ <literal>english</> configuration:
<programlisting>
CREATE TEXT SEARCH CONFIGURATION public.pg ( COPY = pg_catalog.english );
@@ -3137,7 +3138,7 @@ SELECT plainto_tsquery('supernovae stars');
</indexterm>
<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.
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
@@ -3204,7 +3205,7 @@ SELECT plainto_tsquery('supernovae stars');
to check the actual table row to eliminate such false matches.
(<productname>PostgreSQL</productname> does this automatically when needed.)
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
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
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index beb74f9a57ebe6d7d2b6654c356028fce194436d..a1b04ce417f03008fe6dedbf6bc0e5b2d99506c4 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -1,4 +1,4 @@
-<!-- $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">
<title>Type Conversion</title>
@@ -161,7 +161,7 @@ categories</firstterm>, including <type>boolean</type>, <type>numeric</type>,
user-defined. (For a list see <xref linkend="catalog-typcategory-table">;
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
-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
ambiguous expressions (those with multiple candidate parsing solutions) can be
resolved in a useful way.
@@ -189,7 +189,7 @@ calls in the query.
<para>
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
-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>
</listitem>
</itemizedlist>
@@ -206,10 +206,12 @@ should use this new function and no longer do implicit conversion using the old
</indexterm>
<para>
- The specific operator invoked is determined by the following
- steps. Note that this procedure is affected
- by the precedence of the involved operators. See <xref
- linkend="sql-precedence"> for more information.
+ The specific operator that is referenced by an operator expression
+ is determined using the following procedure.
+ Note that this procedure is indirectly affected
+ 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>
<procedure>
@@ -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
<classname>pg_operator</classname> system catalog. If a non-schema-qualified
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">).
If a qualified operator name was given, only operators in the specified
schema are considered.
@@ -250,8 +252,8 @@ operators considered), use it.
<para>
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.
-Cases involving two <type>unknown</type> types will never find a match at
-this step.
+Invocations involving two <type>unknown</type> inputs, or a unary operator
+with an <type>unknown</type> input, will never find a match at this step.
</para>
</step>
</substeps>
@@ -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
and finds that there are candidates accepting both string-category and
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
-type to resolve the unknown literals.
+type to resolve the unknown literals as.
</para>
</example>
@@ -459,8 +461,8 @@ SELECT ~ CAST('20' AS int8) AS "negation";
</indexterm>
<para>
- The specific function to be invoked is determined
- according to the following steps.
+ The specific function that is referenced by a function call
+ is determined using the following procedure.
</para>
<procedure>
@@ -471,7 +473,7 @@ SELECT ~ CAST('20' AS int8) AS "negation";
Select the functions to be considered from the
<classname>pg_proc</classname> system catalog. If a non-schema-qualified
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">).
If a qualified function name was given, only functions in the specified
schema are considered.
@@ -554,7 +556,7 @@ Look for the best match.
<substeps>
<step performance="required">
<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.
<type>unknown</type> literals are
assumed to be convertible to anything for this purpose. If only one
@@ -615,9 +617,10 @@ Some examples follow.
<title>Rounding Function Argument Type Resolution</title>
<para>
-There is only one <function>round</function> function which takes two
-arguments; it takes a first argument of <type>numeric</type> and
-a second argument of <type>integer</type>. So the following query automatically converts
+There is only one <function>round</function> function that takes two
+arguments; it takes a first argument of type <type>numeric</type> and
+a second argument of type <type>integer</type>.
+So the following query automatically converts
the first argument of type <type>integer</type> to
<type>numeric</type>: