Skip to content

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

Proofreading for Bruce's recent round of documentation proofreading. 

Most of those changes were good, but some not so good ...
parent e8d78d35
Hide whitespace changes
Inline Side-by-side
Showing with 514 additions and 440 deletions
doc/src/sgml/advanced.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.58 2009/04/27 16:27:35 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/advanced.sgml,v 1.59 2009/06/17 21:58:48 tgl Exp $ -->
<chapter id="tutorial-advanced">
<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.
......
doc/src/sgml/array.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.69 2009/04/27 16:27:35 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.70 2009/06/17 21:58:48 tgl Exp $ -->
<sect1 id="arrays">
<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] &lt;&gt; pay_by_quarter[2];
......@@ -230,7 +229,7 @@ SELECT name FROM sal_emp WHERE pay_by_quarter[1] &lt;&gt; 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
......
doc/src/sgml/config.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.219 2009/06/03 20:34:29 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.220 2009/06/17 21:58:48 tgl Exp $ -->
<chapter Id="runtime-config">
<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>
......
doc/src/sgml/datatype.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.238 2009/06/10 20:25:41 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.239 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="datatype">
<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>&amp;</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
......
doc/src/sgml/ddl.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.86 2009/04/27 16:27:35 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.87 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="ddl">
<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 &gt;= DATE '2006-02-01' AND
IF ( NEW.logdate &gt;= DATE '2006-02-01' AND
NEW.logdate &lt; DATE '2006-03-01' ) THEN
INSERT INTO measurement_y2006m02 VALUES (NEW.*);
ELSIF ( NEW.logdate &gt;= DATE '2006-03-01' AND
ELSIF ( NEW.logdate &gt;= DATE '2006-03-01' AND
NEW.logdate &lt; DATE '2006-04-01' ) THEN
INSERT INTO measurement_y2006m03 VALUES (NEW.*);
...
ELSIF ( NEW.logdate &gt;= DATE '2008-01-01' AND
ELSIF ( NEW.logdate &gt;= DATE '2008-01-01' AND
NEW.logdate &lt; DATE '2008-02-01' ) THEN
INSERT INTO measurement_y2008m01 VALUES (NEW.*);
ELSE
......@@ -2709,9 +2709,9 @@ SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
Without constraint exclusion, the above query would scan each of
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
......
doc/src/sgml/dml.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.18 2009/04/27 16:27:35 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.19 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="dml">
<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>
doc/src/sgml/docguide.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.75 2009/04/27 16:27:35 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/docguide.sgml,v 1.76 2009/06/17 21:58:49 tgl Exp $ -->
<appendix id="docguide">
<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>
......
doc/src/sgml/func.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.481 2009/05/26 17:36:05 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.482 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="functions">
<title>Functions and Operators</title>
......@@ -268,8 +268,9 @@
<synopsis>
<replaceable>a</replaceable> &gt;= <replaceable>x</replaceable> AND <replaceable>a</replaceable> &lt;= <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 &mdash; but regular expressions use
different special characters than <function>LIKE</function>.
different special characters than <function>LIKE</function> does.
Unlike <function>LIKE</function> patterns, a
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&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'YYYY MON')</literal> works, but
<literal>to_timestamp('2000&nbsp;&nbsp;&nbsp;&nbsp;JUN', 'FXYYYY MON')</literal> returns an error
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., &gt;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 &lt;&gt; 0 THEN y/x &gt; 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 &lt;= txid &lt;
than <literal>xmax</>. A txid that is <literal>xmin &lt;= txid &lt;
xmax</literal> and not in this list was already completed
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>
......
doc/src/sgml/indices.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.77 2009/04/27 16:27:35 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.78 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="indexes">
<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 &gt; inet '192.168.100.0' AND
WHERE NOT (client_ip &gt; inet '192.168.100.0' AND
client_ip &lt; 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
......
doc/src/sgml/installation.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.323 2009/06/12 15:53:32 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.324 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="installation">
<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
......
doc/src/sgml/monitoring.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.69 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.70 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="monitoring">
<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>
......
doc/src/sgml/mvcc.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.71 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.72 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="mvcc">
<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>
......
doc/src/sgml/perform.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.70 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.71 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="performance-tips">
<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 &lt; 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 &lt; 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 &lt; 3;
......@@ -248,8 +249,8 @@ EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 3;
In this case the table rows are fetched in index order, which makes them
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 &lt; 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 &lt; 100</literal>
at that node.
......@@ -409,7 +410,7 @@ WHERE t1.unique1 &lt; 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 &lt; 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>
......
doc/src/sgml/postgres.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.87 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.88 2009/06/17 21:58:49 tgl Exp $ -->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
......@@ -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
......
doc/src/sgml/queries.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.54 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.55 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="queries">
<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
&mdash; 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 &gt; 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 &gt; 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>=&gt;</> <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
&mdash; 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
......
doc/src/sgml/query.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.52 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/query.sgml,v 1.53 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="tutorial-sql">
<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 &mdash; 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:
......
doc/src/sgml/rowtypes.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.10 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.11 2009/06/17 21:58:49 tgl Exp $ -->
<sect1 id="rowtypes">
<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
......
doc/src/sgml/start.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.49 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/start.sgml,v 1.50 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="tutorial-start">
<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>
......
doc/src/sgml/storage.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.28 2009/05/16 22:03:53 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.29 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="storage">
......@@ -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>
......
doc/src/sgml/syntax.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.132 2009/05/05 18:32:17 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.133 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="sql-syntax">
<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
......
doc/src/sgml/textsearch.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/textsearch.sgml,v 1.51 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/textsearch.sgml,v 1.52 2009/06/17 21:58:49 tgl Exp $ -->
<chapter id="textsearch">
<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 &amp; b'</>.
</para>
......@@ -860,7 +860,8 @@ SELECT plainto_tsquery('english', 'The Fat &amp; 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 &amp; 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 &mdash; for
example, to weigh title differently from body &mdash; it is necessary
example, to weight title differently from body &mdash; it is necessary
to write a custom trigger. Here is an example using
<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
......
doc/src/sgml/typeconv.sgml
View file @ c30446b9
<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.59 2009/04/27 16:27:36 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.60 2009/06/17 21:58:49 tgl Exp $ -->
<chapter Id="typeconv">
<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>:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment