mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-22 03:43:22 +02:00
1289 lines
34 KiB
Plaintext
1289 lines
34 KiB
Plaintext
<Chapter Id="datatype">
|
|
<Title>Data Types</Title>
|
|
|
|
<Abstract>
|
|
<Para>
|
|
Describes the built-in data types available in <ProductName>Postgres</ProductName>.
|
|
</Para>
|
|
</Abstract>
|
|
|
|
<Para>
|
|
<ProductName>Postgres</ProductName> has a rich set of native data types available to users.
|
|
Users may add new types to <ProductName>Postgres</ProductName> using the
|
|
<Command>define type</Command>
|
|
command described elsewhere.
|
|
|
|
<Para>
|
|
In the context of data types, the following sections will discuss SQL standards
|
|
compliance, porting issues, and usage.
|
|
|
|
Some <ProductName>Postgres</ProductName> types correspond directly to SQL92-compatible types. In other
|
|
cases, data types defined by SQL92 syntax are mapped directly
|
|
into native <ProductName>Postgres</ProductName> types.
|
|
|
|
Many of the built-in types have obvious external formats. However, several
|
|
types are either unique to <ProductName>Postgres</ProductName>, such as open and closed paths, or have
|
|
several possibilities for formats, such as date and time types.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Data Types</TITLE>
|
|
<TITLEABBREV>Data Types</TITLEABBREV>
|
|
<TGROUP COLS="3">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY><ProductName>Postgres</ProductName> Type</ENTRY>
|
|
<ENTRY><Acronym>SQL92</Acronym> or <Acronym>SQL3</Acronym> Type</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>bool</ENTRY>
|
|
<ENTRY>boolean</ENTRY>
|
|
<ENTRY>logical boolean (true/false)</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>box</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>rectangular box in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>char(n)</ENTRY>
|
|
<ENTRY>character(n)</ENTRY>
|
|
<ENTRY>fixed-length character string</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>circle</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>circle in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>date</ENTRY>
|
|
<ENTRY>date</ENTRY>
|
|
<ENTRY>calendar date without time of day</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>float4/8</ENTRY>
|
|
<ENTRY>float(p)</ENTRY>
|
|
<ENTRY>floating-point number with precision p</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>float8</ENTRY>
|
|
<ENTRY>real, double precision</ENTRY>
|
|
<ENTRY>double-precision floating-point number</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>int2</ENTRY>
|
|
<ENTRY>smallint</ENTRY>
|
|
<ENTRY>signed two-byte integer</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>int4</ENTRY>
|
|
<ENTRY>int, integer</ENTRY>
|
|
<ENTRY>signed 4-byte integer</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>int4</ENTRY>
|
|
<ENTRY>decimal(p,s)</ENTRY>
|
|
<ENTRY>exact numeric for p <= 9, s = 0</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>int4</ENTRY>
|
|
<ENTRY>numeric(p,s)</ENTRY>
|
|
<ENTRY>exact numeric for p == 9, s = 0</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>line</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>infinite line in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>lseg</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>line segment in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>money</ENTRY>
|
|
<ENTRY>decimal(9,2)</ENTRY>
|
|
<ENTRY>US-style currency</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>path</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>open and closed geometric path in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>point</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>geometric point in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>polygon</ENTRY>
|
|
<ENTRY></ENTRY>
|
|
<ENTRY>closed geometric path in 2D plane</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>time</ENTRY>
|
|
<ENTRY>time</ENTRY>
|
|
<ENTRY>time of day</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timespan</ENTRY>
|
|
<ENTRY>interval</ENTRY>
|
|
<ENTRY>general-use time span</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timestamp</ENTRY>
|
|
<ENTRY>timestamp with time zone</ENTRY>
|
|
<ENTRY>date/time</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>varchar(n)</ENTRY>
|
|
<ENTRY>character varying(n)</ENTRY>
|
|
<ENTRY>variable-length character string</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Function Constants</TITLE>
|
|
<TITLEABBREV>Constants</TITLEABBREV>
|
|
<TGROUP COLS="3">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY><ProductName>Postgres</ProductName> Function</ENTRY>
|
|
<ENTRY><Acronym>SQL92</Acronym> Constant</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>getpgusername()</ENTRY>
|
|
<ENTRY>current_user</ENTRY>
|
|
<ENTRY>user name in current session</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>date('now')</ENTRY>
|
|
<ENTRY>current_date</ENTRY>
|
|
<ENTRY>date of current transaction</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>time('now')</ENTRY>
|
|
<ENTRY>current_time</ENTRY>
|
|
<ENTRY>time of current transaction</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timestamp('now')</ENTRY>
|
|
<ENTRY>current_timestamp</ENTRY>
|
|
<ENTRY>date and time of current transaction</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
<ProductName>Postgres</ProductName> has features at the forefront of ORDBMS development. In addition to
|
|
SQL3 conformance, substantial portions of SQL92 are also supported.
|
|
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.
|
|
<ProductName>Postgres</ProductName> will not make great efforts to conform to these aspects;
|
|
however, these
|
|
tend to apply in little-used or obsure cases, and a typical user is not likely to
|
|
run into them.
|
|
|
|
<Para>
|
|
Most of the input and output functions corresponding to the
|
|
base types (e.g., integers and floating point numbers) do some
|
|
error-checking.
|
|
Some of the operators and functions (e.g.,
|
|
addition and multiplication) do not perform run-time error-checking in the
|
|
interests of improving execution speed.
|
|
On some systems, for example, the numeric operators for some data types may
|
|
silently underflow or overflow.
|
|
</Para>
|
|
|
|
<Para>
|
|
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 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>
|
|
|
|
<Sect1>
|
|
<Title>Numeric Types</Title>
|
|
|
|
<Para>
|
|
Numeric types consist of two- and four-byte integers and four- and eight-byte
|
|
floating point numbers.
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Numeric Types</TITLE>
|
|
<TITLEABBREV>Numerics</TITLEABBREV>
|
|
<TGROUP COLS="4">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Numeric Type</ENTRY>
|
|
<ENTRY>Storage</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
<ENTRY>Range</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>int2</ENTRY>
|
|
<ENTRY>2 bytes</ENTRY>
|
|
<ENTRY>Fixed-precision</ENTRY>
|
|
<ENTRY>-32768 to +32767</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>int4</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>Usual choice for fixed-precision</ENTRY>
|
|
<ENTRY>-2147483648 to +2147483647</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>int8</ENTRY>
|
|
<ENTRY>8 bytes</ENTRY>
|
|
<ENTRY>Very large range fixed-precision</ENTRY>
|
|
<ENTRY>+/- > 18 decimal places</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>float4</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>Variable-precision</ENTRY>
|
|
<ENTRY>6 decimal places</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>float8</ENTRY>
|
|
<ENTRY>8 bytes</ENTRY>
|
|
<ENTRY>Variable-precision</ENTRY>
|
|
<ENTRY>15 decimal places</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
The <FirstTerm>exact numerics</FirstTerm> <Type>decimal</Type> and <Type>numeric</Type>
|
|
have fully implemented syntax but currently (<ProductName>Postgres</ProductName> v6.3)
|
|
support only a small range of precision and/or range values.
|
|
The <type>int8</type> type may not be available on all platforms.
|
|
</Para>
|
|
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Monetary Type</Title>
|
|
|
|
<Para>
|
|
The <Type>money</Type> type supports US-style currency with fixed decimal point representation.
|
|
If <ProductName>Postgres</ProductName> is compiled with USE_LOCALE then the money type
|
|
should use the monetary conventions defined for locale(7).
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Numeric Types</TITLE>
|
|
<TITLEABBREV>Numerics</TITLEABBREV>
|
|
<TGROUP COLS="4">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Monetary Type</ENTRY>
|
|
<ENTRY>Storage</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
<ENTRY>Range</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>money</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>Fixed-precision</ENTRY>
|
|
<ENTRY>-21474836.48 to +21474836.47</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
The <FirstTerm>numeric</FirstTerm>
|
|
should eventually replace the money type. It has a
|
|
fully implemented syntax but currently (<ProductName>Postgres</ProductName> v6.3)
|
|
support only a small range of precision and/or range values and cannot substitute for
|
|
the money type.
|
|
</Para>
|
|
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Character Types</Title>
|
|
|
|
<Para>
|
|
<Acronym>SQL92</Acronym> defines two primary character types: <Type>char</Type> and
|
|
<Type>varchar</Type>. <ProductName>Postgres</ProductName> supports these types, in
|
|
addition to the more general <Type>text</Type> type, which unlike <Type>varchar</Type>
|
|
does not require an upper
|
|
limit to be declared on the size of the field.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Character Types</TITLE>
|
|
<TITLEABBREV>Characters</TITLEABBREV>
|
|
<TGROUP COLS="4">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Character Type</ENTRY>
|
|
<ENTRY>Storage</ENTRY>
|
|
<ENTRY>Recommendation</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>char</ENTRY>
|
|
<ENTRY>1 byte</ENTRY>
|
|
<ENTRY>SQL92-compatible</ENTRY>
|
|
<ENTRY>Single character</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>char(n)</ENTRY>
|
|
<ENTRY>(4+n) bytes</ENTRY>
|
|
<ENTRY>SQL92-compatible</ENTRY>
|
|
<ENTRY>Fixed-length blank padded</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>text</ENTRY>
|
|
<ENTRY>(4+x) bytes</ENTRY>
|
|
<ENTRY>Best choice</ENTRY>
|
|
<ENTRY>Variable-length</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>varchar(n)</ENTRY>
|
|
<ENTRY>(4+n) bytes</ENTRY>
|
|
<ENTRY>SQL92-compatible</ENTRY>
|
|
<ENTRY>Variable-length with limit</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
There is currently one other fixed-length character type. The <Type>name</Type> type
|
|
only has one purpose and that is to provide <ProductName>Postgres</ProductName> with a
|
|
special type to use for internal names. It is not intended for use by the general user.
|
|
It's length is currently defined as 32 chars but should be reference using NAMEDATALEN.
|
|
This is set at compile time and may change in any future release.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Specialty Character Type</TITLE>
|
|
<TITLEABBREV>Specialty Characters</TITLEABBREV>
|
|
<TGROUP COLS="3">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Character Type</ENTRY>
|
|
<ENTRY>Storage</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>name</ENTRY>
|
|
<ENTRY>32 bytes</ENTRY>
|
|
<ENTRY>Thirty-two character internal type</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Date/Time Types</Title>
|
|
|
|
<Para>
|
|
There are two fundamental kinds of date and time measurements: clock time and time interval.
|
|
Both quantities have continuity and smoothness, as does time itself.
|
|
<ProductName>Postgres</ProductName> supplies two primary user-oriented date and time types,
|
|
<Type>datetime</Type> and timespan, as well as the related SQL92 types date and time.
|
|
</Para>
|
|
|
|
<Para>
|
|
Other date and time types are available
|
|
also, mostly
|
|
for historical reasons.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Date/Time Types</TITLE>
|
|
<TITLEABBREV>Date/Time</TITLEABBREV>
|
|
<TGROUP COLS="4">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Date/Time Type</ENTRY>
|
|
<ENTRY>Storage</ENTRY>
|
|
<ENTRY>Recommendation</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>abstime</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>original date and time</ENTRY>
|
|
<ENTRY>limited range</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>date</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>SQL92 type</ENTRY>
|
|
<ENTRY>wide range</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>datetime</ENTRY>
|
|
<ENTRY>8 bytes</ENTRY>
|
|
<ENTRY>best general date and time</ENTRY>
|
|
<ENTRY>wide range, high precision</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>interval</ENTRY>
|
|
<ENTRY>12 bytes</ENTRY>
|
|
<ENTRY>SQL92 type</ENTRY>
|
|
<ENTRY>equivalent to timespan</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>reltime</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>original time interval</ENTRY>
|
|
<ENTRY>limited range, low precision</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>time</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>SQL92 type</ENTRY>
|
|
<ENTRY>wide range</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timespan</ENTRY>
|
|
<ENTRY>12 bytes</ENTRY>
|
|
<ENTRY>best general time interval</ENTRY>
|
|
<ENTRY>wide range, high precision</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timestamp</ENTRY>
|
|
<ENTRY>4 bytes</ENTRY>
|
|
<ENTRY>SQL92 type</ENTRY>
|
|
<ENTRY>limited range</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Date/Time Ranges</TITLE>
|
|
<TITLEABBREV>Ranges</TITLEABBREV>
|
|
<TGROUP COLS="4">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Date/Time Type</ENTRY>
|
|
<ENTRY>Earliest</ENTRY>
|
|
<ENTRY>Latest</ENTRY>
|
|
<ENTRY>Resolution</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>abstime</ENTRY>
|
|
<ENTRY>1901-12-14</ENTRY>
|
|
<ENTRY>2038-01-19</ENTRY>
|
|
<ENTRY>1 sec</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>date</ENTRY>
|
|
<ENTRY>4713 BC</ENTRY>
|
|
<ENTRY>no limit</ENTRY>
|
|
<ENTRY>1 day</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>datetime</ENTRY>
|
|
<ENTRY>4713 BC</ENTRY>
|
|
<ENTRY>no limit</ENTRY>
|
|
<ENTRY>1 microsec to 14 digits</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>interval</ENTRY>
|
|
<ENTRY>no limit</ENTRY>
|
|
<ENTRY>no limit</ENTRY>
|
|
<ENTRY>1 microsec</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>reltime</ENTRY>
|
|
<ENTRY>-68 years</ENTRY>
|
|
<ENTRY>+68 years</ENTRY>
|
|
<ENTRY>1 sec</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>time</ENTRY>
|
|
<ENTRY>00:00:00.00</ENTRY>
|
|
<ENTRY>23:59:59.99</ENTRY>
|
|
<ENTRY>1 microsec</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timespan</ENTRY>
|
|
<ENTRY>no limit</ENTRY>
|
|
<ENTRY>no limit</ENTRY>
|
|
<ENTRY>1 microsec (14 digits)</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>timestamp</ENTRY>
|
|
<ENTRY>1901-12-14</ENTRY>
|
|
<ENTRY>2038-01-19</ENTRY>
|
|
<ENTRY>1 sec</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
<ProductName>Postgres</ProductName> endevours to be compatible with
|
|
<Acronym>SQL92</Acronym> definitions for typical usage.
|
|
The <Acronym>SQL92</Acronym> standard has an odd mix of date and
|
|
time types and capabilities. For example, although the date type does not have an associated time zone, the
|
|
time type can. The default time zone is specified as a constant offset from GMT/UTC;
|
|
however, time zones in the real world can have no meaning unless associated with a
|
|
date as well
|
|
as a time since the offset will vary through the year.
|
|
|
|
<Para>
|
|
To obviate these difficulties, <ProductName>Postgres</ProductName> associates time zones
|
|
only with date and time
|
|
types which contain both date and time, and assumes local time for any type containing only
|
|
date or time. Further, time zone support is derived from the underlying operating system
|
|
time zone capabilities, and hence can handle daylight savings time and other expected behavior.
|
|
|
|
<Para>
|
|
In future releases, the number of date/time types will decrease, with the current
|
|
implementation of <Type>datetime</Type> becoming <Type>timestamp</Type>, timespan becoming interval,
|
|
and (possibly) abstime
|
|
and reltime being deprecated in favor of <Type>timestamp</Type> and interval.
|
|
The more arcane features
|
|
of the date/time definitions from the <Acronym>SQL92</Acronym> standard are not likely to be pursued.
|
|
</Para>
|
|
|
|
<Sect2>
|
|
<Title>Date/Time Styles</Title>
|
|
|
|
<Para>
|
|
Output formats can be set to one of four styles:
|
|
ISO-8601, SQL (Ingres), traditional
|
|
Postgres, and German.
|
|
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Date Styles</TITLE>
|
|
<TITLEABBREV>Styles</TITLEABBREV>
|
|
<TGROUP COLS="3">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Style Specification</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
<ENTRY>Example</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>ISO</ENTRY>
|
|
<ENTRY>ISO-8601 standard</ENTRY>
|
|
<ENTRY>1997-12-17 07:37:16-08</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>SQL</ENTRY>
|
|
<ENTRY>Traditional style</ENTRY>
|
|
<ENTRY>12/17/1997 07:37:16.00 PST</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>Postgres</ENTRY>
|
|
<ENTRY>Original style</ENTRY>
|
|
<ENTRY>Wed Dec 17 07:37:16 1997 PST</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>German</ENTRY>
|
|
<ENTRY>Regional style</ENTRY>
|
|
<ENTRY>17.12.1997 07:37:16.00 PST</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
The SQL style has European and non-European (US) variants, which determines whether
|
|
month follows day or vica versa.
|
|
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Date Order Conventions</TITLE>
|
|
<TITLEABBREV>Order</TITLEABBREV>
|
|
<TGROUP COLS="3">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Style Specification</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
<ENTRY>Example</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>European</ENTRY>
|
|
<ENTRY>Regional convention</ENTRY>
|
|
<ENTRY>17/12/1997 15:37:16.00 MET</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>NonEuropean</ENTRY>
|
|
<ENTRY>Regional convention</ENTRY>
|
|
<ENTRY>12/17/1997 07:37:16.00 PST</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>US</ENTRY>
|
|
<ENTRY>Regional convention</ENTRY>
|
|
<ENTRY>12/17/1997 07:37:16.00 PST</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
There are several ways to affect the appearance of date/time types:
|
|
|
|
<ItemizedList Mark="bullet" Spacing="compact">
|
|
<ListItem>
|
|
<Para>
|
|
The PGDATESTYLE environment variable used by the backend directly on postmaster startup.
|
|
</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>
|
|
The PGDATESTYLE environment variable used by the frontend libpq on session startup.
|
|
</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>
|
|
SET DateStyle <Acronym>SQL</Acronym> command.
|
|
</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
|
|
<Para>
|
|
For <ProductName>Postgres</ProductName> v6.3 (and earlier) the default date/time style is
|
|
"non-European traditional Postgres". In future releases, the default may become ISO-8601, which alleviates
|
|
date specification ambiguities and Y2K collation problems.
|
|
</Para>
|
|
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Time Zones</Title>
|
|
|
|
<Para>
|
|
<ProductName>Postgres</ProductName> obtains time zone support from the underlying operating system.
|
|
All dates and times are stored internally in Universal Coordinated Time (UTC), alternately known as
|
|
Greenwich Mean Time (GMT). Times are converted to local time on the database server before being
|
|
sent to the client frontend, hence by default are in the server time zone.
|
|
|
|
<Para>
|
|
There are several ways to affect the time zone behavior:
|
|
|
|
<ItemizedList Mark="bullet" Spacing="compact">
|
|
<ListItem>
|
|
<Para>
|
|
The TZ environment variable used by the backend directly
|
|
on postmaster startup as the default time zone.
|
|
</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>
|
|
The PGTZ environment variable set at the client used by libpq to send time zone information to the backend upon connection.
|
|
</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>
|
|
<Command>set timezone</Command> <Acronym>SQL</Acronym> sets the time zone for the session.
|
|
</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
|
|
<Para>
|
|
If an invalid time zone is specified,
|
|
the time zone becomes GMT (on most systems anyway).
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Date/Time Input</Title>
|
|
|
|
<Para>
|
|
General-use date and time is input using a wide range of
|
|
styles, including ISO-compatible, SQL-compatible, traditional
|
|
<ProductName>Postgres</ProductName>
|
|
and other permutations of date and time. In cases where interpretation
|
|
can be ambiguous (quite possible with many traditional styles of date specification)
|
|
<ProductName>Postgres</ProductName> uses a style setting to resolve the ambiguity.
|
|
</Para>
|
|
|
|
<Para>
|
|
Most date and time types share code for data input. For those types
|
|
the input can have any of a wide variety of styles. For numeric date representations,
|
|
European and US conventions can differ, and the proper interpretation is obtained
|
|
by using the
|
|
<Command>set datestyle</Command>
|
|
command before entering data.
|
|
Note that the style setting does not preclude use of various styles for input; it is
|
|
used primarily to determine the output style and to resolve ambiguities.
|
|
</Para>
|
|
|
|
<Para>
|
|
The special values `current',
|
|
`infinity' and `-infinity' are provided.
|
|
`infinity' specifies a time later than any other valid time, and
|
|
`-infinity' specifies a time earlier than any other valid time.
|
|
`current' indicates that the current time should be
|
|
substituted whenever this value appears in a computation.
|
|
|
|
The strings
|
|
`now',
|
|
`today',
|
|
`yesterday',
|
|
`tomorrow',
|
|
and `epoch' can be used to specify
|
|
time values. `now' means the current transaction time, and differs from
|
|
`current' in that the current time is immediately substituted
|
|
for it. `epoch' means Jan 1 00:00:00 1970 GMT.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Date/Time Special Constants</TITLE>
|
|
<TITLEABBREV>Constants</TITLEABBREV>
|
|
<TGROUP COLS="2">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Constant</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>current</ENTRY>
|
|
<ENTRY>Current transaction time, deferred</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>epoch</ENTRY>
|
|
<ENTRY>1970-01-01 00:00:00+00 (Unix system time zero)</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>infinity</ENTRY>
|
|
<ENTRY>Later than other valid times</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>-infinity</ENTRY>
|
|
<ENTRY>Earlier than other valid times</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>invalid</ENTRY>
|
|
<ENTRY>Illegal entry</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>now</ENTRY>
|
|
<ENTRY>Current transaction time</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>today</ENTRY>
|
|
<ENTRY>Midnight today</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>tomorrow</ENTRY>
|
|
<ENTRY>Midnight tomorrow</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>yesterday</ENTRY>
|
|
<ENTRY>Midnight yesterday</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>datetime</Title>
|
|
|
|
<Para>
|
|
General-use date and time is input using a wide range of
|
|
styles, including ISO-compatible, SQL-compatible, traditional
|
|
<ProductName>Postgres</ProductName> (see section on "absolute time")
|
|
and other permutations of date and time. Output styles can be ISO-compatible,
|
|
SQL-compatible, or traditional <ProductName>Postgres</ProductName>, with the default set to be compatible
|
|
with <ProductName>Postgres</ProductName> v6.0.
|
|
</Para>
|
|
|
|
<Para>
|
|
<Type>datetime</Type> is specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
Year-Month-Day [ Hour : Minute : Second ] [AD,BC] [ Timezone ]
|
|
YearMonthDay [ Hour : Minute : Second ] [AD,BC] [ Timezone ]
|
|
Month Day [ Hour : Minute : Second ] Year [AD,BC] [ Timezone ]
|
|
where
|
|
Year is 4013 BC, ..., very large
|
|
Month is Jan, Feb, ..., Dec or 1, 2, ..., 12
|
|
Day is 1, 2, ..., 31
|
|
Hour is 00, 02, ..., 23
|
|
Minute is 00, 01, ..., 59
|
|
Second is 00, 01, ..., 59 (60 for leap second)
|
|
Timezone is 3 characters or ISO offset to GMT
|
|
</ProgramListing>
|
|
|
|
<Para>
|
|
Valid dates are from Nov 13 00:00:00 4013 BC GMT to far into the future.
|
|
Timezones are either three characters (e.g. "GMT" or "PST") or ISO-compatible
|
|
offsets to GMT (e.g. "-08" or "-08:00" when in Pacific Standard Time).
|
|
Dates are stored internally in Greenwich Mean Time. Input and output routines
|
|
translate time to the local time zone of the server.
|
|
</Para>
|
|
|
|
<Sect2>
|
|
<Title><Type>timespan</Type></Title>
|
|
|
|
<Para>
|
|
General-use time span is input using a wide range of
|
|
syntaxes, including ISO-compatible, SQL-compatible, traditional
|
|
<ProductName>Postgres</ProductName> (see section on "relative time")
|
|
and other permutations of time span. Output formats can be ISO-compatible,
|
|
SQL-compatible, or traditional <ProductName>Postgres</ProductName>, with the default set to be <ProductName>Postgres</ProductName>-compatible.
|
|
Months and years are a "qualitative" time interval, and are stored separately
|
|
from the other "quantitative" time intervals such as day or hour. For date arithmetic,
|
|
the qualitative time units are instantiated in the context of the relevant date or time.
|
|
|
|
<Para>
|
|
Time span is specified with the following syntax:
|
|
|
|
<ProgramListing>
|
|
Quantity Unit [Quantity Unit...] [Direction]
|
|
@ Quantity Unit [Direction]
|
|
where
|
|
Quantity is ..., `-1', `0', `1', `2', ...
|
|
Unit is `second', `minute', `hour', `day', `week', `month', `year',
|
|
'decade', 'century', millenium', or abbreviations or plurals of these units.
|
|
Direction is `ago'.
|
|
</ProgramListing>
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>abstime</Title>
|
|
|
|
<Para>
|
|
Absolute time (abstime) is a limited-range (+/- 68 years) and limited-precision (1 sec)
|
|
date data type. <Type>datetime</Type> may be preferred, since it
|
|
covers a larger range with greater precision.
|
|
|
|
<Para>
|
|
Absolute time is specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
Month Day [ Hour : Minute : Second ] Year [ Timezone ]
|
|
where
|
|
Month is Jan, Feb, ..., Dec
|
|
Day is 1, 2, ..., 31
|
|
Hour is 01, 02, ..., 24
|
|
Minute is 00, 01, ..., 59
|
|
Second is 00, 01, ..., 59
|
|
Year is 1901, 1902, ..., 2038
|
|
</ProgramListing>
|
|
</Para>
|
|
|
|
<Para>
|
|
Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04
|
|
2038 GMT. As of Version 3.0, times are no longer read and written
|
|
using Greenwich Mean Time; the input and output routines default to
|
|
the local time zone.
|
|
|
|
All special values allowed for <Type>datetime</Type> are also allowed for "absolute time".
|
|
</Para>
|
|
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>reltime</Title>
|
|
|
|
<Para>
|
|
Relative time <Type>reltime</Type> is a limited-range (+/- 68 years)
|
|
and limited-precision (1 sec) time span data type.
|
|
<Type>timespan</Type> should be preferred, since it
|
|
covers a larger range with greater precision and, more importantly, can distinguish between
|
|
relative units (months and years) and quantitative units (days, hours, etc). Instead, reltime
|
|
must force months to be exactly 30 days, so time arithmetic does not always work as expected.
|
|
For example, adding one reltime year to abstime today does not produce today's date one year from
|
|
now, but rather a date 360 days from today.
|
|
</Para>
|
|
|
|
<Para>
|
|
<Type>reltime</Type> shares input and output routines with the other time span types.
|
|
The section on <Type>timespan</Type> covers this in more detail.
|
|
</Para>
|
|
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title><Type>timestamp</Type></Title>
|
|
|
|
<Para>
|
|
This is currently a limited-range absolute time which closely resembles the
|
|
abstime
|
|
data type. It shares the general input parser with the other date/time types.
|
|
In future releases this type will absorb the capabilities of the <Type>datetime</Type> type
|
|
and will move toward SQL92 compliance.
|
|
</Para>
|
|
|
|
<Para>
|
|
<Type>timestamp</Type> is specified using the same syntax as for <Type>datetime</Type>.
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title><Type>interval</Type></Title>
|
|
|
|
<Para>
|
|
<Type>interval</Type> is an <Acronym>SQL92</Acronym> data type which is
|
|
currently mapped to the <Type>timespan</Type> <ProductName>Postgres</ProductName>
|
|
data type.
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>tinterval</Title>
|
|
|
|
<Para>
|
|
Time ranges are specified as:
|
|
|
|
<ProgramListing>
|
|
[ 'abstime' 'abstime']
|
|
where
|
|
abstime is a time in the absolute time format.
|
|
</ProgramListing>
|
|
|
|
Special abstime values such as
|
|
`current', `infinity' and `-infinity' can be used.
|
|
</Para>
|
|
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Boolean Type</Title>
|
|
|
|
<Para>
|
|
<ProductName>Postgres</ProductName> supports <Type>bool</Type> as
|
|
the <Acronym>SQL3</Acronym> boolean type.
|
|
<Type>bool</Type> can have one of only two states: 'true' or 'false'. A third state, 'unknown', is not
|
|
implemented and is not suggested in <Acronym>SQL3</Acronym>; <Acronym>NULL</Acronym> is an
|
|
effective substitute. <Type>bool</Type> can be used in any boolean expression, and boolean expressions
|
|
always evaluate to a result compatible with this type.
|
|
|
|
<Para>
|
|
<Type>bool</Type> uses 4 bytes of storage.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Boolean Type</TITLE>
|
|
<TITLEABBREV>Booleans</TITLEABBREV>
|
|
<TGROUP COLS="3">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>State</ENTRY>
|
|
<ENTRY>Output</ENTRY>
|
|
<ENTRY>Input</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>True</ENTRY>
|
|
<ENTRY>'t'</ENTRY>
|
|
<ENTRY>TRUE, 't', 'true', 'y', 'yes', '1'</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>False</ENTRY>
|
|
<ENTRY>'f'</ENTRY>
|
|
<ENTRY>FALSE, 'f', 'false', 'n', 'no', '0'</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
</Sect1>
|
|
|
|
<Sect1>
|
|
<Title>Geometric Types</Title>
|
|
|
|
<Para>
|
|
Geometric types represent two-dimensional spatial objects. The most fundamental type,
|
|
the point, forms the basis for all of the other types.
|
|
</Para>
|
|
|
|
<Para>
|
|
<TABLE TOCENTRY="1">
|
|
<TITLE><ProductName>Postgres</ProductName> Geometric Types</TITLE>
|
|
<TITLEABBREV>Geometrics</TITLEABBREV>
|
|
<TGROUP COLS="4">
|
|
<THEAD>
|
|
<ROW>
|
|
<ENTRY>Geometric Type</ENTRY>
|
|
<ENTRY>Storage</ENTRY>
|
|
<ENTRY>Representation</ENTRY>
|
|
<ENTRY>Description</ENTRY>
|
|
</ROW>
|
|
</THEAD>
|
|
<TBODY>
|
|
<ROW>
|
|
<ENTRY>point</ENTRY>
|
|
<ENTRY>16 bytes</ENTRY>
|
|
<ENTRY>(x,y)</ENTRY>
|
|
<ENTRY>Point in space</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>line</ENTRY>
|
|
<ENTRY>32 bytes</ENTRY>
|
|
<ENTRY>((x1,y1),(x2,y2))</ENTRY>
|
|
<ENTRY>Infinite line</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>lseg</ENTRY>
|
|
<ENTRY>32 bytes</ENTRY>
|
|
<ENTRY>((x1,y1),(x2,y2))</ENTRY>
|
|
<ENTRY>Finite line segment</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>box</ENTRY>
|
|
<ENTRY>32 bytes</ENTRY>
|
|
<ENTRY>((x1,y1),(x2,y2))</ENTRY>
|
|
<ENTRY>Rectangular box</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>path</ENTRY>
|
|
<ENTRY>4+32n bytes</ENTRY>
|
|
<ENTRY>((x1,y1),...)</ENTRY>
|
|
<ENTRY>Closed path (similar to polygon)</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>path</ENTRY>
|
|
<ENTRY>4+32n bytes</ENTRY>
|
|
<ENTRY>[(x1,y1),...]</ENTRY>
|
|
<ENTRY>Open path</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>polygon</ENTRY>
|
|
<ENTRY>4+32n bytes</ENTRY>
|
|
<ENTRY>((x1,y1),...)</ENTRY>
|
|
<ENTRY>Polygon (similar to closed path)</ENTRY>
|
|
</ROW>
|
|
<ROW>
|
|
<ENTRY>circle</ENTRY>
|
|
<ENTRY>24 bytes</ENTRY>
|
|
<ENTRY><(x,y),r></ENTRY>
|
|
<ENTRY>Circle (center and radius)</ENTRY>
|
|
</ROW>
|
|
</TBODY>
|
|
</TGROUP>
|
|
</TABLE>
|
|
</Para>
|
|
|
|
<Para>
|
|
A rich set of functions and operators is available to perform various geometric
|
|
operations such as scaling, translation, rotation, and determining intersections.
|
|
</Para>
|
|
|
|
<Sect2>
|
|
<Title>Point</Title>
|
|
|
|
<Para>
|
|
Points are specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
( x , y )
|
|
x , y
|
|
where
|
|
x is the x-axis coordinate as a floating point number
|
|
y is the y-axis coordinate as a floating point number
|
|
</ProgramListing>
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Line Segment</Title>
|
|
|
|
<Para>
|
|
Line segments (lseg) are represented by pairs of points.
|
|
</Para>
|
|
|
|
<Para>
|
|
lseg is specified using the following syntax:
|
|
<ProgramListing>
|
|
( ( x1 , y1 ) , ( x2 , y2 ) )
|
|
( x1 , y1 ) , ( x2 , y2 )
|
|
x1 , y1 , x2 , y2
|
|
where
|
|
(x1,y1) and (x2,y2) are the endpoints of the segment
|
|
</ProgramListing>
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Box</Title>
|
|
|
|
<Para>
|
|
Boxes are represented by pairs of points which are opposite
|
|
corners of the box.
|
|
</Para>
|
|
|
|
<Para>
|
|
box is specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
( ( x1 , y1 ) , ( x2 , y2 ) )
|
|
( x1 , y1 ) , ( x2 , y2 )
|
|
x1 , y1 , x2 , y2
|
|
where
|
|
(x1,y1) and (x2,y2) are opposite corners
|
|
</ProgramListing>
|
|
|
|
Boxes are output using the first syntax.
|
|
The corners are reordered on input to store
|
|
the lower left corner first and the upper right corner last.
|
|
Other corners of the box can be entered, but the lower
|
|
left and upper right corners are determined from the input and stored.
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Path</Title>
|
|
|
|
<Para>
|
|
Paths are represented by connected sets of points. Paths can be "open", where
|
|
the first and last points in the set are not connected, and "closed",
|
|
where the first and last point are connected. Functions
|
|
<Function>popen(p)</Function>
|
|
and
|
|
<Function>pclose(p)</Function>
|
|
are supplied to force a path to be open or closed, and functions
|
|
<Function>isopen(p)</Function>
|
|
and
|
|
<Function>isclosed(p)</Function>
|
|
are supplied to select either type in a query.
|
|
</Para>
|
|
|
|
<Para>
|
|
path is specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
( ( x1 , y1 ) , ... , ( xn , yn ) )
|
|
[ ( x1 , y1 ) , ... , ( xn , yn ) ]
|
|
( x1 , y1 ) , ... , ( xn , yn )
|
|
( x1 , y1 , ... , xn , yn )
|
|
x1 , y1 , ... , xn , yn
|
|
where
|
|
(x1,y1),...,(xn,yn) are points 1 through n
|
|
a leading "[" indicates an open path
|
|
a leading "(" indicates a closed path
|
|
</ProgramListing>
|
|
Paths are output using the first syntax.
|
|
Note that <ProductName>Postgres</ProductName> versions prior to
|
|
v6.1 used a format for paths which had a single leading parenthesis, a "closed" flag,
|
|
an integer count of the number of points, then the list of points followed by a
|
|
closing parenthesis. The built-in function <Function>upgradepath</Function> is supplied to convert
|
|
paths dumped and reloaded from pre-v6.1 databases.
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Polygon</Title>
|
|
|
|
<Para>
|
|
Polygons are represented by sets of points. Polygons should probably be
|
|
considered
|
|
equivalent to closed paths, but are stored differently and have their own
|
|
set of support routines.
|
|
</Para>
|
|
|
|
<Para>
|
|
polygon is specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
( ( x1 , y1 ) , ... , ( xn , yn ) )
|
|
( x1 , y1 ) , ... , ( xn , yn )
|
|
( x1 , y1 , ... , xn , yn )
|
|
x1 , y1 , ... , xn , yn
|
|
where
|
|
(x1,y1),...,(xn,yn) are points 1 through n
|
|
</ProgramListing>
|
|
|
|
Polygons are output using the first syntax.
|
|
Note that <ProductName>Postgres</ProductName> versions prior to
|
|
v6.1 used a format for polygons which had a single leading parenthesis, the list
|
|
of x-axis coordinates, the list of y-axis coordinates, followed by a closing parenthesis.
|
|
The built-in function <Function>upgradepoly</Function> is supplied to convert
|
|
polygons dumped and reloaded from pre-v6.1 databases.
|
|
</Para>
|
|
</Sect2>
|
|
|
|
<Sect2>
|
|
<Title>Circle</Title>
|
|
|
|
<Para>
|
|
Circles are represented by a center point and a radius.
|
|
</Para>
|
|
|
|
<Para>
|
|
circle is specified using the following syntax:
|
|
|
|
<ProgramListing>
|
|
< ( x , y ) , r >
|
|
( ( x , y ) , r )
|
|
( x , y ) , r
|
|
x , y , r
|
|
where
|
|
(x,y) is the center of the circle
|
|
r is the radius of the circle
|
|
</ProgramListing>
|
|
|
|
Circles are output using the first syntax.
|
|
</Para>
|
|
</Sect2>
|
|
|
|
</Sect1>
|
|
|