Skip to content

P
Postgres FD Implementation
Commit ba3a99f1 authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Split function and operator User Guide info 

 from datatype.sgml into separate files.
Add type conversion information.
Format historical release notes.
parent febe53d8
Show whitespace changes
Inline Side-by-side
Showing with 3436 additions and 833 deletions
doc/src/sgml/datatype.sgml
View file @ ba3a99f1
...@@ -190,26 +190,38 @@ several possibilities for formats, such as date and time types. ...@@ -190,26 +190,38 @@ several possibilities for formats, such as date and time types.
<Para> <Para>
<ProductName>Postgres</ProductName> has features at the forefront of ORDBMS development. In addition to <ProductName>Postgres</ProductName> has features at the forefront of ORDBMS development. In addition to
SQL3 conformance, substantial portions of SQL92 are also supported. SQL3 conformance, substantial portions of SQL92 are also supported.
Although we strive for SQL92 compliance, there are some cases in the standard Although we strive for SQL92 compliance, there are some aspects of the standard
which are ill considered and which should not live through subsequent standards. which are ill considered and which should not live through subsequent standards.
<ProductName>Postgres</ProductName> will not make great efforts to conform to these cases. However, these <ProductName>Postgres</ProductName> will not make great efforts to conform to these aspects;
cases tend to be little-used and obsure, and a typical user is not likely to however, these
tend to apply in little-used or obsure cases, and a typical user is not likely to
run into them. run into them.
<Para> <Para>
Although most of the input and output functions corresponding to the Most of the input and output functions corresponding to the
base types (e.g., integers and floating point numbers) do some base types (e.g., integers and floating point numbers) do some
error-checking, some are not particularly rigorous about it. More error-checking.
importantly, few of the operators and functions (e.g., Some of the operators and functions (e.g.,
addition and multiplication) perform any error-checking at all. addition and multiplication) do not perform run-time error-checking in the
Consequently, many of the numeric operators can (for example) interests of improving execution speed.
On some systems, for example, the numeric operators for some data types may
silently underflow or overflow. silently underflow or overflow.
</Para> </Para>
<Para> <Para>
Some of the input and output functions are not invertible. That is, Note that some of the input and output functions are not invertible. That is,
the result of an output function may lose precision when compared to the result of an output function may lose precision when compared to
the original input. the original input.
<note>
<para>
The original <ProductName>Postgres</ProductName> v4.2 code received from
Berkeley rounded all double precision floating point results to six digits for
output. Starting with v6.1, floating point numbers are allowed to retain
most of the intrinsic precision of the type (typically 15 digits for doubles, 6 digits
for 4-byte floats). Other types with underlying floating point fields (e.g. geometric
types) carry similar precision.
</note>
</Para> </Para>
<Sect1> <Sect1>
...@@ -245,17 +257,23 @@ floating point numbers. ...@@ -245,17 +257,23 @@ floating point numbers.
<ENTRY>Usual choice for fixed-precision</ENTRY> <ENTRY>Usual choice for fixed-precision</ENTRY>
<ENTRY>-2147483648 to +2147483647</ENTRY> <ENTRY>-2147483648 to +2147483647</ENTRY>
</ROW> </ROW>
<ROW>
<ENTRY>int8</ENTRY>
<ENTRY>8 bytes</ENTRY>
<ENTRY>Very large range fixed-precision</ENTRY>
<ENTRY>+/- &gt; 18 decimal places</ENTRY>
</ROW>
<ROW> <ROW>
<ENTRY>float4</ENTRY> <ENTRY>float4</ENTRY>
<ENTRY>4 bytes</ENTRY> <ENTRY>4 bytes</ENTRY>
<ENTRY>Variable-precision</ENTRY> <ENTRY>Variable-precision</ENTRY>
<ENTRY>7 decimal places</ENTRY> <ENTRY>6 decimal places</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>float8</ENTRY> <ENTRY>float8</ENTRY>
<ENTRY>8 bytes</ENTRY> <ENTRY>8 bytes</ENTRY>
<ENTRY>Variable-precision</ENTRY> <ENTRY>Variable-precision</ENTRY>
<ENTRY>14 decimal places</ENTRY> <ENTRY>15 decimal places</ENTRY>
</ROW> </ROW>
</TBODY> </TBODY>
</TGROUP> </TGROUP>
...@@ -266,6 +284,7 @@ floating point numbers. ...@@ -266,6 +284,7 @@ floating point numbers.
The <FirstTerm>exact numerics</FirstTerm> <Type>decimal</Type> and <Type>numeric</Type> The <FirstTerm>exact numerics</FirstTerm> <Type>decimal</Type> and <Type>numeric</Type>
have fully implemented syntax but currently (<ProductName>Postgres</ProductName> v6.3) have fully implemented syntax but currently (<ProductName>Postgres</ProductName> v6.3)
support only a small range of precision and/or range values. support only a small range of precision and/or range values.
The <type>int8</type> type may not be available on all platforms.
</Para> </Para>
</Sect1> </Sect1>
...@@ -1267,790 +1286,3 @@ Circles are output using the first syntax. ...@@ -1267,790 +1286,3 @@ Circles are output using the first syntax.
</Sect1> </Sect1>
<Chapter>
<Title>Operators</Title>
<Para>
<ProductName>Postgres</ProductName> provides a large number of built-in operators on system types.
These operators are declared in the system catalog
pg_operator. Every entry in pg_operator includes
the name of the procedure that implements the operator and the
class <Acronym>OIDs</Acronym> of the input and output types.
<Para>
To view all variations of the <Quote>||</Quote> string concatenation operator, try
<ProgramListing>
SELECT oprleft, oprright, oprresult, oprcode
FROM pg_operator WHERE oprname = '||';
oprleft|oprright|oprresult|oprcode
-------+--------+---------+-------
25| 25| 25|textcat
1042| 1042| 1042|textcat
1043| 1043| 1043|textcat
(3 rows)
</ProgramListing>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> &lt; </ENTRY>
<ENTRY>Less than?</ENTRY>
<ENTRY>1 &lt; 2</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;= </ENTRY>
<ENTRY>Less than or equal to?</ENTRY>
<ENTRY>1 &lt;= 2</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;&gt; </ENTRY>
<ENTRY>Not equal?</ENTRY>
<ENTRY>1 &lt;&gt; 2</ENTRY>
</ROW>
<ROW>
<ENTRY> = </ENTRY>
<ENTRY>Equal?</ENTRY>
<ENTRY>1 = 1</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt; </ENTRY>
<ENTRY>Greater than?</ENTRY>
<ENTRY>2 &gt; 1</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt;= </ENTRY>
<ENTRY>Greater than or equal to?</ENTRY>
<ENTRY>2 &gt;= 1</ENTRY>
</ROW>
<ROW>
<ENTRY> || </ENTRY>
<ENTRY>Concatenate strings</ENTRY>
<ENTRY>'Postgre' || 'SQL'</ENTRY>
</ROW>
<ROW>
<ENTRY> !!= </ENTRY>
<ENTRY>NOT IN</ENTRY>
<ENTRY>3 !!= i</ENTRY>
</ROW>
<ROW>
<ENTRY> ~~ </ENTRY>
<ENTRY>LIKE</ENTRY>
<ENTRY>'scrappy,marc,hermit' ~~ '%scrappy%'</ENTRY>
</ROW>
<ROW>
<ENTRY> !~~ </ENTRY>
<ENTRY>NOT LIKE</ENTRY>
<ENTRY>'bruce' !~~ '%al%'</ENTRY>
</ROW>
<ROW>
<ENTRY> ~ </ENTRY>
<ENTRY>Match (regex), case sensitive</ENTRY>
<ENTRY>'thomas' ~ '*.thomas*.'</ENTRY>
</ROW>
<ROW>
<ENTRY> ~* </ENTRY>
<ENTRY>Match (regex), case insensitive</ENTRY>
<ENTRY>'thomas' ~* '*.Thomas*.'</ENTRY>
</ROW>
<ROW>
<ENTRY> !~ </ENTRY>
<ENTRY>Does not match (regex), case sensitive</ENTRY>
<ENTRY>'thomas' !~ '*.Thomas*.'</ENTRY>
</ROW>
<ROW>
<ENTRY> !~* </ENTRY>
<ENTRY>Does not match (regex), case insensitive</ENTRY>
<ENTRY>'thomas' !~ '*.vadim*.'</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Numerical Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> ! </ENTRY>
<ENTRY>Factorial</ENTRY>
<ENTRY>3 !</ENTRY>
</ROW>
<ROW>
<ENTRY> !! </ENTRY>
<ENTRY>Factorial (left operator)</ENTRY>
<ENTRY>!! 3</ENTRY>
</ROW>
<ROW>
<ENTRY> % </ENTRY>
<ENTRY>Modulo</ENTRY>
<ENTRY>5 % 4</ENTRY>
</ROW>
<ROW>
<ENTRY> % </ENTRY>
<ENTRY>Truncate</ENTRY>
<ENTRY>% 4.5</ENTRY>
</ROW>
<ROW>
<ENTRY> * </ENTRY>
<ENTRY>Multiplication</ENTRY>
<ENTRY>2 * 3</ENTRY>
</ROW>
<ROW>
<ENTRY> + </ENTRY>
<ENTRY>Addition</ENTRY>
<ENTRY>2 + 3</ENTRY>
</ROW>
<ROW>
<ENTRY> - </ENTRY>
<ENTRY>Subtraction</ENTRY>
<ENTRY>2 - 3</ENTRY>
</ROW>
<ROW>
<ENTRY> / </ENTRY>
<ENTRY>Division</ENTRY>
<ENTRY>4 / 2</ENTRY>
</ROW>
<ROW>
<ENTRY> : </ENTRY>
<ENTRY>Natural Exponentiation</ENTRY>
<ENTRY>: 3.0</ENTRY>
</ROW>
<ROW>
<ENTRY> ; </ENTRY>
<ENTRY>Natural Logarithm</ENTRY>
<ENTRY>(; 5.0)</ENTRY>
</ROW>
<ROW>
<ENTRY> @ </ENTRY>
<ENTRY>Absolute value</ENTRY>
<ENTRY>@ -5.0</ENTRY>
</ROW>
<ROW>
<ENTRY> ^ </ENTRY>
<ENTRY>Exponentiation</ENTRY>
<ENTRY>2.0 ^ 3.0</ENTRY>
</ROW>
<ROW>
<ENTRY> |/ </ENTRY>
<ENTRY>Square root</ENTRY>
<ENTRY>|/ 25.0</ENTRY>
</ROW>
<ROW>
<ENTRY> ||/ </ENTRY>
<ENTRY>Cube root</ENTRY>
<ENTRY>||/ 27.0</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Geometric Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> + </ENTRY>
<ENTRY>Translation</ENTRY>
<ENTRY>'((0,0),(1,1))'::box + '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> - </ENTRY>
<ENTRY>Translation</ENTRY>
<ENTRY>'((0,0),(1,1))'::box - '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> * </ENTRY>
<ENTRY>Scaling/rotation</ENTRY>
<ENTRY>'((0,0),(1,1))'::box * '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> / </ENTRY>
<ENTRY>Scaling/rotation</ENTRY>
<ENTRY>'((0,0),(2,2))'::box / '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> # </ENTRY>
<ENTRY>Intersection</ENTRY>
<ENTRY>'((1,-1),(-1,1))' # '((1,1),(-1,-1))'</ENTRY>
</ROW>
<ROW>
<ENTRY> # </ENTRY>
<ENTRY>Number of points in polygon</ENTRY>
<ENTRY># '((1,0),(0,1),(-1,0))'</ENTRY>
</ROW>
<ROW>
<ENTRY> ## </ENTRY>
<ENTRY>Point of closest proximity</ENTRY>
<ENTRY>'(0,0)'::point ## '((2,0),(0,2))'::lseg</ENTRY>
</ROW>
<ROW>
<ENTRY> &amp;&amp; </ENTRY>
<ENTRY>Overlaps?</ENTRY>
<ENTRY>'((0,0),(1,1))'::box &amp;&amp; '((0,0),(2,2))'::box</ENTRY>
</ROW>
<ROW>
<ENTRY> &amp;&lt; </ENTRY>
<ENTRY>Overlaps to left?</ENTRY>
<ENTRY>'((0,0),(1,1))'::box &amp;&lt; '((0,0),(2,2))'::box</ENTRY>
</ROW>
<ROW>
<ENTRY> &amp;&gt; </ENTRY>
<ENTRY>Overlaps to right?</ENTRY>
<ENTRY>'((0,0),(3,3))'::box &amp;&gt; '((0,0),(2,2))'::box</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;-&gt; </ENTRY>
<ENTRY>Distance between</ENTRY>
<ENTRY>'((0,0),1)'::circle &lt;-&gt; '((5,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;&lt; </ENTRY>
<ENTRY>Left of?</ENTRY>
<ENTRY>'((0,0),1)'::circle &lt;&lt; '((5,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;^ </ENTRY>
<ENTRY>Is below?</ENTRY>
<ENTRY>'((0,0),1)'::circle &lt;^ '((0,5),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt;&gt; </ENTRY>
<ENTRY>Is right of?</ENTRY>
<ENTRY>'((5,0),1)'::circle &gt;&gt; '((0,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt;^ </ENTRY>
<ENTRY>Is above?</ENTRY>
<ENTRY>'((0,5),1)'::circle >^ '((0,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> ?# </ENTRY>
<ENTRY>Intersects or overlaps</ENTRY>
<ENTRY>'((-1,0),(1,0))'::lseg ?# '((-2,-2),(2,2))'::box;</ENTRY>
</ROW>
<ROW>
<ENTRY> ?- </ENTRY>
<ENTRY>Is horizontal?</ENTRY>
<ENTRY>'(1,0)'::point ?- '(0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> ?-| </ENTRY>
<ENTRY>Is perpendicular?</ENTRY>
<ENTRY>'((0,0),(0,1))'::lseg ?-| '((0,0),(1,0))'::lseg</ENTRY>
</ROW>
<ROW>
<ENTRY> @-@ </ENTRY>
<ENTRY>Length or circumference</ENTRY>
<ENTRY>@-@ '((0,0),(1,0))'::path</ENTRY>
</ROW>
<ROW>
<ENTRY> ?| </ENTRY>
<ENTRY>Is vertical?</ENTRY>
<ENTRY>'(0,1)'::point ?| '(0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> ?|| </ENTRY>
<ENTRY>Is parallel?</ENTRY>
<ENTRY>'((-1,0),(1,0))'::lseg ?|| '((-1,2),(1,2))'::lseg</ENTRY>
</ROW>
<ROW>
<ENTRY> @ </ENTRY>
<ENTRY>Contained or on</ENTRY>
<ENTRY>'(1,1)'::point @ '((0,0),2)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> @@ </ENTRY>
<ENTRY>Center of</ENTRY>
<ENTRY>@@ '((0,0),10)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> ~= </ENTRY>
<ENTRY>Same as</ENTRY>
<ENTRY>'((0,0),(1,1))'::polygon ~= '((1,1),(0,0))'::polygon</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
The time interval data type <Type>tinterval</Type> is a legacy from the original
date/time types and is not as well supported as the more modern types. There
are several operators for this type.
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Time Interval Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> #&lt; </ENTRY>
<ENTRY>Interval less than?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&lt;= </ENTRY>
<ENTRY>Interval less than or equal to?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&lt;&gt; </ENTRY>
<ENTRY>Interval not equal?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #= </ENTRY>
<ENTRY>Interval equal?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&gt; </ENTRY>
<ENTRY>Interval greater than?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&gt;= </ENTRY>
<ENTRY>Interval greater than or equal to?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;#&gt; </ENTRY>
<ENTRY>Convert to time interval</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;&lt; </ENTRY>
<ENTRY>Interval less than?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> | </ENTRY>
<ENTRY>Start of interval</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> ~= </ENTRY>
<ENTRY>Same as</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;?&gt; </ENTRY>
<ENTRY>Time inside interval?</ENTRY>
<ENTRY></ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
Users may invoke operators using the operator name, as in:
<ProgramListing>
select * from emp where salary < 40000;
</ProgramListing>
Alternatively, users may call the functions that implement the
operators directly. In this case, the query above would be expressed
as:
<ProgramListing>
select * from emp where int4lt(salary, 40000);
</ProgramListing>
<Para>
<Application>psql</Application>
has a <Command>\dd</Command> command to show these operators.
</Chapter>
<Chapter>
<Title>Functions</Title>
<Para>
Many data types have functions available for conversion to other related types.
In addition, there are some type-specific functions. Functions which are also
available through operators are documented as operators only.
</Para>
<Para>
Some functions defined for text are also available for char() and varchar().
</Para>
<Para>
For the
<Function>date_part</Function> and <Function>date_trunc</Function>
functions, arguments can be
`year', `month', `day', `hour', `minute', and `second',
as well as the more specialized quantities
`decade', `century', `millenium', `millisecond', and `microsecond'.
<Function>date_part</Function> allows `dow'
to return day of week and `epoch' to return seconds since 1970 (for <Type>datetime</Type>)
or 'epoch' to return total elapsed seconds (for <Type>timespan</Type>).
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Mathematical Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> float(int) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> convert integer to floating point </ENTRY>
<ENTRY> float(2) </ENTRY>
</ROW>
<ROW>
<ENTRY> float4(int) </ENTRY>
<ENTRY> float4 </ENTRY>
<ENTRY> convert integer to floating point </ENTRY>
<ENTRY> float4(2) </ENTRY>
</ROW>
<ROW>
<ENTRY> int </ENTRY>
<ENTRY> integer(float) </ENTRY>
<ENTRY> convert floating point to integer </ENTRY>
<ENTRY> integer(2.0) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
Many of the string functions are available for text, varchar(), and char() types.
At the moment, some functions are available only for the text type.
<TABLE TOCENTRY="1">
<TITLE>String Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> lower(text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> convert text to lower case </ENTRY>
<ENTRY> lower('TOM') </ENTRY>
</ROW>
<ROW>
<ENTRY> lpad(text,int,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> left pad string to specified length </ENTRY>
<ENTRY> lpad('hi',4,'??') </ENTRY>
</ROW>
<ROW>
<ENTRY> ltrim(text,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> left trim characters from text </ENTRY>
<ENTRY> ltrim('xxxxtrim','x') </ENTRY>
</ROW>
<ROW>
<ENTRY> position(text,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> position('high','ig') </ENTRY>
</ROW>
<ROW>
<ENTRY> rpad(text,int,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> right pad string to specified length </ENTRY>
<ENTRY> rpad('hi',4,'x') </ENTRY>
</ROW>
<ROW>
<ENTRY> rtrim(text,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> right trim characters from text </ENTRY>
<ENTRY> rtrim('trimxxxx','x') </ENTRY>
</ROW>
<ROW>
<ENTRY> substr(text,int[,int]) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> substr('hi there',3,5) </ENTRY>
</ROW>
<ROW>
<ENTRY> upper(text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> convert text to upper case </ENTRY>
<ENTRY> upper('tom') </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Date/Time Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> isfinite(abstime) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a finite time </ENTRY>
<ENTRY> isfinite('now'::abstime) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(abstime) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('now'::abstime) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(date) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('today'::date) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(date,time) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('1998-02-24'::datetime, '23:07'::time); </ENTRY>
</ROW>
<ROW>
<ENTRY> age(datetime,datetime) </ENTRY>
<ENTRY> timespan </ENTRY>
<ENTRY> span preserving months and years </ENTRY>
<ENTRY> age('now','1957-06-13'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> date_part(text,datetime) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> specified portion of date field </ENTRY>
<ENTRY> date_part('dow','now'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> date_trunc(text,datetime) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> truncate date at specified units </ENTRY>
<ENTRY> date_trunc('month','now'::abstime) </ENTRY>
</ROW>
<ROW>
<ENTRY> isfinite(datetime) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a finite time </ENTRY>
<ENTRY> isfinite('now'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> abstime(datetime) </ENTRY>
<ENTRY> abstime </ENTRY>
<ENTRY> convert to abstime </ENTRY>
<ENTRY> abstime('now'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> timespan(reltime) </ENTRY>
<ENTRY> timespan </ENTRY>
<ENTRY> convert to timespan </ENTRY>
<ENTRY> timespan('4 hours'::reltime) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(date,time) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('1998-02-25'::date,'06:41'::time) </ENTRY>
</ROW>
<ROW>
<ENTRY> date_part(text,timespan) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> specified portion of time field </ENTRY>
<ENTRY> date_part('hour','4 hrs 3 mins'::timespan) </ENTRY>
</ROW>
<ROW>
<ENTRY> isfinite(timespan) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a finite time </ENTRY>
<ENTRY> isfinite('4 hrs'::timespan) </ENTRY>
</ROW>
<ROW>
<ENTRY> reltime(timespan) </ENTRY>
<ENTRY> reltime </ENTRY>
<ENTRY> convert to reltime </ENTRY>
<ENTRY> reltime('4 hrs'::timespan) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Geometric Functions</TITLE>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> box(point,point) </ENTRY>
<ENTRY> box </ENTRY>
<ENTRY> convert points to box </ENTRY>
<ENTRY> box('(0,0)'::point,'(1,1)'::point) </ENTRY>
</ROW>
<ROW>
<ENTRY> area(box) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> area of box </ENTRY>
<ENTRY> area('((0,0),(1,1))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> isopen(path) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is an open path </ENTRY>
<ENTRY> isopen('[(0,0),(1,1),(2,0)]'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> isclosed(path) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a closed path </ENTRY>
<ENTRY> isclosed('((0,0),(1,1),(2,0))'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> circle(point,float8) </ENTRY>
<ENTRY> circle </ENTRY>
<ENTRY> convert to circle </ENTRY>
<ENTRY> circle('(0,0)'::point,2.0) </ENTRY>
</ROW>
<ROW>
<ENTRY> polygon(npts,circle) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert to polygon with npts points </ENTRY>
<ENTRY> polygon(12,'((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> center(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> center of object </ENTRY>
<ENTRY> center('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> radius(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> radius of circle </ENTRY>
<ENTRY> radius('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> diameter(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> diameter of circle </ENTRY>
<ENTRY> diameter('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> area(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> area of circle </ENTRY>
<ENTRY> area('((0,0),2.0)'::circle) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
SQL92 defines functions with specific syntax. Some of these
are implemented using other <ProductName>Postgres</ProductName> functions.
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE><Acronym>SQL92</Acronym> Text Functions</TITLE>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> position(text in text) </ENTRY>
<ENTRY> int4 </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> position('o' in 'Tom') </ENTRY>
</ROW>
<ROW>
<ENTRY> substring(text [from int] [for int]) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> substring('Tom' from 2 for 2) </ENTRY>
</ROW>
<ROW>
<ENTRY> trim([leading|trailing|both] [text] from text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> trim characters from text </ENTRY>
<ENTRY> trim(both 'x' from 'xTomx') </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
doc/src/sgml/docguide.sgml
View file @ ba3a99f1
...@@ -239,7 +239,7 @@ right, and I can verify the document with "nsgmls -s docguide.sgml". ...@@ -239,7 +239,7 @@ right, and I can verify the document with "nsgmls -s docguide.sgml".
<title>Building Documentation</title> <title>Building Documentation</title>
<para> <para>
GNU <programname>make</programname> is used to build documentation from the DocBook sources. GNU <application>make</application> is used to build documentation from the DocBook sources.
There are a few environment definitions which may need to be set or modified for your installation. There are a few environment definitions which may need to be set or modified for your installation.
The <filename>Makefile</filename> looks for The <filename>Makefile</filename> looks for
<filename>doc/../src/Makefile</filename> <filename>doc/../src/Makefile</filename>
......
doc/src/sgml/func.sgml 0 → 100644
View file @ ba3a99f1
<Chapter>
<Title>Functions</Title>
<Abstract>
<Para>
Describes the built-in functions available in <ProductName>Postgres</ProductName>.
</Para>
</Abstract>
<Para>
Many data types have functions available for conversion to other related types.
In addition, there are some type-specific functions. Some functions are also
available through operators and may be documented as operators only.
</Para>
<sect1>
<title>Mathematical Functions</title>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Mathematical Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> dexp(float8) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> raise e to the specified exponent </ENTRY>
<ENTRY> dexp(2.0) </ENTRY>
</ROW>
<ROW>
<ENTRY> dpow(float8,float8) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> raise a number to the specified exponent </ENTRY>
<ENTRY> dpow(2.0, 16.0) </ENTRY>
</ROW>
<ROW>
<ENTRY> float(int) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> convert integer to floating point </ENTRY>
<ENTRY> float(2) </ENTRY>
</ROW>
<ROW>
<ENTRY> float4(int) </ENTRY>
<ENTRY> float4 </ENTRY>
<ENTRY> convert integer to floating point </ENTRY>
<ENTRY> float4(2) </ENTRY>
</ROW>
<ROW>
<ENTRY> integer(float) </ENTRY>
<ENTRY> int </ENTRY>
<ENTRY> convert floating point to integer </ENTRY>
<ENTRY> integer(2.0) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<sect1>
<title>String Functions</title>
<Para>
SQL92 defines string functions with specific syntax. Some of these
are implemented using other <ProductName>Postgres</ProductName> functions.
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE><Acronym>SQL92</Acronym> Text Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> position(text in text) </ENTRY>
<ENTRY> int4 </ENTRY>
<ENTRY> location of specified substring </ENTRY>
<ENTRY> position('o' in 'Tom') </ENTRY>
</ROW>
<ROW>
<ENTRY> substring(text [from int] [for int]) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> substring('Tom' from 2 for 2) </ENTRY>
</ROW>
<ROW>
<ENTRY> trim([leading|trailing|both] [text] from text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> trim characters from text </ENTRY>
<ENTRY> trim(both 'x' from 'xTomx') </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
Many string functions are available for text, varchar(), and char() types.
Some are used internally to implement the SQL92 string functions listed above.
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>String Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> char(text) </ENTRY>
<ENTRY> char </ENTRY>
<ENTRY> convert text to char type </ENTRY>
<ENTRY> char('text string') </ENTRY>
</ROW>
<ROW>
<ENTRY> char(varchar) </ENTRY>
<ENTRY> char </ENTRY>
<ENTRY> convert varchar to char type </ENTRY>
<ENTRY> char(varchar 'varchar string') </ENTRY>
</ROW>
<ROW>
<ENTRY> lower(text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> convert text to lower case </ENTRY>
<ENTRY> lower('TOM') </ENTRY>
</ROW>
<ROW>
<ENTRY> lpad(text,int,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> left pad string to specified length </ENTRY>
<ENTRY> lpad('hi',4,'??') </ENTRY>
</ROW>
<ROW>
<ENTRY> ltrim(text,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> left trim characters from text </ENTRY>
<ENTRY> ltrim('xxxxtrim','x') </ENTRY>
</ROW>
<ROW>
<ENTRY> position(text,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> position('high','ig') </ENTRY>
</ROW>
<ROW>
<ENTRY> rpad(text,int,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> right pad string to specified length </ENTRY>
<ENTRY> rpad('hi',4,'x') </ENTRY>
</ROW>
<ROW>
<ENTRY> rtrim(text,text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> right trim characters from text </ENTRY>
<ENTRY> rtrim('trimxxxx','x') </ENTRY>
</ROW>
<ROW>
<ENTRY> substr(text,int[,int]) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> extract specified substring </ENTRY>
<ENTRY> substr('hi there',3,5) </ENTRY>
</ROW>
<ROW>
<ENTRY> text(char) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> convert char to text type </ENTRY>
<ENTRY> text('char string') </ENTRY>
</ROW>
<ROW>
<ENTRY> text(varchar) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> convert varchar to text type </ENTRY>
<ENTRY> text(varchar 'varchar string') </ENTRY>
</ROW>
<ROW>
<ENTRY> varchar(char) </ENTRY>
<ENTRY> varchar </ENTRY>
<ENTRY> convert char to varchar type </ENTRY>
<ENTRY> varchar('char string') </ENTRY>
</ROW>
<ROW>
<ENTRY> varchar(text) </ENTRY>
<ENTRY> varchar </ENTRY>
<ENTRY> convert text to varchar type </ENTRY>
<ENTRY> varchar('text string') </ENTRY>
</ROW>
<ROW>
<ENTRY> upper(text) </ENTRY>
<ENTRY> text </ENTRY>
<ENTRY> convert text to upper case </ENTRY>
<ENTRY> upper('tom') </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<para>
Most functions explicitly defined for text will work for char() and varchar() arguments.
</para>
<sect1>
<title>Date/Time Functions</title>
<para>
The date/time functions provide a powerful set of tools for manipulating various date/time types.
</para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Date/Time Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> abstime(datetime) </ENTRY>
<ENTRY> abstime </ENTRY>
<ENTRY> convert to abstime </ENTRY>
<ENTRY> abstime('now'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> age(datetime,datetime) </ENTRY>
<ENTRY> timespan </ENTRY>
<ENTRY> span preserving months and years </ENTRY>
<ENTRY> age('now','1957-06-13'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(abstime) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('now'::abstime) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(date) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('today'::date) </ENTRY>
</ROW>
<ROW>
<ENTRY> datetime(date,time) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> convert to datetime </ENTRY>
<ENTRY> datetime('1998-02-24'::datetime, '23:07'::time); </ENTRY>
</ROW>
<ROW>
<ENTRY> date_part(text,datetime) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> specified portion of date field </ENTRY>
<ENTRY> date_part('dow','now'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> date_part(text,timespan) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> specified portion of time field </ENTRY>
<ENTRY> date_part('hour','4 hrs 3 mins'::timespan) </ENTRY>
</ROW>
<ROW>
<ENTRY> date_trunc(text,datetime) </ENTRY>
<ENTRY> datetime </ENTRY>
<ENTRY> truncate date at specified units </ENTRY>
<ENTRY> date_trunc('month','now'::abstime) </ENTRY>
</ROW>
<ROW>
<ENTRY> isfinite(abstime) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a finite time </ENTRY>
<ENTRY> isfinite('now'::abstime) </ENTRY>
</ROW>
<ROW>
<ENTRY> isfinite(datetime) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a finite time </ENTRY>
<ENTRY> isfinite('now'::datetime) </ENTRY>
</ROW>
<ROW>
<ENTRY> isfinite(timespan) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a finite time </ENTRY>
<ENTRY> isfinite('4 hrs'::timespan) </ENTRY>
</ROW>
<ROW>
<ENTRY> reltime(timespan) </ENTRY>
<ENTRY> reltime </ENTRY>
<ENTRY> convert to reltime </ENTRY>
<ENTRY> reltime('4 hrs'::timespan) </ENTRY>
</ROW>
<ROW>
<ENTRY> timespan(reltime) </ENTRY>
<ENTRY> timespan </ENTRY>
<ENTRY> convert to timespan </ENTRY>
<ENTRY> timespan('4 hours'::reltime) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
For the
<Function>date_part</Function> and <Function>date_trunc</Function>
functions, arguments can be
`year', `month', `day', `hour', `minute', and `second',
as well as the more specialized quantities
`decade', `century', `millenium', `millisecond', and `microsecond'.
<Function>date_part</Function> allows `dow'
to return day of week and `epoch' to return seconds since 1970 (for <Type>datetime</Type>)
or 'epoch' to return total elapsed seconds (for <Type>timespan</Type>).
</Para>
<sect1>
<title>Geometric Functions</title>
<para>
The geometric types point, box, lseg, line, path, polygon, and circle have a large set of native
support functions.
</para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Geometric Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> area(box) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> area of box </ENTRY>
<ENTRY> area('((0,0),(1,1))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> area(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> area of circle </ENTRY>
<ENTRY> area('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> box(box,box) </ENTRY>
<ENTRY> box </ENTRY>
<ENTRY> boxes to intersection box </ENTRY>
<ENTRY> box('((0,0),(1,1))','((0.5,0.5),(2,2))') </ENTRY>
</ROW>
<ROW>
<ENTRY> center(box) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> center of object </ENTRY>
<ENTRY> center('((0,0),(1,2))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> center(circle) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> center of object </ENTRY>
<ENTRY> center('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> diameter(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> diameter of circle </ENTRY>
<ENTRY> diameter('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> height(box) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> vertical size of box </ENTRY>
<ENTRY> height('((0,0),(1,1))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> isclosed(path) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is a closed path </ENTRY>
<ENTRY> isclosed('((0,0),(1,1),(2,0))'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> isopen(path) </ENTRY>
<ENTRY> bool </ENTRY>
<ENTRY> TRUE if this is an open path </ENTRY>
<ENTRY> isopen('[(0,0),(1,1),(2,0)]'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> length(lseg) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> length of line segment </ENTRY>
<ENTRY> length('((-1,0),(1,0))'::lseg) </ENTRY>
</ROW>
<ROW>
<ENTRY> length(path) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> length of path </ENTRY>
<ENTRY> length('((0,0),(1,1),(2,0))'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> pclose(path) </ENTRY>
<ENTRY> path </ENTRY>
<ENTRY> convert path to closed variant </ENTRY>
<ENTRY> popen('[(0,0),(1,1),(2,0)]'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> point(lseg,lseg) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> convert to point (intersection) </ENTRY>
<ENTRY> point('((-1,0),(1,0))'::lseg,'((-2,-2),(2,2))'::lseg) </ENTRY>
</ROW>
<ROW>
<ENTRY> points(path) </ENTRY>
<ENTRY> int4 </ENTRY>
<ENTRY> number of points in path </ENTRY>
<ENTRY> points('[(0,0),(1,1),(2,0)]'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> popen(path) </ENTRY>
<ENTRY> path </ENTRY>
<ENTRY> convert path to open variant </ENTRY>
<ENTRY> popen('((0,0),(1,1),(2,0))'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> radius(circle) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> radius of circle </ENTRY>
<ENTRY> radius('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> width(box) </ENTRY>
<ENTRY> float8 </ENTRY>
<ENTRY> horizontal size of box </ENTRY>
<ENTRY> width('((0,0),(1,1))'::box) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Geometric Type Conversion Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> box(circle) </ENTRY>
<ENTRY> box </ENTRY>
<ENTRY> convert circle to box </ENTRY>
<ENTRY> box('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> box(point,point) </ENTRY>
<ENTRY> box </ENTRY>
<ENTRY> convert points to box </ENTRY>
<ENTRY> box('(0,0)'::point,'(1,1)'::point) </ENTRY>
</ROW>
<ROW>
<ENTRY> box(polygon) </ENTRY>
<ENTRY> box </ENTRY>
<ENTRY> convert polygon to box </ENTRY>
<ENTRY> box('((0,0),(1,1),(2,0))'::polygon) </ENTRY>
</ROW>
<ROW>
<ENTRY> circle(box) </ENTRY>
<ENTRY> circle </ENTRY>
<ENTRY> convert to circle </ENTRY>
<ENTRY> circle('((0,0),(1,1))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> circle(point,float8) </ENTRY>
<ENTRY> circle </ENTRY>
<ENTRY> convert to circle </ENTRY>
<ENTRY> circle('(0,0)'::point,2.0) </ENTRY>
</ROW>
<ROW>
<ENTRY> lseg(box) </ENTRY>
<ENTRY> lseg </ENTRY>
<ENTRY> convert diagonal to lseg </ENTRY>
<ENTRY> lseg('((-1,0),(1,0))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> lseg(point,point) </ENTRY>
<ENTRY> lseg </ENTRY>
<ENTRY> convert to lseg </ENTRY>
<ENTRY> lseg('(-1,0)'::point,'(1,0)'::point) </ENTRY>
</ROW>
<ROW>
<ENTRY> path(polygon) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> convert to path </ENTRY>
<ENTRY> path('((0,0),(1,1),(2,0))'::polygon) </ENTRY>
</ROW>
<ROW>
<ENTRY> point(circle) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> convert to point (center) </ENTRY>
<ENTRY> point('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> point(lseg,lseg) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> convert to point (intersection) </ENTRY>
<ENTRY> point('((-1,0),(1,0))'::lseg,'((-2,-2),(2,2))'::lseg) </ENTRY>
</ROW>
<ROW>
<ENTRY> point(polygon) </ENTRY>
<ENTRY> point </ENTRY>
<ENTRY> center of polygon </ENTRY>
<ENTRY> point('((0,0),(1,1),(2,0))'::polygon) </ENTRY>
</ROW>
<ROW>
<ENTRY> polygon(box) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert to polygon with 12 points </ENTRY>
<ENTRY> polygon('((0,0),(1,1))'::box) </ENTRY>
</ROW>
<ROW>
<ENTRY> polygon(circle) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert to polygon with 12 points </ENTRY>
<ENTRY> polygon('((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> polygon(npts,circle) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert to polygon with npts points </ENTRY>
<ENTRY> polygon(12,'((0,0),2.0)'::circle) </ENTRY>
</ROW>
<ROW>
<ENTRY> polygon(path) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert to polygon </ENTRY>
<ENTRY> polygon('((0,0),(1,1),(2,0))'::path) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
<TABLE TOCENTRY="1">
<TITLE>Geometric Upgrade Functions</TITLE>
<TGROUP COLS="4">
<THEAD>
<ROW>
<ENTRY>Function</ENTRY>
<ENTRY>Returns</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Example</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> isoldpath(path) </ENTRY>
<ENTRY> path </ENTRY>
<ENTRY> test path for pre-v6.1 form </ENTRY>
<ENTRY> isoldpath('(1,3,0,0,1,1,2,0)'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> revertpoly(polygon) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert pre-v6.1 polygon </ENTRY>
<ENTRY> revertpoly('((0,0),(1,1),(2,0))'::polygon) </ENTRY>
</ROW>
<ROW>
<ENTRY> upgradepath(path) </ENTRY>
<ENTRY> path </ENTRY>
<ENTRY> convert pre-v6.1 path </ENTRY>
<ENTRY> upgradepath('(1,3,0,0,1,1,2,0)'::path) </ENTRY>
</ROW>
<ROW>
<ENTRY> upgradepoly(polygon) </ENTRY>
<ENTRY> polygon </ENTRY>
<ENTRY> convert pre-v6.1 polygon </ENTRY>
<ENTRY> upgradepoly('(0,1,2,0,1,0)'::polygon) </ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
</chapter>
doc/src/sgml/oper.sgml 0 → 100644
View file @ ba3a99f1
<Chapter>
<Title>Operators</Title>
<Abstract>
<Para>
Describes the built-in operators available in <ProductName>Postgres</ProductName>.
</Para>
</Abstract>
<Para>
<ProductName>Postgres</ProductName> provides a large number of built-in operators on system types.
These operators are declared in the system catalog
pg_operator. Every entry in pg_operator includes
the name of the procedure that implements the operator and the
class <Acronym>OIDs</Acronym> of the input and output types.
<Para>
To view all variations of the <Quote>||</Quote> string concatenation operator, try
<ProgramListing>
SELECT oprleft, oprright, oprresult, oprcode
FROM pg_operator WHERE oprname = '||';
oprleft|oprright|oprresult|oprcode
-------+--------+---------+-------
25| 25| 25|textcat
1042| 1042| 1042|textcat
1043| 1043| 1043|textcat
(3 rows)
</ProgramListing>
</Para>
<sect1>
<title>General Operators</title>
<para>
The operators listed here are defined for a number of native data types, ranging
from numeric types to data/time types.
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> &lt; </ENTRY>
<ENTRY>Less than?</ENTRY>
<ENTRY>1 &lt; 2</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;= </ENTRY>
<ENTRY>Less than or equal to?</ENTRY>
<ENTRY>1 &lt;= 2</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;&gt; </ENTRY>
<ENTRY>Not equal?</ENTRY>
<ENTRY>1 &lt;&gt; 2</ENTRY>
</ROW>
<ROW>
<ENTRY> = </ENTRY>
<ENTRY>Equal?</ENTRY>
<ENTRY>1 = 1</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt; </ENTRY>
<ENTRY>Greater than?</ENTRY>
<ENTRY>2 &gt; 1</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt;= </ENTRY>
<ENTRY>Greater than or equal to?</ENTRY>
<ENTRY>2 &gt;= 1</ENTRY>
</ROW>
<ROW>
<ENTRY> || </ENTRY>
<ENTRY>Concatenate strings</ENTRY>
<ENTRY>'Postgre' || 'SQL'</ENTRY>
</ROW>
<ROW>
<ENTRY> !!= </ENTRY>
<ENTRY>NOT IN</ENTRY>
<ENTRY>3 !!= i</ENTRY>
</ROW>
<ROW>
<ENTRY> ~~ </ENTRY>
<ENTRY>LIKE</ENTRY>
<ENTRY>'scrappy,marc,hermit' ~~ '%scrappy%'</ENTRY>
</ROW>
<ROW>
<ENTRY> !~~ </ENTRY>
<ENTRY>NOT LIKE</ENTRY>
<ENTRY>'bruce' !~~ '%al%'</ENTRY>
</ROW>
<ROW>
<ENTRY> ~ </ENTRY>
<ENTRY>Match (regex), case sensitive</ENTRY>
<ENTRY>'thomas' ~ '*.thomas*.'</ENTRY>
</ROW>
<ROW>
<ENTRY> ~* </ENTRY>
<ENTRY>Match (regex), case insensitive</ENTRY>
<ENTRY>'thomas' ~* '*.Thomas*.'</ENTRY>
</ROW>
<ROW>
<ENTRY> !~ </ENTRY>
<ENTRY>Does not match (regex), case sensitive</ENTRY>
<ENTRY>'thomas' !~ '*.Thomas*.'</ENTRY>
</ROW>
<ROW>
<ENTRY> !~* </ENTRY>
<ENTRY>Does not match (regex), case insensitive</ENTRY>
<ENTRY>'thomas' !~ '*.vadim*.'</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<sect1>
<title>Numerical Operators</title>
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Numerical Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> ! </ENTRY>
<ENTRY>Factorial</ENTRY>
<ENTRY>3 !</ENTRY>
</ROW>
<ROW>
<ENTRY> !! </ENTRY>
<ENTRY>Factorial (left operator)</ENTRY>
<ENTRY>!! 3</ENTRY>
</ROW>
<ROW>
<ENTRY> % </ENTRY>
<ENTRY>Modulo</ENTRY>
<ENTRY>5 % 4</ENTRY>
</ROW>
<ROW>
<ENTRY> % </ENTRY>
<ENTRY>Truncate</ENTRY>
<ENTRY>% 4.5</ENTRY>
</ROW>
<ROW>
<ENTRY> * </ENTRY>
<ENTRY>Multiplication</ENTRY>
<ENTRY>2 * 3</ENTRY>
</ROW>
<ROW>
<ENTRY> + </ENTRY>
<ENTRY>Addition</ENTRY>
<ENTRY>2 + 3</ENTRY>
</ROW>
<ROW>
<ENTRY> - </ENTRY>
<ENTRY>Subtraction</ENTRY>
<ENTRY>2 - 3</ENTRY>
</ROW>
<ROW>
<ENTRY> / </ENTRY>
<ENTRY>Division</ENTRY>
<ENTRY>4 / 2</ENTRY>
</ROW>
<ROW>
<ENTRY> : </ENTRY>
<ENTRY>Natural Exponentiation</ENTRY>
<ENTRY>: 3.0</ENTRY>
</ROW>
<ROW>
<ENTRY> ; </ENTRY>
<ENTRY>Natural Logarithm</ENTRY>
<ENTRY>(; 5.0)</ENTRY>
</ROW>
<ROW>
<ENTRY> @ </ENTRY>
<ENTRY>Absolute value</ENTRY>
<ENTRY>@ -5.0</ENTRY>
</ROW>
<ROW>
<ENTRY> ^ </ENTRY>
<ENTRY>Exponentiation</ENTRY>
<ENTRY>2.0 ^ 3.0</ENTRY>
</ROW>
<ROW>
<ENTRY> |/ </ENTRY>
<ENTRY>Square root</ENTRY>
<ENTRY>|/ 25.0</ENTRY>
</ROW>
<ROW>
<ENTRY> ||/ </ENTRY>
<ENTRY>Cube root</ENTRY>
<ENTRY>||/ 27.0</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<sect1>
<title>Geometric Operators</title>
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Geometric Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> + </ENTRY>
<ENTRY>Translation</ENTRY>
<ENTRY>'((0,0),(1,1))'::box + '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> - </ENTRY>
<ENTRY>Translation</ENTRY>
<ENTRY>'((0,0),(1,1))'::box - '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> * </ENTRY>
<ENTRY>Scaling/rotation</ENTRY>
<ENTRY>'((0,0),(1,1))'::box * '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> / </ENTRY>
<ENTRY>Scaling/rotation</ENTRY>
<ENTRY>'((0,0),(2,2))'::box / '(2.0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> # </ENTRY>
<ENTRY>Intersection</ENTRY>
<ENTRY>'((1,-1),(-1,1))' # '((1,1),(-1,-1))'</ENTRY>
</ROW>
<ROW>
<ENTRY> # </ENTRY>
<ENTRY>Number of points in polygon</ENTRY>
<ENTRY># '((1,0),(0,1),(-1,0))'</ENTRY>
</ROW>
<ROW>
<ENTRY> ## </ENTRY>
<ENTRY>Point of closest proximity</ENTRY>
<ENTRY>'(0,0)'::point ## '((2,0),(0,2))'::lseg</ENTRY>
</ROW>
<ROW>
<ENTRY> &amp;&amp; </ENTRY>
<ENTRY>Overlaps?</ENTRY>
<ENTRY>'((0,0),(1,1))'::box &amp;&amp; '((0,0),(2,2))'::box</ENTRY>
</ROW>
<ROW>
<ENTRY> &amp;&lt; </ENTRY>
<ENTRY>Overlaps to left?</ENTRY>
<ENTRY>'((0,0),(1,1))'::box &amp;&lt; '((0,0),(2,2))'::box</ENTRY>
</ROW>
<ROW>
<ENTRY> &amp;&gt; </ENTRY>
<ENTRY>Overlaps to right?</ENTRY>
<ENTRY>'((0,0),(3,3))'::box &amp;&gt; '((0,0),(2,2))'::box</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;-&gt; </ENTRY>
<ENTRY>Distance between</ENTRY>
<ENTRY>'((0,0),1)'::circle &lt;-&gt; '((5,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;&lt; </ENTRY>
<ENTRY>Left of?</ENTRY>
<ENTRY>'((0,0),1)'::circle &lt;&lt; '((5,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;^ </ENTRY>
<ENTRY>Is below?</ENTRY>
<ENTRY>'((0,0),1)'::circle &lt;^ '((0,5),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt;&gt; </ENTRY>
<ENTRY>Is right of?</ENTRY>
<ENTRY>'((5,0),1)'::circle &gt;&gt; '((0,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> &gt;^ </ENTRY>
<ENTRY>Is above?</ENTRY>
<ENTRY>'((0,5),1)'::circle >^ '((0,0),1)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> ?# </ENTRY>
<ENTRY>Intersects or overlaps</ENTRY>
<ENTRY>'((-1,0),(1,0))'::lseg ?# '((-2,-2),(2,2))'::box;</ENTRY>
</ROW>
<ROW>
<ENTRY> ?- </ENTRY>
<ENTRY>Is horizontal?</ENTRY>
<ENTRY>'(1,0)'::point ?- '(0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> ?-| </ENTRY>
<ENTRY>Is perpendicular?</ENTRY>
<ENTRY>'((0,0),(0,1))'::lseg ?-| '((0,0),(1,0))'::lseg</ENTRY>
</ROW>
<ROW>
<ENTRY> @-@ </ENTRY>
<ENTRY>Length or circumference</ENTRY>
<ENTRY>@-@ '((0,0),(1,0))'::path</ENTRY>
</ROW>
<ROW>
<ENTRY> ?| </ENTRY>
<ENTRY>Is vertical?</ENTRY>
<ENTRY>'(0,1)'::point ?| '(0,0)'::point</ENTRY>
</ROW>
<ROW>
<ENTRY> ?|| </ENTRY>
<ENTRY>Is parallel?</ENTRY>
<ENTRY>'((-1,0),(1,0))'::lseg ?|| '((-1,2),(1,2))'::lseg</ENTRY>
</ROW>
<ROW>
<ENTRY> @ </ENTRY>
<ENTRY>Contained or on</ENTRY>
<ENTRY>'(1,1)'::point @ '((0,0),2)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> @@ </ENTRY>
<ENTRY>Center of</ENTRY>
<ENTRY>@@ '((0,0),10)'::circle</ENTRY>
</ROW>
<ROW>
<ENTRY> ~= </ENTRY>
<ENTRY>Same as</ENTRY>
<ENTRY>'((0,0),(1,1))'::polygon ~= '((1,1),(0,0))'::polygon</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<sect1>
<title>Time Interval Operators</title>
<Para>
The time interval data type <Type>tinterval</Type> is a legacy from the original
date/time types and is not as well supported as the more modern types. There
are several operators for this type.
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Time Interval Operators</TITLE>
<TITLEABBREV>Operators</TITLEABBREV>
<TGROUP COLS="3">
<THEAD>
<ROW>
<ENTRY>Operator</ENTRY>
<ENTRY>Description</ENTRY>
<ENTRY>Usage</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY> #&lt; </ENTRY>
<ENTRY>Interval less than?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&lt;= </ENTRY>
<ENTRY>Interval less than or equal to?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&lt;&gt; </ENTRY>
<ENTRY>Interval not equal?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #= </ENTRY>
<ENTRY>Interval equal?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&gt; </ENTRY>
<ENTRY>Interval greater than?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> #&gt;= </ENTRY>
<ENTRY>Interval greater than or equal to?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;#&gt; </ENTRY>
<ENTRY>Convert to time interval</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;&lt; </ENTRY>
<ENTRY>Interval less than?</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> | </ENTRY>
<ENTRY>Start of interval</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> ~= </ENTRY>
<ENTRY>Same as</ENTRY>
<ENTRY></ENTRY>
</ROW>
<ROW>
<ENTRY> &lt;?&gt; </ENTRY>
<ENTRY>Time inside interval?</ENTRY>
<ENTRY></ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
Users may invoke operators using the operator name, as in:
<ProgramListing>
select * from emp where salary < 40000;
</ProgramListing>
Alternatively, users may call the functions that implement the
operators directly. In this case, the query above would be expressed
as:
<ProgramListing>
select * from emp where int4lt(salary, 40000);
</ProgramListing>
<Para>
<Application>psql</Application>
has a command (<Command>\dd</Command>) to show these operators.
</Chapter>
doc/src/sgml/postgres.sgml
View file @ ba3a99f1
...@@ -18,6 +18,9 @@ ...@@ -18,6 +18,9 @@
<!entity environ SYSTEM "environ.sgml"> <!entity environ SYSTEM "environ.sgml">
<!entity manage SYSTEM "manage.sgml"> <!entity manage SYSTEM "manage.sgml">
<!entity datatype SYSTEM "datatype.sgml"> <!entity datatype SYSTEM "datatype.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity func SYSTEM "func.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!entity array SYSTEM "array.sgml"> <!entity array SYSTEM "array.sgml">
<!entity inherit SYSTEM "inherit.sgml"> <!entity inherit SYSTEM "inherit.sgml">
<!entity query-ug SYSTEM "query-ug.sgml"> <!entity query-ug SYSTEM "query-ug.sgml">
...@@ -162,6 +165,9 @@ Information for users. ...@@ -162,6 +165,9 @@ Information for users.
&environ; &environ;
&manage; &manage;
&datatype; &datatype;
&oper;
&func;
&typeconv;
&array; &array;
&inherit; &inherit;
&query-ug; &query-ug;
......
doc/src/sgml/release.sgml
View file @ ba3a99f1
...@@ -7,74 +7,804 @@ ...@@ -7,74 +7,804 @@
Should include the migration notes from <FileName>migration/</FileName>. Should include the migration notes from <FileName>migration/</FileName>.
</Para> </Para>
</Note> </Note>
</Para>
<Para> The release notes have not yet been fully integrated into the new documentation.
The release notes have not yet been integrated into the new documentation.
Check for plain text files in the top of the distribution directory tree Check for plain text files in the top of the distribution directory tree
and in the <FileName>migration/</FileName> directory for current information. and in the <FileName>migration/</FileName> directory for current information.
<Sect1> <Sect1>
<Title>Release 6.3</Title> <Title>Release 6.4</Title>
<Para> <Para>
TBD TBD
</Para> </Para>
</Sect1>
<Sect1> <Sect1>
<Title>Release 6.2.1</Title> <Title>Release 6.3.2</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>Tue Apr 7 16:53:16 EDT 1998</date>
</docinfo>
-->
<para>
This is a bugfix release for 6.3.x.
Refer to the release notes for v6.3 for a more complete summary of new features.
<para>
Summary:
<itemizedlist spacing="compact">
<listitem>
<para>
Repairs automatic configuration support for some platforms, including Linux,
from breakage inadvertently introduced in v6.3.1.
<listitem>
<para>
Correctly handles function calls at the left side of BETWEEN and LIKE clauses.
</itemizedlist>
<Para> <Para>
<Note> A dump/restore is NOT required for those running 6.3 or 6.3.1. A
'make distclean', 'make', and 'make install' is all that is required.
This last step should be performed while the postmaster is not running.
You should re-link any custom applications that use <productname>Postgres</productname> libraries.
<para>
For upgrades from pre-v6.3 installations,
refer to the installation and migration instructions for v6.3.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Changes
-------
Configure detection improvements for tcl/tk(Brook Milligan, Alvin)
Manual page improvements(Bruce)
BETWEEN and LIKE fix(Thomas)
fix for psql \connect used by pg_dump(Oliver Elphick)
New odbc driver
pgaccess, version 0.86
qsort removed, now uses libc version, cleanups(Jeroen)
fix for buffer over-runs detected(Maurice Gittens)
fix for buffer overrun in libpgtcl(Randy Kunkee)
fix for UNION with DISTINCT or ORDER BY(Bruce)
gettimeofday configure check(Doug Winterburn)
Fix "indexes not used" bug(Vadim)
docs additions(Thomas)
Fix for backend memory leak(Bruce)
libreadline cleanup(Erwan MAS)
Remove DISTDIR(Bruce)
Makefile dependency cleanup(Jeroen van Vianen)
ASSERT fixes(Bruce)
</programlisting>
<Sect1>
<Title>Release 6.3.1</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Mon Mar 23 10:21:52 EST 1998
</date>
</docinfo>
-->
<para>
Summary:
<itemizedlist spacing="compact">
<listitem>
<para>
Additional support for multi-byte character sets.
<listitem>
<para>
Repair byte ordering for mixed-endian clients and servers.
<listitem>
<para>
Minor updates to allowed SQL syntax.
<listitem>
<para>
Improvements to the configuration autodetection for installation.
<listitem>
<para>
</itemizedlist>
<Para> <Para>
v6.2.1 was a bug-fix and usability release on v6.2. Needs only a few notes. A dump/restore is NOT required for those running 6.3. A
</Para> 'make distclean', 'make', and 'make install' is all that is required.
</Note> This last step should be performed while the postmaster is not running.
You should re-link any custom applications that use <productname>Postgres</productname> libraries.
<para>
For upgrades from pre-v6.3 installations,
refer to the installation and migration instructions for v6.3.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Changes
-------
ecpg cleanup/fixes, now version 1.1(Michael Meskes)
pg_user cleanup(Bruce)
large object fix for pg_dump and tclsh (alvin)
LIKE fix for multiple adjacent underscores
fix for redefining builtin functions(Thomas)
ultrix4 cleanup
upgrade to pg_access 0.83
updated CLUSTER manual page
multi-byte character set support, see doc/README.mb(Tatsuo)
configure --with-pgport fix
pg_ident fix
big-endian fix for backend communications(Kataoka)
SUBSTR() and substring() fix(Jan)
several jdbc fixes(Peter)
libpgtcl improvements, see libptcl/README(Randy Kunkee)
Fix for "Datasize = 0" error(Vadim)
Prevent \do from wrapping(Bruce)
Remove duplicate Russian character set entries
Sunos4 cleanup
Allow optional TABLE keyword in LOCK and SELECT INTO(Thomas)
CREATE SEQUENCE options to allow a negative integer(Thomas)
Add "PASSWORD" as an allowed column identifier(Thomas)
Add checks for UNION target fields(Bruce)
Fix Alpha port(Dwayne Bailey)
Fix for text arrays containing quotes(Doug Gibson)
Solaris compile fix(Albert Chin-A-Young)
Better identify tcl and tk libs and includes(Bruce)
</programlisting>
<Sect1>
<Title>Release 6.3</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Sun Mar 1 14:57:30 EST 1998
</date>
</docinfo>
-->
<para>
There are <emphasis>many</emphasis> new features and improvements in this release.
Here is a brief, incomplete summary:
<itemizedlist spacing="compact">
<listitem>
<para>
Many new SQL features, including
full <acronym>SQL92</acronym> subselect capability
(everything is here but target-list subselects).
<listitem>
<para>
Support for client-side environment variables to specify time zone and date style.
<listitem>
<para>
Socket interface for client/server connection. This is the default now
so you may need to start <application>postmaster</application> with the
<quote>-i</quote> flag.
<listitem>
<para>
Better password authorization mechanisms. Default table permissions have changed.
<listitem>
<para>
Old-style <quote>time travel</quote> has been removed. Performance has been improved.
</itemizedlist>
<note>
<para>
Bruce Momjian wrote the following notes to introduce the new release.
<note>
<para>
There are some general 6.3 issues that I want to mention. These are
only the big items that can not be described in one sentence. A review
of the detailed changes list is still needed.
<para>
First, we now have subselects. Now that we have them, I would like to
mention that without subselects, SQL is a very limited language.
Subselects are a major feature, and you should review your code for
places where subselects provide a better solution for your queries. I
think you will find that there are more uses for subselects than you may
think. Vadim has put us on the big SQL map with subselects, and fully
functional ones too. The only thing you can't do with subselects is to
use them in the target list.
<para>
Second, 6.3 uses unix domain sockets rather than TCP/IP by default. To
enable connections from other machines, you have to use the new
postmaster -i option, and of course edit pg_hba.conf. Also, for this
reason, the format of pg_hba.conf has changed.
<para>
Third, char() fields will now allow faster access than varchar() or
text. Specifically, the text and varchar() have a penalty for access to
any columns after the first column of this type. char() used to also
have this access penalty, but it no longer does. This may suggest that
you redesign some of your tables, especially if you have short character
columns that you have defined as varchar() or text. This and other
changes make 6.3 even faster than earlier releases.
<para>
We now have passwords definable independent of any Unix file. There are
new SQL USER commands. See the pg_hba.conf manual page for more
information. There is a new table, pg_shadow, which is used to store
user information and user passwords, and it by default only SELECT-able
by the postgres super-user. pg_user is now a view of pg_shadow, and is
SELECT-able by PUBLIC. You should keep using pg_user in your
application without changes.
<para>
User-created tables now no longer have SELECT permission to PUBLIC by
default. This was done because the ANSI standard requires it. You can
of course GRANT any permissions you want after the table is created.
System tables continue to be SELECT-able by PUBLIC.
<para>
We also have real deadlock detection code. No more sixty-second
timeouts. And the new locking code implements a FIFO better, so there
should be less resource starvation during heavy use.
<para>
Many complaints have been made about inadequate documenation in previous
releases. Thomas has put much effort into many new manuals for this
release. Check out the doc/ directory.
<para>
For performance reasons, time travel is gone, but can be implemented
using triggers (see pgsql/contrib/spi/README). Please check out the new
\d command for types, operators, etc. Also, views have their own
permissions now, not based on the underlying tables, so permissions on
them have to be set separately. Check /pgsql/interfaces for some new
ways to talk to <productname>Postgres</productname>.
<para>
This is the first release that really required an explanation for
existing users. In many ways, this was necessary because the new
release removes many limitations, and the work-arounds people were using
are no longer needed.
<sect2>
<title>Migration to v6.3</title>
<para>
A dump/restore using <application>pg_dump</application>
or <application>pg_dumpall</application>
is required for those wishing to migrate data from any
previous release of <productname>Postgres</productname>.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Bug Fixes
---------
Fix binary cursors broken by MOVE implementation(Vadim)
Fix for tcl library crash(Jan)
Fix for array handling, from Gerhard Hintermayer
Fix acl error, and remove duplicate pqtrace(Bruce)
Fix psql \e for empty file(Bruce)
Fix for textcat on varchar() fields(Bruce)
Fix for DBT Sendproc (Zeugswetter Andres)
Fix vacuum analyze syntax problem(Bruce)
Fix for international identifiers(Tatsuo)
Fix aggregates on inherited tables(Bruce)
Fix substr() for out-of-bounds data
Fix for select 1=1 or 2=2, select 1=1 and 2=2, and select sum(2+2)(Bruce)
Fix notty output to show status result. -q option still turns it off(Bruce)
Fix for count(*), aggs with views and multiple tables and sum(3)(Bruce)
Fix cluster(Bruce)
Fix for PQtrace start/stop several times(Bruce)
Fix a variety of locking problems like newer lock waiters getting
lock before older waiters, and having readlock people not share
locks if a writer is waiting for a lock, and waiting writers not
getting priority over waiting readers(Bruce)
Fix crashes in psql when executing queries from external files(James)
Fix problem with multiple order by columns, with the first one having
NULL values(Jeroen)
Use correct hash table support functions for float8 and int4(Thomas)
Re-enable JOIN= option in CREATE OPERATOR statement (Thomas)
Change precedence for boolean operators to match expected behavior(Thomas)
Generate elog(ERROR) on over-large integer(Bruce)
Allow multiple-argument functions in constraint clauses(Thomas)
Check boolean input literals for 'true','false','yes','no','1','0'
and throw elog(ERROR) if unrecognized(Thomas)
Major large objects fix
Fix for GROUP BY showing duplicates(Vadim)
Fix for index scans in MergeJion(Vadim)
Enhancements
------------
Subselects with EXISTS, IN, ALL, ANY keywords (Vadim, Bruce, Thomas)
New User Manual(Thomas, others)
Speedup by inlining some frequently-called functions
Real deadlock detection, no more timeouts(Bruce)
Add SQL92 "constants" CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP,
CURRENT_USER(Thomas)
Modify constraint syntax to be SQL92-compliant(Thomas)
Implement SQL92 PRIMARY KEY and UNIQUE clauses using indices(Thomas)
Recognize SQL92 syntax for FOREIGN KEY. Throw elog notice(Thomas)
Allow NOT NULL UNIQUE constraint clause (each allowed separately before)(Thomas)
Allow Postgres-style casting ("::") of non-constants(Thomas)
Add support for SQL3 TRUE and FALSE boolean constants(Thomas)
Support SQL92 syntax for IS TRUE/IS FALSE/IS NOT TRUE/IS NOT FALSE(Thomas)
Allow shorter strings for boolean literals (e.g. "t", "tr", "tru")(Thomas)
Allow SQL92 delimited identifiers(Thomas)
Implement SQL92 binary and hexadecimal string decoding (b'10' and x'1F')(Thomas)
Support SQL92 syntax for type coercion of literal strings
(e.g. "DATETIME 'now'")(Thomas)
Add conversions for int2, int4, and OID types to and from text(Thomas)
Use shared lock when building indices(Vadim)
Free memory allocated for an user query inside transaction block after
this query is done, was turned off in <= 6.2.1(Vadim)
New SQL statement CREATE PROCEDURAL LANGUAGE(Jan)
New <productname>Postgres</productname> Procedural Language (PL) backend interface(Jan)
Rename pg_dump -H option to -h(Bruce)
Add Java support for passwords, European dates(Peter)
Use indices for LIKE and ~, !~ operations(Bruce)
Add hash functions for datetime and timespan(Thomas)
Time Travel removed(Vadim, Bruce)
Add paging for \d and \z, and fix \i(Bruce)
Add Unix domain socket support to backend and to frontend library(Goran)
Implement CREATE DATABASE/WITH LOCATION and initlocation utility(Thomas)
Allow more SQL92 and/or <productname>Postgres</productname> reserved words as column identifiers(Thomas)
Augment support for SQL92 SET TIME ZONE...(Thomas)
SET/SHOW/RESET TIME ZONE uses TZ backend environment variable(Thomas)
Implement SET keyword = DEFAULT and SET TIME ZONE DEFAULT(Thomas)
Enable SET TIME ZONE using TZ environment variable(Thomas)
Add PGDATESTYLE environment variable to frontend and backend initialization(Thomas)
Add PGTZ, PGCOSTHEAP, PGCOSTINDEX, PGRPLANS, PGGEQO
frontend library initialization environment variables(Thomas)
Regression tests time zone automatically set with "setenv PGTZ PST8PDT"(Thomas)
Add pg_description table for info on tables, columns, operators, types, and
aggregates(Bruce)
Increase 16 char limit on system table/index names to 32 characters(Bruce)
Rename system indices(Bruce)
Add 'GERMAN' option to SET DATESTYLE(Thomas)
Define an "ISO-style" timespan output format with "hh:mm:ss" fields(Thomas)
Allow fractional values for delta times (e.g. '2.5 days')(Thomas)
Validate numeric input more carefully for delta times(Thomas)
Implement day of year as possible input to date_part()(Thomas)
Define timespan_finite() and text_timespan() functions(Thomas)
Remove archive stuff(Bruce)
Allow for a pg_password authentication database that is separate from
the system password file(Todd)
Dump ACLs, GRANT, REVOKE permissions(Matt)
Define text, varchar, and bpchar string length functions(Thomas)
Fix Query handling for inheritance, and cost computations(Bruce)
Implement CREATE TABLE/AS SELECT (alternative to SELECT/INTO)(Thomas)
Allow NOT, IS NULL, IS NOT NULL in constraints(Thomas)
Implement UNIONs for SELECT(Bruce)
Add UNION, GROUP, DISTINCT to INSERT(Bruce)
varchar() stores only necessary bytes on disk(Bruce)
Fix for BLOBs(Peter)
Mega-Patch for JDBC...see README_6.3 for list of changes(Peter)
Remove unused "option" from PQconnectdb()
New LOCK command and lock manual page describing deadlocks(Bruce)
Add new psql \da, \dd, \df, \do, \dS, and \dT commands(Bruce)
Enhance psql \z to show sequences(Bruce)
Show NOT NULL and DEFAULT in psql \d table(Bruce)
New psql .psqlrc file startup(Andrew)
Modify sample startup script in contrib/linux to show syslog(Thomas)
New types for IP and MAC addresses in contrib/ip_and_mac(TomH)
Unix system time conversions with date/time types in contrib/unixdate(Thomas)
Update of contrib stuff(Massimo)
Add Unix socket support to DBD::Pg(Goran)
New python interface (PyGreSQL 2.0)(D'Arcy)
New frontend/backend protocol has a version number, network byte order(Phil)
Security features in pg_hba.conf enhanced and documented, many cleanups(Phil)
CHAR() now faster access than VARCHAR() or TEXT
ecpg embedded SQL preprocessor
Reduce system column overhead(Vadmin)
Remove pg_time table(Vadim)
Add pg_type attribute to identify types that need length (bpchar, varchar)
Add report of offending line when COPY command fails
Allow VIEW permissions to be set separately from the underlying tables.
For security, use GRANT/REVOKE on views as appropriate(Jan)
Tables now have no default GRANT SELECT TO PUBLIC. You must
explicitly grant such permissions.
Clean up tutorial examples(Darren)
Source Tree Changes
-------------------
Add new html development tools, and flow chart in /tools/backend
Fix for SCO compiles
Stratus computer port Robert Gillies
Added support for shlib for BSD44_derived & i386_solaris
Make configure more automated(Brook)
Add script to check regression test results
Break parser functions into smaller files, group together(Bruce)
Rename heap_create to heap_create_and_catalog, rename heap_creatr
to heap_create()(Bruce)
Sparc/Linux patch for locking(TomS)
Remove PORTNAME and reorganize port-specific stuff(Marc)
Add optimizer README file(Bruce)
Remove some recursion in optimizer and clean up some code there(Bruce)
Fix for NetBSD locking(Henry)
Fix for libptcl make(Tatsuo)
AIX patch(Darren)
Change IS TRUE, IS FALSE, ... to expressions using "=" rather than
function calls to istrue() or isfalse() to allow optimization(Thomas)
Various fixes NetBSD/Sparc related(TomH)
Alpha linux locking(Travis,Ryan)
Change elog(WARN) to elog(ERROR)(Bruce)
FAQ for FreeBSD(Marc)
Bring in the PostODBC source tree as part of our standard distribution(Marc)
A minor patch for HP/UX 10 vs 9(Stan)
New pg_attribute.atttypmod for type-specific info like varchar length(Bruce)
Unixware patches(Billy)
New i386 'lock' for spin lock asm(Billy)
Support for multiplexed backends is removed
Start an OpenBSD port
Start an AUX port
Start a Cygnus port
Add string functions to regression suite(Thomas)
Expand a few function names formerly truncated to 16 characters(Thomas)
Remove un-needed malloc() calls and replace with palloc()(Bruce)
</programlisting>
</Para> </Para>
</Sect1> </Sect1>
<Sect1> <Sect1>
<Title>Release 6.2</Title> <Title>Release 6.2.1</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Fri Oct 17 00:01:27 EDT 1997
</date>
</docinfo>
-->
<Para> <para>
<Note> v6.2.1 is a bug-fix and usability release on v6.2.
<Para>
This should include information based on Bruce's release summary. <para>
</Para> Summary:
</Note>
</Para>
<itemizedlist spacing="compact">
<listitem>
<para>
Allow strings to span lines, per <acronym>SQL92</acronym>.
<listitem>
<para>
Include example trigger function for inserting user names on table updates.
</itemizedlist>
<para>
This is a minor bug-fix release on v6.2.
For upgrades from pre-v6.2 systems, a full dump/reload is required.
Refer to the v6.2 release notes for instructions.
<sect2>
<title>Migration from v6.2 to v6.2.1</title>
<para>
This is a minor bug-fix release. A dump/reload is not required from v6.2,
but is required from any release prior to v6.2.
<para>
In upgrading from v6.2, if you choose to dump/reload you will find that
avg(money) is now calculated correctly. All other bug fixes take effect
upon updating the executables.
<para>
Another way to avoid dump/reload is to use the following SQL command
from psql to update the existing system table:
<programlisting>
update pg_aggregate set aggfinalfn = 'cash_div_flt8'
where aggname = 'avg' and aggbasetype = 790;
</programlisting>
<para>
This will need to be done to every existing database, including template1.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Changes in this release
-----------------------
Allow TIME and TYPE column names(Thomas)
Allow larger range of true/false as boolean values(Thomas)
Support output of "now" and "current"(Thomas)
Handle DEFAULT with INSERT of NULL properly(Vadim)
Fix for relation reference counts problem in buffer manager(Vadim)
Allow strings to span lines, like ANSI(Thomas)
Fix for backward cursor with ORDER BY(Vadim)
Fix avg(cash) computation(Thomas)
Fix for specifying a column twice in ORDER/GROUP BY(Vadim)
Documented new libpq function to return affected rows, PQcmdTuples(Bruce)
Trigger function for inserting user names for INSERT/UPDATE(Brook Milligan)
</programlisting>
</Sect1> </Sect1>
<Sect1> <Sect1>
<Title>Release 6.1</Title> <Title>Release 6.2</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Thu Oct 02 12:53:46 EDT 1997
</date>
</docinfo>
-->
<Para> <para>
<Note> A dump/restore is required for those wishing to migrate data from
<Para> previous releases of <productname>Postgres</productname>.
This should include information based on Bruce's release summary.
</Para> <sect2>
</Note> <title>Migration from v6.1 to v6.2</title>
</Para>
<para>
This migration requires a complete dump of the 6.1 database and a
restore of the database in 6.2.
<para>
Note that the pg_dump and pg_dumpall utility from 6.2 should be used
to dump the 6.1 database.
<sect2>
<title>Migration from v1.x to v6.2</title>
<para>
Those migrating from earlier 1.* releases should first upgrade to 1.09
because the COPY output format was improved from the 1.02 release.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Bug Fixes
---------
Fix problems with pg_dump for inheritance, sequences, archive tables(Bruce)
Fix compile errors on overflow due to shifts, unsigned, and bad prototypes
from Solaris(Diab Jerius)
Fix bugs in geometric line arithmetic (bad intersection calculations)(Thomas)
Check for geometric intersections at endpoints to avoid rounding ugliness(Thomas)
Catch non-functional delete attempts(Vadim)
Change time function names to be more consistent(Michael Reifenberg)
Check for zero divides(Michael Reifenberg)
Fix very old bug which made tuples changed/inserted by a commnd
visible to the command itself (so we had multiple update of
updated tuples, etc)(Vadim)
Fix for SELECT null, 'fail' FROM pg_am (Patrick)
SELECT NULL as EMPTY_FIELD now allowed(Patrick)
Remove un-needed signal stuff from contrib/pginterface
Fix OR (where x &lt;&gt; 1 or x isnull didn't return tuples with x NULL) (Vadim)
Fix time_cmp function (Vadim)
Fix handling of functions with non-attribute first argument in
WHERE clauses (Vadim)
Fix GROUP BY when order of entries is different from order
in target list (Vadim)
Fix pg_dump for aggregates without sfunc1 (Vadim)
Enhancements
------------
Default genetic optimizer GEQO parameter is now 8(Bruce)
Allow use parameters in target list having aggregates in functions(Vadim)
Added JDBC driver as an interface(Adrian & Peter)
pg_password utility
Return number of tuples inserted/affected by INSERT/UPDATE/DELETE etc.(Vadim)
Triggers implemented with CREATE TRIGGER (SQL3)(Vadim)
SPI (Server Programming Interface) allows execution of queries inside
C-functions (Vadim)
NOT NULL implemented (SQL92)(Robson Paniago de Miranda)
Include reserved words for string handling, outer joins, and unions(Thomas)
Implement extended comments ("/* ... */") using exclusive states(Thomas)
Add "//" single-line comments(Bruce)
Remove some restrictions on characters in operator names(Thomas)
DEFAULT and CONSTRAINT for tables implemented (SQL92)(Vadim & Thomas)
Add text concatenation operator and function (SQL92)(Thomas)
Support WITH TIME ZONE syntax (SQL92)(Thomas)
Support INTERVAL unit TO unit syntax (SQL92)(Thomas)
Define types DOUBLE PRECISION, INTERVAL, CHARACTER,
and CHARACTER VARYING (SQL92)(Thomas)
Define type FLOAT(p) and rudimentary DECIMAL(p,s), NUMERIC(p,s) (SQL92)(Thomas)
Define EXTRACT(), POSITION(), SUBSTRING(), and TRIM() (SQL92)(Thomas)
Define CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP (SQL92)(Thomas)
Add syntax and warnings for UNION, HAVING, INNER and OUTER JOIN (SQL92)(Thomas)
Add more reserved words, mostly for SQL92 compliance(Thomas)
Allow hh:mm:ss time entry for timespan/reltime types(Thomas)
Add center() routines for lseg, path, polygon(Thomas)
Add distance() routines for circle-polygon, polygon-polygon(Thomas)
Check explicitly for points and polygons contained within polygons
using an axis-crossing algorithm(Thomas)
Add routine to convert circle-box(Thomas)
Merge conflicting operators for different geometric data types(Thomas)
Replace distance operator "<===>" with "<->"(Thomas)
Replace "above" operator "!^" with ">^" and "below" operator "!|" with "<^"(Thomas)
Add routines for text trimming on both ends, substring, and string position(Thomas)
Added conversion routines circle(box) and poly(circle)(Thomas)
Allow internal sorts to be stored in memory rather than in files(Bruce & Vadim)
Allow functions and operators on internally-identical types to succeed(Bruce)
Speed up backend startup after profiling analysis(Bruce)
Inline frequently called functions for performance(Bruce)
Reduce open() calls(Bruce)
psql: Add PAGER for \h and \?,\C fix
Fix for psql pager when no tty(Bruce)
New entab utility(Bruce)
General trigger functions for referential integrity (Vadim)
General trigger functions for time travel (Vadim)
General trigger functions for AUTOINCREMENT/IDENTITY feature (Vadim)
MOVE implementation (Vadim)
Source Tree Changes
-------------------
HPUX 10 patches (Vladimir Turin)
Added SCO support, (Daniel Harris)
mkLinux patches (Tatsuo Ishii)
Change geometric box terminology from "length" to "width"(Thomas)
Deprecate temporary unstored slope fields in geometric code(Thomas)
Remove restart instructions from INSTALL(Bruce)
Look in /usr/ucb first for install(Bruce)
Fix c++ copy example code(Thomas)
Add -o to psql manual page(Bruce)
Prevent relname unallocated string length from being copied into database(Bruce)
Cleanup for NAMEDATALEN use(Bruce)
Fix pg_proc names over 15 chars in output(Bruce)
Add strNcpy() function(Bruce)
remove some (void) casts that are unnecessary(Bruce)
new interfaces directory(Marc)
Replace fopen() calls with calls to fd.c functions(Bruce)
Make functions static where possible(Bruce)
enclose unused functions in #ifdef NOT_USED(Bruce)
Remove call to difftime() in timestamp support to fix SunOS(Bruce & Thomas)
Changes for Digital Unix
Portability fix for pg_dumpall(Bruce)
Rename pg_attribute.attnvals to attdisbursion(Bruce)
"intro/unix" manual page now "pgintro"(Bruce)
"built-in" manual page now "pgbuiltin"(Bruce)
"drop" manual page now "drop_table"(Bruce)
Add "create_trigger", "drop_trigger" manual pages(Thomas)
Add constraints regression test(Vadim & Thomas)
Add comments syntax regression test(Thomas)
Add PGINDENT and support program(Bruce)
Massive commit to run PGINDENT on all *.c and *.h files(Bruce)
Files moved to /src/tools directory(Bruce)
SPI and Trigger programming guides (Vadim & D'Arcy)
</programlisting>
<Sect1>
<Title>Release 6.1.1</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Mon Jul 22 18:04:49 EDT 1997
</date>
</docinfo>
-->
<sect2>
<title>Migration from v6.1 to v6.1.1</title>
<para>
This is a minor bug-fix release. A dump/reload is not required from v6.1,
but is required from any release prior to v6.1.
Refer to the release notes for v6.1 for more details.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Changes in this release
-----------------------
fix for SET with options (Thomas)
allow pg_dump/pg_dumpall to preserve ownership of all tables/objects(Bruce)
new psql \connect option allows changing usernames without chaning databases
fix for initdb --debug option(Yoshihiko Ichikawa))
lextest cleanup(Bruce)
hash fixes(Vadim)
fix date/time month boundary arithmetic(Thomas)
fix timezone daylight handling for some ports(Thomas, Bruce, Tatsuo)
timestamp overhauled to use standard functions(Thomas)
other code cleanup in date/time routines(Thomas)
psql's \d now case-insensitive(Bruce)
psql's backslash commands can now have trailing semicolon(Bruce)
fix memory leak in psql when using \g(Bruce)
major fix for endian handling of communication to server(Thomas, Tatsuo)
Fix for Solaris assembler and include files(Yoshihiko Ichikawa)
allow underscores in usernames(Bruce)
pg_dumpall now returns proper status, portability fix(Bruce)
</programlisting>
<Sect1>
<Title>Release 6.1</Title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Sun Jun 8 14:41:13 EDT 1997
</date>
</docinfo>
-->
<Para> <Para>
The regression tests have been adapted and extensively modified for the The regression tests have been adapted and extensively modified for the
v6.1 release of PostgreSQL. v6.1 release of <productname>Postgres</productname>.
</Para> </Para>
<Para> <Para>
Three new data types (datetime, timespan, and circle) have been added to Three new data types (datetime, timespan, and circle) have been added to
the native set of PostgreSQL types. Points, boxes, paths, and polygons the native set of <productname>Postgres</productname> types. Points, boxes, paths, and polygons
have had their output formats made consistant across the data types. have had their output formats made consistant across the data types.
The polygon output in misc.out has only been spot-checked for correctness The polygon output in misc.out has only been spot-checked for correctness
relative to the original regression output. relative to the original regression output.
</Para> </Para>
<Para> <Para>
PostgreSQL v6.1 introduces a new, alternate optimizer which uses <FirstTerm>genetic</FirstTerm> <productname>Postgres</productname> v6.1 introduces a new, alternate optimizer which uses <FirstTerm>genetic</FirstTerm>
algorithms. These algorithms introduce a random behavior in the ordering algorithms. These algorithms introduce a random behavior in the ordering
of query results when the query contains multiple qualifiers or multiple of query results when the query contains multiple qualifiers or multiple
tables (giving the optimizer a choice on order of evaluation). Several tables (giving the optimizer a choice on order of evaluation). Several
...@@ -105,23 +835,926 @@ This should include information based on Bruce's release summary. ...@@ -105,23 +835,926 @@ This should include information based on Bruce's release summary.
test machine (Linux/gcc/i686). test machine (Linux/gcc/i686).
</Para> </Para>
<sect2>
<title>Migration to v6.1</title>
<para>
This migration requires a complete dump of the 6.0 database and a
restore of the database in 6.1.
<para>
Those migrating from earlier 1.* releases should first upgrade to 1.09
because the COPY output format was improved from the 1.02 release.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Bug Fixes
---------
packet length checking in library routines
lock manager priority patch
check for under/over flow of float8(Bruce)
multi-table join fix(Vadim)
SIGPIPE crash fix(Darren)
large object fixes(Sven)
allow btree indexes to handle NULLs(Vadim)
timezone fixes(D'Arcy)
select SUM(x) can return NULL on no rows(Thomas)
internal optimizer, executor bug fixes(Vadim)
fix problem where inner loop in < or <= has no rows(Vadim)
prevent re-commuting join index clauses(Vadim)
fix join clauses for multiple tables(Vadim)
fix hash, hashjoin for arrays(Vadim)
fix btree for abstime type(Vadim)
large object fixes(Raymond)
fix buffer leak in hash indices (Vadim)
fix rtree for use in inner scan (Vadim)
fix gist for use in inner scan, cleanups (Vadim, Andrea)
avoid unnecessary local buffers allocation (Vadim, Massimo)
fix local buffers leak in transaction aborts (Vadim)
fix file manager memmory leaks, cleanups (Vadim, Massimo)
fix storage manager memmory leaks (Vadim)
fix btree duplicates handling (Vadim)
fix deleted tuples re-incarnation caused by vacuum (Vadim)
fix SELECT varchar()/char() INTO TABLE made zero-length fields(Bruce)
many psql, pg_dump, and libpq memory leaks fixed using Purify (Igor)
Enhancements
------------
attribute optimization statistics(Bruce)
much faster new btree bulk load code(Paul)
BTREE UNIQUE added to bulk load code(Vadim)
new lock debug code(Massimo)
massive changes to libpg++(Leo)
new GEQO optimizer speeds table multi-table optimization(Martin)
new WARN message for non-unique insert into unique key(Marc)
update x=-3, no spaces, now valid(Bruce)
remove case-sensitive identifier handling(Bruce,Thomas,Dan)
debug backend now pretty-prints tree(Darren)
new Oracle character functions(Edmund)
new plaintext password functions(Dan)
no such class or insufficient privilege changed to distinct messages(Dan)
new ANSI timestamp function(Dan)
new ANSI Time and Date types (Thomas)
move large chunks of data in backend(Martin)
multi-column btree indexes(Vadim)
new SET var TO value command(Martin)
update transaction status on reads(Dan)
new locale settings for character types(Oleg)
new SEQUENCE serial number generator(Vadim)
GROUP BY function now possible(Vadim)
re-organize regression test(Thomas,Marc)
new optimizer operation weights(Vadim)
new psql \z grant/permit option(Marc)
new MONEY data type(D'Arcy,Thomas)
tcp socket communication speed improved(Vadim)
new VACUUM option for attribute statistics, and for certain columns (Vadim)
many geometric type improvements(Thomas,Keith)
additional regression tests(Thomas)
new datestyle variable(Thomas,Vadim,Martin)
more comparison operators for sorting types(Thomas)
new conversion functions(Thomas)
new more compact btree format(Vadim)
allow pg_dumpall to preserve database ownership(Bruce)
new SET GEQO=# and R_PLANS variable(Vadim)
old (!GEQO) optimizer can use right-sided plans (Vadim)
typechecking improvement in SQL parser(Bruce)
new SET, SHOW, RESET commands(Thomas,Vadim)
new \connect database USER option
new destroydb -i option (Igor)
new \dt and \di psql commands (Darren)
SELECT "\n" now escapes newline (A. Duursma)
new geometry conversion functions from old format (Thomas)
Source tree changes
-------------------
new configuration script(Marc)
readline configuration option added(Marc)
OS-specific configuration options removed(Marc)
new OS-specific template files(Marc)
no more need to edit Makefile.global(Marc)
re-arrange include files(Marc)
nextstep patches (Gregor Hoffleit)
removed WIN32-specific code(Bruce)
removed postmaster -e option, now only postgres -e option (Bruce)
merge duplicate library code in front/backends(Martin)
now works with eBones, international Kerberos(Jun)
more shared library support
c++ include file cleanup(Bruce)
warn about buggy flex(Bruce)
DG-UX, Ultrix, Irix, AIX portability fixes
</programlisting>
<sect1>
<title>Release v6.0</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Wed Jan 29 00:19:54 EST 1997
</date>
</docinfo>
-->
<para>
A dump/restore is required for those wishing to migrate data from
previous releases of <productname>Postgres</productname>.
<sect2>
<title>Migration from v1.09 to v6.0</title>
<para>
This migration requires a complete dump of the 1.09 database and a
restore of the database in 6.0.
<sect2>
<title>Migration from pre-v1.09 to v6.0</title>
<para>
Those migrating from earlier 1.* releases should first upgrade to 1.09
because the COPY output format was improved from the 1.02 release.
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Bug Fixes
---------
ALTER TABLE bug - running postgress process needs to re-read table definition
Allow vacuum to be run on one table or entire database(Bruce)
Array fixes
Fix array over-runs of memory writes(Kurt)
Fix elusive btree range/non-range bug(Dan)
Fix for hash indexes on some types like time and date
Fix for pg_log size explosion
Fix permissions on lo_export()(Bruce)
Fix unitialized reads of memory(Kurt)
Fixed ALTER TABLE ... char(3) bug(Bruce)
Fixed a few small memory leaks
Fixed EXPLAIN handling of options and changed full_path option name
Fixed output of group acl permissions
Memory leaks (hunt and destroy with tools like Purify(Kurt)
Minor improvements to rules system
NOTIFY fixes
New asserts for run-checking
Overhauled parser/analyze code to properly report errors and increase speed
Pg_dump -d now handles NULL's properly(Bruce)
Prevent SELECT NULL from crashing server (Bruce)
Properly report errors when INSERT ... SELECT columns did not match
Properly report errors when insert column names were not correct
Psql \g filename now works(Bruce)
Psql fixed problem with multiple statements on one line with multiple outputs
Removed duplicate system oid's
SELECT * INTO TABLE . GROUP/ORDER BY gives unlink error if table exists(Bruce)
Several fixes for queries that crashed the backend
Starting quote in insert string errors(Bruce)
Submitting an empty query now returns empty status, not just " " query(Bruce)
Enhancements
------------
Add EXPLAIN manual page(Bruce)
Add UNIQUE index capability(Dan)
Add hostname/user level access control rather than just hostname and user
Add synonym of != for &lt;&gt;(Bruce)
Allow "select oid,* from table"
Allow BY,ORDER BY to specify columns by number, or by non-alias table.column(Bruce)
Allow COPY from the frontend(Bryan)
Allow GROUP BY to use alias column name(Bruce)
Allow actual compression, not just reuse on the same page(Vadim)
Allow installation-configuration option to auto-add all local users(Bryan)
Allow libpq to distinguish between text value '' and null(Bruce)
Allow non-postgres users with createdb privs to destroydb's
Allow restriction on who can create C functions(Bryan)
Allow restriction on who can do backend COPY(Bryan)
Can shrink tables, pg_time and pg_log(Vadim & Erich)
Change debug level 2 to print queries only, changed debug heading layout(Bruce)
Change default decimal constant representation from float4 to float8(Bruce)
European date format now set when postmaster is started
Execute lowercase function names if not found with exact case
Fixes for aggregate/GROUP processing, allow 'select sum(func(x),sum(x+y) from z'
Gist now included in the distrubution(Marc)
Idend authentication of local users(Bryan)
Implement BETWEEN qualifier(Bruce)
Implement IN qualifier(Bruce)
Libpq has PQgetisnull()(Bruce)
Libpq++ improvements
New options to initdb(Bryan)
Pg_dump allow dump of oid's(Bruce)
Pg_dump create indexes after tables are loaded for speed(Bruce)
Pg_dumpall dumps all databases, and the user table
Pginterface additions for NULL values(Bruce)
Prevent postmaster from being run as root
Psql \h and \? is now readable(Bruce)
Psql allow backslashed, semicolons anywhere on the line(Bruce)
Psql changed command prompt for lines in query or in quotes(Bruce)
Psql char(3) now displays as (bp)char in \d output(Bruce)
Psql return code now more accurate(Bryan?)
Psql updated help syntax(Bruce)
Re-visit and fix vacuum(Vadim)
Reduce size of regression diffs, remove timezone name difference(Bruce)
Remove compile-time parameters to enable binary distributions(Bryan)
Reverse meaning of HBA masks(Bryan)
Secure Authentication of local users(Bryan)
Speed up vacuum(Vadim)
Vacuum now had VERBOSE option(Bruce)
Source tree changes
-------------------
All functions now have prototypes that are compared against the calls
Allow asserts to be disabled easly from Makefile.global(Bruce)
Change oid constants used in code to #define names
Decoupled sparc and solaris defines(Kurt)
Gcc -Wall compiles cleanly with warnings only from unfixable constructs
Major include file reorganization/reduction(Marc)
Make now stops on compile failure(Bryan)
Makefile restructuring(Bryan, Marc)
Merge bsdi_2_1 to bsdi(Bruce)
Monitor program removed
Name change from Postgres95 to PostgreSQL
New config.h file(Marc, Bryan)
PG_VERSION now set to 6.0 and used by postmaster
Portability additions, including Ultrix, DG/UX, AIX, and Solaris
Reduced the number of #define's, centeralized #define's
Remove duplicate OIDS in system tables(Dan)
Remove duplicate system catalog info or report mismatches(Dan)
Removed many os-specific #define's
Restructured object file generation/location(Bryan, Marc)
Restructured port-specific file locations(Bryan, Marc)
Unused/uninialized variables corrected
</programlisting>
<sect1>
<title>Release v1.09</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Unknown
</date>
</docinfo>
-->
<para>
Sorry, we stopped keeping track of changes from 1.02 to 1.09. Some of
the changes listed in 6.0 were actually included in the 1.02.1 to 1.09
releases.
<sect1>
<title>Release v1.02</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Thu Aug 1 18:00:00 EDT 1996
</date>
</docinfo>
-->
<sect2>
<title>Migration from v1.02 to v1.02.1</title>
<para>
Here is a new migration file for 1.02.1. It includes the 'copy' change
and a script to convert old ascii files.
<note>
<para>
The following notes are for the benefit of users who want to migrate
databases from postgres95 1.01 and 1.02 to postgres95 1.02.1.
<para>
If you are starting afresh with postgres95 1.02.1 and do not need
to migrate old databases, you do not need to read any further.
</note>
<para>
In order to upgrade older postgres95 version 1.01 or 1.02 databases to
version 1.02.1, the following steps are required:
<procedure>
<step>
<para>
Start up a new 1.02.1 postmaster
<step>
<para>
Add the new built-in functions and operators of 1.02.1 to 1.01 or 1.02
databases. This is done by running the new 1.02.1 server against
your own 1.01 or 1.02 database and applying the queries attached at
the end of thie file. This can be done easily through psql. If your
1.01 or 1.02 database is named "testdb" and you have cut the commands
from the end of this file and saved them in addfunc.sql:
<programlisting>
% psql testdb -f addfunc.sql
</programlisting>
Those upgrading 1.02 databases will get a warning when executing the
last two statements in the file because they are already present in 1.02. This is
not a cause for concern.
</procedure>
<sect2>
<title>Dump/Reload Procedure</title>
<para>
If you are trying to reload a pg_dump or text-mode 'copy tablename to
stdout' generated with a previous version, you will need to run the
attached sed script on the ASCII file before loading it into the
database. The old format used '.' as end-of-data, while '\.' is now the
end-of-data marker. Also, empty strings are now loaded in as '' rather
than NULL. See the copy manual page for full details.
<programlisting>
sed 's/^\.$/\\./g' &lt;in_file &gt;out_file
</programlisting>
<para>
If you are loading an older binary copy or non-stdout copy, there is no
end-of-data character, and hence no conversion necessary.
<programlisting>
-- following lines added by agc to reflect the case-insensitive
-- regexp searching for varchar (in 1.02), and bpchar (in 1.02.1)
create operator ~* (leftarg = bpchar, rightarg = text, procedure = texticregexeq);
create operator !~* (leftarg = bpchar, rightarg = text, procedure = texticregexne);
create operator ~* (leftarg = varchar, rightarg = text, procedure = texticregexeq);
create operator !~* (leftarg = varchar, rightarg = text, procedure = texticregexne);
</programlisting>
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Source code maintenance and development
* worldwide team of volunteers
* the source tree now in CVS at ftp.ki.net
Enhancements
* psql (and underlying libpq library) now has many more options for
formatting output, including HTML
* pg_dump now output the schema and/or the data, with many fixes to
enhance completeness.
* psql used in place of monitor in administration shell scripts.
monitor to be depreciated in next release.
* date/time functions enhanced
* NULL insert/update/comparison fixed/enhanced
* TCL/TK lib and shell fixed to work with both tck7.4/tk4.0 and tcl7.5/tk4.1
Bug Fixes (almost too numerous to mention)
* indexes
* storage management
* check for NULL pointer before dereferencing
* Makefile fixes
New Ports
* added SolarisX86 port
* added BSDI 2.1 port
* added DGUX port
</programlisting>
<!--
Contributors (appologies to any missed)
* Kurt J. Lidl <lidl@va.pubnix.com>
(missed in first run, but no less important)
* Erich Stamberger <eberger@gewi.kfunigraz.ac.at>
* Jason Wright <jason@shiloh.vnet.net>
* Cees de Groot <C.deGroot@inter.NL.net>
* ernst.molitor@uni-bonn.de
* michael.siebenborn@ae3.Hypo.DE (Michael Siebenborn (6929))
* Brian E. Gallew <geek+@cmu.edu>
* Vadim B. Mikheev <vadim@sable.krasnoyarsk.su>
* Adam Sussman <myddryn@vidya.com>
* Chris Dunlop <chris@onthe.net.au>
* Marc G. Fournier <scrappy@ki.net>
* Dan McGuirk <mcguirk@indirect.com>
* Dr_George_D_Detlefsen <drgeorge@ilt.com>
* Erich Stamberger <eberger@gewi.kfunigraz.ac.at>
* Massimo Dal Zotto <dz@cs.unitn.it>
* Randy Kunkee <kunkee@Starbase.NeoSoft.COM>
* Rick Weldon <rick@wisetech.com>
* Thomas van Reimersdahl <reimersd@dali.techinfo.rwth-aachen.de>
* david bennett <dave@bensoft.com>
* ernst.molitor@uni-bonn.de
* Julian Assange <proff@suburbia.net>
* Bruce Momjian <maillist@candle.pha.pa.us>
* Paul "Shag" Walmsley <ccshag@cclabs.missouri.edu>
* "Alistair G. Crooks" <azcb0@sde.uts.amdahl.com>
-->
<sect1>
<title>Release v1.01</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Fri Feb 23 18:20:36 PST 1996
</date>
</docinfo>
-->
<sect2>
<title>Migration from v1.0 to v1.01</title>
<para>
The following notes are for the benefit of users who want to migrate
databases from postgres95 1.0 to postgres95 1.01.
<para>
If you are starting afresh with postgres95 1.01 and do not need
to migrate old databases, you do not need to read any further.
<para>
In order to postgres95 version 1.01 with databases created with
postgres95 version 1.0, the following steps are required:
<procedure>
<step>
<para>
Set the definition of NAMEDATALEN in src/Makefile.global to 16
and OIDNAMELEN to 20.
<step>
<para>
Decide whether you want to use Host based authentication.
<substeps>
<step>
<para>
If you do, you must create a file name "pg_hba" in your top-level data
directory (typically the value of your $PGDATA). src/libpq/pg_hba
shows an example syntax.
<step>
<para>
If you do not want host-based authentication, you can comment out
the line
<programlisting>
HBA = 1
</programlisting>
in src/Makefile.global
<para>
Note that host-based authentication is turned on by default, and if
you do not take steps A or B above, the out-of-the-box 1.01 will
not allow you to connect to 1.0 databases.
</substeps>
<step>
<para>
Compile and install 1.01, but DO NOT do the initdb step.
<step>
<para>
Before doing anything else, terminate your 1.0 postmaster, and
backup your existing $PGDATA directory.
<step>
<para>
Set your PGDATA environment variable to your 1.0 databases, but set up
path up so that 1.01 binaries are being used.
<step>
<para>
Modify the file $PGDATA/PG_VERSION from 5.0 to 5.1
<step>
<para>
Start up a new 1.01 postmaster
<step>
<para>
Add the new built-in functions and operators of 1.01 to 1.0
databases. This is done by running the new 1.01 server against
your own 1.0 database and applying the queries attached and saving
in the file 1.0_to_1.01.sql. This can be done easily through psql.
If your 1.0 database is name "testdb":
<programlisting>
% psql testdb -f 1.0_to_1.01.sql
</programlisting>
and then execute the following commands (cut and paste from here):
<programlisting>
-- add builtin functions that are new to 1.01
create function int4eqoid (int4, oid) returns bool as 'foo'
language 'internal';
create function oideqint4 (oid, int4) returns bool as 'foo'
language 'internal';
create function char2icregexeq (char2, text) returns bool as 'foo'
language 'internal';
create function char2icregexne (char2, text) returns bool as 'foo'
language 'internal';
create function char4icregexeq (char4, text) returns bool as 'foo'
language 'internal';
create function char4icregexne (char4, text) returns bool as 'foo'
language 'internal';
create function char8icregexeq (char8, text) returns bool as 'foo'
language 'internal';
create function char8icregexne (char8, text) returns bool as 'foo'
language 'internal';
create function char16icregexeq (char16, text) returns bool as 'foo'
language 'internal';
create function char16icregexne (char16, text) returns bool as 'foo'
language 'internal';
create function texticregexeq (text, text) returns bool as 'foo'
language 'internal';
create function texticregexne (text, text) returns bool as 'foo'
language 'internal';
-- add builtin functions that are new to 1.01
create operator = (leftarg = int4, rightarg = oid, procedure = int4eqoid);
create operator = (leftarg = oid, rightarg = int4, procedure = oideqint4);
create operator ~* (leftarg = char2, rightarg = text, procedure = char2icregexeq);
create operator !~* (leftarg = char2, rightarg = text, procedure = char2icregexne);
create operator ~* (leftarg = char4, rightarg = text, procedure = char4icregexeq);
create operator !~* (leftarg = char4, rightarg = text, procedure = char4icregexne);
create operator ~* (leftarg = char8, rightarg = text, procedure = char8icregexeq);
create operator !~* (leftarg = char8, rightarg = text, procedure = char8icregexne);
create operator ~* (leftarg = char16, rightarg = text, procedure = char16icregexeq);
create operator !~* (leftarg = char16, rightarg = text, procedure = char16icregexne);
create operator ~* (leftarg = text, rightarg = text, procedure = texticregexeq);
create operator !~* (leftarg = text, rightarg = text, procedure = texticregexne);
</programlisting>
</procedure>
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Incompatibilities:
* 1.01 is backwards compatible with 1.0 database provided the user
follow the steps outlined in the MIGRATION_from_1.0_to_1.01 file.
If those steps are not taken, 1.01 is not compatible with 1.0 database.
Enhancements:
* added PQdisplayTuples() to libpq and changed monitor and psql to use it
* added NeXT port (requires SysVIPC implementation)
* added CAST .. AS ... syntax
* added ASC and DESC keywords
* added 'internal' as a possible language for CREATE FUNCTION
internal functions are C functions which have been statically linked
into the postgres backend.
* a new type "name" has been added for system identifiers (table names,
attribute names, etc.) This replaces the old char16 type. The
of name is set by the NAMEDATALEN #define in src/Makefile.global
* a readable reference manual that describes the query language.
* added host-based access control. A configuration file ($PGDATA/pg_hba)
is used to hold the configuration data. If host-based access control
is not desired, comment out HBA=1 in src/Makefile.global.
* changed regex handling to be uniform use of Henry Spencer's regex code
regardless of platform. The regex code is included in the distribution
* added functions and operators for case-insensitive regular expressions.
The operators are ~* and !~*.
* pg_dump uses COPY instead of SELECT loop for better performance
Bug fixes:
* fixed an optimizer bug that was causing core dumps when
functions calls were used in comparisons in the WHERE clause
* changed all uses of getuid to geteuid so that effective uids are used
* psql now returns non-zero status on errors when using -c
* applied public patches 1-14
</programlisting>
<sect1>
<title>Release v1.0</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Tue Sep 5 11:24:11 PDT 1995
</date>
</docinfo>
-->
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Copyright change:
* The copyright of <productname>Postgres</productname> 1.0 has been loosened to be freely modifiable
and modifiable for any purpose. Please read the COPYRIGHT file.
Thanks to Professor Michael Stonebraker for making this possible.
Incompatibilities:
* date formats have to be MM-DD-YYYY (or DD-MM-YYYY if you're using
EUROPEAN STYLE). This follows SQL-92 specs.
* "delimiters" is now a keyword
Enhancements:
* sql LIKE syntax has been added
* copy command now takes an optional USING DELIMITER specification.
delimiters can be any single-character string.
* IRIX 5.3 port has been added.
Thanks to Paul Walmsley and others.
* updated pg_dump to work with new libpq
* \d has been added psql
Thanks to Keith Parks
* regexp performance for architectures that use POSIX regex has been
improved due to caching of precompiled patterns.
Thanks to Alistair Crooks
* a new version of libpq++
Thanks to William Wanders
Bug fixes:
* arbitrary userids can be specified in the createuser script
* \c to connect to other databases in psql now works.
* bad pg_proc entry for float4inc() is fixed
* users with usecreatedb field set can now create databases without
having to be usesuper
* remove access control entries when the entry no longer has any
permissions
* fixed non-portable datetimes implementation
* added kerberos flags to the src/backend/Makefile
* libpq now works with kerberos
* typographic errors in the user manual have been corrected.
* btrees with multiple index never worked, now we tell you they don't
work when you try to use them
</programlisting>
<sect1>
<title><productname>Postgres95</productname> Beta 0.03</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Fri Jul 21 14:49:31 PDT 1995
</date>
</docinfo>
-->
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Incompatible changes:
* BETA-0.3 IS INCOMPATIBLE WITH DATABASES CREATED WITH PREVIOUS VERSIONS
(due to system catalog changes and indexing structure changes).
* double-quote (") is deprecated as a quoting character for string literals;
you need to convert them to single quotes (').
* name of aggregates (eg. int4sum) are renamed in accordance with the
SQL standard (eg. sum).
* CHANGE ACL syntax is replaced by GRANT/REVOKE syntax.
* float literals (eg. 3.14) are now of type float4 (instead of float8 in
previous releases); you might have to do typecasting if you depend on it
being of type float8. If you neglect to do the typecasting and you assign
a float literal to a field of type float8, you may get incorrect values
stored!
* LIBPQ has been totally revamped so that frontend applications
can connect to multiple backends
* the usesysid field in pg_user has been changed from int2 to int4 to
allow wider range of Unix user ids.
* the netbsd/freebsd/bsd o/s ports have been consolidated into a
single BSD44_derived port. (thanks to Alistair Crooks)
SQL standard-compliance (the following details changes that makes postgres95
more compliant to the SQL-92 standard):
* the following SQL types are now built-in: smallint, int(eger), float, real,
char(N), varchar(N), date and time.
The following are aliases to existing postgres types:
smallint -> int2
integer, int -> int4
float, real -> float4
char(N) and varchar(N) are implemented as truncated text types. In
addition, char(N) does blank-padding.
* single-quote (') is used for quoting string literals; '' (in addition to
\') is supported as means of inserting a single quote in a string
* SQL standard aggregate names (MAX, MIN, AVG, SUM, COUNT) are used
(Also, aggregates can now be overloaded, i.e. you can define your
own MAX aggregate to take in a user-defined type.)
* CHANGE ACL removed. GRANT/REVOKE syntax added.
- Privileges can be given to a group using the "GROUP" keyword.
For example:
GRANT SELECT ON foobar TO GROUP my_group;
The keyword 'PUBLIC' is also supported to mean all users.
Privileges can only be granted or revoked to one user or group
at a time.
"WITH GRANT OPTION" is not supported. Only class owners can change
access control
- The default access control is to to grant users readonly access.
You must explicitly grant insert/update access to users. To change
this, modify the line in
src/backend/utils/acl.h
that defines ACL_WORLD_DEFAULT
Bug fixes:
* the bug where aggregates of empty tables were not run has been fixed. Now,
aggregates run on empty tables will return the initial conditions of the
aggregates. Thus, COUNT of an empty table will now properly return 0.
MAX/MIN of an empty table will return a tuple of value NULL.
* allow the use of \; inside the monitor
* the LISTEN/NOTIFY asynchronous notification mechanism now work
* NOTIFY in rule action bodies now work
* hash indices work, and access methods in general should perform better.
creation of large btree indices should be much faster. (thanks to Paul
Aoki)
Other changes and enhancements:
* addition of an EXPLAIN statement used for explaining the query execution
plan (eg. "EXPLAIN SELECT * FROM EMP" prints out the execution plan for
the query).
* WARN and NOTICE messages no longer have timestamps on them. To turn on
timestamps of error messages, uncomment the line in
src/backend/utils/elog.h:
/* define ELOG_TIMESTAMPS */
* On an access control violation, the message
"Either no such class or insufficient privilege"
will be given. This is the same message that is returned when
a class is not found. This dissuades non-privileged users from
guessing the existence of privileged classes.
* some additional system catalog changes have been made that are not
visible to the user.
libpgtcl changes:
* The -oid option has been added to the "pg_result" tcl command.
pg_result -oid returns oid of the last tuple inserted. If the
last command was not an INSERT, then pg_result -oid returns "".
* the large object interface is available as pg_lo* tcl commands:
pg_lo_open, pg_lo_close, pg_lo_creat, etc.
Portability enhancements and New Ports:
* flex/lex problems have been cleared up. Now, you should be able to use
flex instead of lex on any platforms. We no longer make assumptions of
what lexer you use based on the platform you use.
* The Linux-ELF port is now supported. Various configuration have been
tested: The following configuration is known to work:
kernel 1.2.10, gcc 2.6.3, libc 4.7.2, flex 2.5.2, bison 1.24
with everything in ELF format,
New utilities:
* ipcclean added to the distribution
ipcclean usually does not need to be run, but if your backend crashes
and leaves shared memory segments hanging around, ipcclean will
clean them up for you.
New documentation:
* the user manual has been revised and libpq documentation added.
</programlisting>
<sect1>
<title><productname>Postgres95</productname> Beta 0.02</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Thu May 25 16:54:46 PDT 1995
</date>
</docinfo>
-->
<sect2>
<title>Detailed Change List</title>
<para>
<programlisting>
Incompatible changes:
* The SQL statement for creating a database is 'CREATE DATABASE' instead
of 'CREATEDB'. Similarly, dropping a database is 'DROP DATABASE' instead
of 'DESTROYDB'. However, the names of the executables 'createdb' and
'destroydb' remain the same.
New tools:
* pgperl - a Perl (4.036) interface to Postgres95
* pg_dump - a utility for dumping out a postgres database into a
script file containing query commands. The script files are in a ASCII
format and can be used to reconstruct the database, even on other
machines and other architectures. (Also good for converting
a Postgres 4.2 database to Postgres95 database.)
The following ports have been incorporated into postgres95-beta-0.02:
* the NetBSD port by Alistair Crooks
* the AIX port by Mike Tung
* the Windows NT port by Jon Forrest (more stuff but not done yet)
* the Linux ELF port by Brian Gallew
The following bugs have been fixed in postgres95-beta-0.02:
* new lines not escaped in COPY OUT and problem with COPY OUT when first
attribute is a '.'
* cannot type return to use the default user id in createuser
* SELECT DISTINCT on big tables crashes
* Linux installation problems
* monitor doesn't allow use of 'localhost' as PGHOST
* psql core dumps when doing \c or \l
* the "pgtclsh" target missing from src/bin/pgtclsh/Makefile
* libpgtcl has a hard-wired default port number
* SELECT DISTINCT INTO TABLE hangs
* CREATE TYPE doesn't accept 'variable' as the internallength
* wrong result using more than 1 aggregate in a SELECT
</programlisting>
<sect1>
<title><productname>Postgres95</productname> Beta 0.01</title>
<!--
<docinfo>
<authorgroup>
<author>
<firstname>Bruce</firstname>
<surname>Momjian</surname>
</author>
</authorgroup>
<date>
Mon May 1 19:03:10 PDT 1995
</date>
</docinfo>
-->
<para>
Initial release.
<Sect1> <Sect1>
<Title>Timing Results</Title> <Title>Timing Results</Title>
<Para> <Para>
These timing results are from running the regression test with the command These timing results are from running the regression test with the commands
<ProgramListing> <ProgramListing>
% cd src/test/regress
% make all
% time make runtest % time make runtest
</ProgramListing> </ProgramListing>
<Para> <Para>
Timing under Linux 2.0.27 seems to have a roughly 5% variation from run Timing under Linux 2.0.27 seems to have a roughly 5% variation from run
to run, presumably due to the timing vagaries of multitasking systems. to run, presumably due to the scheduling vagaries of multitasking systems.
<Sect2>
<Title>v6.4beta</Title>
<para>
The times for this release are not directly comparable to those for previous releases
since some additional regression tests have been included.
In general, however, v6.4 should be slightly faster than the previous release (thanks, Bruce!).
<Para>
<ProgramListing>
Time System
02:35 Dual Pentium Pro 180, 96MB, UW-SCSI, Linux 2.0.30, gcc 2.7.2.1 -O2 -m486
</ProgramListing>
<Sect2> <Sect2>
<Title>v6.3</Title> <Title>v6.3</Title>
<para>
The times for this release are not directly comparable to those for previous releases
since some additional regression tests have been included and some obsolete tests involving
time travel have been removed.
In general, however, v6.3 is substantially faster than previous releases (thanks, Bruce!).
<Para> <Para>
<ProgramListing> <ProgramListing>
Time System Time System
...@@ -135,10 +1768,9 @@ These timing results are from running the regression test with the command ...@@ -135,10 +1768,9 @@ These timing results are from running the regression test with the command
<Para> <Para>
<ProgramListing> <ProgramListing>
Time System Time System
06:12 Pentium Pro 180, 32MB, Linux 2.0.30, gcc 2.7.2 -O2 -m486 06:12 Pentium Pro 180, 32MB, EIDE, Linux 2.0.30, gcc 2.7.2 -O2 -m486
12:06 P-100, 48MB, Linux 2.0.29, gcc 12:06 P-100, 48MB, Linux 2.0.29, gcc
39:58 Sparc IPC 32MB, Solaris 2.5, gcc 2.7.2.1 -O -g 39:58 Sparc IPC 32MB, Solaris 2.5, gcc 2.7.2.1 -O -g
</ProgramListing> </ProgramListing>
</Chapter> </Chapter>
doc/src/sgml/typeconv.sgml 0 → 100644
View file @ ba3a99f1
<chapter>
<title>Type Conversion</title>
<para>
<acronym>SQL</acronym> queries can, intentionally or not, require
mixing of different data types in the same expression.
<productname>Postgres</productname> has extensive facilities for
evaluating mixed-type expressions.
<para>
In many cases a user will not need
to understand the details of the type conversion mechanism.
However, the implicit conversions done by <productname>Postgres</productname>
can affect the apparent results of a query, and these results
can be tailored by a user or programmer
using <emphasis>explicit</emphasis> type coersion.
<para>
This chapter introduces the <productname>Postgres</productname>
type conversion mechanisms and conventions.
Refer to the relevant sections in the User's Guide and Programmer's Guide
for more information on specific data types and allowed functions and operators.
<para>
The Programmer's Guide has more details on the exact algorithms used for
implicit type conversion and coersion.
<sect1>
<title>Overview</title>
<para>
<acronym>SQL</acronym> is a strongly typed language. That is, every data item
has an associated data type which determines its behavior and allowed usage.
<productname>Postgres</productname> has an extensible type system which is
much more general and flexible than other <acronym>RDBMS</acronym> implementations.
Hence, most type conversion behavior in <productname>Postgres</productname>
should be governed by general rules rather than by ad-hoc heuristics to allow
mixed-type expressions to be meaningful, even with user-defined types.
<para>
The <productname>Postgres</productname> scanner/parser decodes lexical elements
into only five fundamental categories: integers, floats, strings, names, and keywords.
Most extended types are first tokenized into strings. The <acronym>SQL</acronym>
language definition allows specifying type names with strings, and this mechanism
is used by <productname>Postgres</productname>
to start the parser down the correct path. For example, the query
<programlisting>
tgl=> SELECT text 'Origin' AS "Label", point '(0,0)' AS "Value";
Label |Value
------+-----
Origin|(0,0)
(1 row)
</programlisting>
has two strings, of type <type>text</type> and <type>point</type>.
If a type is not specified, then the placeholder type <type>unknown</type>
is assigned initially, to be resolved in later stages as described below.
<para>
There are four fundamental <acronym>SQL</acronym> constructs requiring
distinct type conversion rules in the <productname>Postgres</productname>
parser:
<variablelist>
<varlistentry>
<term>
Operators
</term>
<listitem>
<para>
<productname>Postgres</productname> allows expressions with
left- and right-unary (one argument) operators,
as well as binary (two argument) operators.
</listitem>
</varlistentry>
<varlistentry>
<term>
Function calls
</term>
<listitem>
<para>
Much of the <productname>Postgres</productname> type system is built around a rich set of
functions. Function calls have one or more arguments which, for any specific query,
must be matched to the functions available in the system catalog.
</listitem>
</varlistentry>
<varlistentry>
<term>
Query targets
</term>
<listitem>
<para>
<acronym>SQL</acronym> INSERT statements place the results of query into a table. The expressions
in the query must be matched up with, and perhaps converted to, the target columns of the insert.
</listitem>
</varlistentry>
<varlistentry>
<term>
UNION queries
</term>
<listitem>
<para>
Since all select results from a UNION SELECT statement must appear in a single set of columns, the types
of each SELECT clause must be matched up and converted to a uniform set.
</listitem>
</varlistentry>
</variablelist>
<para>
Many of the general type conversion rules use simple conventions built on
the <productname>Postgres</productname> function and operator system tables.
There are some heuristics included in the conversion rules to better support
conventions for the <acronym>SQL92</acronym> standard native types such as
<type>smallint</type>, <type>integer</type>, and <type>float</type>.
<para>
The <productname>Postgres</productname> parser uses the convention that all
type conversion functions take a single argument of the source type and are
named with the same name as the target type. Any function meeting this
criteria is considered to be a valid conversion function, and may be used
by the parser as such. This simple assumption gives the parser the power
to explore type conversion possibilities without hardcoding, allowing
extended user-defined types to use these same features transparently.
<para>
An additional heuristic is provided in the parser to allow better guesses
at proper behavior for <acronym>SQL</acronym> standard types. There are
five categories of types defined: boolean, string, numeric, geometric,
and user-defined. Each category, with the exception of user-defined, has
a "preferred type" which is used to resolve ambiguities in candidates.
Each "user-defined" type is its own "preferred type", so ambiguous
expressions (those with multiple candidate parsing solutions)
with only one user-defined type can resolve to a single best choice, while those with
multiple user-defined types will remain ambiguous and throw an error.
<para>
Ambiguous expressions which have candidate solutions within only one type category are
likely to resolve, while ambiguous expressions with candidates spanning multiple
categories are likely to throw an error and ask for clarification from the user.
<sect2>
<title>Guidelines</title>
<para>
All type conversion rules are designed with several principles in mind:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
Implicit conversions should never have suprising or unpredictable outcomes.
<listitem>
<para>
User-defined types, of which the parser has no apriori knowledge, should be
"higher" in the type heirarchy. In mixed-type expressions, native types shall always
be converted to a user-defined type (of course, only if conversion is necessary).
<listitem>
<para>
User-defined types are not related. Currently, <productname>Postgres</productname>
does not have information available to it on relationships between types, other than
hardcoded heuristics for built-in types and implicit relationships based on available functions
in the catalog.
<listitem>
<para>
There should be no extra overhead from the parser or executor
if a query does not need implicit type conversion.
That is, if a query is well formulated and the types already match up, then the query should proceed
without spending extra time in the parser and without introducing unnecessary implicit conversion
functions into the query.
<para>
Additionally, if a query usually requires an implicit conversion for a function, and
if then the user defines an explicit function with the correct argument types, the parser
should use this new function and will no longer do the implicit conversion using the old function.
</itemizedlist>
<sect1>
<title>Operators</title>
<sect2>
<title>Conversion Procedure</title>
<para>
<procedure>
<title>Operator Evaluation</title>
<para>
<step performance="required">
<para>
Check for an exact match in the pg_operator system catalog.
<substeps>
<step performance="optional">
<para>
If one argument of a binary operator is <type>unknown</type>,
then assume it is the same type as the other argument.
<step performance="required">
<para>
Reverse the arguments, and look for an exact match with an operator which
points to itself as being commutative.
If found, then reverse the arguments in the parse tree and use this operator.
</substeps>
<step performance="required">
<para>
Look for the best match.
<substeps>
<step performance="optional">
<para>
Make a list of all operators of the same name.
<step performance="required">
<para>
If only one operator is in the list, use it if the input type can be coerced,
and throw an error if the type cannot be coerced.
<step performance="required">
<para>
Keep all operators with the most explicit matches for types. Keep all if there
are no explicit matches and move to the next step.
If only one candidate remains, use it if the type can be coerced.
<step performance="required">
<para>
If any input arguments are "unknown", categorize the input candidates as
boolean, numeric, string, geometric, or user-defined. If there is a mix of
categories, or more than one user-defined type, throw an error because
the correct choice cannot be deduced without more clues.
If only one category is present, then assign the "preferred type"
to the input column which had been previously "unknown".
<step performance="required">
<para>
Choose the candidate with the most exact type matches, and which matches
the "preferred type" for each column category from the previous step.
If there is still more than one candidate, or if there are none,
then throw an error.
</substeps>
</procedure>
<sect2>
<title>Examples</title>
<sect3>
<title>Exponentiation Operator</title>
<para>
There is only one exponentiation
operator defined in the catalog, and it takes <type>float8</type> arguments.
The scanner assigns an initial type of <type>int4</type> to both arguments
of this query expression:
<programlisting>
tgl=> select 2 ^ 3 AS "Exp";
Exp
---
8
(1 row)
</programlisting>
So the parser does a type conversion on both operands and the query
is equivalent to
<programlisting>
tgl=> select float8(2) ^ float8(3) AS "Exp";
Exp
---
8
(1 row)
</programlisting>
or
<programlisting>
tgl=> select 2.0 ^ 3.0 AS "Exp";
Exp
---
8
(1 row)
</programlisting>
<note>
<para>
This last form has the least overhead, since no functions are called to do
implicit type conversion. This is not an issue for small queries, but may
have an impact on the performance of queries involving large tables.
</note>
<sect3>
<title>String Concatenation</title>
<para>
A string-like syntax is used for working with string types as well as for
working with complex extended types.
Strings with unspecified type are matched with likely operator candidates.
<para>
One unspecified argument:
<programlisting>
tgl=> SELECT text 'abc' || 'def' AS "Text and Unknown";
Text and Unknown
----------------
abcdef
(1 row)
</programlisting>
<para>
In this case the parser looks to see if there is an operator taking <type>text</type>
for both arguments. Since there is, it assumes that the second argument should
be interpreted as of type <type>text</type>.
<para>
Concatenation on unspecified types:
<programlisting>
tgl=> SELECT 'abc' || 'def' AS "Unspecified";
Unspecified
-----------
abcdef
(1 row)
</programlisting>
<para>
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 all arguments for all the candidates are string types. It chooses
the "preferred type" for strings, <type>text</type>, for this query.
<note>
<para>
If a user defines a new type and defines an operator <quote>||</quote> to work
with it, then this query would no longer succeed as written. The parser would
now have candidate types from two categories, and could not decide which to use.
</note>
<sect3>
<title>Factorial</title>
<para>
This example illustrates an interesting result. Traditionally, the
factorial operator is defined for integers only. The <productname>Postgres</productname>
operator catalog has only one entry for factorial, taking an integer operand.
If given a non-integer numeric argument, <productname>Postgres</productname>
will try to convert that argument to an integer for evaluation of the
factorial.
<programlisting>
tgl=> select (4.3 !);
?column?
--------
24
(1 row)
</programlisting>
<note>
<para>
Of course, this leads to a mathematically suspect result,
since in principle the factorial of a non-integer is not defined.
However, the role of a database is not to teach mathematics, but
to be a tool for data manipulation. If a user chooses to take the
factorial of a floating point number, <productname>Postgres</productname>
will try to oblige.
</note>
<sect1>
<title>Functions</title>
<para>
<procedure>
<title>Function Evaluation</title>
<step performance="required">
<para>
Check for an exact match in the pg_proc system catalog.
<step performance="required">
<para>
Look for the best match.
<substeps>
<step performance="required">
<para>
Make a list of all functions of the same name with the same number of arguments.
<step performance="required">
<para>
If only one function is in the list, use it if the input types can be coerced,
and throw an error if the types cannot be coerced.
<step performance="required">
<para>
Keep all functions with the most explicit matches for types. Keep all if there
are no explicit matches and move to the next step.
If only one candidate remains, use it if the type can be coerced.
<step performance="required">
<para>
If any input arguments are "unknown", categorize the input candidate arguments as
boolean, numeric, string, geometric, or user-defined. If there is a mix of
categories, or more than one user-defined type, throw an error because
the correct choice cannot be deduced without more clues.
If only one category is present, then assign the "preferred type"
to the input column which had been previously "unknown".
<step performance="required">
<para>
Choose the candidate with the most exact type matches, and which matches
the "preferred type" for each column category from the previous step.
If there is still more than one candidate, or if there are none,
then throw an error.
</substeps>
</procedure>
<sect2>
<title>Examples</title>
<sect3>
<title>Factorial Function</title>
<para>
There is only one factorial function defined in the pg_proc catalog.
So the following query automatically converts the <type>int2</type> argument
to <type>int4</type>:
<programlisting>
tgl=> select int4fac(int2 '4');
int4fac
-------
24
(1 row)
</programlisting>
and is actually transformed by the parser to
<programlisting>
tgl=> select int4fac(int4(int2 '4'));
int4fac
-------
24
(1 row)
</programlisting>
<sect3>
<title>Substring Function</title>
<para>
There are two <function>substr</function> functions declared in pg_proc. However,
only one takes two arguments, of types <type>text</type> and <type>int4</type>.
<para>
If called with a string constant of unspecified type, the type is matched up
directly with the only candidate function type:
<programlisting>
tgl=> select substr('1234', 3);
substr
------
34
(1 row)
</programlisting>
<para>
If the string is declared to be of type <type>varchar</type>, as might be the case
if it comes from a table, then the parser will try to coerce it to become <type>text</type>:
<programlisting>
tgl=> select substr(varchar '1234', 3);
substr
------
34
(1 row)
</programlisting>
which is transformed by the parser to become
<programlisting>
tgl=> select substr(text(varchar '1234'), 3);
substr
------
34
(1 row)
</programlisting>
<note>
<para>
There are some heuristics in the parser to optimize the relationship between the
<type>char</type>, <type>varchar</type>, and <type>text</type> types.
For this case, <function>substr</function> is called directly with the <type>varchar</type> string
rather than inserting an explicit conversion call.
</note>
<para>
And, if the function is called with an <type>int4</type>, the parser will
try to convert that to <type>text</type>:
<programlisting>
tgl=> select substr(1234, 3);
substr
------
34
(1 row)
</programlisting>
actually executes as
<programlisting>
tgl=> select substr(text(1234), 3);
substr
------
34
(1 row)
</programlisting>
<sect1>
<title>Query Targets</title>
<para>
<procedure>
<title>Target Evaluation</title>
<step performance="required">
<para>
Check for an exact match with the target.
<step performance="required">
<para>
Try to coerce the expression directly to the target type if necessary.
<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 of the same name
as the type taking two arguments, the first the type name and the second an
integer length.
</procedure>
<sect2>
<title>Examples</title>
<sect3>
<title><type>varchar</type> Storage</title>
<para>
For a target column declared as <type>varchar(4)</type> the following query
ensures that the target is sized correctly:
<programlisting>
tgl=> CREATE TABLE vv (v varchar(4));
CREATE
tgl=> INSERT INTO vv SELECT 'abc' || 'def';
INSERT 392905 1
tgl=> select * from vv;
v
----
abcd
(1 row)
</programlisting>
<sect1>
<title>UNION Queries</title>
<para>
The UNION construct is somewhat different in that it must match up
possibly dissimilar types to become a single result set.
<procedure>
<title>UNION Evaluation</title>
<step performance="required">
<para>
Check for identical types for all results.
<step performance="required">
<para>
Coerce each result from the UNION clauses to match the type of the
first SELECT clause or the target column.
</procedure>
<sect2>
<title>Examples</title>
<sect3>
<title>Underspecified Types</title>
<para>
<programlisting>
tgl=> SELECT text 'a' AS "Text" UNION SELECT 'b';
Text
----
a
b
(2 rows)
</programlisting>
<sect3>
<title>Simple UNION</title>
<para>
<programlisting>
tgl=> SELECT 1.2 AS Float8 UNION SELECT 1;
Float8
------
1
1.2
(2 rows)
</programlisting>
<sect3>
<title>Transposed UNION</title>
<para>
The types of the union are forced to match the types of
the first/top clause in the union:
<programlisting>
tgl=> SELECT 1 AS "All integers"
tgl-> UNION SELECT '2.2'::float4
tgl-> UNION SELECT 3.3;
All integers
------------
1
2
3
(3 rows)
</programlisting>
<para>
An alternate parser strategy could be to choose the "best" type of the bunch, but
this is more difficult because of the nice recursion technique used in the
parser. However, the "best" type is used when selecting <emphasis>into</emphasis>
a table:
<programlisting>
tgl=> CREATE TABLE ff (f float);
CREATE
tgl=> INSERT INTO ff
tgl-> SELECT 1
tgl-> UNION SELECT '2.2'::float4
tgl-> UNION SELECT 3.3;
INSERT 0 3
tgl=> SELECT f AS "Floating point" from ff;
Floating point
----------------
1
2.20000004768372
3.3
(3 rows)
</programlisting>
</chapter>
doc/src/sgml/user.sgml
View file @ ba3a99f1
...@@ -11,6 +11,9 @@ ...@@ -11,6 +11,9 @@
<!entity environ SYSTEM "environ.sgml"> <!entity environ SYSTEM "environ.sgml">
<!entity manage SYSTEM "manage.sgml"> <!entity manage SYSTEM "manage.sgml">
<!entity datatype SYSTEM "datatype.sgml"> <!entity datatype SYSTEM "datatype.sgml">
<!entity oper SYSTEM "oper.sgml">
<!entity func SYSTEM "func.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!entity array SYSTEM "array.sgml"> <!entity array SYSTEM "array.sgml">
<!entity inherit SYSTEM "inherit.sgml"> <!entity inherit SYSTEM "inherit.sgml">
<!entity query-ug SYSTEM "query-ug.sgml"> <!entity query-ug SYSTEM "query-ug.sgml">
...@@ -92,6 +95,9 @@ It provides SQL92/SQL3 language support, ...@@ -92,6 +95,9 @@ It provides SQL92/SQL3 language support,
&environ; &environ;
&manage; &manage;
&datatype; &datatype;
&oper;
&func;
&typeconv;
&array; &array;
&inherit; &inherit;
&query-ug; &query-ug;
......
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