open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

A small pass of docs review and copy-editing.

Browse Source
REL8_0_STABLE
Tom Lane 21 years ago
parent 3621657a61
commit f8ffb60492
9 changed files with 171 additions and 128 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 22
      doc/src/sgml/array.sgml
  2. 74
      doc/src/sgml/datatype.sgml
  3. 91
      doc/src/sgml/ddl.sgml
  4. 19
      doc/src/sgml/dml.sgml
  5. 10
      doc/src/sgml/intro.sgml
  6. 4
      doc/src/sgml/postgres.sgml
  7. 55
      doc/src/sgml/queries.sgml
  8. 4
      doc/src/sgml/rowtypes.sgml
  9. 20
      doc/src/sgml/syntax.sgml

22
doc/src/sgml/array.sgml
Unescape View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.41 2004/12/13 18:05:07 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.42 2004/12/23 05:37:39 tgl Exp $ -->
<sect1 id="arrays">
<title>Arrays</title>
@ -546,11 +546,11 @@ SELECT * FROM sal_emp WHERE 10000 = ALL (pay_by_quarter);
set to one. If any of an array's dimensions has a lower bound index not
equal to one, an additional decoration that indicates the actual
array dimensions will precede the array structure decoration.
The decoration consists of square braces (<literal>[</> and <literal>]</>)
around each array dimension's lower and upper bound indices, plus
a colon (<literal>:</>) delimiter character in between. Delimiting the
array dimension decoration from the array structure decoration is a
single assignment operator (<literal>=</>). For example:
This decoration consists of square brackets (<literal>[]</>)
around each array dimension's lower and upper bounds, with
a colon (<literal>:</>) delimiter character in between. The
array dimension decoration is followed by an equal sign (<literal>=</>).
For example:
<programlisting>
SELECT 1 || ARRAY[2,3] AS array;
@ -569,8 +569,8 @@ SELECT ARRAY[1,2] || ARRAY[[3,4]] AS array;
</para>
<para>
In a similar fashion, an array with non-default indices may be specified
using the same literal syntax. For example:
This syntax can also be used to specify non-default array subscripts
in an array literal. For example:
<programlisting>
SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
FROM (SELECT '[1:1][-2:-1][3:5]={{{1,2,3},{4,5,6}}}'::int[] AS f1) AS ss;
@ -598,8 +598,8 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
You may write whitespace before a left brace or after a right
brace. You may also write 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
non-whitespace characters of an element, are not ignored.
whitespace within double-quoted elements, or surrounded on both sides by
non-whitespace characters of an element, is not ignored.
</para>
<note>
@ -618,6 +618,8 @@ INSERT ... VALUES ('{"\\\\","\\""}');
with a data type whose input routine also treated backslashes specially,
<type>bytea</> for example, we might need as many as eight backslashes
in the command to get one backslash into the stored array element.)
Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be
used to avoid the need to double backslashes.
</para>
</note>

