sharpetronics/PostgreSQL
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-05-22 00:02:02 -04:00
Code Issues Projects Releases Wiki Activity

Update references to char2 type by using char(2).

Browse Source 
Thanks to Garr Updegraff <garru@uci.edu> for the tip.
This commit is contained in:
Thomas G. Lockhart 1999-08-08 04:21:33 +00:00
parent f11bdb9db5
commit c9ff1a5a75
3 changed files with 281 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

374
doc/src/sgml/advanced.sgml
View File

@ -1,59 +1,65 @@
<Chapter Id="advanced"> <chapter id="advanced">
<Title>Advanced <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> Features</Title> <title>Advanced <productname>Postgres</productname> <acronym>SQL</acronym> Features</title>
<Para> <para>
Having covered the basics of using <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> to Having covered the basics of using
access your data, we will now discuss those features of <productname>e>Postgr</productname>e> <acronym>SQL</acronym> to
<ProductName>Postgres</ProductName> that distinguish it from conventional data access your data, we will now discuss those features of
managers. These features include inheritance, time <productname>Postgres</productname> that distinguish it from conventional data
travel and non-atomic data values (array- and managers. These features include inheritance, time
set-valued attributes). travel and non-atomic data values (array- and
Examples in this section can also be found in set-valued attributes).
<FileName>advance.sql</FileName> in the tutorial directory. Examples in this section can also be found in
(Refer to <XRef LinkEnd="QUERY"> for how to use it.) <filename>advance.sql</filename> in the tutorial directory.
</Para> (Refer to <xref linkend="QUERY"> for how to use it.)
</para>
<Sect1> <sect1>
<Title>Inheritance</Title> <title>Inheritance</title>
<Para> <para>
Let's create two classes. The capitals class contains Let's create two classes. The capitals class contains
state capitals which are also cities. Naturally, the state capitals which are also cities. Naturally, the
capitals class should inherit from cities. capitals class should inherit from cities.
<ProgramListing> <programlisting>
CREATE TABLE cities ( CREATE TABLE cities (
name text, name text,
population float, population float,
altitude int -- (in ft) altitude int -- (in ft)
); );
CREATE TABLE capitals ( CREATE TABLE capitals (
state char2 state char(2)
) INHERITS (cities); ) INHERITS (cities);
</ProgramListing> </programlisting>
In this case, an instance of capitals <FirstTerm>inherits</FirstTerm> all In this case, an instance of capitals <firstterm>inherits</firstterm> all
attributes (name, population, and altitude) from its attributes (name, population, and altitude) from its
parent, cities. The type of the attribute name is parent, cities. The type of the attribute name is
<Type>text</Type>, a native <ProductName>Postgres</ProductName> type for variable length <type>text</type>, a native <productname>Postgres</productname>
ASCII strings. The type of the attribute population is type for variable length
<Type>float</Type>, a native <ProductName>Postgres</ProductName> type for double precision ASCII strings. The type of the attribute population is
floating point numbers. State capitals have an extra <type>float</type>, a native <productname>Postgres</productname>
attribute, state, that shows their state. In <ProductName>Postgres</ProductName>, type for double precision
a class can inherit from zero or more other classes, floating point numbers. State capitals have an extra
and a query can reference either all instances of a attribute, state, that shows their state.
class or all instances of a class plus all of its In <productname>Postgres</productname>,
descendants. a class can inherit from zero or more other classes,
<Note> and a query can reference either all instances of a
<Para> class or all instances of a class plus all of its
The inheritance hierarchy is a directed acyclic graph. descendants.
</Para>
</Note> <note>
For example, the following query finds <para>
all the cities that are situated at an attitude of 500ft or higher: The inheritance hierarchy is a directed acyclic graph.
</para>
</note>
For example, the following query finds
all the cities that are situated at an attitude of 500ft or higher:
<ProgramListing> <programlisting>
SELECT name, altitude SELECT name, altitude
FROM cities FROM cities
WHERE altitude &gt; 500; WHERE altitude &gt; 500;
@ -65,23 +71,23 @@ SELECT name, altitude
+----------+----------+ +----------+----------+
|Mariposa | 1953 | |Mariposa | 1953 |
+----------+----------+ +----------+----------+
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
On the other hand, to find the names of all cities, On the other hand, to find the names of all cities,
including state capitals, that are located at an altitude including state capitals, that are located at an altitude
over 500ft, the query is: over 500ft, the query is:
<ProgramListing> <programlisting>
SELECT c.name, c.altitude SELECT c.name, c.altitude
FROM cities* c FROM cities* c
WHERE c.altitude > 500; WHERE c.altitude > 500;
</ProgramListing> </programlisting>
which returns: which returns:
<ProgramListing> <programlisting>
+----------+----------+ +----------+----------+
|name | altitude | |name | altitude |
+----------+----------+ +----------+----------+
@ -91,60 +97,62 @@ SELECT c.name, c.altitude
+----------+----------+ +----------+----------+
|Madison | 845 | |Madison | 845 |
+----------+----------+ +----------+----------+
</ProgramListing> </programlisting>
Here the <Quote>*</Quote> after cities indicates that the query should Here the <quote>*</quote> after cities indicates that the query should
be run over cities and all classes below cities in the be run over cities and all classes below cities in the
inheritance hierarchy. Many of the commands that we inheritance hierarchy. Many of the commands that we
have already discussed (<Command>select</Command>, <Command>update</Command> and <Command>delete</Command>) have already discussed (<command>select</command>,
support this <Quote>*</Quote> notation, as do others, like <Command>alter</Command>. <command>and>up</command>and> and <command>delete</command>)
</Para> support this <quote>*</quote> notation, as do others, like
<command>alter</command>.
</para>
</sect1>
</Sect1> <sect1>
<title>Non-Atomic Values</title>
<Sect1> <para>
<Title>Non-Atomic Values</Title> One of the tenets of the relational model is that the
attributes of a relation are atomic. <productname>Postgres</productname> does not
have this restriction; attributes can themselves contain
sub-values that can be accessed from the query
language. For example, you can create attributes that
are arrays of base types.
</para>
<Para> <sect2>
One of the tenets of the relational model is that the <title>Arrays</title>
attributes of a relation are atomic. <ProductName>Postgres</ProductName> does not
have this restriction; attributes can themselves contain
sub-values that can be accessed from the query
language. For example, you can create attributes that
are arrays of base types.
</Para>
<Sect2> <para>
<Title>Arrays</Title> <productname>Postgres</productname> allows attributes of an instance to be defined
<Para>
<ProductName>Postgres</ProductName> allows attributes of an instance to be defined
as fixed-length or variable-length multi-dimensional as fixed-length or variable-length multi-dimensional
arrays. Arrays of any base type or user-defined type arrays. Arrays of any base type or user-defined type
can be created. To illustrate their use, we first create a can be created. To illustrate their use, we first create a
class with arrays of base types. class with arrays of base types.
<ProgramListing> <programlisting>
CREATE TABLE SAL_EMP ( CREATE TABLE SAL_EMP (
name text, name text,
pay_by_quarter int4[], pay_by_quarter int4[],
schedule text[][] schedule text[][]
); );
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
The above query will create a class named SAL_EMP with The above query will create a class named SAL_EMP with
a <FirstTerm>text</FirstTerm> string (name), a one-dimensional array of <FirstTerm>int4</FirstTerm> a <firstterm>text</firstterm> string (name), a one-dimensional
array of <firstterm>int4</firstterm>
(pay_by_quarter), which represents the employee's (pay_by_quarter), which represents the employee's
salary by quarter and a two-dimensional array of <FirstTerm>text</FirstTerm> salary by quarter and a two-dimensional array of <firstterm>text</firstterm>
(schedule), which represents the employee's weekly (schedule), which represents the employee's weekly
schedule. Now we do some <FirstTerm>INSERTS</FirstTerm>s; note that when schedule. Now we do some <firstterm>INSERTS</firstterm>s; note that when
appending to an array, we enclose the values within appending to an array, we enclose the values within
braces and separate them by commas. If you know <FirstTerm>C</FirstTerm>, braces and separate them by commas. If you know <firstterm>C</firstterm>,
this is not unlike the syntax for initializing structures. this is not unlike the syntax for initializing structures.
<ProgramListing> <programlisting>
INSERT INTO SAL_EMP INSERT INTO SAL_EMP
VALUES ('Bill', VALUES ('Bill',
'{10000, 10000, 10000, 10000}', '{10000, 10000, 10000, 10000}',
@ -154,16 +162,17 @@ INSERT INTO SAL_EMP
VALUES ('Carol', VALUES ('Carol',
'{20000, 25000, 25000, 25000}', '{20000, 25000, 25000, 25000}',
'{{"talk", "consult"}, {"meeting"}}'); '{{"talk", "consult"}, {"meeting"}}');
</ProgramListing> </programlisting>
By default, <ProductName>Postgres</ProductName> uses the "one-based" numbering By default, <productname>Postgres</productname> uses the "one-based" numbering
convention for arrays -- that is, an array of n elements starts with array[1] and ends with array[n]. convention for arrays -- that is, an array of n elements
starts with array[1] and ends with array[n].
Now, we can run some queries on SAL_EMP. First, we Now, we can run some queries on SAL_EMP. First, we
show how to access a single element of an array at a show how to access a single element of an array at a
time. This query retrieves the names of the employees time. This query retrieves the names of the employees
whose pay changed in the second quarter: whose pay changed in the second quarter:
<ProgramListing> <programlisting>
SELECT name SELECT name
FROM SAL_EMP FROM SAL_EMP
WHERE SAL_EMP.pay_by_quarter[1] &lt;&gt; WHERE SAL_EMP.pay_by_quarter[1] &lt;&gt;
@ -174,14 +183,14 @@ SELECT name
+------+ +------+
|Carol | |Carol |
+------+ +------+
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
This query retrieves the third quarter pay of all This query retrieves the third quarter pay of all
employees: employees:
<ProgramListing> <programlisting>
SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP; SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP;
@ -192,15 +201,15 @@ SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP;
+---------------+ +---------------+
|25000 | |25000 |
+---------------+ +---------------+
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
We can also access arbitrary slices of an array, or We can also access arbitrary slices of an array, or
subarrays. This query retrieves the first item on subarrays. This query retrieves the first item on
Bill's schedule for the first two days of the week. Bill's schedule for the first two days of the week.
<ProgramListing> <programlisting>
SELECT SAL_EMP.schedule[1:2][1:1] SELECT SAL_EMP.schedule[1:2][1:1]
FROM SAL_EMP FROM SAL_EMP
WHERE SAL_EMP.name = 'Bill'; WHERE SAL_EMP.name = 'Bill';
@ -210,41 +219,43 @@ SELECT SAL_EMP.schedule[1:2][1:1]
+-------------------+ +-------------------+
|{{"meeting"},{""}} | |{{"meeting"},{""}} |
+-------------------+ +-------------------+
</ProgramListing> </programlisting>
</Para> </para>
</sect2> </sect2>
</Sect1> </sect1>
<Sect1> <sect1>
<Title>Time Travel</Title> <title>Time Travel</title>
<Para> <para>
As of <ProductName>Postgres</ProductName> v6.2, <Emphasis>time travel is no longer supported</Emphasis>. There are As of <productname>Postgres</productname> v6.2, <emphasis>time
several reasons for this: performance impact, storage size, and a pg_time file which grows travel is no longer supported</emphasis>. There are
toward infinite size in a short period of time. several reasons for this: performance impact, storage size, and a
</Para> pg_time file which grows
toward infinite size in a short period of time.
</para>
<Para> <para>
New features such as triggers allow one to mimic the behavior of time travel when desired, without New features such as triggers allow one to mimic the behavior of time travel when desired, without
incurring the overhead when it is not needed (for most users, this is most of the time). incurring the overhead when it is not needed (for most users, this is most of the time).
See examples in the <FileName>contrib</FileName> directory for more information. See examples in the <filename>contrib</filename> directory for more information.
</Para> </para>
<Note> <note>
<Title>Time travel is deprecated</Title> <title>Time travel is deprecated</title>
<Para> <para>
The remaining text in this section is retained only until it can be rewritten in the context The remaining text in this section is retained only until it can be rewritten in the context
of new techniques to accomplish the same purpose. Volunteers? - thomas 1998-01-12 of new techniques to accomplish the same purpose. Volunteers? - thomas 1998-01-12
</Para> </para>
</Note> </note>
<Para> <para>
<ProductName>Postgres</ProductName> supports the notion of time travel. This feature <productname>Postgres</productname> supports the notion of time travel. This feature
allows a user to run historical queries. For allows a user to run historical queries. For
example, to find the current population of Mariposa example, to find the current population of Mariposa
city, one would query: city, one would query:
<ProgramListing> <programlisting>
SELECT * FROM cities WHERE name = 'Mariposa'; SELECT * FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+ +---------+------------+----------+
@ -252,34 +263,35 @@ SELECT * FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+ +---------+------------+----------+
|Mariposa | 1320 | 1953 | |Mariposa | 1320 | 1953 |
+---------+------------+----------+ +---------+------------+----------+
</ProgramListing> </programlisting>
<ProductName>Postgres</ProductName> will automatically find the version of Mariposa's <productname>Postgres</productname> will automatically find the version of Mariposa's
record valid at the current time. record valid at the current time.
One can also give a time range. For example to see the One can also give a time range. For example to see the
past and present populations of Mariposa, one would past and present populations of Mariposa, one would
query: query:
<ProgramListing> <programlisting>
SELECT name, population SELECT name, population
FROM cities['epoch', 'now'] FROM cities['epoch', 'now']
WHERE name = 'Mariposa'; WHERE name = 'Mariposa';
</ProgramListing> </programlisting>
where "epoch" indicates the beginning of the system where "epoch" indicates the beginning of the system
clock. clock.
<Note>
<Para>
On UNIX systems, this is always midnight, January 1, 1970 GMT.
</Para>
</Note>
</Para>
<Para> <note>
If you have executed all of the examples so <para>
far, then the above query returns: On UNIX systems, this is always midnight, January 1, 1970 GMT.
</para>
<ProgramListing> </note>
</para>
<para>
If you have executed all of the examples so
far, then the above query returns:
<programlisting>
+---------+------------+ +---------+------------+
|name | population | |name | population |
+---------+------------+ +---------+------------+
@ -287,25 +299,43 @@ On UNIX systems, this is always midnight, January 1, 1970 GMT.
+---------+------------+ +---------+------------+
|Mariposa | 1320 | |Mariposa | 1320 |
+---------+------------+ +---------+------------+
</ProgramListing> </programlisting>
</Para> </para>
<Para> <para>
The default beginning of a time range is the earliest The default beginning of a time range is the earliest
time representable by the system and the default end is time representable by the system and the default end is
the current time; thus, the above time range can be the current time; thus, the above time range can be
abbreviated as ``[,].'' abbreviated as ``[,].''
</Para> </para>
</sect1> </sect1>
<Sect1> <sect1>
<Title>More Advanced Features</Title> <title>More Advanced Features</title>
<Para> <para>
<ProductName>Postgres</ProductName> has many features not touched upon in this <productname>Postgres</productname> has many features not touched upon in this
tutorial introduction, which has been oriented toward newer users of <Acronym>SQL</Acronym>. tutorial introduction, which has been oriented toward newer users of
These are discussed in more detail in both the User's and Programmer's Guides. <acronym>SQL</acronym>.
</Para> These are discussed in more detail in both the User's and Programmer's Guides.
</para>
</sect1> </sect1>
</Chapter> </chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

122
doc/src/sgml/inherit.sgml
View File

@ -1,44 +1,46 @@
<Chapter Id="inherit"> <chapter id="inherit">
<Title>Inheritance</Title> <title>Inheritance</title>
<Para> <para>
Let's create two classes. The capitals class contains Let's create two classes. The capitals class contains
state capitals which are also cities. Naturally, the state capitals which are also cities. Naturally, the
capitals class should inherit from cities. capitals class should inherit from cities.
<ProgramListing> <programlisting>
CREATE TABLE cities ( CREATE TABLE cities (
name text, name text,
population float, population float,
altitude int -- (in ft) altitude int -- (in ft)
); );
CREATE TABLE capitals ( CREATE TABLE capitals (
state char2 state char(2)
) INHERITS (cities); ) INHERITS (cities);
</ProgramListing> </programlisting>
In this case, an instance of capitals <FirstTerm>inherits</FirstTerm> all In this case, an instance of capitals <firstterm>inherits</firstterm> all
attributes (name, population, and altitude) from its attributes (name, population, and altitude) from its
parent, cities. The type of the attribute name is parent, cities. The type of the attribute name is
<Type>text</Type>, a native <ProductName>Postgres</ProductName> type for variable length <type>text</type>, a native <productname>Postgres</productname> type for variable length
ASCII strings. The type of the attribute population is ASCII strings. The type of the attribute population is
<Type>float</Type>, a native <ProductName>Postgres</ProductName> type for double precision <type>float</type>, a native <productname>Postgres</productname> type for double precision
floating point numbers. State capitals have an extra floating point numbers. State capitals have an extra
attribute, state, that shows their state. In <ProductName>Postgres</ProductName>, attribute, state, that shows their state. In <productname>Postgres</productname>,
a class can inherit from zero or more other classes, a class can inherit from zero or more other classes,
and a query can reference either all instances of a and a query can reference either all instances of a
class or all instances of a class plus all of its class or all instances of a class plus all of its
descendants. descendants.
<Note>
<Para> <note>
The inheritance hierarchy is a actually a directed acyclic graph. <para>
</Para> The inheritance hierarchy is a actually a directed acyclic graph.
</Note> </para>
For example, the following query finds </note>
all the cities that are situated at an attitude of 500ft or higher:
For example, the following query finds
<ProgramListing> all the cities that are situated at an attitude of 500ft or higher:
<programlisting>
SELECT name, altitude SELECT name, altitude
FROM cities FROM cities
WHERE altitude &gt; 500; WHERE altitude &gt; 500;
@ -50,23 +52,23 @@ SELECT name, altitude
+----------+----------+ +----------+----------+
|Mariposa | 1953 | |Mariposa | 1953 |
+----------+----------+ +----------+----------+
</ProgramListing> </programlisting>
</para> </para>
<Para> <para>
On the other hand, to find the names of all cities, On the other hand, to find the names of all cities,
including state capitals, that are located at an altitude including state capitals, that are located at an altitude
over 500ft, the query is: over 500ft, the query is:
<ProgramListing> <programlisting>
SELECT c.name, c.altitude SELECT c.name, c.altitude
FROM cities* c FROM cities* c
WHERE c.altitude > 500; WHERE c.altitude > 500;
</ProgramListing> </programlisting>
which returns: which returns:
<ProgramListing> <programlisting>
+----------+----------+ +----------+----------+
|name | altitude | |name | altitude |
+----------+----------+ +----------+----------+
@ -76,13 +78,31 @@ SELECT c.name, c.altitude
+----------+----------+ +----------+----------+
|Madison | 845 | |Madison | 845 |
+----------+----------+ +----------+----------+
</ProgramListing> </programlisting>
Here the <Quote>*</Quote> after cities indicates that the query should Here the <quote>*</quote> after cities indicates that the query should
be run over cities and all classes below cities in the be run over cities and all classes below cities in the
inheritance hierarchy. Many of the commands that we inheritance hierarchy. Many of the commands that we
have already discussed -- <Command>select</Command>, <Command>update</Command> and <Command>delete</Command> -- have already discussed -- <command>SELECT</command>,
support this <Quote>*</Quote> notation, as do others, like <Command>alter</Command>. <command>UPDATE</command> and <command>DELETE</command> --
</Para> support this <quote>*</quote> notation, as do others, like
<command>ALTER TABLE</command>.
</para>
</chapter>
</Chapter> <!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

16
doc/src/sgml/libpq++.sgml
View File

@ -737,14 +737,14 @@
As an example: As an example:
<programlisting> <programlisting>
PgDatabase data; PgDatabase data;
data.Exec("create table foo (a int4, b char16, d float8)"); data.Exec("create table foo (a int4, b char(16), d float8)");
data.Exec("copy foo from stdin"); data.Exec("copy foo from stdin");
data.putline("3\etHello World\et4.5\en"); data.putline("3\etHello World\et4.5\en");
data.putline("4\etGoodbye World\et7.11\en"); data.putline("4\etGoodbye World\et7.11\en");
&amp;... &amp;...
data.putline(".\en"); data.putline(".\en");
data.endcopy(); data.endcopy();
</programlisting> </programlisting>
</para> </para>
</sect1> </sect1>