Describes the built-in data types available in Postgres. Postgres has a rich set of native data types available to users. Users may add new types to Postgres using the define type command described elsewhere. In the context of data types, the following sections will discuss SQL standards compliance, porting issues, and usage. Some Postgres types correspond directly to SQL92-compatible types. In other cases, data types defined by SQL92 syntax are mapped directly into native Postgres types. Many of the built-in types have obvious external formats. However, several types are either unique to Postgres, such as open and closed paths, or have several possibilities for formats, such as date and time types. Data Types Postgres Type SQL92 or SQL3 Type Description bool boolean logical boolean (true/false) box rectangular box in 2D plane char(n) character(n) fixed-length character string circle circle in 2D plane date date calendar date without time of day float4/8 float(p) floating-point number with precision p float8 real, double precision double-precision floating-point number int2 smallint signed two-byte integer int4 int, integer signed 4-byte integer int4 decimal(p,s) exact numeric for p <= 9, s = 0 int4 numeric(p,s) exact numeric for p == 9, s = 0 line infinite line in 2D plane lseg line segment in 2D plane money decimal(9,2) US-style currency path open and closed geometric path in 2D plane point geometric point in 2D plane polygon closed geometric path in 2D plane time time time of day timespan interval general-use time span timestamp timestamp with time zone date/time varchar(n) character varying(n) variable-length character string Constants Postgres Function SQL92 Constant Description getpgusername() current_user user name in current session date('now') current_date date of current transaction time('now') current_time time of current transaction timestamp('now') current_timestamp date and time of current transaction Postgres 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 cases in the standard which are ill considered and which should not live through subsequent standards. Postgres will not make great efforts to conform to these cases. However, these cases tend to be little-used and obsure, and a typical user is not likely to run into them. Although most of the input and output functions corresponding to the base types (e.g., integers and floating point numbers) do some error-checking, some are not particularly rigorous about it. More importantly, few of the operators and functions (e.g., addition and multiplication) perform any error-checking at all. Consequently, many of the numeric operators can (for example) silently underflow or overflow. 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. Numeric types consist of two- and four-byte integers and four- and eight-byte floating point numbers. Numerics Numeric Type Storage Description Range int2 2 bytes Fixed-precision -32768 to +32767 int4 4 bytes Usual choice for fixed-precision -2147483648 to +2147483647 float4 4 bytes Variable-precision 7 decimal places float8 8 bytes Variable-precision 14 decimal places The exact numerics decimal and numeric have fully implemented syntax but currently (Postgres v6.3) support only a small range of precision and/or range values. The money type supports US-style currency with fixed decimal point representation. If Postgres is compiled with USE_LOCALE then the money type should use the monetary conventions defined for locale(7). Numerics Monetary Type Storage Description Range money 4 bytes Fixed-precision -21474836.48 to +21474836.47 The numeric should eventually replace the money type. It has a fully implemented syntax but currently (Postgres v6.3) support only a small range of precision and/or range values and cannot substitute for the money type. SQL92 defines two primary character types: char and varchar. Postgres supports these types, in addition to the more general text type, which unlike varchar does not require an upper limit to be declared on the size of the field. Characters Character Type Storage Recommendation Description char 1 byte SQL92-compatible Single character char(n) (4+n) bytes SQL92-compatible Fixed-length blank padded text (4+x) bytes Best choice Variable-length varchar(n) (4+n) bytes SQL92-compatible Variable-length with limit There are currently other fixed-length character types. These provide no additional functionality and are likely to be deprecated in the future. Specialty Characters Character Type Storage Description char2 2 bytes Two characters char4 4 bytes Four characters char8 8 bytes Eight characters char16 16 bytes Sixteen characters 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. Postgres supplies two primary user-oriented date and time types, datetime and timespan, as well as the related SQL92 types date and time. Other date and time types are available also, mostly for historical reasons. Date/Time Date/Time Type Storage Recommendation Description abstime 4 bytes original date and time limited range date 4 bytes SQL92 type wide range datetime 8 bytes best general date and time wide range, high precision interval 12 bytes SQL92 type equivalent to timespan reltime 4 bytes original time interval limited range, low precision time 4 bytes SQL92 type wide range timespan 12 bytes best general time interval wide range, high precision timestamp 4 bytes SQL92 type limited range Ranges Date/Time Type Earliest Latest Resolution abstime 1901-12-14 2038-01-19 1 sec date 4713 BC no limit 1 day datetime 4713 BC no limit 1 microsec to 14 digits interval no limit no limit 1 microsec reltime -68 years +68 years 1 sec time 00:00:00.00 23:59:59.99 1 microsec timespan no limit no limit 1 microsec (14 digits) timestamp 1901-12-14 2038-01-19 1 sec Postgres endevours to be compatible with SQL92 definitions for typical usage. The SQL92 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. To obviate these difficulties, Postgres 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. In future releases, the number of date/time types will decrease, with the current implementation of datetime becoming timestamp, timespan becoming interval, and (possibly) abstime and reltime being deprecated in favor of timestamp and interval. The more arcane features of the date/time definitions from the SQL92 standard are not likely to be pursued. Output formats can be set to one of four styles: ISO-8601, SQL (Ingres), traditional Postgres, and German. Styles Style Specification Description Example ISO ISO-8601 standard 1997-12-17 07:37:16-08 SQL Traditional style 12/17/1997 07:37:16.00 PST Postgres Original style Wed Dec 17 07:37:16 1997 PST German Regional style 17.12.1997 07:37:16.00 PST The SQL style has European and non-European (US) variants, which determines whether month follows day or vica versa. Order Style Specification Description Example European Regional convention 17/12/1997 15:37:16.00 MET NonEuropean Regional convention 12/17/1997 07:37:16.00 PST US Regional convention 12/17/1997 07:37:16.00 PST There are several ways to affect the appearance of date/time types: The PGDATESTYLE environment variable used by the backend directly on postmaster startup. The PGDATESTYLE environment variable used by the frontend libpq on session startup. SET DateStyle SQL command. For Postgres v6.3 (and earlier) the default date/time style is "traditional Postgres". In future releases, the default may become ISO-8601, which alleviates date specification ambiguities and Y2K collation problems. Postgres 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. There are several ways to affect the time zone behavior: The TZ environment variable used by the backend directly on postmaster startup as the default time zone. The PGTZ environment variable set at the client used by libpq to send time zone information to the backend upon connection. set timezone SQL sets the time zone for the session. If an invalid time zone is specified, the time zone becomes GMT (on most systems anyway). General-use date and time is input using a wide range of styles, including ISO-compatible, SQL-compatible, traditional Postgres and other permutations of date and time. In cases where interpretation can be ambiguous (quite possible with many traditional styles of date specification) Postgres uses a style setting to resolve the ambiguity. 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 set datestyle 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. 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. Constants Constant Description current Current transaction time, deferred epoch 1970-01-01 00:00:00+00 (Unix system time zero) infinity Later than other valid times -infinity Earlier than other valid times invalid Illegal entry now Current transaction time today Midnight today tomorrow Midnight tomorrow yesterday Midnight yesterday General-use date and time is input using a wide range of styles, including ISO-compatible, SQL-compatible, traditional Postgres (see section on "absolute time") and other permutations of date and time. Output styles can be ISO-compatible, SQL-compatible, or traditional Postgres, with the default set to be compatible with Postgres v6.0. datetime is specified using the following syntax: 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 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. General-use time span is input using a wide range of syntaxes, including ISO-compatible, SQL-compatible, traditional Postgres (see section on "relative time") and other permutations of time span. Output formats can be ISO-compatible, SQL-compatible, or traditional Postgres, with the default set to be Postgres-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. Time span is specified with the following syntax: 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'. Absolute time (abstime) is a limited-range (+/- 68 years) and limited-precision (1 sec) date data type. datetime may be preferred, since it covers a larger range with greater precision. Absolute time is specified using the following syntax: 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 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 datetime are also allowed for "absolute time". Relative time reltime is a limited-range (+/- 68 years) and limited-precision (1 sec) time span data type. timespan 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. reltime shares input and output routines with the other time span types. The section on timespan covers this in more detail. 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 datetime type and will move toward SQL92 compliance. timestamp is specified using the same syntax as for datetime. interval is an SQL92 data type which is currently mapped to the timespan Postgres data type. Time ranges are specified as: [ 'abstime' 'abstime'] where abstime is a time in the absolute time format. Special abstime values such as `current', `infinity' and `-infinity' can be used. Postgres supports bool as the SQL3 boolean type. bool can have one of only two states: 'true' or 'false'. A third state, 'unknown', is not implemented and is not suggested in SQL3; NULL is an effective substitute. bool can be used in any boolean expression, and boolean expressions always evaluate to a result compatible with this type. bool uses 4 bytes of storage. Booleans State Output Input True 't' TRUE, 't', 'true', 'y', 'yes', '1' False 'f' FALSE, 'f', 'false', 'n', 'no', '0' Geometric types represent two-dimensional spatial objects. The most fundamental type, the point, forms the basis for all of the other types. Geometrics Geometric Type Storage Representation Description point 16 bytes (x,y) Point in space line 32 bytes ((x1,y1),(x2,y2)) Infinite line lseg 32 bytes ((x1,y1),(x2,y2)) Finite line segment box 32 bytes ((x1,y1),(x2,y2)) Rectangular box path 4+32n bytes ((x1,y1),...) Closed path (similar to polygon) path 4+32n bytes [(x1,y1),...] Open path polygon 4+32n bytes ((x1,y1),...) Polygon (similar to closed path) circle 24 bytes <(x,y),r> Circle (center and radius) A rich set of functions and operators is available to perform various geometric operations such as scaling, translation, rotation, and determining intersections. Points are specified using the following syntax: ( 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 Line segments (lseg) are represented by pairs of points. lseg is specified using the following syntax: ( ( x1 , y1 ) , ( x2 , y2 ) ) ( x1 , y1 ) , ( x2 , y2 ) x1 , y1 , x2 , y2 where (x1,y1) and (x2,y2) are the endpoints of the segment Boxes are represented by pairs of points which are opposite corners of the box. box is specified using the following syntax: ( ( x1 , y1 ) , ( x2 , y2 ) ) ( x1 , y1 ) , ( x2 , y2 ) x1 , y1 , x2 , y2 where (x1,y1) and (x2,y2) are opposite corners 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. 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 popen(p) and pclose(p) are supplied to force a path to be open or closed, and functions isopen(p) and isclosed(p) are supplied to select either type in a query. path is specified using the following syntax: ( ( 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 Paths are output using the first syntax. Note that Postgres 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 upgradepath is supplied to convert paths dumped and reloaded from pre-v6.1 databases. 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. polygon is specified using the following syntax: ( ( 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 Polygons are output using the first syntax. Note that Postgres 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 upgradepoly is supplied to convert polygons dumped and reloaded from pre-v6.1 databases. Circles are represented by a center point and a radius. circle is specified using the following syntax: < ( 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 Circles are output using the first syntax. Postgres 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 OIDs of the input and output types. To view all variations of the || string concatenation operator, try 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) Operators Operator Description Usage < Less than? 1 < 2 <= Less than or equal to? 1 <= 2 <> Not equal? 1 <> 2 = Equal? 1 = 1 > Greater than? 2 > 1 >= Greater than or equal to? 2 >= 1 || Concatenate strings 'Postgre' || 'SQL' !!= NOT IN 3 !!= i ~~ LIKE 'scrappy,marc,hermit' ~~ '%scrappy%' !~~ NOT LIKE 'bruce' !~~ '%al%' ~ Match (regex), case sensitive 'thomas' ~ '*.thomas*.' ~* Match (regex), case insensitive 'thomas' ~* '*.Thomas*.' !~ Does not match (regex), case sensitive 'thomas' !~ '*.Thomas*.' !~* Does not match (regex), case insensitive 'thomas' !~ '*.vadim*.' Operators Operator Description Usage ! Factorial 3 ! !! Factorial (left operator) !! 3 % Modulo 5 % 4 % Truncate % 4.5 * Multiplication 2 * 3 + Addition 2 + 3 - Subtraction 2 - 3 / Division 4 / 2 : Natural Exponentiation : 3.0 ; Natural Logarithm (; 5.0) @ Absolute value @ -5.0 ^ Exponentiation 2.0 ^ 3.0 |/ Square root |/ 25.0 ||/ Cube root ||/ 27.0 Operators Operator Description Usage + Translation '((0,0),(1,1))'::box + '(2.0,0)'::point - Translation '((0,0),(1,1))'::box - '(2.0,0)'::point * Scaling/rotation '((0,0),(1,1))'::box * '(2.0,0)'::point / Scaling/rotation '((0,0),(2,2))'::box / '(2.0,0)'::point # Intersection '((1,-1),(-1,1))' # '((1,1),(-1,-1))' # Number of points in polygon # '((1,0),(0,1),(-1,0))' ## Point of closest proximity '(0,0)'::point ## '((2,0),(0,2))'::lseg && Overlaps? '((0,0),(1,1))'::box && '((0,0),(2,2))'::box &< Overlaps to left? '((0,0),(1,1))'::box &< '((0,0),(2,2))'::box &> Overlaps to right? '((0,0),(3,3))'::box &> '((0,0),(2,2))'::box <-> Distance between '((0,0),1)'::circle <-> '((5,0),1)'::circle << Left of? '((0,0),1)'::circle << '((5,0),1)'::circle <^ Is below? '((0,0),1)'::circle <^ '((0,5),1)'::circle >> Is right of? '((5,0),1)'::circle >> '((0,0),1)'::circle >^ Is above? '((0,5),1)'::circle >^ '((0,0),1)'::circle ?# Intersects or overlaps '((-1,0),(1,0))'::lseg ?# '((-2,-2),(2,2))'::box; ?- Is horizontal? '(1,0)'::point ?- '(0,0)'::point ?-| Is perpendicular? '((0,0),(0,1))'::lseg ?-| '((0,0),(1,0))'::lseg @-@ Length or circumference @-@ '((0,0),(1,0))'::path ?| Is vertical? '(0,1)'::point ?| '(0,0)'::point ?|| Is parallel? '((-1,0),(1,0))'::lseg ?|| '((-1,2),(1,2))'::lseg @ Contained or on '(1,1)'::point @ '((0,0),2)'::circle @@ Center of @@ '((0,0),10)'::circle ~= Same as '((0,0),(1,1))'::polygon ~= '((1,1),(0,0))'::polygon The time interval data type tinterval 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. Operators Operator Description Usage #< Interval less than? #<= Interval less than or equal to? #<> Interval not equal? #= Interval equal? #> Interval greater than? #>= Interval greater than or equal to? <#> Convert to time interval << Interval less than? | Start of interval ~= Same as <?> Time inside interval? Users may invoke operators using the operator name, as in: select * from emp where salary < 40000; Alternatively, users may call the functions that implement the operators directly. In this case, the query above would be expressed as: select * from emp where int4lt(salary, 40000); psql has a \dd command to show these operators. 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. Some functions defined for text are also available for char() and varchar(). For the date_part and date_trunc functions, arguments can be `year', `month', `day', `hour', `minute', and `second', as well as the more specialized quantities `decade', `century', `millenium', `millisecond', and `microsecond'. date_part allows `dow' to return day of week and `epoch' to return seconds since 1970 (for datetime) or 'epoch' to return total elapsed seconds (for timespan). Function Returns Description Example float(int) float8 convert integer to floating point float(2) float4(int) float4 convert integer to floating point float4(2) int integer(float) convert floating point to integer integer(2.0) 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. Function Returns Description Example lower(text) text convert text to lower case lower('TOM') lpad(text,int,text) text left pad string to specified length lpad('hi',4,'??') ltrim(text,text) text left trim characters from text ltrim('xxxxtrim','x') position(text,text) text extract specified substring position('high','ig') rpad(text,int,text) text right pad string to specified length rpad('hi',4,'x') rtrim(text,text) text right trim characters from text rtrim('trimxxxx','x') substr(text,int[,int]) text extract specified substring substr('hi there',3,5) upper(text) text convert text to upper case upper('tom') Function Returns Description Example isfinite(abstime) bool TRUE if this is a finite time isfinite('now'::abstime) datetime(abstime) datetime convert to datetime datetime('now'::abstime) datetime(date) datetime convert to datetime datetime('today'::date) datetime(date,time) datetime convert to datetime datetime('1998-02-24':datetime, '23:07'::time); age(datetime,datetime) timespan span preserving months and years age('now','1957-06-13':datetime) date_part(text,datetime) float8 specified portion of date field date_part('dow','now'::datetime) date_trunc(text,datetime) datetime truncate date at specified units date_trunc('month','now'::abstime) isfinite(datetime) bool TRUE if this is a finite time isfinite('now'::datetime) abstime(datetime) abstime convert to abstime abstime('now'::datetime) timespan(reltime) timespan convert to timespan timespan('4 hours'::reltime) datetime(date,time) datetime convert to datetime datetime('1998-02-25'::date,'06:41'::time) date_part(text,timespan) float8 specified portion of time field date_part('hour','4 hrs 3 mins'::timespan) isfinite(timespan) bool TRUE if this is a finite time isfinite('4 hrs'::timespan) reltime(timespan) reltime convert to reltime reltime('4 hrs'::timespan) Function Returns Description Example box(point,point) box convert points to box box('(0,0)'::point,'(1,1)'::point) area(box) float8 area of box area('((0,0),(1,1))'::box) isopen(path) bool TRUE if this is an open path isopen('[(0,0),(1,1),(2,0)]'::path) isclosed(path) bool TRUE if this is a closed path isclosed('((0,0),(1,1),(2,0))'::path) circle(point,float8) circle convert to circle circle('(0,0)'::point,2.0) polygon(npts,circle) polygon convert to polygon with npts points polygon(12,'((0,0),2.0)'::circle) center(circle) float8 center of object center('((0,0),2.0)'::circle) radius(circle) float8 radius of circle radius('((0,0),2.0)'::circle) diameter(circle) float8 diameter of circle diameter('((0,0),2.0)'::circle) area(circle) float8 area of circle area('((0,0),2.0)'::circle) SQL92 defines functions with specific syntax. Some of these are implemented using other Postgres functions. Function Returns Description Example position(text in text) int4 extract specified substring position('o' in 'Tom') substring(text [from int] [for int]) text extract specified substring substring('Tom' from 2 for 2) trim([leading|trailing|both] [text] from text) text trim characters from text trim(both 'x' from 'xTomx')