74
doc/src/sgml/datatype.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.152 2004/12/23 05:37:39 tgl Exp $
-->
<chapter id="datatype">
@ -22,9 +22,8 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
</para>
<para>
<xref linkend="datatype-table"> shows all built-in general-purpose data types.
Most of the alternative names
listed in the
<xref linkend="datatype-table"> shows all the built-in general-purpose data
types. Most of the alternative names listed in the
<quote>Aliases</quote> column are the names used internally by
<productname>PostgreSQL</productname> for historical reasons. In
addition, some internally used or deprecated types are available,
@ -82,7 +81,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
<row>
<entry><type>bytea</type></entry>
<entry></entry>
<entry>binary data</entry>
<entry>binary data (<quote>byte array</>)</entry>
</row>
<row>
@ -142,7 +141,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
<row>
<entry><type>line</type></entry>
<entry></entry>
<entry>infinite line in the plane (not fully implemented)</entry>
<entry>infinite line in the plane</entry>
</row>
<row>
@ -168,13 +167,13 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
<replaceable>s</replaceable>) ]</type></entry>
<entry><type>decimal [ (<replaceable>p</replaceable>,
<replaceable>s</replaceable>) ]</type></entry>
<entry>exact numeric with selectable precision</entry>
<entry>exact numeric of selectable precision</entry>
</row>
<row>
<entry><type>path</type></entry>
<entry></entry>
<entry>open or closed geometric path in the plane</entry>
<entry>geometric path in the plane</entry>
</row>
<row>
@ -227,7 +226,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
<row>
<entry><type>timestamp [ (<replaceable>p</replaceable>) ] [ without time zone ]</type></entry>
<entry><type></type></entry>
<entry></entry>
<entry>date and time</entry>
</row>
@ -259,7 +258,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
Each data type has an external representation determined by its input
and output functions. Many of the built-in types have
obvious external formats. However, several types are either unique
to <productname>PostgreSQL</productname>, such as open and closed
to <productname>PostgreSQL</productname>, such as geometric
paths, or have several possibilities for formats, such as the date
and time types.
Some of the input and output functions are not invertible. That is,
@ -267,14 +266,6 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
the original input.
</para>
<para>
Some of the operators and functions (e.g.,
addition and multiplication) do not perform run-time error-checking in the
interests of improving execution speed.
On some systems, for example, the numeric operators for some data types may
silently cause underflow or overflow.
</para>
<sect1 id="datatype-numeric">
<title>Numeric Types</title>
@ -285,7 +276,7 @@ $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.151 2004/11/27 21:27:05 petere
<para>
Numeric types consist of two-, four-, and eight-byte integers,
four- and eight-byte floating-point numbers, and fixed-precision
four- and eight-byte floating-point numbers, and selectable-precision
decimals. <xref linkend="datatype-numeric-table"> lists the
available types.
</para>
@ -755,7 +746,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
created by reloading a dump from a pre-7.3 database; the dump
file does not contain the information needed to establish the
dependency link.) Furthermore, this dependency between sequence
and column is made only for the <type>serial</> column itself; if
and column is made only for the <type>serial</> column itself. If
any other columns reference the sequence (perhaps by manually
calling the <function>nextval</> function), they will be broken
if the sequence is removed. Using a <type>serial</> column's sequence
@ -916,7 +907,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
varying(<replaceable>n</>)</type> and
<type>character(<replaceable>n</>)</type>, respectively.
<type>character</type> without length specifier is equivalent to
<type>character(1)</type>; if <type>character varying</type> is used
<type>character(1)</type>. If <type>character varying</type> is used
without length specifier, the type accepts strings of any size. The
latter is a <productname>PostgreSQL</> extension.
</para>
@ -1114,8 +1105,8 @@ SELECT b, char_length(b) FROM test2;
literal in an <acronym>SQL</acronym> statement. In general, to
escape an octet, it is converted into the three-digit octal number
equivalent of its decimal octet value, and preceded by two
backslashes. <xref linkend="datatype-binary-sqlesc"> contains the
characters which must be escaped, and gives the alternate escape
backslashes. <xref linkend="datatype-binary-sqlesc"> shows the
characters that must be escaped, and gives the alternate escape
sequences where applicable.
</para>
@ -2429,7 +2420,7 @@ SELECT * FROM test1 WHERE a;
<para>
Boxes are represented by pairs of points that are opposite
corners of the box.
Values of type <type>box</type> is specified using the following syntax:
Values of type <type>box</type> are specified using the following syntax:
<synopsis>
( ( <replaceable>x1</replaceable> , <replaceable>y1</replaceable> ) , ( <replaceable>x2</replaceable> , <replaceable>y2</replaceable> ) )
@ -2441,7 +2432,7 @@ SELECT * FROM test1 WHERE a;
<literal>(<replaceable>x1</replaceable>,<replaceable>y1</replaceable>)</literal>
and
<literal>(<replaceable>x2</replaceable>,<replaceable>y2</replaceable>)</literal>
are the opposite corners of the box.
are any two opposite corners of the box.
</para>
<para>
@ -2449,7 +2440,7 @@ SELECT * FROM test1 WHERE a;
The corners are reordered on input to store
the upper right corner, then the lower left corner.
Other corners of the box can be entered, but the lower
left and upper right corners are determined from the input and stored corners.
left and upper right corners are determined from the input and stored.
</para>
</sect2>
@ -2461,18 +2452,11 @@ SELECT * FROM test1 WHERE a;
</indexterm>
<para>
Paths are represented by connected sets of points. Paths can be
Paths are represented by lists of connected points. Paths can be
<firstterm>open</firstterm>, where
the first and last points in the set are not connected, and <firstterm>closed</firstterm>,
where the first and last point are connected. The functions
<function>popen(<replaceable>p</>)</function>
and
<function>pclose(<replaceable>p</>)</function>
are supplied to force a path to be open or closed, and the functions
<function>isopen(<replaceable>p</>)</function>
and
<function>isclosed(<replaceable>p</>)</function>
are supplied to test for either type in an expression.
the first and last points in the list are not connected, or
<firstterm>closed</firstterm>,
where the first and last points are connected.
</para>
<para>
@ -2505,7 +2489,8 @@ SELECT * FROM test1 WHERE a;
</indexterm>
<para>
Polygons are represented by sets of points. Polygons should probably be
Polygons are represented by lists of points (the vertexes of the
polygon). Polygons should probably be
considered equivalent to closed paths, but are stored differently
and have their own set of support routines.
</para>
@ -2569,8 +2554,9 @@ SELECT * FROM test1 WHERE a;
<para>
<productname>PostgreSQL</> offers data types to store IPv4, IPv6, and MAC
addresses, shown in <xref linkend="datatype-net-types-table">. It
is preferable to use these types over plain text types, because
addresses, as shown in <xref linkend="datatype-net-types-table">. It
is preferable to use these types instead of plain text types to store
network addresses, because
these types offer input error checking and several specialized
operators and functions.
</para>
@ -2590,7 +2576,7 @@ SELECT * FROM test1 WHERE a;
<row>
<entry><type>cidr</type></entry>
<entry>12 or 24 bytes</entry>
<entry>IPv4 or IPv6 networks</entry>
<entry>IPv4 and IPv6 networks</entry>
</row>
<row>
@ -2631,7 +2617,7 @@ SELECT * FROM test1 WHERE a;
the host address represent the network address (the
<quote>netmask</quote>). If the netmask is 32 and the address is IPv4,
then the value does not indicate a subnet, only a single host.
In IPv6, the address length is 128 bits, so 128 bits will specify a
In IPv6, the address length is 128 bits, so 128 bits specify a
unique host address. Note that if you
want to accept networks only, you should use the
<type>cidr</type> type rather than <type>inet</type>.
@ -2647,7 +2633,7 @@ SELECT * FROM test1 WHERE a;
is the number of bits in the netmask. If the
<replaceable class="parameter">/y</replaceable>
part is left off, then the
netmask is 32 for IPv4 and 128 for IPv6, and the value represents
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>
portion is suppressed if the netmask specifies a single host.
@ -2824,7 +2810,7 @@ SELECT * FROM test1 WHERE a;
which would all specify the same
address. Upper and lower case is accepted for the digits
<literal>a</> through <literal>f</>. Output is always in the
last of the shown forms.
last of the forms shown.
</para>
<para>

