mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2025-03-01 19:45:33 +08:00
Code Issues Packages Projects Releases Wiki Activity

More minor updates and copy-editing.

Browse Source
This commit is contained in:
Tom Lane 2004-12-23 23:07:38 +00:00
parent 08457504f0
commit 0add759825
5 changed files with 108 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
doc/src/sgml/func.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.231 2004/12/21 01:02:28 momjian Exp $
$PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.232 2004/12/23 23:07:38 tgl Exp $
PostgreSQL documentation
-->
@ -1347,7 +1347,8 @@ PostgreSQL documentation
<footnote>
<para>
The <function>to_ascii</function> function supports conversion from
<literal>LATIN1</>, <literal>LATIN2</>, and <literal>WIN1250</> only.
<literal>LATIN1</>, <literal>LATIN2</>, <literal>LATIN9</>,
and <literal>WIN1250</> encodings only.
</para>
</footnote>
</entry>
@ -2483,11 +2484,11 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
There are three separate approaches to pattern matching provided
by <productname>PostgreSQL</productname>: the traditional
<acronym>SQL</acronym> <function>LIKE</function> operator, the
more recent <literal>>SIMILAR TO</literal> operator (since
more recent <function>SIMILAR TO</function> operator (added in
SQL:1999), and <acronym>POSIX</acronym>-style regular expressions.
Additionally, a pattern matching function,
<function>substring</function>, is available, using either
<literal>SIMILAR TO</literal>-style or POSIX-style regular
<function>SIMILAR TO</function>-style or POSIX-style regular
expressions.
</para>
@ -2544,7 +2545,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para>
<function>LIKE</function> pattern matches always cover the entire
string. To match a pattern anywhere within a string, the
string. To match a sequence anywhere within a string, the
pattern must therefore start and end with a percent sign.
</para>
@ -2578,7 +2579,7 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para>
The key word <token>ILIKE</token> can be used instead of
<token>LIKE</token> to make the match case insensitive according
<token>LIKE</token> to make the match case-insensitive according
to the active locale. This is not in the <acronym>SQL</acronym> standard but is a
<productname>PostgreSQL</productname> extension.
</para>
@ -2818,9 +2819,11 @@ substring('foobar' from '#"o_b#"%' for '#') <lineannotation>NULL</lineannotat
pattern. But if the pattern contains any parentheses, the portion
of the text that matched the first parenthesized subexpression (the
one whose left parenthesis comes first) is
returned. You can always put parentheses around the whole expression
returned. You can put parentheses around the whole expression
if you want to use parentheses within it without triggering this
exception. Also see the non-capturing parentheses described below.
exception. If you need parentheses in the pattern before the
subexpression you want to extract, see the non-capturing parentheses
described below.
</para>
<para>
@ -3073,7 +3076,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
<para>
The forms using <literal>{</><replaceable>...</><literal>}</>
are known as <firstterm>bound</>s.
are known as <firstterm>bounds</>.
The numbers <replaceable>m</> and <replaceable>n</> within a bound are
unsigned decimal integers with permissible values from 0 to 255 inclusive.
</para>
@ -3603,9 +3606,10 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
Normally the flavor of RE being used is determined by
<varname>regex_flavor</>.
However, this can be overridden by a <firstterm>director</> prefix.
If an RE of any flavor begins with <literal>***:</>,
the rest of the RE is taken as an ARE.
If an RE of any flavor begins with <literal>***=</>,
If an RE begins with <literal>***:</>,
the rest of the RE is taken as an ARE regardless of
<varname>regex_flavor</>.
If an RE begins with <literal>***=</>,
the rest of the RE is taken to be a literal string,
with all characters considered ordinary characters.
</para>
@ -3703,8 +3707,8 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
<para>
Embedded options take effect at the <literal>)</> terminating the sequence.
They are available only at the start of an ARE,
and may not be used later within it.
They may appear only at the start of an ARE (after the
<literal>***:</> director if any).
</para>
<para>
@ -3732,13 +3736,13 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</listitem>
<listitem>
<para>
white space and comments are illegal within multi-character symbols,
like the ARE <literal>(?:</> or the BRE <literal>\(</>
white space and comments cannot appear within multi-character symbols,
such as <literal>(?:</>
</para>
</listitem>
</itemizedlist>
Expanded-syntax white-space characters are blank, tab, newline, and
For this purpose, white-space characters are blank, tab, newline, and
any character that belongs to the <replaceable>space</> character class.
</para>
@ -4330,7 +4334,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</table>
<para>
Usage notes for the date/time formatting:
Usage notes for date/time formatting:
<itemizedlist>
<listitem>
@ -4506,7 +4510,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
</table>
<para>
Usage notes for the numeric formatting:
Usage notes for numeric formatting:
<itemizedlist>
<listitem>
@ -5068,10 +5072,10 @@ EXTRACT (<replaceable>field</replaceable> FROM <replaceable>source</replaceable>
<para>
The <function>extract</function> function retrieves subfields
from date/time values, such as year or hour.
<replaceable>source</replaceable> is a value expression that
evaluates to type <type>timestamp</type> or <type>interval</type>.
(Expressions of type <type>date</type> or <type>time</type> will
such as year or hour from date/time values.
<replaceable>source</replaceable> must be a value expression of
type <type>timestamp</type>, <type>time</type>, or <type>interval</type>.
(Expressions of type <type>date</type> will
be cast to <type>timestamp</type> and can therefore be used as
well.) <replaceable>field</replaceable> is an identifier or
string that selects what field to extract from the source value.
@ -5699,7 +5703,7 @@ SELECT TIMESTAMP 'now';
</programlisting>
</para>
<note>
<tip>
<para>
You do not want to use the third form when specifying a <literal>DEFAULT</>
clause while creating a table. The system will convert <literal>now</literal>
@ -5710,7 +5714,7 @@ SELECT TIMESTAMP 'now';
because they are function calls. Thus they will give the desired
behavior of defaulting to the time of row insertion.
</para>
</note>
</tip>
</sect2>
</sect1>
@ -6803,7 +6807,7 @@ SELECT NULLIF(value, '(none)') ...
<para>
<xref linkend="array-functions-table"> shows the functions
available for use with array types. See <xref linkend="arrays">
for more discussion and examples for the use of these functions.
for more discussion and examples of the use of these functions.
</para>
<table id="array-functions-table">
@ -6827,10 +6831,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>anyarray</type></entry>
<entry>
concatenate two arrays, returning <literal>NULL</literal>
for <literal>NULL</literal> inputs
</entry>
<entry>concatenate two arrays</entry>
<entry><literal>array_cat(ARRAY[1,2,3], ARRAY[4,5])</literal></entry>
<entry><literal>{1,2,3,4,5}</literal></entry>
</row>
@ -6842,10 +6843,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>anyarray</type></entry>
<entry>
append an element to the end of an array, returning
<literal>NULL</literal> for <literal>NULL</literal> inputs
</entry>
<entry>append an element to the end of an array</entry>
<entry><literal>array_append(ARRAY[1,2], 3)</literal></entry>
<entry><literal>{1,2,3}</literal></entry>
</row>
@ -6857,10 +6855,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>anyarray</type></entry>
<entry>
append an element to the beginning of an array, returning
<literal>NULL</literal> for <literal>NULL</literal> inputs
</entry>
<entry>append an element to the beginning of an array</entry>
<entry><literal>array_prepend(1, ARRAY[2,3])</literal></entry>
<entry><literal>{1,2,3}</literal></entry>
</row>
@ -6872,10 +6867,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>text</type></entry>
<entry>
returns a text representation of array dimension lower and upper bounds,
generating an ERROR for <literal>NULL</literal> inputs
</entry>
<entry>returns a text representation of array's dimensions</entry>
<entry><literal>array_dims(array[[1,2,3], [4,5,6]])</literal></entry>
<entry><literal>[1:2][1:3]</literal></entry>
</row>
@ -6887,10 +6879,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>integer</type></entry>
<entry>
returns lower bound of the requested array dimension, returning
<literal>NULL</literal> for <literal>NULL</literal> inputs
</entry>
<entry>returns lower bound of the requested array dimension</entry>
<entry><literal>array_lower(array_prepend(0, ARRAY[1,2,3]), 1)</literal></entry>
<entry><literal>0</literal></entry>
</row>
@ -6902,10 +6891,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>integer</type></entry>
<entry>
returns upper bound of the requested array dimension, returning
<literal>NULL</literal> for <literal>NULL</literal> inputs
</entry>
<entry>returns upper bound of the requested array dimension</entry>
<entry><literal>array_upper(ARRAY[1,2,3,4], 1)</literal></entry>
<entry><literal>4</literal></entry>
</row>
@ -6917,10 +6903,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>text</type></entry>
<entry>
concatenates array elements using provided delimiter, returning
<literal>NULL</literal> for <literal>NULL</literal> inputs
</entry>
<entry>concatenates array elements using provided delimiter</entry>
<entry><literal>array_to_string(array[1, 2, 3], '~^~')</literal></entry>
<entry><literal>1~^~2~^~3</literal></entry>
</row>
@ -6932,10 +6915,7 @@ SELECT NULLIF(value, '(none)') ...
</literal>
</entry>
<entry><type>text[]</type></entry>
<entry>
splits string into array elements using provided delimiter, returning
<literal>NULL</literal> for <literal>NULL</literal> inputs
</entry>
<entry>splits string into array elements using provided delimiter</entry>
<entry><literal>string_to_array( 'xx~^~yy~^~zz', '~^~')</literal></entry>
<entry><literal>{xx,yy,zz}</literal></entry>
</row>
@ -7181,7 +7161,7 @@ SELECT NULLIF(value, '(none)') ...
It should be noted that except for <function>count</function>,
these functions return a null value when no rows are selected. In
particular, <function>sum</function> of no rows returns null, not
zero as one might expect. The function <function>coalesce</function> may be
zero as one might expect. The <function>coalesce</function> function may be
used to substitute zero for null when necessary.
</para>
@ -8045,9 +8025,10 @@ select current_date + s.a as dates from generate_series(0,14,7) as s(a);
</indexterm>
<para>
The <function>session_user</function> is the user that initiated a
database connection; it is fixed for the duration of that
connection. The <function>current_user</function> is the user identifier
The <function>session_user</function> is normally the user who initiated
the current database connection; but superusers can change this setting
with <xref linkend="sql-set-session-authorization">.
The <function>current_user</function> is the user identifier
that is applicable for permission checking. Normally, it is equal
to the session user, but it changes during the execution of
functions with the attribute <literal>SECURITY DEFINER</literal>.
@ -8106,8 +8087,8 @@ SET search_path TO <replaceable>schema</> <optional>, <replaceable>schema</>, ..
<function>inet_server_addr</function> returns the IP address on which
the server accepted the current connection, and
<function>inet_server_port</function> returns the port number.
All these functions return NULL if the connection is via a Unix-domain
socket.
All these functions return NULL if the current connection is via a
Unix-domain socket.
</para>
<indexterm zone="functions-info">
@ -8325,7 +8306,7 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
</para>
<para>
To evaluate whether a user holds a grant option on the privilege,
To test whether a user holds a grant option on the privilege,
append <literal> WITH GRANT OPTION</literal> to the privilege key
word; for example <literal>'UPDATE WITH GRANT OPTION'</literal>.
</para>

6
doc/src/sgml/indices.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.47 2003/11/29 19:51:37 pgsql Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/indices.sgml,v 1.48 2004/12/23 23:07:38 tgl Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
@ -71,7 +71,7 @@ CREATE INDEX test1_id_index ON test1 (id);
</para>
<para>
Once the index is created, no further intervention is required: the
Once an index is created, no further intervention is required: the
system will update the index when the table is modified, and it will
use the index in queries when it thinks this would be more efficient
than a sequential table scan. But you may have to run the
@ -761,7 +761,7 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target)
</para>
<para>
It is especially fatal to use proportionally reduced data sets.
It is especially fatal to use very small test data sets.
While selecting 1000 out of 100000 rows could be a candidate for
an index, selecting 1 out of 100 rows will hardly be, because the
100 rows will probably fit within a single disk page, and there

10
doc/src/sgml/mvcc.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.45 2004/11/15 06:32:14 neilc Exp $
$PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.46 2004/12/23 23:07:38 tgl Exp $
-->
<chapter id="mvcc">
@ -206,9 +206,9 @@ $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.45 2004/11/15 06:32:14 neilc Exp $
</table>
<para>
In <productname>PostgreSQL</productname>, you can use all four
possible transaction isolation levels. Internally, there are only
two distinct isolation levels, which correspond to the levels Read
In <productname>PostgreSQL</productname>, you can request any of the
four standard transaction isolation levels. But internally, there are
only two distinct isolation levels, which correspond to the levels Read
Committed and Serializable. When you select the level Read
Uncommitted you really get Read Committed, and when you select
Repeatable Read you really get Serializable, so the actual
@ -217,7 +217,7 @@ $PostgreSQL: pgsql/doc/src/sgml/mvcc.sgml,v 2.45 2004/11/15 06:32:14 neilc Exp $
define which phenomena must not happen, they do not define which
phenomena must happen. The reason that <productname>PostgreSQL</>
only provides two isolation levels is that this is the only
sensible way to map the isolation levels to the multiversion
sensible way to map the standard isolation levels to the multiversion
concurrency control architecture. The behavior of the available
isolation levels is detailed in the following subsections.
</para>

35
doc/src/sgml/perform.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.48 2004/12/01 19:00:27 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.49 2004/12/23 23:07:38 tgl Exp $
-->
<chapter id="performance-tips">
@ -78,7 +78,7 @@ $PostgreSQL: pgsql/doc/src/sgml/perform.sgml,v 1.48 2004/12/01 19:00:27 tgl Exp
estimates are converted into disk-page units using some
fairly arbitrary fudge factors. If you want to experiment with these
factors, see the list of run-time configuration parameters in
<xref linkend="runtime-config-resource">.)
<xref linkend="runtime-config-query-constants">.)
</para>
<para>
@ -657,16 +657,6 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
point would be rolled back, so you won't be stuck with partially
loaded data.
</para>
<para>
If you are issuing a large sequence of <command>INSERT</command>
commands to bulk load some data, also consider using <xref
linkend="sql-prepare" endterm="sql-prepare-title"> to create a
prepared <command>INSERT</command> statement. Since you are
executing the same command multiple times, it is more efficient to
prepare the command once and then use <command>EXECUTE</command>
as many times as required.
</para>
</sect2>
<sect2 id="populate-copy-from">
@ -683,12 +673,20 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
use this method to populate a table.
</para>
<para>
If you cannot use <command>COPY</command>, it may help to use <xref
linkend="sql-prepare" endterm="sql-prepare-title"> to create a
prepared <command>INSERT</command> statement, and then use
<command>EXECUTE</command> as many times as required. This avoids
some of the overhead of repeatedly parsing and planning
<command>INSERT</command>.
</para>
<para>
Note that loading a large number of rows using
<command>COPY</command> is almost always faster than using
<command>INSERT</command>, even if multiple
<command>INSERT</command> commands are batched into a single
transaction.
<command>INSERT</command>, even if <command>PREPARE</> is used and
multiple insertions are batched into a single transaction.
</para>
</sect2>
@ -719,10 +717,10 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
<para>
Temporarily increasing the <xref linkend="guc-maintenance-work-mem">
configuration variable when restoring large amounts of data can
configuration variable when loading large amounts of data can
lead to improved performance. This is because when a B-tree index
is created from scratch, the existing content of the table needs
to be sorted. Allowing the external merge sort to use more memory
to be sorted. Allowing the merge sort to use more memory
means that fewer merge passes will be required. A larger setting for
<varname>maintenance_work_mem</varname> may also speed up validation
of foreign-key constraints.
@ -754,8 +752,7 @@ SELECT * FROM x, y, a, b, c WHERE something AND somethingelse;
Whenever you have significantly altered the distribution of data
within a table, running <xref linkend="sql-analyze"
endterm="sql-analyze-title"> is strongly recommended. This
includes when bulk loading large amounts of data into
<productname>PostgreSQL</productname>. Running
includes bulk loading large amounts of data into the table. Running
<command>ANALYZE</command> (or <command>VACUUM ANALYZE</command>)
ensures that the planner has up-to-date statistics about the
table. With no statistics or obsolete statistics, the planner may

70
doc/src/sgml/typeconv.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.42 2003/12/14 00:10:32 neilc Exp $
$PostgreSQL: pgsql/doc/src/sgml/typeconv.sgml,v 1.43 2004/12/23 23:07:38 tgl Exp $
-->
<chapter Id="typeconv">
@ -22,8 +22,7 @@ In many cases a user will not need
to understand the details of the type conversion mechanism.
However, the implicit conversions done by <productname>PostgreSQL</productname>
can affect the results of a query. When necessary, these results
can be tailored by a user or programmer
using <emphasis>explicit</emphasis> type conversion.
can be tailored by using <emphasis>explicit</emphasis> type conversion.
</para>
<para>
@ -43,16 +42,17 @@ has an associated data type which determines its behavior and allowed usage.
<productname>PostgreSQL</productname> has an extensible type system that is
much more general and flexible than other <acronym>SQL</acronym> implementations.
Hence, most type conversion behavior in <productname>PostgreSQL</productname>
should be governed by general rules rather than by <foreignphrase>ad hoc</> heuristics, to allow
is governed by general rules rather than by <foreignphrase>ad hoc</>
heuristics. This allows
mixed-type expressions to be meaningful even with user-defined types.
</para>
<para>
The <productname>PostgreSQL</productname> scanner/parser decodes lexical
elements into only five fundamental categories: integers, floating-point numbers, strings,
names, and key words. Constants of most non-numeric types are first classified as
strings. The <acronym>SQL</acronym> language definition allows specifying type
names with strings, and this mechanism can be used in
The <productname>PostgreSQL</productname> scanner/parser divides lexical
elements into only five fundamental categories: integers, non-integer numbers,
strings, identifiers, and key words. Constants of most non-numeric types are
first classified as strings. The <acronym>SQL</acronym> language definition
allows specifying type names with strings, and this mechanism can be used in
<productname>PostgreSQL</productname> to start the parser down the correct
path. For example, the query
@ -79,28 +79,30 @@ parser:
<variablelist>
<varlistentry>
<term>
Function calls
</term>
<listitem>
<para>
Much of the <productname>PostgreSQL</productname> type system is built around a
rich set of functions. Functions can have one or more arguments.
Since <productname>PostgreSQL</productname> permits function
overloading, the function name alone does not uniquely identify the function
to be called; the parser must select the right function based on the data
types of the supplied arguments.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Operators
</term>
<listitem>
<para>
<productname>PostgreSQL</productname> allows expressions with
prefix and postfix unary (one-argument) operators,
as well as binary (two-argument) operators.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
Function calls
</term>
<listitem>
<para>
Much of the <productname>PostgreSQL</productname> type system is built around a
rich set of functions. Function calls can have one or more arguments.
Since <productname>PostgreSQL</productname> permits function
overloading, the function name alone does not uniquely identify the function
to be called; the parser must select the right function based on the data
types of the supplied arguments.
as well as binary (two-argument) operators. Like functions, operators can
be overloaded, and so the same problem of selecting the right operator
exists.
</para>
</listitem>
</varlistentry>
@ -125,7 +127,7 @@ with, and perhaps converted to, the types of the target columns.
Since all query results from a unionized <command>SELECT</command> statement
must appear in a single set of columns, the types of the results of each
<command>SELECT</> clause must be matched up and converted to a uniform set.
Similarly, the branch expressions of a <literal>CASE</> construct must be
Similarly, the result expressions of a <literal>CASE</> construct must be
converted to a common type so that the <literal>CASE</> expression as a whole
has a known output type. The same holds for <literal>ARRAY</> constructs.
</para>
@ -728,12 +730,16 @@ type.
<step performance="required">
<para>
If the target is a fixed-length type (e.g., <type>char</type> or <type>varchar</type>
declared with a length) then try to find a sizing function for the target
type. A sizing function is a function of the same name as the type,
taking two arguments of which the first is that type and the second is of type
<type>integer</type>, and returning the same type. If one is found, it is applied,
passing the column's declared length as the second parameter.
Check to see if there is a sizing cast for the target type. A sizing
cast is a cast from that type to itself. If one is found in the
<structname>pg_cast</> catalog, apply it to the expression before storing
into the destination column. The implementation function for such a cast
always takes an extra parameter of type <type>integer</type>, which receives
the destination column's declared length (actually, its
<structfield>atttypmod</> value; the interpretation of
<structfield>atttypmod</> varies for different datatypes). The cast function
is responsible for applying any length-dependent semantics such as size
checking or truncation.
</para>
</step>