91
doc/src/sgml/ddl.sgml
Unescape View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.34 2004/12/13 18:05:08 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/ddl.sgml,v 1.35 2004/12/23 05:37:39 tgl Exp $ -->
<chapter id="ddl">
<title>Data Definition</title>
@ -260,7 +260,7 @@ DROP TABLE products;
<para>
The identity (transaction ID) of the deleting transaction, or
zero for an undeleted row version. It is possible for this column to
be nonzero in a visible row version: That usually indicates that the
be nonzero in a visible row version. That usually indicates that the
deleting transaction hasn't committed yet, or that an attempted
deletion was rolled back.
</para>
@ -329,8 +329,8 @@ DROP TABLE products;
<para>
The tables in question should be created using <literal>WITH
OIDS</literal> to ensure forward compatibility with future
releases of <productname>PostgreSQL</productname> in which OIDs
are not included in all tables by default.
releases of <productname>PostgreSQL</productname>. It is
planned that <literal>WITHOUT OIDS</> will become the default.
</para>
</listitem>
</itemizedlist>
@ -367,15 +367,15 @@ DROP TABLE products;
created and no values are specified for some of the columns, the
columns will be filled with their respective default values. A
data manipulation command can also request explicitly that a column
be set to its default value, without knowing what this value is.
be set to its default value, without having to know what that value is.
(Details about data manipulation commands are in <xref linkend="dml">.)
</para>
<para>
<indexterm><primary>null value</primary><secondary>default value</secondary></indexterm>
If no default value is declared explicitly, the null value is the
default value. This usually makes sense because a null value can
be thought to represent unknown data.
If no default value is declared explicitly, the default value is the
null value. This usually makes sense because a null value can
be considered to represent unknown data.
</para>
<para>
@ -393,7 +393,9 @@ CREATE TABLE products (
<para>
The default value may be a scalar expression, which will be
evaluated whenever the default value is inserted
(<emphasis>not</emphasis> when the table is created).
(<emphasis>not</emphasis> when the table is created). A common example
is that a timestamp column may have a default of <literal>now()</>,
so that it gets set to the time of row insertion.
</para>
</sect1>
@ -544,7 +546,7 @@ CREATE TABLE products (
expressions will evaluate to the null value if one operand is null,
they will not prevent null values in the constrained columns. To
ensure that a column does not contain null values, the not-null
constraint described in the next section should be used.
constraint described in the next section can be used.
</para>
</sect2>
@ -691,11 +693,11 @@ CREATE TABLE products (
</indexterm>
<para>
In general, a unique constraint is violated when there are (at
least) two rows in the table where the values of each of the
corresponding columns that are part of the constraint are equal.
In general, a unique constraint is violated when there are two or
more rows in the table where the values of all of the
columns included in the constraint are equal.
However, null values are not considered equal in this
consideration. That means even in the presence of a
comparison. That means even in the presence of a
unique constraint it is possible to store an unlimited number of
rows that contain a null value in at least one of the constrained
columns. This behavior conforms to the SQL standard, but we have
@ -839,7 +841,7 @@ CREATE TABLE orders (
);
</programlisting>
because in absence of a column list the primary key of the
referenced table is used as the referenced column.
referenced table is used as the referenced column(s).
</para>
<para>
@ -902,7 +904,7 @@ CREATE TABLE order_items (
We know that the foreign keys disallow creation of orders that
do not relate to any products. But what if a product is removed
after an order is created that references it? SQL allows you to
specify that as well. Intuitively, we have a few options:
handle that as well. Intuitively, we have a few options:
<itemizedlist spacing="compact">
<listitem><para>Disallow deleting a referenced product</para></listitem>
<listitem><para>Delete the orders as well</para></listitem>
@ -940,13 +942,15 @@ CREATE TABLE order_items (
<para>
Restricting and cascading deletes are the two most common options.
<literal>RESTRICT</literal> prevents a statement from deleting a
<literal>RESTRICT</literal> prevents deletion of a
referenced row. <literal>NO ACTION</literal> means that if any
referencing rows still exist when the constraint is checked, an error
is raised; this is the default if you do not specify anything.
(The essential difference between these choices is that
is raised; this is the default behavior if you do not specify anything.
(The essential difference between these two choices is that
<literal>NO ACTION</literal> allows the check to be deferred until
later in the transaction, whereas <literal>RESTRICT</literal> does not.)
<literal>CASCADE</> specifies that when a referenced row is deleted,
row(s) referencing it should be automatically deleted as well.
There are two other options:
<literal>SET NULL</literal> and <literal>SET DEFAULT</literal>.
These cause the referencing columns to be set to nulls or default
@ -954,13 +958,13 @@ CREATE TABLE order_items (
Note that these do not excuse you from observing any constraints.
For example, if an action specifies <literal>SET DEFAULT</literal>
but the default value would not satisfy the foreign key, the
deletion of the primary key will fail.
operation will fail.
</para>
<para>
Analogous to <literal>ON DELETE</literal> there is also
<literal>ON UPDATE</literal> which is invoked when a primary key
is changed (updated). The possible actions are the same.
<literal>ON UPDATE</literal> which is invoked when a referenced
column is changed (updated). The possible actions are the same.
</para>
<para>
@ -1219,6 +1223,9 @@ WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
<listitem>
<para>Change default values,</para>
</listitem>
<listitem>
<para>Change column data types,</para>
</listitem>
<listitem>
<para>Rename columns,</para>
</listitem>
@ -1227,8 +1234,9 @@ WHERE c.altitude &gt; 500 and c.tableoid = p.oid;
</listitem>
</itemizedlist>
All these actions are performed using the <literal>ALTER
TABLE</literal> command.
All these actions are performed using the
<xref linkend="sql-altertable" endterm="sql-altertable-title">
command.
</para>
<sect2>
@ -1343,7 +1351,7 @@ ALTER TABLE products ALTER COLUMN product_no DROP NOT NULL;
</sect2>
<sect2>
<title>Changing the Default</title>
<title>Changing a Column's Default Value</title>
<indexterm>
<primary>default value</primary>
@ -1366,6 +1374,35 @@ ALTER TABLE products ALTER COLUMN price DROP DEFAULT;
</para>
</sect2>
<sect2>
<title>Changing a Column's Data Type</title>
<indexterm>
<primary>column data type</primary>
<secondary>changing</secondary>
</indexterm>
<para>
To convert a column to a different data type, use a command like this:
<programlisting>
ALTER TABLE products ALTER COLUMN price TYPE numeric(10,2);
</programlisting>
This will succeed only if each existing entry in the column can be
converted to the new type by an implicit cast. If a more complex
conversion is needed, you can add a <literal>USING</> clause that
specifies how to compute the new values from the old.
</para>
<para>
<productname>PostgreSQL</> will attempt to convert the column's
default value (if any) to the new type, as well as any constraints
that involve the column. But these conversions may fail, or may
produce surprising results. It's often best to drop any constraints
on the column before altering its type, and then add back suitably
modified constraints afterwards.
</para>
</sect2>
<sect2>
<title>Renaming a Column</title>
@ -1568,7 +1605,7 @@ REVOKE ALL ON accounts FROM PUBLIC;
</indexterm>
<para>
To create a separate schema, use the command <literal>CREATE
To create a schema, use the command <literal>CREATE
SCHEMA</literal>. Give the schema a name of your choice. For
example:
<programlisting>
@ -1830,7 +1867,7 @@ REVOKE CREATE ON SCHEMA public FROM PUBLIC;
(The first <quote>public</quote> is the schema, the second
<quote>public</quote> means <quote>every user</quote>. In the
first sense it is an identifier, in the second sense it is a
reserved word, hence the different capitalization; recall the
key word, hence the different capitalization; recall the
guidelines from <xref linkend="sql-syntax-identifiers">.)
</para>
</sect2>

19
doc/src/sgml/dml.sgml
Unescape View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.8 2003/11/29 19:51:36 pgsql Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/dml.sgml,v 1.9 2004/12/23 05:37:39 tgl Exp $ -->
<chapter id="dml">
<title>Data Manipulation</title>
@ -161,7 +161,7 @@ UPDATE products SET price = 10 WHERE price = 5;
</para>
<para>
Let's look at that command in detail: First is the key word
Let's look at that command in detail. First is the key word
<literal>UPDATE</literal> followed by the table name. As usual,
the table name may be schema-qualified, otherwise it is looked up
in the path. Next is the key word <literal>SET</literal> followed
@ -172,21 +172,22 @@ UPDATE products SET price = 10 WHERE price = 5;
<programlisting>
UPDATE products SET price = price * 1.10;
</programlisting>
As you see, the expression for the new value can also refer to the
old value. We also left out the <literal>WHERE</literal> clause.
As you see, the expression for the new value can refer to the existing
value(s) in the row. We also left out the <literal>WHERE</literal> clause.
If it is omitted, it means that all rows in the table are updated.
If it is present, only those rows that match the condition after
the <literal>WHERE</literal> are updated. Note that the equals
If it is present, only those rows that match the
<literal>WHERE</literal> condition are updated. Note that the equals
sign in the <literal>SET</literal> clause is an assignment while
the one in the <literal>WHERE</literal> clause is a comparison, but
this does not create any ambiguity. Of course, the condition does
this does not create any ambiguity. Of course, the
<literal>WHERE</literal> condition does
not have to be an equality test. Many other operators are
available (see <xref linkend="functions">). But the expression
needs to evaluate to a Boolean result.
</para>
<para>
You can also update more than one column in an
You can update more than one column in an
<literal>UPDATE</literal> command by listing more than one
assignment in the <literal>SET</literal> clause. For example:
<programlisting>
@ -211,7 +212,7 @@ UPDATE mytable SET a = 5, b = 3, c = 1 WHERE a > 0;
change data. What remains is to discuss how to remove data that is
no longer needed. Just as adding data is only possible in whole
rows, you can only remove entire rows from a table. In the
previous section we discussed that SQL does not provide a way to
previous section we explained that SQL does not provide a way to
directly address individual rows. Therefore, removing rows can
only be done by specifying conditions that the rows to be removed
have to match. If you have a primary key in the table then you can

10
doc/src/sgml/intro.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.27 2004/12/23 05:37:39 tgl Exp $
-->
<preface id="preface">
@ -41,7 +41,7 @@ $PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp
<listitem>
<para>
<xref linkend="admin"> describes the installation and
administration of the server. Everyone that runs a
administration of the server. Everyone who runs a
<productname>PostgreSQL</productname> server, be it for private
use or for others, should read this part.
</para>
@ -67,8 +67,8 @@ $PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp
<listitem>
<para>
<xref linkend="reference"> contains information about the syntax
of SQL commands, client and server programs. This part supports
<xref linkend="reference"> contains reference information about
SQL commands, client and server programs. This part supports
the other parts with structured information sorted by command or
program.
</para>
@ -76,7 +76,7 @@ $PostgreSQL: pgsql/doc/src/sgml/intro.sgml,v 1.26 2004/11/27 21:27:06 petere Exp
<listitem>
<para>
<xref linkend="internals"> contains assorted information that can be of
<xref linkend="internals"> contains assorted information that may be of
use to <productname>PostgreSQL</> developers.
</para>
</listitem>

4
doc/src/sgml/postgres.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.68 2004/12/03 05:50:18 momjian Exp $
$PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.69 2004/12/23 05:37:39 tgl Exp $
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
@ -67,7 +67,7 @@ $PostgreSQL: pgsql/doc/src/sgml/postgres.sgml,v 1.68 2004/12/03 05:50:18 momjian
explain how to create the structures to hold data, how to populate
the database, and how to query it. The middle part lists the
available data types and functions for use in
<acronym>SQL</acronym> data commands. The rest treats several
<acronym>SQL</acronym> commands. The rest treats several
aspects that are important for tuning a database for optimal
performance.
</para>

55
doc/src/sgml/queries.sgml
Unescape View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.31 2004/11/15 06:32:14 neilc Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/queries.sgml,v 1.32 2004/12/23 05:37:40 tgl Exp $ -->
<chapter id="queries">
<title>Queries</title>
@ -477,7 +477,7 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
<para>
A temporary name can be given to tables and complex table
references to be used for references to the derived table in
further processing. This is called a <firstterm>table
the rest of the query. This is called a <firstterm>table
alias</firstterm>.
</para>
@ -542,7 +542,8 @@ SELECT * FROM (my_table AS a CROSS JOIN my_table) AS b ...
</para>
<para>
Another form of table aliasing also gives temporary names to the columns of the table:
Another form of table aliasing gives temporary names to the columns of
the table, as well as the table itself:
<synopsis>
FROM <replaceable>table_reference</replaceable> <optional>AS</optional> <replaceable>alias</replaceable> ( <replaceable>column1</replaceable> <optional>, <replaceable>column2</replaceable> <optional>, ...</optional></optional> )
</synopsis>
@ -642,6 +643,7 @@ SELECT * FROM foo
where z.fooid = foo.fooid);
CREATE VIEW vw_getfoo AS SELECT * FROM getfoo(1);
SELECT * FROM vw_getfoo;
</programlisting>
</para>
@ -679,12 +681,12 @@ SELECT *
<para>
The syntax of the <xref linkend="sql-where"
endterm="sql-where-title"> clause is
endterm="sql-where-title"> is
<synopsis>
WHERE <replaceable>search_condition</replaceable>
</synopsis>
where <replaceable>search_condition</replaceable> is any value
expression as defined in <xref linkend="sql-expressions"> that
expression (see <xref linkend="sql-expressions">) that
returns a value of type <type>boolean</type>.
</para>
@ -694,17 +696,16 @@ WHERE <replaceable>search_condition</replaceable>
condition. If the result of the condition is true, the row is
kept in the output table, otherwise (that is, if the result is
false or null) it is discarded. The search condition typically
references at least some column in the table generated in the
references at least some column of the table generated in the
<literal>FROM</> clause; this is not required, but otherwise the
<literal>WHERE</> clause will be fairly useless.
</para>
<note>
<para>
Before the implementation of the <literal>JOIN</> syntax, it was
necessary to put the join condition of an inner join in the
<literal>WHERE</> clause. For example, these table expressions
are equivalent:
The join condition of an inner join can be written either in
the <literal>WHERE</> clause or in the <literal>JOIN</> clause.
For example, these table expressions are equivalent:
<programlisting>
FROM a, b WHERE a.id = b.id AND b.val &gt; 5
</programlisting>
@ -788,7 +789,7 @@ SELECT <replaceable>select_list</replaceable>
The <xref linkend="sql-groupby" endterm="sql-groupby-title"> is
used to group together those rows in a table that share the same
values in all the columns listed. The order in which the columns
are listed does not matter. The purpose is to reduce each group
are listed does not matter. The effect is to combine each set
of rows sharing common values into one group row that is
representative of all rows in the group. This is done to
eliminate redundancy in the output and/or compute aggregates that
@ -818,7 +819,7 @@ SELECT <replaceable>select_list</replaceable>
FROM test1 GROUP BY x</literal>, because there is no single value
for the column <literal>y</> that could be associated with each
group. The grouped-by columns can be referenced in the select list since
they have a known constant value per group.
they have a single value in each group.
</para>
<para>
@ -1055,14 +1056,14 @@ SELECT a AS value, b + c AS sum FROM ...
<para>
After the select list has been processed, the result table may
optionally be subject to the elimination of duplicates. The
<literal>DISTINCT</literal> key word is written directly after the
<literal>SELECT</literal> to enable this:
optionally be subject to the elimination of duplicate rows. The
<literal>DISTINCT</literal> key word is written directly after
<literal>SELECT</literal> to specify this:
<synopsis>
SELECT DISTINCT <replaceable>select_list</replaceable> ...
</synopsis>
(Instead of <literal>DISTINCT</> the key word <literal>ALL</literal>
can be used to select the default behavior of retaining all rows.)
can be used to specify the default behavior of retaining all rows.)
</para>
<para>
@ -1153,8 +1154,8 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
<replaceable>query2</replaceable> to the result of
<replaceable>query1</replaceable> (although there is no guarantee
that this is the order in which the rows are actually returned).
Furthermore, it eliminates all duplicate rows, in the sense of
<literal>DISTINCT</>, unless <literal>UNION ALL</> is used.
Furthermore, it eliminates duplicate rows from its result, in the same
way as <literal>DISTINCT</>, unless <literal>UNION ALL</> is used.
</para>
<para>
@ -1175,8 +1176,8 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
<para>
In order to calculate the union, intersection, or difference of two
queries, the two queries must be <quote>union compatible</quote>,
which means that they both return the same number of columns, and
that the corresponding columns have compatible data types, as
which means that they return the same number of columns and
the corresponding columns have compatible data types, as
described in <xref linkend="typeconv-union-case">.
</para>
</sect1>
@ -1196,7 +1197,7 @@ SELECT DISTINCT ON (<replaceable>expression</replaceable> <optional>, <replaceab
<para>
After a query has produced an output table (after the select list
has been processed) it can optionally be sorted. If sorting is not
chosen, the rows will be returned in random order. The actual
chosen, the rows will be returned in an unspecified order. The actual
order in that case will depend on the scan and join plan types and
the order on disk, but it must not be relied on. A particular
output ordering can only be guaranteed if the sort step is explicitly
@ -1227,10 +1228,10 @@ SELECT a, sum(b) FROM table1 GROUP BY a ORDER BY 1;
<programlisting>
SELECT a, b FROM table1 ORDER BY a + b;
</programlisting>
References to column names in the <literal>FROM</> clause that are
renamed in the select list are also allowed:
References to column names of the <literal>FROM</> clause that are
not present in the select list are also allowed:
<programlisting>
SELECT a AS b FROM table1 ORDER BY a;
SELECT a FROM table1 ORDER BY b;
</programlisting>
But these extensions do not work in queries involving
<literal>UNION</>, <literal>INTERSECT</>, or <literal>EXCEPT</>,
@ -1325,6 +1326,12 @@ SELECT <replaceable>select_list</replaceable>
deliver the results of a query in any particular order unless
<literal>ORDER BY</> is used to constrain the order.
</para>
<para>
The rows skipped by an <literal>OFFSET</> clause still have to be
computed inside the server; therefore a large <literal>OFFSET</>
can be inefficient.
</para>
</sect1>
</chapter>

4
doc/src/sgml/rowtypes.sgml
Unescape View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.3 2004/12/13 18:05:09 petere Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/rowtypes.sgml,v 2.4 2004/12/23 05:37:40 tgl Exp $ -->
<sect1 id="rowtypes">
<title>Composite Types</title>
@ -308,6 +308,8 @@ INSERT ... VALUES ('("\\"\\\\")');
with a data type whose input routine also treated backslashes specially,
<type>bytea</> for example, we might need as many as eight backslashes
in the command to get one backslash into the stored composite field.)
Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be
used to avoid the need to double backslashes.
</para>
</note>

20
doc/src/sgml/syntax.sgml
Unescape View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.98 2004/12/13 18:05:09 petere Exp $
$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.99 2004/12/23 05:37:40 tgl Exp $
-->
<chapter id="sql-syntax">
@ -599,7 +599,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
A dollar sign (<literal>$</literal>) followed by digits is used
to represent a positional parameter in the body of a function
definition or a prepared statement. In other contexts the
dollar sign may be part of an identifier.
dollar sign may be part of an identifier or a dollar-quoted string
constant.
</para>
</listitem>
@ -646,8 +647,9 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<listitem>
<para>
The asterisk (<literal>*</literal>) has a special meaning when
used in the <command>SELECT</command> command or with the
The asterisk (<literal>*</literal>) is used in some contexts to denote
all the fields of a table row or composite value. It also
has a special meaning when used as the argument of the
<function>COUNT</function> aggregate function.
</para>
</listitem>
@ -823,7 +825,7 @@ SELECT (5 !) - 6;
<row>
<entry><token>BETWEEN</token></entry>
<entry></entry>
<entry>containment</entry>
<entry>range containment</entry>
</row>
<row>
@ -1083,7 +1085,7 @@ $<replaceable>number</replaceable>
<programlisting>
CREATE FUNCTION dept(text) RETURNS dept
AS $$SELECT * FROM dept WHERE name = $1$$
AS $$ SELECT * FROM dept WHERE name = $1 $$
LANGUAGE SQL;
</programlisting>
@ -1552,7 +1554,9 @@ SELECT ROW(1,2.5,'this is a test');
to avoid ambiguity. For example:
<programlisting>
CREATE TABLE mytable(f1 int, f2 float, f3 text);
CREATE FUNCTION getf1(mytable) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
-- No cast needed since only one getf1() exists
SELECT getf1(ROW(1,2.5,'this is a test'));
getf1
@ -1561,10 +1565,13 @@ SELECT getf1(ROW(1,2.5,'this is a test'));
(1 row)
CREATE TYPE myrowtype AS (f1 int, f2 text, f3 numeric);
CREATE FUNCTION getf1(myrowtype) RETURNS int AS 'SELECT $1.f1' LANGUAGE SQL;
-- Now we need a cast to indicate which function to call:
SELECT getf1(ROW(1,2.5,'this is a test'));
ERROR: function getf1(record) is not unique
SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
getf1
-------
@ -1587,6 +1594,7 @@ SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
<literal>IS NULL</> or <literal>IS NOT NULL</>, for example
<programlisting>
SELECT ROW(1,2.5,'this is a test') = ROW(1, 3, 'not the same');
SELECT ROW(a, b, c) IS NOT NULL FROM table;
</programlisting>
For more detail see <xref linkend="functions-comparisons">.

Write Preview
Loading…
Cancel
Save