From: Peter Eisentraut Date: Sun, 10 Nov 2002 12:45:43 +0000 (+0000) Subject: Cleanup pass over User's Guide. Key word table updated. X-Git-Tag: REL7_3~59 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=3590e9fac83b0d11855388b36223daf445a57b74;p=postgresql Cleanup pass over User's Guide. Key word table updated. --- diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml index deca39f0ae..5f2a780862 100644 --- a/doc/src/sgml/array.sgml +++ b/doc/src/sgml/array.sgml @@ -1,4 +1,4 @@ - + Arrays @@ -21,7 +21,7 @@ CREATE TABLE sal_emp ( As shown, an array data type is named by appending square brackets ([]) to the data type name of the array elements. - The above query will create a table named + The above command will create a table named sal_emp with columns including a text string (name), a one-dimensional array of type @@ -68,7 +68,7 @@ SELECT name FROM sal_emp WHERE pay_by_quarter[1] <> pay_by_quarter[2]; The array subscript numbers are written within square brackets. By default PostgreSQL uses the - one-based numbering convention for arrays, that is, + one-based numbering convention for arrays, that is, an array of n elements starts with array[1] and ends with array[n]. @@ -90,10 +90,9 @@ SELECT pay_by_quarter[3] FROM sal_emp; We can also access arbitrary rectangular slices of an array, or subarrays. An array slice is denoted by writing - lower subscript : - upper subscript for one or more - array dimensions. This query retrieves the first item on Bill's - schedule for the first two days of the week: + lower-bound:upper-bound + for one or more array dimensions. This query retrieves the first + item on Bill's schedule for the first two days of the week: SELECT schedule[1:2][1:1] FROM sal_emp WHERE name = 'Bill'; @@ -112,9 +111,10 @@ SELECT schedule[1:2][1] FROM sal_emp WHERE name = 'Bill'; with the same result. An array subscripting operation is taken to represent an array slice if any of the subscripts are written in the - form lower : - upper. A lower bound of 1 is assumed for - any subscript where only one value is specified. + form + lower:upper. + A lower bound of 1 is assumed for any subscript where only one value + is specified. @@ -308,7 +308,7 @@ SELECT * FROM sal_emp WHERE pay_by_quarter **= 10000; - Remember that what you write in an SQL query will first be interpreted + Remember that what you write in an SQL command will first be interpreted as a string literal, and then as an array. This doubles the number of backslashes you need. For example, to insert a text array value containing a backslash and a double quote, you'd need to write @@ -321,7 +321,7 @@ INSERT ... VALUES ('{"\\\\","\\""}'); become \ and " respectively. (If we were working with a data type whose input routine also treated backslashes specially, bytea for example, we might need as many as eight backslashes - in the query to get one backslash into the stored array element.) + in the command to get one backslash into the stored array element.) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 24b169ba6a..1e247ec033 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1,5 +1,5 @@ @@ -161,7 +161,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.106 2002/10/31 22:18:42 t money - US-style currency + currency amount @@ -347,12 +347,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.106 2002/10/31 22:18:42 t Numeric types consist of two-, four-, and eight-byte integers, - four- and eight-byte - floating-point numbers and fixed-precision decimals. + four- and eight-byte floating-point numbers, and fixed-precision + decimals. lists the + available types. - - +
Numeric Types @@ -368,19 +368,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.106 2002/10/31 22:18:42 t smallint 2 bytes - Fixed-precision + small range fixed-precision -32768 to +32767 integer 4 bytes - Usual choice for fixed-precision + usual choice for fixed-precision -2147483648 to +2147483647 bigint 8 bytes - Very large range fixed-precision + large range fixed-precision -9223372036854775808 to 9223372036854775807 @@ -420,13 +420,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.106 2002/10/31 22:18:42 t bigserial 8 bytes - autoincrementing integer + large autoincrementing integer 1 to 9223372036854775807
- The syntax of constants for the numeric types is described in @@ -469,7 +468,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.106 2002/10/31 22:18:42 t int) and smallint. The type bigint, and the type names int2, int4, and int8 are extensions, which - are shared with various other RDBMS products. + are shared with various other SQL database systems. @@ -542,7 +541,7 @@ NUMERIC values to any particular scale, whereas numeric columns with a declared scale will coerce input values to that scale. (The SQL standard requires a default scale of 0, i.e., coercion to - integer accuracy. We find this a bit useless. If you're concerned about + integer precision. We find this a bit useless. If you're concerned about portability, always specify the precision and scale explicitly.) @@ -566,10 +565,11 @@ NUMERIC The data types real and double precision are inexact, variable-precision numeric types. - In practice, these types are usually implementations of IEEE 754 - binary floating point (single and double precision, - respectively), to the extent that the underlying processor, - operating system, and compiler support it. + In practice, these types are usually implementations of + IEEE Standard 754 for Binary Floating-Point + Arithmetic (single and double precision, respectively), to the + extent that the underlying processor, operating system, and + compiler support it. @@ -671,7 +671,7 @@ CREATE TABLE tablename ( Thus, we have created an integer column and arranged for its default values to be assigned from a sequence generator. A NOT NULL - constraint is applied to ensure that a NULL value cannot be explicitly + constraint is applied to ensure that a null value cannot be explicitly inserted, either. In most cases you would also want to attach a UNIQUE or PRIMARY KEY constraint to prevent duplicate values from being inserted by accident, but this is @@ -712,7 +712,7 @@ CREATE TABLE tablename ( Monetary Type - Deprecated + Note The money type is deprecated. Use numeric or decimal instead, in @@ -724,7 +724,8 @@ CREATE TABLE tablename ( The money type stores a currency amount with fixed - decimal point representation. The output format is + decimal point representation; see . The output format is locale-specific. @@ -735,8 +736,7 @@ CREATE TABLE tablename ( Output is in the latter form. - - +
Monetary Types @@ -751,13 +751,12 @@ CREATE TABLE tablename ( money 4 bytes - Fixed-precision + currency amount -21474836.48 to +21474836.47
- @@ -779,7 +778,7 @@ CREATE TABLE tablename ( character strings - +
Character Types @@ -791,20 +790,25 @@ CREATE TABLE tablename ( character(n), char(n) - Fixed-length blank padded + fixed-length, blank padded character varying(n), varchar(n) - Variable-length with limit + variable-length with limit text - Variable unlimited length + variable unlimited length
+ + shows the + general-purpose character types available in PostgreSQL. + + SQL defines two primary character types: character(n) and character @@ -930,7 +934,8 @@ SELECT b, char_length(b) FROM test2; There are two other fixed-length character types in - PostgreSQL. The name type + PostgreSQL, shown in . + The name type exists only for storage of internal catalog names and is not intended for use by the general user. Its length is currently defined as 64 bytes (63 usable characters plus terminator) @@ -944,7 +949,7 @@ SELECT b, char_length(b) FROM test2; enumeration type. - +
Specialty Character Types @@ -956,14 +961,14 @@ SELECT b, char_length(b) FROM test2; - "char" + "char" 1 byte - Single character internal type + single character internal type - name + name 64 bytes - Sixty-three character internal type + sixty-three character internal type @@ -974,10 +979,11 @@ SELECT b, char_length(b) FROM test2; Binary Strings - The bytea data type allows storage of binary strings. + The bytea data type allows storage of binary strings; + see . -
+
Binary String Types @@ -999,24 +1005,28 @@ SELECT b, char_length(b) FROM test2;
- A binary string is a sequence of octets that does not have either a - character set or collation associated with it. Bytea - specifically allows storing octets of zero value and other - non-printable octets. + A binary string is a sequence of octets (or bytes). Binary + strings are distinguished from characters strings by two + characteristics: First, binary strings specifically allow storing + octets of zero value and other non-printable + octets. Second, operations on binary strings process the actual + bytes, whereas the encoding and processing of character strings + depends on locale settings. - Octets of certain values must be escaped (but all - octet values may be escaped) when used as part of - a string literal in an SQL statement. In general, - to escape an octet, it is converted into the three-digit octal number + When entering bytea values, octets of certain values + must be escaped (but all octet values + may be escaped) when used as part of a string + literal in an SQL statement. In general, to + escape an octet, it is converted into the three-digit octal number equivalent of its decimal octet value, and preceded by two backslashes. Some octet values have alternate escape sequences, as shown in . - <acronym>SQL</acronym> Literal Escaped Octets + <type>bytea</> Literal Escaped Octets @@ -1030,27 +1040,27 @@ SELECT b, char_length(b) FROM test2; - 0 - zero octet - '\\000' - select '\\000'::bytea; - \000 + 0 + zero octet + '\\000' + SELECT '\\000'::bytea; + \000 - 39 - single quote - '\'' or '\\047' - select '\''::bytea; - ' + 39 + single quote + '\'' or '\\047' + SELECT '\''::bytea; + ' - 92 - backslash - '\\\\' or '\\134' - select '\\\\'::bytea; - \\ + 92 + backslash + '\\\\' or '\\134' + SELECT '\\\\'::bytea; + \\ @@ -1058,7 +1068,7 @@ SELECT b, char_length(b) FROM test2;
- Note that the result in each of the examples above was exactly one + Note that the result in each of the examples in was exactly one octet in length, even though the output representation of the zero octet and backslash are more than one character. Bytea output octets are also escaped. In general, each @@ -1071,7 +1081,7 @@ SELECT b, char_length(b) FROM test2; - <acronym>SQL</acronym> Output Escaped Octets + <type>bytea</> Output Escaped Octets @@ -1086,27 +1096,27 @@ SELECT b, char_length(b) FROM test2; - 92 - backslash - \\ - select '\\134'::bytea; - \\ + 92 + backslash + \\ + SELECT '\\134'::bytea; + \\ - 0 to 31 and 127 to 255 - non-printable octets - \### (octal value) - select '\\001'::bytea; - \001 + 0 to 31 and 127 to 255 + non-printable octets + \### (octal value) + SELECT '\\001'::bytea; + \001 - 32 to 126 - printable octets - ASCII representation - select '\\176'::bytea; - ~ + 32 to 126 + printable octets + ASCII representation + SELECT '\\176'::bytea; + ~ @@ -1114,18 +1124,19 @@ SELECT b, char_length(b) FROM test2;
- SQL string literals (input strings) must be - preceded with two backslashes due to the fact that they must pass - through two parsers in the PostgreSQL backend. The first backslash - is interpreted as an escape character by the string-literal parser, - and therefore is consumed, leaving the octets that follow. - The remaining backslash is recognized by the bytea input - function as the prefix of a three digit octal value. For example, a string - literal passed to the backend as '\\001' becomes + To use the bytea escaped octet notation, string + literals (input strings) must contain two backslashes due because + they must pass through two parsers in the PostgreSQL server. The + first backslash is interpreted as an escape character by the + string-literal parser, and therefore is consumed, leaving the + characters that follow. The remaining backslash is recognized by + the bytea input function as the prefix of a three + digit octal value. For example, a string literal passed to the + backend as '\\001' becomes '\001' after passing through the string-literal parser. The '\001' is then sent to the - bytea input function, where it is converted to a single - octet with a decimal value of 1. + bytea input function, where it is converted to a + single octet with a decimal value of 1. @@ -1136,7 +1147,7 @@ SELECT b, char_length(b) FROM test2; backslashes in the string passed to the bytea input function, which interprets them as representing a single backslash. For example, a string literal passed to the - backend as '\\\\' becomes '\\' + server as '\\\\' becomes '\\' after passing through the string-literal parser. The '\\' is then sent to the bytea input function, where it is converted to a single octet with a decimal @@ -1168,88 +1179,13 @@ SELECT b, char_length(b) FROM test2; escape character. - - Bytea provides most of the functionality of the binary - string type per SQL99 section 4.3. A comparison of SQL99 Binary - Strings and PostgreSQL bytea is presented in - . - - - - Comparison of SQL99 Binary String and PostgreSQL - <type>BYTEA</type> types - - - - SQL99 - BYTEA - - - - - - Name of data type BINARY LARGE OBJECT - or BLOB - Name of data type BYTEA - - - - Sequence of octets that does not have either a character set - or collation associated with it. - same - - - - Described by a binary data type descriptor containing the - name of the data type and the maximum length - in octets - Described by a binary data type descriptor containing the - name of the data type with no specific maximum length - - - - - All binary strings are mutually comparable in accordance - with the rules of comparison predicates. - same - - - - Binary string values can only be compared for equality. - - Binary string values can be compared for equality, greater - than, greater than or equal, less than, less than or equal - - - - - Operators operating on and returning binary strings - include concatenation, substring, overlay, and trim - Operators operating on and returning binary strings - include concatenation, substring, and trim. The - leading and trailing - arguments for trim are not yet implemented. - - - - - Other operators involving binary strings - include length, position, and the like predicate - same - - - - A binary string literal is comprised of an even number of - hexadecimal digits, in single quotes, preceded by X, - e.g. X'1a43fe' - A binary string literal is comprised of octets - escaped according to the rules shown in - - - - -
- + + The SQL standard defines a different binary string type, called + BLOB or BINARY LARGE OBJECT. The input + format is different compared to bytea, but the + provided functions and operators are mostly the same. + + @@ -1257,11 +1193,11 @@ SELECT b, char_length(b) FROM test2; PostgreSQL supports the full set of - SQL date and time types. + SQL date and time types, shown in . - - +
Date/Time Types @@ -1326,20 +1262,21 @@ SELECT b, char_length(b) FROM test2;
- - time, timestamp, and interval - accept an - optional precision value p which - specifies the number of fractional digits retained in the seconds - field. By default, there is no explicit bound on precision. The - allowed range of p is from 0 to 6. + time, timestamp, and + interval accept an optional precision value + p which specifies the number of + fractional digits retained in the seconds field. By default, there + is no explicit bound on precision. The allowed range of + p is from 0 to 6 for the + timestamp and interval types, 0 to 13 + for the time types. - When timestamps are stored as double precision floating-point + When timestamp values are stored as double precision floating-point numbers (currently the default), the effective limit of precision may be less than 6, since timestamp values are stored as seconds since 2000-01-01. Microsecond precision is achieved for dates within @@ -1366,6 +1303,16 @@ SELECT b, char_length(b) FROM test2; outside that range are in UTC. + + The type time with time zone is defined by the SQL + standard, but the definition exhibits properties which lead to + questionable usefulness. In most cases, a combination of + date, time, timestamp without time + zone and timestamp with time zone should + provide a complete range of date/time functionality required by + any application. + + The types abstime and reltime are lower precision types which are used internally. @@ -1390,8 +1337,7 @@ SELECT b, char_length(b) FROM test2; or SET DateStyle TO 'NonEuropean' specifies the variant month before day, the command SET DateStyle TO 'European' sets the variant - day before month. The ISO style - is the default but this default can be changed at compile time or at run time. + day before month. @@ -1409,7 +1355,7 @@ SELECT b, char_length(b) FROM test2; in single quotes, like text strings. Refer to for more information. - SQL9x requires the following syntax + SQL requires the following syntax type [ (p) ] 'value' @@ -1422,7 +1368,7 @@ SELECT b, char_length(b) FROM test2; - <type>date</type> + Dates date @@ -1430,9 +1376,11 @@ SELECT b, char_length(b) FROM test2; - The following are some possible inputs for the date type. + shows some possible + inputs for the date type. + - +
Date Input @@ -1444,7 +1392,7 @@ SELECT b, char_length(b) FROM test2; January 8, 1999 - Unambiguous + unambiguous 1999-01-08 @@ -1472,11 +1420,11 @@ SELECT b, char_length(b) FROM test2; 1999.008 - Year and day of year + year and day of year 99008 - Year and day of year + year and day of year J2451187 @@ -1484,16 +1432,15 @@ SELECT b, char_length(b) FROM test2; January 8, 99 BC - Year 99 before the Common Era + year 99 before the Common Era
- - <type>time [ ( <replaceable>p</replaceable> ) ] [ without time zone ]</type> + Times time @@ -1503,18 +1450,23 @@ SELECT b, char_length(b) FROM test2; time without time zone time + + time with time zone + data type + - Per SQL99, this type can be specified as time or + The time type can be specified as time or as time without time zone. The optional precision p should be between 0 and 13, and defaults to the precision of the input time literal. - The following are valid time inputs. + shows the valid time inputs. + - +
Time Input @@ -1542,56 +1494,28 @@ SELECT b, char_length(b) FROM test2; 04:05 AM - Same as 04:05; AM does not affect value + same as 04:05; AM does not affect value 04:05 PM - Same as 16:05; input hour must be <= 12 + same as 16:05; input hour must be <= 12 allballs - Same as 00:00:00 + same as 00:00:00
- - - - - <type>time [ ( <replaceable>precision</replaceable> ) ] with time zone</type> - - - time with time zone - data type - - - time - data type - - - - This type is defined by SQL92, but the definition exhibits - properties which lead to questionable usefulness. In - most cases, a combination of date, - time, timestamp without time zone - and timestamp with time zone - should provide a complete range of date/time functionality - required by any application. - - The optional precision - p should be between 0 and 13, and - defaults to the precision of the input time literal. + The type time with time zone accepts all input also + legal for the time type, appended with a legal time + zone, as shown in . - - time with time zone accepts all input also legal - for the time type, appended with a legal time zone, - as follows: - - +
Time With Time Zone Input @@ -1620,7 +1544,6 @@ SELECT b, char_length(b) FROM test2;
- Refer to for @@ -1629,7 +1552,12 @@ SELECT b, char_length(b) FROM test2; - <type>timestamp [ (<replaceable>precision</replaceable>) ] without time zone</type> + Time stamps + + + timestamp + data type + timestamp without time zone @@ -1637,19 +1565,31 @@ SELECT b, char_length(b) FROM test2; - Valid input for the timestamp [ (p) ] without time zone - type consists of a concatenation - of a date and a time, followed by an optional AD or - BC, followed by an optional time zone. (See below.) - Thus + Time stamp types exist as timestamp [ + (p) ], timestamp [ + (p) ] without time zone and + timestamp [ (p) ] without time + zone. A plain timestamp is equivalent to + timestamp without timezone. + + + + Valid input for the time stamp types consists of a concatenation + of a date and a time, followed by an optional + AD or BC, followed by an + optional time zone. (See .) Thus 1999-01-08 04:05:06 + + and + +1999-01-08 04:05:06 -8:00 - is a valid timestamp without time zone value that - is ISO-compliant. - In addition, the wide-spread format + are valid values, which follow the ISO 8601 + standard. In addition, the wide-spread format January 8 04:05:06 1999 PST @@ -1659,7 +1599,7 @@ January 8 04:05:06 1999 PST The optional precision - p should be between 0 and 13, and + p should be between 0 and 6, and defaults to the precision of the input timestamp literal. @@ -1669,42 +1609,7 @@ January 8 04:05:06 1999 PST resulting date/time value is derived from the explicit date/time fields in the input value, and is not adjusted for time zone. - - - - <type>timestamp [ (<replaceable>precision</replaceable>) ] with time zone</type> - - - timestamp - data type - - - - Valid input for the timestamp type consists of a concatenation - of a date and a time, followed by an optional AD or - BC, followed by an optional time zone. (See below.) - Thus - - -1999-01-08 04:05:06 -8:00 - - - is a valid timestamp value that is ISO-compliant. - In addition, the wide-spread format - - -January 8 04:05:06 1999 PST - - is supported. - - - - The optional precision - p should be between 0 and 13, and - defaults to the precision of the input timestamp literal. - - Time Zone Input @@ -1734,11 +1639,10 @@ January 8 04:05:06 1999 PST
- - <type>interval [ ( <replaceable>precision</replaceable> ) ]</type> + Intervals interval @@ -1772,7 +1676,7 @@ January 8 04:05:06 1999 PST The optional precision - p should be between 0 and 13, and + p should be between 0 and 6, and defaults to the precision of the input literal. @@ -1796,14 +1700,16 @@ January 8 04:05:06 1999 PST input for the corresponding data type: CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP. The latter two accept an - optional precision specification. + optional precision specification. (See also .) PostgreSQL also supports several - special constants for convenience. + special constants for convenience, shown in . + - +
Special Date/Time Constants @@ -1819,31 +1725,31 @@ January 8 04:05:06 1999 PST infinity - Later than other valid times + later than other valid times -infinity - Earlier than other valid times + earlier than other valid times invalid - Illegal entry + illegal entry now - Current transaction time + current transaction time today - Midnight today + midnight today tomorrow - Midnight tomorrow + midnight tomorrow yesterday - Midnight yesterday + midnight yesterday zulu, allballs, z @@ -1853,22 +1759,6 @@ January 8 04:05:06 1999 PST
- 'now' is - evaluated when the value is first interpreted. - - - - - As of PostgreSQL version 7.2, - 'current' is no longer supported as a - date/time constant. - Previously, - 'current' was stored as a special value, - and evaluated to 'now' only when - used in an expression or type - conversion. - - @@ -1888,12 +1778,19 @@ January 8 04:05:06 1999 PST - Output formats can be set to one of the four styles - ISO 8601, SQL (Ingres), traditional - PostgreSQL, and German, using the SET DateStyle. - The default is the ISO format. + Output formats can be set to one of the four styles ISO 8601, + SQL (Ingres), traditional PostgreSQL, and + German, using the SET DateStyle. The default + is the ISO format. (The SQL standard requires + the use of the ISO 8601 format. The name of the + SQL output format is a historical accident.) + shows examples of + each output style. The output of the date and + time types is of course only the date or time part + in accordance with the given examples. + - +
Date/Time Output Styles @@ -1905,46 +1802,40 @@ January 8 04:05:06 1999 PST - 'ISO' - ISO-8601 standard + ISO + ISO 8601/SQL standard 1997-12-17 07:37:16-08 - 'SQL' - Traditional style + SQL + traditional style 12/17/1997 07:37:16.00 PST - 'PostgreSQL' - Original style + PostgreSQL + original style Wed Dec 17 07:37:16 1997 PST - 'German' - Regional style + German + regional style 17.12.1997 07:37:16.00 PST
- - The output of the date and time styles - is of course - only the date or time part in accordance with the above examples. + The SQL style has European and non-European + (U.S.) variants, which determines whether month follows day or + vice versa. (See + for how this setting also affects interpretation of input values.) + shows an + example. - - The SQL style has European and non-European - (U.S.) variants, - which determines whether month follows day or vice versa. (See - also - for how this setting affects interpretation of - input values.) - - - Date-Order Conventions +
+ Date Order Conventions @@ -1967,7 +1858,6 @@ January 8 04:05:06 1999 PST
- interval output looks like the input format, except that units like @@ -1980,29 +1870,15 @@ January 8 04:05:06 1999 PST - There are several ways to affect the appearance of date/time types: - - - - - The PGDATESTYLE environment variable used by the backend directly - on postmaster start-up. - - - - - The PGDATESTYLE environment variable used by the frontend libpq - on session start-up. - - - - - SET DATESTYLE SQL command. - - - + The date/time styles can be selected by the user using the + SET DATESTYLE command, the + datestyle parameter in the + postgresql.conf configuration file, and the + PGDATESTYLE environment variable on the server or + client. The formatting function to_char + (see ) is also available as + a more flexible way to format the date/time output. - @@ -2014,8 +1890,8 @@ January 8 04:05:06 1999 PST PostgreSQL endeavors to be compatible with - SQL92 definitions for typical usage. - However, the SQL92 standard has an odd mix of date and + the SQL standard definitions for typical usage. + However, the SQL standard has an odd mix of date and time types and capabilities. Two obvious problems are: @@ -2046,10 +1922,10 @@ January 8 04:05:06 1999 PST To address these difficulties, we recommend using date/time types that contain both date and time when using time zones. We - recommend not using the SQL92 type time + recommend not using the type time with time zone (though it is supported by PostgreSQL for legacy applications and - for compatibility with other RDBMS implementations). + for compatibility with other SQL implementations). PostgreSQL assumes your local time zone for any type containing only date or time. Further, time zone support is derived from @@ -2077,35 +1953,39 @@ January 8 04:05:06 1999 PST There are several ways to affect the time-zone behavior: - + - The TZ environment variable is used by the backend directly - on postmaster start-up as the default time zone. + The TZ environment variable on the server host + is used by the server as the default time zone. + - The PGTZ environment variable, if set at the client, is used by libpq - to send a SET TIME ZONE command to the backend upon - connection. + The PGTZ environment variable, if set at the + client, is used by libpq + applications to send a SET TIME ZONE + command to the server upon connection. + The SQL command SET TIME ZONE sets the time zone for the session. + - The SQL92 qualifier on + The construct timestamp AT TIME ZONE 'zone' where zone can be specified as a - text time zone (e.g. 'PST') or as an - interval (e.g. INTERVAL '-08:00'). + text time zone (e.g., 'PST') or as an + interval (e.g., INTERVAL '-08:00'). @@ -2118,13 +1998,10 @@ January 8 04:05:06 1999 PST - - - If the run-time option AUSTRALIAN_TIMEZONES is set - then CST and EST refer to - Australian time zones, not American ones. - - + + Refer to for a list of + available time zones. + @@ -2134,7 +2011,7 @@ January 8 04:05:06 1999 PST PostgreSQL uses Julian dates for all date/time calculations. They have the nice property of correctly - predicting/calculating any date more recent than 4713BC + predicting/calculating any date more recent than 4713 BC to far into the future, using the assumption that the length of the year is 365.2425 days. @@ -2165,11 +2042,11 @@ January 8 04:05:06 1999 PST PostgreSQL provides the - SQL99 type boolean. + standard SQL type boolean. boolean can have one of only two states: true or false. A third state, unknown, is represented by the - SQL NULL state. + SQL null value. @@ -2245,13 +2122,13 @@ SELECT * FROM test1 WHERE a; Geometric Types - Geometric types represent two-dimensional spatial objects. - The most fundamental type, - the point, forms the basis for all of the other types. + Geometric data types represent two-dimensional spatial + objects. shows the geometric + types available in PostgreSQL. The most fundamental type, the + point, forms the basis for all of the other types. - - +
Geometric Types @@ -2314,12 +2191,11 @@ SELECT * FROM test1 WHERE a;
- A rich set of functions and operators is available to perform various geometric operations such as scaling, translation, rotation, and determining - intersections. + intersections. They are explained in . @@ -2331,15 +2207,12 @@ SELECT * FROM test1 WHERE a; Points are the fundamental two-dimensional building block for geometric types. - - - point is specified using the following syntax: - + ( x , y ) x , y - + where the arguments are @@ -2348,7 +2221,7 @@ SELECT * FROM test1 WHERE a; x - The x-axis coordinate as a floating-point number + the x-axis coordinate as a floating-point number @@ -2357,7 +2230,7 @@ SELECT * FROM test1 WHERE a; y - The y-axis coordinate as a floating-point number + the y-axis coordinate as a floating-point number @@ -2374,16 +2247,13 @@ SELECT * FROM test1 WHERE a; 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 the arguments are @@ -2393,7 +2263,7 @@ SELECT * FROM test1 WHERE a; (x2,y2) - The end points of the line segment + the end points of the line segment @@ -2411,16 +2281,13 @@ SELECT * FROM test1 WHERE a; Boxes are represented by pairs of points that 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 the arguments are @@ -2430,7 +2297,7 @@ SELECT * FROM test1 WHERE a; (x2,y2) - Opposite corners of the box + opposite corners of the box @@ -2442,7 +2309,7 @@ SELECT * FROM test1 WHERE a; The corners are reordered on input to store the upper right corner, then the lower left corner. Other corners of the box can be entered, but the lower - left and upper right corners are determined from the input and stored. + left and upper right corners are determined from the input and stored corners. @@ -2471,13 +2338,13 @@ SELECT * FROM test1 WHERE a; 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 the arguments are @@ -2487,8 +2354,8 @@ SELECT * FROM test1 WHERE a; End points of the line segments comprising the path. - A leading square bracket ("[") indicates an open path, while - a leading parenthesis ("(") indicates a closed path. + A leading square bracket ([) indicates an open path, while + a leading parenthesis (() indicates a closed path. @@ -2516,12 +2383,12 @@ SELECT * FROM test1 WHERE a; polygon is specified using the following syntax: - + ( ( x1 , y1 ) , ... , ( xn , yn ) ) ( x1 , y1 ) , ... , ( xn , yn ) ( x1 , y1 , ... , xn , yn ) x1 , y1 , ... , xn , yn - + where the arguments are @@ -2552,17 +2419,14 @@ SELECT * FROM test1 WHERE a; 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 the arguments are @@ -2571,7 +2435,7 @@ SELECT * FROM test1 WHERE a; (x,y) - Center of the circle + center of the circle @@ -2580,7 +2444,7 @@ SELECT * FROM test1 WHERE a; r - Radius of the circle + radius of the circle @@ -2604,9 +2468,11 @@ SELECT * FROM test1 WHERE a; PostgreSQL offers data types to store IP and MAC - addresses. It is preferable to use these types over plain text - types, because these types offer input error checking and several - specialized operators and functions. + addresses, shown in . It + is preferable to use these types over plain text types, because + these types offer input error checking and several specialized + operators and functions. + Network Address Data Types @@ -2645,10 +2511,9 @@ SELECT * FROM test1 WHERE a;
- - IP v6 is not yet supported. + IPv6 is not yet supported. @@ -2706,9 +2571,10 @@ SELECT * FROM test1 WHERE a; - Here are some examples: + shows some examples. + - +
<type>cidr</> Type Input Examples @@ -2777,7 +2643,6 @@ SELECT * FROM test1 WHERE a;
- @@ -2974,7 +2839,7 @@ SELECT * FROM test; Type oid represents an object identifier. There are also several aliases for oid: regproc, regprocedure, regoper, regoperator, regclass, - and regtype. + and regtype. shows an overview. @@ -3002,13 +2867,12 @@ SELECT * FROM test; types allow simplified lookup of OID values for objects: for example, one may write 'mytable'::regclass to get the OID of table mytable, rather than SELECT oid FROM pg_class WHERE - relname = 'mytable'. (In reality, a much more complicated SELECT would + relname = 'mytable'. (In reality, a much more complicated SELECT would be needed to deal with selecting the right OID when there are multiple tables named mytable in different schemas.) - - +
Object Identifier Types @@ -3016,7 +2880,7 @@ SELECT * FROM test; Type nameReferencesDescription - Examples + Value example @@ -3025,55 +2889,54 @@ SELECT * FROM test; oid any - Numeric object identifier - 564182 + numeric object identifier + 564182 regproc pg_proc - Function name - sum + function name + sum regprocedure pg_proc - Function with argument types - sum(int4) + function with argument types + sum(int4) regoper - pg_operator - Operator name - + + pg_operator + operator name + + regoperator - pg_operator - Operator with argument types - *(integer,integer) -(NONE,integer) + pg_operator + operator with argument types + *(integer,integer) or -(NONE,integer) regclass - pg_class - Relation name - pg_type + pg_class + relation name + pg_type regtype - pg_type - Type name - integer + pg_type + type name + integer
- All of the OID alias types accept schema-qualified names, and will @@ -3083,7 +2946,7 @@ SELECT * FROM test; accept input names that are unique (not overloaded), so they are of limited use; for most uses regprocedure or regoperator is more appropriate. For regoperator, - unary operators are identified by writing NONE for the unused + unary operators are identified by writing NONE for the unused operand. @@ -3109,7 +2972,7 @@ SELECT * FROM test; Transaction identifiers are 32-bit quantities. In a long-lived database it is possible for transaction IDs to wrap around. This is not a fatal problem given appropriate maintenance procedures; - see the Administrator's Guide for details. However, it is + see the &cite-admin; for details. However, it is unwise to depend on uniqueness of transaction IDs over the long term (more than one billion transactions). @@ -3122,7 +2985,7 @@ SELECT * FROM test; limit of 232 (4 billion) SQL commands within a single transaction. In practice this limit is not a problem --- note that the limit is on - number of SQL queries, not number of tuples processed. + number of SQL commands, not number of tuples processed. @@ -3175,17 +3038,18 @@ SELECT * FROM test; - The PostgreSQL type system contains a number - of special-purpose entries that are collectively called - pseudo-types. A pseudo-type cannot be used as a column - data type, but it can be used to declare a function's argument or result - type. Each of the available pseudo-types is useful in situations where - a function's behavior does not correspond to simply taking or returning - a value of a specific SQL data type. + The PostgreSQL type system contains a + number of special-purpose entries that are collectively called + pseudo-types. A pseudo-type cannot be used as a + column data type, but it can be used to declare a function's + argument or result type. Each of the available pseudo-types is + useful in situations where a function's behavior does not + correspond to simply taking or returning a value of a specific SQL + data type. lists the + existing pseudo-types. - - +
Pseudo-Types @@ -3199,7 +3063,7 @@ SELECT * FROM test; record - Identifies a function returning an unspecified tuple type + Identifies a function returning an unspecified row type @@ -3245,7 +3109,6 @@ SELECT * FROM test;
- Functions coded in C (whether built-in or dynamically loaded) may be diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index 6296040d81..7cf2f9da29 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -1,5 +1,5 @@ @@ -8,7 +8,7 @@ Date/time details PostgreSQL uses an internal heuristic - parser for all date/time support. Dates and times are input as + parser for all date/time input support. Dates and times are input as strings, and are broken up into distinct fields with a preliminary determination of what kind of information may be in the field. Each field is interpreted and either assigned a numeric @@ -25,10 +25,203 @@ Date/time details - Date/Time Keywords + Date/Time Input Interpretation + + + The date/time types are all decoded using a common set of routines. + + + + Date/Time Input Interpretation + + + + Break the input string into tokens and categorize each token as + a string, time, time zone, or number. + + + + + + If the numeric token contains a colon (:), this is + a time string. Include all subsequent digits and colons. + + + + + + If the numeric token contains a dash (-), slash + (/), or two or more dots (.), this is + a date string which may have a text month. + + + + + + If the token is numeric only, then it is either a single field + or an ISO 8601 concatenated date (e.g., + 19990113 for January 13, 1999) or time + (e.g. 141516 for 14:15:16). + + + + + + If the token starts with a plus (+) or minus + (-), then it is either a time zone or a special + field. + + + + + + + + If the token is a text string, match up with possible strings. + + + + + + Do a binary-search table lookup for the token + as either a special string (e.g., today), + day (e.g., Thursday), + month (e.g., January), + or noise word (e.g., at, on). + + + + Set field values and bit mask for fields. + For example, set year, month, day for today, + and additionally hour, minute, second for now. + + + + + + If not found, do a similar binary-search table lookup to match + the token with a time zone. + + + + + + If not found, throw an error. + + + + + + + + The token is a number or number field. + + + + + + If there are more than 4 digits, + and if no other date fields have been previously read, then interpret + as a concatenated date (e.g., 19990118). 8 + and 6 digits are interpreted as year, month, and day, while 7 + and 5 digits are interpreted as year, day of year, respectively. + + + + + + If the token is three digits + and a year has already been decoded, then interpret as day of year. + + + + + + If four or six digits and a year has already been read, then + interpret as a time. + + + + + + If four or more digits, then interpret as a year. + + + + + + If in European date mode, and if the day field has not yet been read, + and if the value is less than or equal to 31, then interpret as a day. + + + + + + If the month field has not yet been read, + and if the value is less than or equal to 12, then interpret as a month. + + + + + + If the day field has not yet been read, + and if the value is less than or equal to 31, then interpret as a day. + + + + + + If two digits or four or more digits, then interpret as a year. + + + + + + Otherwise, throw an error. + + + + + + + + If BC has been specified, negate the year and add one for + internal storage. (There is no year zero in the Gregorian + calendar, so numerically 1BC becomes year + zero.) + + + + + + If BC was not specified, and if the year field was two digits in length, then + adjust the year to 4 digits. If the field was less than 70, then add 2000; + otherwise, add 1900. + + + + Gregorian years AD 1-99 may be entered by using 4 digits with leading + zeros (e.g., 0099 is AD 99). Previous versions of + PostgreSQL accepted years with three + digits and with single digits, but as of version 7.0 the rules have + been tightened up to reduce the possibility of ambiguity. + + + + + + + + + + Date/Time Key Words - + shows the tokens that are + permissible as abbreviations for the names of the month. + + +
Month Abbreviations @@ -88,13 +281,17 @@ Date/time details - The month May has no explicit abbreviation, for obvious reasons. + The month May has no explicit abbreviation, for obvious reasons. - -
+ shows the tokens that are + permissible as abbreviations for the names of the days of the + week. + + +
Day of the Week Abbreviations @@ -135,12 +332,14 @@ Date/time details
- - - <productname>PostgreSQL</productname> Field Modifiers - Field Modifiers + shows the tokens that serve + various modifier purposes. + + +
+ Date/Time Field Modifiers @@ -151,7 +350,7 @@ Date/time details ABSTIME - Keyword ignored + Key word ignored AM @@ -159,7 +358,7 @@ Date/time details AT - Keyword ignored + Key word ignored JULIAN, JD, J @@ -167,7 +366,7 @@ Date/time details ON - Keyword ignored + Key word ignored PM @@ -180,44 +379,40 @@ Date/time details
- - The keyword ABSTIME is ignored for historical + The key word ABSTIME is ignored for historical reasons; in very old releases of - PostgreSQL invalid ABSTIME - fields were emitted as Invalid Abstime. This is no - longer the case however and this keyword will likely be dropped in + PostgreSQL invalid fields of type abstime + were emitted as Invalid Abstime. This is no + longer the case however and this key word will likely be dropped in a future release. - - - Time Zones - - + time zones + shows the time zone + abbreviations recognized by PostgreSQL. PostgreSQL contains internal tabular - information for time zone decoding, since there is no *nix standard - system interface to provide access to general, cross-timezone - information. The underlying OS is used to - provide time zone information for output, however. + information for time zone decoding, since there is no standard + operating system interface to provide access to general, + cross-time zone information. The underlying operating system + is used to provide time zone information for + output, however. - The following table of time zones recognized by - PostgreSQL is organized by time - zone offset from UTC, rather than alphabetically; this is intended - to facilitate + The table is organized by time zone offset from UTC, + rather than alphabetically; this is intended to facilitate matching local usage with recognized abbreviations for cases where these might differ. + - - <productname>PostgreSQL</productname> Recognized Time Zones - Time Zones +
+ Time Zone Abbreviations @@ -749,31 +944,29 @@ Date/time details
- - + Australian Time Zones - Australian time zones and their naming variants - account for fully one quarter of all time zones in the - PostgreSQL time zone lookup table. - There are two naming conflicts with time zones commonly used - in the United States, CST and EST. + There are three naming conflicts between Australian time zone + names with time zones commonly used in North and South America: + ACST, CST, and + EST. If the run-time option + AUSTRALIAN_TIMEZONES is set to true then + ACST, CST, + EST, and SAT are interpreted + as Australian time zone names, as shown in . If it is false (which is the + default), then ACST, CST, + and EST are taken as American time zone names, + and SAT is interpreted as a noise word + indicating Saturday. + - - If the run-time option AUSTRALIAN_TIMEZONES is set - then CST, EST, and - SAT will be - interpreted as Australian timezone names. Without this option, - CST and EST are taken as - American timezone names, while SAT is interpreted as a - noise word indicating Saturday. - - - <productname>PostgreSQL</productname> Australian Time Zones - Australian Time Zones +
+ Australian Time Zone Abbreviations @@ -806,196 +999,10 @@ Date/time details
- - - - - Date/Time Input Interpretation - - The date/time types are all decoded using a common set of routines. - - - - Date/Time Input Interpretation - - - - Break the input string into tokens and categorize each token as - a string, time, time zone, or number. - - - - - - If the numeric token contains a colon (":"), this is a time - string. Include all subsequent digits and colons. - - - - - - If the numeric token contains a dash ("-"), slash ("/"), or - two or more dots ("."), - this is a date string which may have a text month. - - - - - - If the token is numeric only, then it is either a single field - or an ISO-8601 concatenated date - (e.g. 19990113 for January 13, 1999) - or time (e.g. 141516 for 14:15:16). - - - - - If the token starts with a plus ("+") or minus ("-"), - then it is either a time zone or a special field. - - - - - - - - If the token is a text string, match up with possible strings. - - - - - - Do a binary-search table lookup for the token - as either a special string (e.g. today), - day (e.g. Thursday), - month (e.g. January), - or noise word (e.g. at, on). - - - Set field values and bit mask for fields. - For example, set year, month, day for today, - and additionally hour, minute, second for now. - - - - - - If not found, do a similar binary-search table lookup to match - the token with a time zone. - - - - - - If not found, throw an error. - - - - - - - - The token is a number or number field. - - - - - - If there are more than 4 digits, - and if no other date fields have been previously read, then interpret - as a concatenated date (e.g. 19990118). 8 - and 6 digits are interpreted as year, month, and day, while 7 - and 5 digits are interpreted as year, day of year, respectively. - - - - - - If the token is three digits - and a year has already been decoded, then interpret as day of year. - - - - - - If four or six digits and a year has already been read, then - interpret as a time. - - - - - - If four or more digits, then interpret as a year. - - - - - - If in European date mode, and if the day field has not yet been read, - and if the value is less than or equal to 31, then interpret as a day. - - - - - - If the month field has not yet been read, - and if the value is less than or equal to 12, then interpret as a month. - - - - - - If the day field has not yet been read, - and if the value is less than or equal to 31, then interpret as a day. - - - - - - If two digits or four or more digits, then interpret as a year. - - - - - - Otherwise, throw an error. - - - - - - - - If BC has been specified, negate the year and add one for - internal storage - (there is no year zero in the Gregorian calendar, so numerically - 1BC becomes year zero). - - - - - - If BC was not specified, and if the year field was two digits in length, then - adjust the year to 4 digits. If the field was less than 70, then add 2000; - otherwise, add 1900. - - - - Gregorian years 1-99AD may be entered by using 4 digits with leading - zeros (e.g. 0099 is 99AD). Previous versions of - PostgreSQL accepted years with three - digits and with single digits, but as of version 7.0 the rules have - been tightened up to reduce the possibility of ambiguity. - - - - - - - + - + History of Units @@ -1015,22 +1022,20 @@ Date/time details to noon UTC on 2 January 4713 BC. - - Julian Day is different from Julian Date. - - The Julian calendar was introduced by Julius Caesar in 45 BC. It was - in common use until the 1582, when countries started changing to the - Gregorian calendar. - - In the Julian calendar, the tropical year is approximated as 365 1/4 - days = 365.25 days. This gives an error of about 1 day in - 128 years. - The accumulating calendar error prompted Pope Gregory XIII - to reform the calendar in accordance with instructions - from the Council of Trent. + + The Julian Day is different from the Julian + Date. The Julian date refers to the Julian calendar, which + was introduced by Julius Caesar in 45 BC. It was in common use + until the 1582, when countries started changing to the Gregorian + calendar. In the Julian calendar, the tropical year is + approximated as 365 1/4 days = 365.25 days. This gives an error of + about 1 day in 128 years. + The accumulating calendar error prompted + Pope Gregory XIII to reform the calendar in accordance with + instructions from the Council of Trent. In the Gregorian calendar, the tropical year is approximated as 365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300 years for the tropical year to shift one day with respect to the @@ -1066,37 +1071,36 @@ Date/time details This was observed in Italy, Poland, Portugal, and Spain. Other Catholic countries followed shortly after, but Protestant countries were reluctant to change, and the Greek orthodox countries didn't change - until the start of this century. + until the start of the 20th century. The reform was observed by Great Britain and Dominions (including what is now the USA) in 1752. - Thus 2 Sep 1752 was followed by 14 Sep 1752. + Thus 2 September 1752 was followed by 14 September 1752. - This is why Unix systems have cal + This is why Unix systems have the cal program produce the following: - -% cal 9 1752 + +$ cal 9 1752 September 1752 S M Tu W Th F S 1 2 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 - + - - - SQL92 states that - Within the definition of a datetime literal, - the datetime values are constrained by the - natural rules for dates and times - according to the Gregorian calendar. - Dates between 1752-09-03 and 1752-09-13, although eliminated in - some countries by Papal fiat, conform to - natural rules and are hence valid dates. - - + + + The SQL standard states that Within the definition of a + datetime literal, the datetime + values are constrained by the natural rules for dates and + times according to the Gregorian calendar. Dates between + 1752-09-03 and 1752-09-13, although eliminated in some countries + by Papal fiat, conform to natural rules and are + hence valid dates. + + Different calendars have been developed in various parts of the @@ -1108,7 +1112,7 @@ Date/time details calendar in 2637 BC. The People's Republic of China uses the Gregorian calendar - for civil purposes. Chinese calendar is used for determining + for civil purposes. The Chinese calendar is used for determining festivals. diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml index 934196981a..6d4b22e2ea 100644 --- a/doc/src/sgml/ddl.sgml +++ b/doc/src/sgml/ddl.sgml @@ -1,4 +1,4 @@ - + Data Definition @@ -222,7 +222,7 @@ DROP TABLE products; The identity (transaction ID) of the deleting transaction, or zero for an undeleted tuple. It is possible for this field to - be nonzero in a visible tuple: that usually indicates that the + be nonzero in a visible tuple: That usually indicates that the deleting transaction hasn't committed yet, or that an attempted deletion was rolled back. @@ -353,7 +353,7 @@ CREATE TABLE products ( price numeric CONSTRAINT positive_price CHECK (price > 0) ); - To specify a named constraint, use the key word + So, to specify a named constraint, use the key word CONSTRAINT followed by an identifier followed by the constraint definition. @@ -382,7 +382,7 @@ CREATE TABLE products ( - We say that the first two are column constraints, whereas the + We say that the first two constraints are column constraints, whereas the third one is a table constraint because it is written separately from the column definitions. Column constraints can also be written as table constraints, while the reverse is not necessarily @@ -931,7 +931,7 @@ WHERE c.altitude > 500 and c.tableoid = p.oid; In previous versions of PostgreSQL, the default was not to get access to child tables. This was found to - be error prone and is also in violation of SQL99. Under the old + be error prone and is also in violation of the SQL standard. Under the old syntax, to get the sub-tables you append * to the table name. For example @@ -1609,7 +1609,7 @@ REVOKE CREATE ON public FROM PUBLIC; standard. Therefore, many users consider qualified names to really consist of username.tablename. - This is also supported by PostgreSQL if you create a per-user + This is how PostgreSQL will effectively behave if you create a per-user schema for every user. @@ -1693,8 +1693,8 @@ DROP TABLE products CASCADE; and all the dependent objects will be removed. In this case, it doesn't remove the orders table, it only removes the foreign key - constraint. (If you want to check what DROP ... CASCADE will do, - run DROP without CASCADE and read the NOTICEs.) + constraint. (If you want to check what DROP ... CASCADE will do, + run DROP without CASCADE and read the NOTICE messages.) diff --git a/doc/src/sgml/dml.sgml b/doc/src/sgml/dml.sgml index 788f4d7dac..a7d15cb52b 100644 --- a/doc/src/sgml/dml.sgml +++ b/doc/src/sgml/dml.sgml @@ -1,4 +1,4 @@ - + Data Manipulation @@ -23,10 +23,10 @@ When a table is created, it contains no data. The first thing to do before a database can be of much use is to insert data. Data is - inserted one row at a time. This does not mean that there are no - means to bulk load many rows efficiently. But there - is no way to insert less than one row at a time. Even if you know - only some column values, a complete row must be created. + conceptually inserted one row at a time. Of course you can also + insert more than one row, but there is no way to insert less than + one row at a time. Even if you know only some column values, a + complete row must be created. @@ -84,6 +84,15 @@ INSERT INTO products (product_no, name, price) VALUES (1, 'Cheese', DEFAULT); INSERT INTO products DEFAULT VALUES; + + + + To do bulk loads, that is, inserting a lot of data, + take a look at the COPY command (see + &cite-reference;). It is not as flexible as the + INSERT command, but more efficient. + + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index afd8ee6883..8030497e77 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,5 +1,5 @@ @@ -18,7 +18,7 @@ PostgreSQL documentation PostgreSQL provides a large number of functions and operators for the built-in data types. Users can also define their own functions and operators, as described in the - Programmer's Guide. The + &cite-programmer;. The psql commands \df and \do can be used to show the list of all actually available functions and operators, respectively. @@ -31,7 +31,7 @@ PostgreSQL documentation and some explicitly marked functions, are not specified by the SQL standard. Some of this extended functionality is present in other - RDBMS products, and in many cases this + SQL implementations, and in many cases this functionality is compatible and consistent between various products. @@ -172,7 +172,12 @@ PostgreSQL documentation operators - + + The usual comparison operators are available, shown in . + + +
Comparison Operators @@ -240,21 +245,21 @@ PostgreSQL documentation In addition to the comparison operators, the special BETWEEN construct is available. - + a BETWEEN x AND y - + is equivalent to - + a >= x AND a <= y - + Similarly, - + a NOT BETWEEN x AND y - + is equivalent to - + a < x OR a > y - + There is no difference between the two respective forms apart from the CPU cycles required to rewrite the first one into the second one internally. @@ -262,15 +267,15 @@ PostgreSQL documentation To check whether a value is or is not null, use the constructs - + expression IS NULL expression IS NOT NULL - - or the equivalent, but less standard, constructs - + + or the equivalent, but nonstandard, constructs + expression ISNULL expression NOTNULL - + @@ -296,14 +301,14 @@ PostgreSQL documentation Boolean values can also be tested using the constructs - + expression IS TRUE expression IS NOT TRUE expression IS FALSE expression IS NOT FALSE expression IS UNKNOWN expression IS NOT UNKNOWN - + These are similar to IS NULL in that they will always return true or false, never a null value, even when the operand is null. A null input is treated as the logical value unknown. @@ -317,11 +322,15 @@ PostgreSQL documentation Mathematical operators are provided for many PostgreSQL types. For types without common mathematical conventions for all possible permutations - (e.g. date/time types) we + (e.g., date/time types) we describe the actual behavior in subsequent sections. -
+ + shows the available mathematical operators. + + +
Mathematical Operators @@ -337,119 +346,119 @@ PostgreSQL documentation + - Addition + addition 2 + 3 5 - - Subtraction + subtraction 2 - 3 -1 * - Multiplication + multiplication 2 * 3 6 / - Division (integer division truncates results) + division (integer division truncates results) 4 / 2 2 % - Modulo (remainder) + modulo (remainder) 5 % 4 1 ^ - Exponentiation + exponentiation 2.0 ^ 3.0 8 |/ - Square root + square root |/ 25.0 5 ||/ - Cube root + cube root ||/ 27.0 3 ! - Factorial + factorial 5 ! 120 !! - Factorial (prefix operator) + factorial (prefix operator) !! 5 120 @ - Absolute value + absolute value @ -5.0 5 & - Binary AND + binary AND 91 & 15 11 | - Binary OR + binary OR 32 | 3 35 # - Binary XOR + binary XOR 17 # 5 20 ~ - Binary NOT + binary NOT ~1 -2 << - Binary shift left + binary shift left 1 << 4 16 >> - Binary shift right + binary shift right 8 >> 2 2 @@ -460,9 +469,14 @@ PostgreSQL documentation The binary operators are also available for the bit - string types BIT and BIT VARYING. + string types BIT and BIT VARYING, as + shown in . + Bit string arguments to &, |, + and # must be of equal length. When bit + shifting, the original length of the string is preserved, as shown in the table. + -
+
Bit String Binary Operators @@ -502,13 +516,23 @@ PostgreSQL documentation
- Bit string arguments to &, |, - and # must be of equal length. When bit - shifting, the original length of the string is preserved, as shown - here. - + + shows the available + mathematical functions. In the table, dp + indicates double precision. The functions + exp, ln, + log, pow, + round (1 argument), sqrt, + and trunc (1 argument) are also available for + the type numeric in place of double + precision. Functions returning a numeric + result take numeric input arguments, unless otherwise + specified. Many of these functions are implemented on top of the + host system's C library; accuracy and behavior in boundary cases + could therefore vary depending on the host system. + - +
Mathematical Functions @@ -524,7 +548,7 @@ PostgreSQL documentation abs(x) - (same as x) + (same as x) absolute value abs(-17.4) 17.4 @@ -697,22 +721,14 @@ PostgreSQL documentation
- - In the table above, dp indicates double precision. - The functions exp, ln, - log, pow, - round (1 argument), sqrt, - and trunc (1 argument) are also available for - the type numeric in place of - double precision. - Functions returning a numeric result take - numeric input arguments, unless otherwise specified. - Many of these functions are implemented on top - of the host system's C library; accuracy and behavior in boundary cases - could therefore vary depending on the host system. - + + Finally, shows the + available trigonometric functions. All trigonometric functions + have arguments and return values of type double + precision. + - +
Trigonometric Functions @@ -769,11 +785,6 @@ PostgreSQL documentation
- - All trigonometric functions have arguments and return values of - type double precision. - - @@ -795,7 +806,7 @@ PostgreSQL documentation SQL defines some string functions with a special syntax where - certain keywords rather than commas are used to separate the + certain key words rather than commas are used to separate the arguments. Details are in . These functions are also implemented using the regular syntax for function invocation. (See .) @@ -820,20 +831,20 @@ PostgreSQL documentation string text - string concatenation + String concatenation character strings concatenation - 'Postgre' || 'SQL' + 'Post' || 'greSQL' PostgreSQL bit_length(string) integer - number of bits in string + Number of bits in string bit_length('jose') 32 @@ -842,7 +853,7 @@ PostgreSQL documentation char_length(string) or character_length(string) integer - number of characters in string + Number of characters in string character strings length @@ -869,13 +880,13 @@ PostgreSQL documentation names. convert('PostgreSQL' using iso_8859_1_to_utf_8) - 'PostgreSQL' in UNICODE (UTF-8) encoding + 'PostgreSQL' in Unicode (UTF-8) encoding lower(string) text - Convert string to lower case. + Convert string to lower case lower('TOM') tom @@ -883,7 +894,7 @@ PostgreSQL documentation octet_length(string) integer - number of bytes in string + Number of bytes in string octet_length('jose') 4 @@ -892,7 +903,7 @@ PostgreSQL documentation overlay(string placing string from integer for integer) text - insert substring + Insert substring overlay @@ -904,7 +915,7 @@ PostgreSQL documentation position(substring in string) integer - location of specified substring + Location of specified substring position('om' in 'Thomas') 3 @@ -913,7 +924,7 @@ PostgreSQL documentation substring(string from integer for integer) text - extract substring + Extract substring substring @@ -926,7 +937,7 @@ PostgreSQL documentation substring(string from pattern) text - extract substring matching POSIX regular expression + Extract substring matching POSIX regular expression substring @@ -939,7 +950,7 @@ PostgreSQL documentation substring(string from pattern for escape) text - extract substring matching SQL99 regular expression + Extract substring matching SQL regular expression substring @@ -956,9 +967,9 @@ PostgreSQL documentation text - Removes the longest string containing only the + Remove the longest string containing only the characters (a space by default) from the - beginning/end/both ends of the string. + beginning/end/both ends of the string trim(both 'x' from 'xTomxx') Tom @@ -967,7 +978,7 @@ PostgreSQL documentation upper(string) text - Convert string to upper case. + Convert string to upper case upper('tom') TOM @@ -977,8 +988,8 @@ PostgreSQL documentation Additional string manipulation functions are available and are - listed below. Some of them are used internally to implement the - SQL-standard string functions listed above. + listed in . Some of them are used internally to implement the + SQL-standard string functions listed in . @@ -998,7 +1009,7 @@ PostgreSQL documentation ascii(text) integer - Returns the ASCII code of the first character of the argument. + ASCII code of the first character of the argument. ascii('x') 120 @@ -1009,7 +1020,7 @@ PostgreSQL documentation Remove (trim) the longest string consisting only of characters in trim from the start and end of - string. + string btrim('xyxtrimyyx','xy')trim @@ -1018,7 +1029,7 @@ PostgreSQL documentation chr(integer) text - Returns the character with the given ASCII code. + Character with the given ASCII code chr(65) A @@ -1032,7 +1043,7 @@ PostgreSQL documentation text - Converts string using dest_encoding. + Convert string to dest_encoding. The original encoding is specified by src_encoding. If src_encoding is omitted, database @@ -1049,8 +1060,8 @@ PostgreSQL documentation bytea - Decodes binary data from string previously - encoded with encode(). Parameter type is same as in encode(). + Decode binary data from string previously + encoded with encode(). Parameter type is same as in encode(). decode('MTIzAAE=', 'base64')123\000\001 @@ -1063,8 +1074,8 @@ PostgreSQL documentation text - Encodes binary data to ASCII-only representation. Supported - types are: 'base64', 'hex', 'escape'. + Encode binary data to ASCII-only representation. Supported + types are: base64, hex, escape. encode('123\\000\\001', 'base64')MTIzAAE= @@ -1073,7 +1084,7 @@ PostgreSQL documentation initcap(text) text - Converts first letter of each word (whitespace separated) to upper case. + Convert first letter of each word (whitespace separated) to upper case initcap('hi thomas') Hi Thomas @@ -1082,7 +1093,7 @@ PostgreSQL documentation length(string)integer - length of string + Length of string character strings length @@ -1105,7 +1116,7 @@ PostgreSQL documentation text - Fills up the string to length + Fill up the string to length length by prepending the characters fill (a space by default). If the string is already longer than @@ -1120,7 +1131,7 @@ PostgreSQL documentation ltrim(string text, text text) text - Removes the longest string containing only characters from + Remove the longest string containing only characters from trim from the start of the string. ltrim('zzzytrim','xyz') @@ -1131,7 +1142,7 @@ PostgreSQL documentation pg_client_encoding() name - Returns current client encoding name. + Current client encoding name. pg_client_encoding() SQL_ASCII @@ -1141,7 +1152,7 @@ PostgreSQL documentation quote_ident(string text) text - Returns the given string suitably quoted to be used as an identifier + Return the given string suitably quoted to be used as an identifier in an SQL query string. Quotes are added only if necessary (i.e., if the string contains non-identifier characters or would be case-folded). @@ -1155,7 +1166,7 @@ PostgreSQL documentation quote_literal(string text) text - Returns the given string suitably quoted to be used as a literal + Return the given string suitably quoted to be used as a literal in an SQL query string. Embedded quotes and backslashes are properly doubled. @@ -1166,7 +1177,7 @@ PostgreSQL documentation repeat(text, integer) text - Repeat text a number of times. + Repeat text a number of times repeat('Pg', 4) PgPgPgPg @@ -1191,7 +1202,7 @@ PostgreSQL documentation text - Fills up the string to length + Fill up the string to length length by appending the characters fill (a space by default). If the string is already longer than @@ -1206,7 +1217,7 @@ PostgreSQL documentation text, trim text) text - Removes the longest string containing only characters from + Remove the longest string containing only characters from trim from the end of the string. rtrim('trimxxxx','x') @@ -1229,7 +1240,7 @@ PostgreSQL documentation strpos(string, substring) text - Locates specified substring. (same as + Locate specified substring (same as position(substring in string), but note the reversed argument order) @@ -1242,7 +1253,7 @@ PostgreSQL documentation substr(string, from , count) text - Extracts specified substring. (same as + Extract specified substring (same as substring(string from from for count)) substr('alphabet', 3, 2) @@ -1253,7 +1264,17 @@ PostgreSQL documentation to_ascii(text , encoding) text - Converts text from multibyte encoding to ASCII. + + + Convert text to ASCII from other encoding + + + The to_ascii function supports conversion from + LATIN1, LATIN2, and WIN1250 only. + + + + to_ascii('Karel') Karel @@ -1263,7 +1284,7 @@ PostgreSQL documentation or bigint) text Convert number to its equivalent hexadecimal - representation. + representation to_hex(9223372036854775807::bigint) 7fffffffffffffff @@ -1291,11 +1312,6 @@ PostgreSQL documentation
- - The to_ascii function supports conversion from - LATIN1, LATIN2, and WIN1250 only. - - Built-in Conversions @@ -2023,7 +2039,7 @@ PostgreSQL documentation SQL defines some string functions with a special syntax where - certain keywords rather than commas are used to separate the + certain key words rather than commas are used to separate the arguments. Details are in . Some functions are also implemented using the regular syntax for @@ -2050,20 +2066,20 @@ PostgreSQL documentation string bytea - string concatenation + String concatenation binary strings concatenation - '\\\\Postgre'::bytea || '\\047SQL\\000'::bytea - \\Postgre'SQL\000 + '\\\\Post'::bytea || '\\047greSQL\\000'::bytea + \\Post'greSQL\000 octet_length(string) integer - number of bytes in binary string + Number of bytes in binary string octet_length('jo\\000se'::bytea) 5 @@ -2071,7 +2087,7 @@ PostgreSQL documentation position(substring in string) integer - location of specified substring + Location of specified substring position('\\000om'::bytea in 'Th\\000omas'::bytea) 3 @@ -2080,7 +2096,7 @@ PostgreSQL documentation substring(string from integer for integer) bytea - extract substring + Extract substring substring @@ -2097,9 +2113,9 @@ PostgreSQL documentation bytea - Removes the longest string containing only the + Remove the longest string containing only the characters from the - beginning/end/both ends of the string. + beginning/end/both ends of the string trim('\\000'::bytea from '\\000Tom\\000'::bytea) Tom @@ -2109,9 +2125,11 @@ PostgreSQL documentation
- Additional binary string manipulation functions are available and are - listed below. Some of them are used internally to implement the - SQL-standard string functions listed above. + Additional binary string manipulation functions are available and + are listed in . Some + of them are used internally to implement the + SQL-standard string functions listed in . @@ -2145,7 +2163,7 @@ PostgreSQL documentation length(string)integer - length of binary string + Length of binary string binary strings length @@ -2167,8 +2185,8 @@ PostgreSQL documentation text - Encodes binary string to ASCII-only representation. Supported - types are: 'base64', 'hex', 'escape'. + Encode binary string to ASCII-only representation. Supported + types are: base64, hex, escape. encode('123\\000456'::bytea, 'escape')123\000456 @@ -2181,8 +2199,8 @@ PostgreSQL documentation bytea - Decodes binary string from string previously - encoded with encode(). Parameter type is same as in encode(). + Decode binary string from string previously + encoded with encode(). Parameter type is same as in encode(). decode('123\\000456', 'escape')123\000456 @@ -2225,10 +2243,10 @@ PostgreSQL documentation like - + string LIKE pattern ESCAPE escape-character string NOT LIKE pattern ESCAPE escape-character - + Every pattern defines a set of strings. @@ -2252,18 +2270,16 @@ PostgreSQL documentation of zero or more characters. - - - Some examples: - + + Some examples: + 'abc' LIKE 'abc' true 'abc' LIKE 'a%' true 'abc' LIKE '_b_' true 'abc' LIKE 'c' false - - - - + + + LIKE pattern matches always cover the entire string. To match a pattern anywhere within a string, the @@ -2334,10 +2350,10 @@ PostgreSQL documentation substring - + string SIMILAR TO pattern ESCAPE escape-character string NOT SIMILAR TO pattern ESCAPE escape-character - + The SIMILAR TO operator returns true or false @@ -2411,42 +2427,38 @@ PostgreSQL documentation be specified with ESCAPE. - - - Some examples: - + + Some examples: + 'abc' SIMILAR TO 'abc' true 'abc' SIMILAR TO 'a' false 'abc' SIMILAR TO '%(b|d)%' true 'abc' SIMILAR TO '(b|c)%' false - - - + + - The SUBSTRING function with three parameters, - SUBSTRING(string FROM + The SUBSTRING function with three parameters, + SUBSTRING(string FROM pattern FOR - escape), provides extraction of a substring - that matches a SQL99 regular expression pattern. As with SIMILAR TO, - the specified pattern must match to the entire data string, else the - function fails and returns NULL. To indicate the part of the pattern - that should be returned on success, SQL99 specifies that the pattern - must contain two occurrences of the escape character followed by - double quote ("). The text matching the portion of the - pattern between these markers is returned. + escape), provides + extraction of a substring that matches a SQL99 regular expression + pattern. As with SIMILAR TO, the specified pattern + must match to the entire data string, else the function fails and + returns null. To indicate the part of the pattern that should be + returned on success, SQL99 specifies that the pattern must + contain two occurrences of the escape character followed by + double quote ("). The text matching the portion of + the pattern between these markers is returned. - - - Some examples: - + + Some examples: + SUBSTRING('foobar' FROM '%#"o_b#"%' FOR '#') oob SUBSTRING('foobar' FROM '#"o_b#"%' FOR '#') NULL - - - - + + @@ -2457,7 +2469,12 @@ SUBSTRING('foobar' FROM '#"o_b#"%' FOR '#') NULLpattern matching -
+ + lists the available + operators for pattern matching using POSIX regular expressions. + + +
Regular Expression Match Operators @@ -2522,23 +2539,21 @@ SUBSTRING('foobar' FROM '#"o_b#"%' FOR '#') NULL - - - Some examples: - + + Some examples: + 'abc' ~ 'abc' true 'abc' ~ '^a' true 'abc' ~ '(b|d)' true 'abc' ~ '^(b|c)' false - - - + + - The SUBSTRING function with two parameters, - SUBSTRING(string FROM - pattern), provides extraction of a substring - that matches a POSIX regular expression pattern. It returns NULL if + The SUBSTRING function with two parameters, + SUBSTRING(string FROM + pattern), provides extraction of a substring + that matches a POSIX regular expression pattern. It returns null if there is no match, otherwise the portion of the text that matched the pattern. But if the pattern contains any parentheses, the portion of the text that matched the first parenthesized subexpression (the @@ -2548,15 +2563,13 @@ SUBSTRING('foobar' FROM '#"o_b#"%' FOR '#') NULL - - - Some examples: - + + Some examples: + SUBSTRING('foobar' FROM 'o.b') oob SUBSTRING('foobar' FROM 'o(.)b') o - - - + + @@ -2807,24 +2820,18 @@ SUBSTRING('foobar' FROM 'o(.)b') o formatting - - Author - - Written by Karel Zak (zakkr@zf.jcu.cz) on 2000-01-24 - - - The PostgreSQL formatting functions provide a powerful set of tools for converting various data types (date/time, integer, floating point, numeric) to formatted strings and for converting from formatted strings to specific data types. + lists them. These functions all follow a common calling convention: the first argument is the value to be formatted and the second argument is a template that defines the output or input format. -
+
Formatting Functions @@ -2851,7 +2858,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o to_char(int, text) text - convert int4/int8 to string + convert integer to string to_char(125, '999') @@ -2898,7 +2905,12 @@ SUBSTRING('foobar' FROM 'o(.)b') o values to be found there. -
+ + shows the + template patterns available for formatting date and time values. + + +
Template patterns for date/time conversions @@ -3078,11 +3090,11 @@ SUBSTRING('foobar' FROM 'o(.)b') o TZ - timezone name - upper case + time-zone name - upper case tz - timezone name - lower case + time-zone name - lower case @@ -3093,9 +3105,11 @@ SUBSTRING('foobar' FROM 'o(.)b') o behavior. For example, FMMonth is the Month pattern with the FM prefix. + shows the + modifier patterns for date/time formatting. -
+
Template pattern modifiers for date/time conversions @@ -3123,7 +3137,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o FX prefix - Fixed format global option (see below) + fixed format global option (see usage notes) FX Month DD Day @@ -3136,12 +3150,12 @@ SUBSTRING('foobar' FROM 'o(.)b') o
- Usage notes: + Usage notes for the date/time formatting: - FM suppresses leading zeroes or trailing blanks + FM suppresses leading zeroes and trailing blanks that would otherwise be added to make the output of a pattern be fixed-width. @@ -3175,8 +3189,8 @@ SUBSTRING('foobar' FROM 'o(.)b') o templates and will be output literally. You can put a substring in double quotes to force it to be interpreted as literal text even if it contains pattern keywords. For example, in - '"Hello Year: "YYYY', the YYYY - will be replaced by year data, but the single Y + '"Hello Year "YYYY', the YYYY + will be replaced by the year data, but the single Y in Year will not be. @@ -3229,7 +3243,12 @@ SUBSTRING('foobar' FROM 'o(.)b') o - + + shows the + template patterns available for formatting numeric values. + + +
Template patterns for numeric conversions @@ -3309,7 +3328,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o
- Usage notes: + Usage notes for the numeric formatting: @@ -3330,7 +3349,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o 9 specifies a value with the same number of digits as there are 9s. If a digit is - not available use blank space. + not available it outputs a space. @@ -3364,7 +3383,12 @@ SUBSTRING('foobar' FROM 'o(.)b') o - + + shows some + examples of the use of the to_char function. + + +
<function>to_char</function> Examples @@ -3516,21 +3540,19 @@ SUBSTRING('foobar' FROM 'o(.)b') o Date/Time Functions and Operators - - shows the available - functions for date/time value processing. - illustrates the - behaviors of the basic arithmetic - operators (+, *, etc.). - For formatting functions, refer to . You should be familiar with the - background information on date/time data types (see ). - - - - The date/time operators described below behave similarly for types - involving time zones as well as those without. + + shows the available + functions for date/time value processing, with details appearing in + the following subsections. illustrates the behaviors of + the basic arithmetic operators (+, + *, etc.). For formatting functions, refer to + . You should be familiar with + the background information on date/time data types (see ). The date/time operators described + below behave similarly for types involving time zones as well as + those without. +
Date/Time Operators @@ -3547,65 +3569,60 @@ SUBSTRING('foobar' FROM 'o(.)b') o + - timestamp '2001-09-28 01:00' + interval '23 hours' - timestamp '2001-09-29 00:00' + timestamp '2001-09-28 01:00' + interval '23 hours' + timestamp '2001-09-29 00:00' + - date '2001-09-28' + interval '1 hour' - timestamp '2001-09-28 01:00' + date '2001-09-28' + interval '1 hour' + timestamp '2001-09-28 01:00' + - time '01:00' + interval '3 hours' - time '04:00' + time '01:00' + interval '3 hours' + time '04:00' - - timestamp '2001-09-28 23:00' - interval '23 hours' - timestamp '2001-09-28' + timestamp '2001-09-28 23:00' - interval '23 hours' + timestamp '2001-09-28' - - date '2001-09-28' - interval '1 hour' - timestamp '2001-09-27 23:00' + date '2001-09-28' - interval '1 hour' + timestamp '2001-09-27 23:00' - - time '05:00' - interval '2 hours' - time '03:00' + time '05:00' - interval '2 hours' + time '03:00' - - interval '2 hours' - time '05:00' - time '03:00:00' + interval '2 hours' - time '05:00' + time '03:00:00' * - interval '1 hour' * int '3' - interval '03:00' + interval '1 hour' * int '3' + interval '03:00' / - interval '1 hour' / int '3' - interval '00:20' + interval '1 hour' / int '3' + interval '00:20'
- - - - The date/time functions are summarized below, with additional - details in subsequent sections. Date/Time Functions @@ -3640,7 +3657,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o current_date date - Today's date; see below + Today's date; see @@ -3649,7 +3666,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o current_time time with time zone - Time of day; see below + Time of day; see @@ -3658,7 +3675,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o current_timestamp timestamp with time zone - Date and time; see below + Date and time; see @@ -3689,8 +3706,8 @@ SUBSTRING('foobar' FROM 'o(.)b') o date_trunc(text, timestamp) timestamp - Truncate to specified precision; see also below + Truncate to specified precision; see also date_trunc('hour', timestamp '2001-02-16 20:38:40') 2001-02-16 20:00:00+00 @@ -3700,8 +3717,8 @@ SUBSTRING('foobar' FROM 'o(.)b') o extract(field from timestamp) double precision - Get subfield; see also below + Get subfield; see also extract(hour from timestamp '2001-02-16 20:38:40') 20 @@ -3711,8 +3728,8 @@ SUBSTRING('foobar' FROM 'o(.)b') o extract(field from interval) double precision - Get subfield; see also below + Get subfield; see also extract(month from interval '2 years 3 months') 3 @@ -3737,7 +3754,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o localtime time - Time of day; see below + Time of day; see @@ -3746,7 +3763,7 @@ SUBSTRING('foobar' FROM 'o(.)b') o localtimestamp timestamp - Date and time; see below + Date and time; see @@ -3756,8 +3773,8 @@ SUBSTRING('foobar' FROM 'o(.)b') o now() timestamp Current date and time (equivalent to - current_timestamp); see below + current_timestamp); see @@ -3766,8 +3783,8 @@ SUBSTRING('foobar' FROM 'o(.)b') o timeofday() text - Current date and time; see below + Current date and time; see timeofday() Wed Feb 21 17:01:13.000126 2001 EST @@ -3776,7 +3793,6 @@ SUBSTRING('foobar' FROM 'o(.)b') o
- <function>EXTRACT</function>, <function>date_part</function> @@ -3786,7 +3802,7 @@ EXTRACT (field FROM source - The extract function retrieves sub-fields + The extract function retrieves subfields from date/time values, such as year or hour. source is a value expression that evaluates to type timestamp or interval. @@ -3807,12 +3823,10 @@ EXTRACT (field FROM source The year field divided by 100 - SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 20 - Note that the result for the century field is simply the year field @@ -3829,12 +3843,10 @@ SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40'); The day (of the month) field (1 - 31) - SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 16 - @@ -3845,12 +3857,10 @@ SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40'); The year field divided by 10 - SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 200 - @@ -3862,12 +3872,10 @@ SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40'); timestamp values only) - SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 5 - @@ -3877,12 +3885,11 @@ SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40'); The day of the year (1 - 365/366) (for timestamp values only) - + SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 47 - @@ -3896,7 +3903,6 @@ SELECT EXTRACT(DOY FROM TIMESTAMP '2001-02-16 20:38:40'); of seconds in the interval - SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 982352320 @@ -3904,7 +3910,6 @@ SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40'); SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); Result: 442800 - @@ -3915,12 +3920,10 @@ SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); The hour field (0 - 23) - SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 20 - @@ -3932,12 +3935,10 @@ SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); 000 000. Note that this includes full seconds. - SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5'); Result: 28500000 - @@ -3948,12 +3949,10 @@ SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5'); The year field divided by 1000 - SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 2 - Note that the result for the millennium field is simply the year field @@ -3971,12 +3970,10 @@ SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40'); 1000. Note that this includes full seconds. - SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5'); Result: 28500 - @@ -3987,12 +3984,10 @@ SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5'); The minutes field (0 - 59) - SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 38 - @@ -4005,7 +4000,6 @@ SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40'); the number of months, modulo 12 (0 - 11) - SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 2 @@ -4016,7 +4010,6 @@ SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months'); SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months'); Result: 1 - @@ -4028,12 +4021,10 @@ SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months'); timestamp values only) - SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 1 - @@ -4046,7 +4037,6 @@ SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40'); implemented by the operating system) - SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40'); Result: 40 @@ -4054,7 +4044,6 @@ SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40'); SELECT EXTRACT(SECOND FROM TIME '17:12:28.5'); Result: 28.5 - + Indexes @@ -432,172 +432,6 @@ SELECT am.amname AS acc_method, - - Keys - - - - Author - - Written by Herouth Maoz (herouth@oumail.openu.ac.il). - This originally appeared on the User's Mailing List on 1998-03-02 - in response to the question: - "What is the difference between PRIMARY KEY and UNIQUE constraints?". - - - - - - -Subject: Re: [QUESTIONS] PRIMARY KEY | UNIQUE - - What's the difference between: - - PRIMARY KEY(fields,...) and - UNIQUE (fields,...) - - - Is this an alias? - - If PRIMARY KEY is already unique, then why - is there another kind of key named UNIQUE? - - - - - A primary key is the field(s) used to identify a specific row. For example, - Social Security numbers identifying a person. - - - - A simply UNIQUE combination of fields has nothing to do with identifying - the row. It's simply an integrity constraint. For example, I have - collections of links. Each collection is identified by a unique number, - which is the primary key. This key is used in relations. - - - - However, my application requires that each collection will also have a - unique name. Why? So that a human being who wants to modify a collection - will be able to identify it. It's much harder to know, if you have two - collections named Life Science, the one tagged 24433 is the one you - need, and the one tagged 29882 is not. - - - - So, the user selects the collection by its name. We therefore make sure, - within the database, that names are unique. However, no other table in the - database relates to the collections table by the collection Name. That - would be very inefficient. - - - - Moreover, despite being unique, the collection name does not actually - define the collection! For example, if somebody decided to change the name - of the collection from Life Science to Biology, it will still be the - same collection, only with a different name. As long as the name is unique, - that's OK. - - - - So: - - - - - Primary key: - - - - Is used for identifying the row and relating to it. - - - - - Is impossible (or hard) to update. - - - - - Should not allow null values. - - - - - - - - - Unique field(s): - - - - Are used as an alternative access to the row. - - - - - Are updatable, so long as they are kept unique. - - - - - Null values are acceptable. - - - - - - - - - - As for why no non-unique keys are defined explicitly in standard - SQL syntax? Well, you - must understand that indexes are implementation-dependent. - SQL does not - define the implementation, merely the relations between data in the - database. PostgreSQL does allow - non-unique indexes, but indexes - used to enforce SQL keys are always unique. - - - - Thus, you may query a table by any combination of its columns, despite the - fact that you don't have an index on these columns. The indexes are merely - an implementation aid that each RDBMS offers - you, in order to cause - commonly used queries to be done more efficiently. - Some RDBMS may give you - additional measures, such as keeping a key stored in main memory. They will - have a special command, for example - -CREATE MEMSTORE ON table COLUMNS cols - - (This is not an existing command, just an example.) - - - - In fact, when you create a primary key or a unique combination of fields, - nowhere in the SQL specification does it say - that an index is created, nor that - the retrieval of data by the key is going to be more efficient than a - sequential scan! - - - - So, if you want to use a combination of fields that is not unique as a - secondary key, you really don't have to specify anything - just start - retrieving by that combination! However, if you want to make the retrieval - efficient, you'll have to resort to the means your - RDBMS provider gives you - - be it an index, my imaginary MEMSTORE command, or an intelligent - RDBMS - that creates indexes without your knowledge based on the fact that you have - sent it many queries based on a specific combination of keys... (It learns - from experience). - - - - Partial Indexes @@ -876,8 +710,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) When indexes are not used, it can be useful for testing to force their use. There are run-time parameters that can turn off - various plan types (described in the Administrator's - Guide). For instance, turning off sequential scans + various plan types (described in the &cite-admin;). + For instance, turning off sequential scans (enable_seqscan) and nested-loop joins (enable_nestloop), which are the most basic plans, will force the system to use a different plan. If the system @@ -906,8 +740,8 @@ CREATE UNIQUE INDEX tests_success_constraint ON tests (subject, target) again, two possibilities. The total cost is computed from the per-row costs of each plan node times the selectivity estimate of the plan node. The costs of the plan nodes can be tuned with - run-time parameters (described in the Administrator's - Guide). An inaccurate selectivity estimate is due to + run-time parameters (described in the &cite-admin;). + An inaccurate selectivity estimate is due to insufficient statistics. It may be possible to help this by tuning the statistics-gathering parameters (see ALTER TABLE reference). diff --git a/doc/src/sgml/keywords.sgml b/doc/src/sgml/keywords.sgml index 4986e3089e..f897a39058 100644 --- a/doc/src/sgml/keywords.sgml +++ b/doc/src/sgml/keywords.sgml @@ -1,4 +1,4 @@ - + <acronym>SQL</acronym> Key Words @@ -232,13 +232,13 @@ ASSERTION - + non-reserved reserved reserved ASSIGNMENT - + non-reserved non-reserved @@ -262,7 +262,7 @@ AUTHORIZATION - non-reserved + reserved (can be function) reserved reserved @@ -296,6 +296,12 @@ non-reserved reserved + + BIGINT + non-reserved (cannot be function or type) + + + BINARY reserved (can be function) @@ -328,7 +334,7 @@ BOOLEAN - + non-reserved (cannot be function or type) reserved @@ -370,7 +376,7 @@ CALLED - + non-reserved non-reserved @@ -490,7 +496,7 @@ CLASS - + non-reserved reserved @@ -680,6 +686,12 @@ reserved reserved + + CONVERSION + non-reserved + + + CONVERT non-reserved (cannot be function or type) @@ -706,7 +718,7 @@ CREATE - non-reserved + reserved reserved reserved @@ -832,7 +844,7 @@ DEALLOCATE - + non-reserved reserved reserved @@ -880,7 +892,7 @@ DEFINER - + non-reserved non-reserved @@ -988,7 +1000,7 @@ DOMAIN - + non-reserved reserved reserved @@ -1126,7 +1138,7 @@ EXTERNAL - + non-reserved reserved reserved @@ -1252,7 +1264,7 @@ GET - + non-reserved reserved reserved @@ -1276,7 +1288,7 @@ GRANT - non-reserved + reserved reserved reserved @@ -1358,12 +1370,24 @@ reserved reserved + + IMMUTABLE + non-reserved + + + IMPLEMENTATION non-reserved + + IMPLICIT + non-reserved + + + IN reserved (can be function) @@ -1426,7 +1450,7 @@ INPUT - + non-reserved reserved reserved @@ -1462,13 +1486,13 @@ INT - + non-reserved (cannot be function or type) reserved reserved INTEGER - + non-reserved (cannot be function or type) reserved reserved @@ -1492,7 +1516,7 @@ INVOKER - + non-reserved non-reserved @@ -1642,13 +1666,13 @@ LOCALTIME - + reserved reserved LOCALTIMESTAMP - + reserved reserved @@ -2056,7 +2080,7 @@ OVERLAY - + non-reserved (cannot be function or type) non-reserved @@ -2156,6 +2180,12 @@ + + PLACING + reserved + + + PLI @@ -2194,7 +2224,7 @@ PREPARE - + non-reserved reserved reserved @@ -2236,7 +2266,7 @@ PUBLIC - reserved (can be function) + reserved reserved @@ -2254,10 +2284,16 @@ REAL - + non-reserved (cannot be function or type) reserved reserved + + RECHECK + non-reserved + + + RECURSIVE @@ -2416,7 +2452,7 @@ ROW - non-reserved + non-reserved (cannot be function or type) reserved @@ -2494,7 +2530,7 @@ SECURITY - + non-reserved non-reserved @@ -2578,13 +2614,13 @@ SIMILAR - + reserved (can be function) non-reserved SIMPLE - + non-reserved non-reserved @@ -2596,7 +2632,7 @@ SMALLINT - + non-reserved (cannot be function or type) reserved reserved @@ -2672,6 +2708,12 @@ reserved + + STABLE + non-reserved + + + START non-reserved @@ -2714,6 +2756,18 @@ + + STORAGE + non-reserved + + + + + STRICT + non-reserved + + + STRUCTURE @@ -2914,7 +2968,7 @@ TREAT - + non-reserved (cannot be function or type) reserved @@ -3046,7 +3100,7 @@ USAGE - + non-reserved reserved reserved @@ -3092,6 +3146,12 @@ + + VALIDATOR + non-reserved + + + VALUE @@ -3140,6 +3200,12 @@ reserved reserved + + VOLATILE + non-reserved + + + WHEN reserved @@ -3178,7 +3244,7 @@ WRITE - + non-reserved reserved reserved diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 5d27af7e8a..34e9877687 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -1,5 +1,5 @@ @@ -9,24 +9,23 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere concurrency - - - Multiversion Concurrency Control - (MVCC) - is an advanced technique for improving database performance in a - multiuser environment. - Vadim Mikheev (vadim@krs.ru) provided - the implementation for PostgreSQL. - - + + This chapter describes the behavior of the PostgreSQL database + system when two or more sessions try to access the same data at the + same time. The goals in that situation are to allow efficient + access for all sessions while maintaining strict data integrity. + Every developer of database applications should be familiar with + the topics covered in this chapter. + Introduction - Unlike most other database systems which use locks for concurrency control, + Unlike traditional database systems which use locks for concurrency control, PostgreSQL - maintains data consistency by using a multiversion model. + maintains data consistency by using a multiversion model + (Multiversion Concurrency Control, MVCC). This means that while querying a database each transaction sees a snapshot of data (a database version) as it was some @@ -56,7 +55,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere Transaction Isolation - The ANSI/ISO SQL + The SQL standard defines four levels of transaction isolation in terms of three phenomena that must be prevented between concurrent transactions. @@ -65,8 +64,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere - dirty reads - dirty reads + dirty read + dirty read @@ -77,8 +76,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere - non-repeatable reads - non-repeatable reads + nonrepeatable read + nonrepeatable read @@ -92,7 +91,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere phantom read - phantom reads + phantom read @@ -111,6 +110,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere The four transaction isolation levels and the corresponding behaviors are described in . + <acronym>SQL</acronym> Transaction Isolation Levels @@ -125,7 +125,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere Dirty Read - Non-Repeatable Read + Nonrepeatable Read Phantom Read @@ -195,15 +195,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere
- PostgreSQL offers the read committed and serializable isolation levels. - - + Read Committed Isolation Level @@ -229,7 +227,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.28 2002/09/21 18:32:53 petere - UPDATE, DELETE and SELECT + UPDATE, DELETE, and SELECT FOR UPDATE commands behave the same as SELECT in terms of searching for target rows: they will only find target rows that were committed as of the query start time. However, such a target @@ -287,9 +285,9 @@ COMMIT; be necessary to guarantee a more rigorously consistent view of the database than the Read Committed mode provides. - + - + Serializable Isolation Level @@ -316,13 +314,13 @@ COMMIT; committed.) This is different from Read Committed in that the SELECT sees a snapshot as of the start of the transaction, not as of the start - of the current query within the transaction. Successive + of the current query within the transaction. Thus, successive SELECTs within a single transaction always see the same data. - UPDATE, DELETE and SELECT + UPDATE, DELETE, and SELECT FOR UPDATE commands behave the same as SELECT in terms of searching for target rows: they will only find target rows that were committed as of the transaction start time. However, such a @@ -370,7 +368,8 @@ ERROR: Can't serialize access due to concurrent update a transaction performs several successive queries that must see identical views of the database. - + + Explicit Locking @@ -421,8 +420,7 @@ ERROR: Can't serialize access due to concurrent update To examine a list of the currently outstanding locks in a database server, use the pg_locks system view. For more information on monitoring the status of the lock - manager subsystem, refer to the Administrator's - Guide. + manager subsystem, refer to the &cite-admin;. @@ -647,14 +645,14 @@ ERROR: Can't serialize access due to concurrent update Use of explicit locking can cause deadlocks, wherein two (or more) transactions each hold locks that the other wants. - For example, if transaction 1 acquires exclusive lock on table A - and then tries to acquire exclusive lock on table B, while transaction - 2 has already exclusive-locked table B and now wants exclusive lock + For example, if transaction 1 acquires an exclusive lock on table A + and then tries to acquire an exclusive lock on table B, while transaction + 2 has already exclusive-locked table B and now wants an exclusive lock on table A, then neither one can proceed. PostgreSQL automatically detects deadlock situations and resolves them by aborting one of the transactions involved, allowing the other(s) to complete. (Exactly which transaction - will be aborted is difficult to predict, and should not be relied on.) + will be aborted is difficult to predict and should not be relied on.) @@ -678,7 +676,7 @@ ERROR: Can't serialize access due to concurrent update - Data consistency checks at the application level + Data Consistency Checks at the Application Level Because readers in PostgreSQL @@ -718,11 +716,10 @@ ERROR: Can't serialize access due to concurrent update - Before version 6.5 PostgreSQL - used read-locks and so the - above consideration is also the case - when upgrading to 6.5 (or higher) from previous - PostgreSQL versions. + Before version 6.5 PostgreSQL used + read locks, and so the above consideration is also the case when + upgrading from PostgreSQL versions + prior to 6.5. @@ -732,7 +729,7 @@ ERROR: Can't serialize access due to concurrent update example, a banking application might wish to check that the sum of all credits in one table equals the sum of debits in another table, when both tables are being actively updated. Comparing the results of two - successive SELECT SUM(...) commands will not work reliably under + successive SELECT SUM(...) commands will not work reliably under Read Committed mode, since the second query will likely include the results of transactions not counted by the first. Doing the two sums in a single serializable transaction will give an accurate picture of the @@ -758,7 +755,8 @@ ERROR: Can't serialize access due to concurrent update the table are still running --- but if the snapshot seen by the transaction predates obtaining the lock, it may predate some now-committed changes in the table. A serializable transaction's snapshot is actually - frozen at the start of its first query (SELECT/INSERT/UPDATE/DELETE), so + frozen at the start of its first query (SELECT, INSERT, + UPDATE, or DELETE), so it's possible to obtain explicit locks before the snapshot is frozen. @@ -781,47 +779,40 @@ ERROR: Can't serialize access due to concurrent update - GiST and R-Tree indexes + B-tree indexes - Share/exclusive index-level locks are used for read/write access. - Locks are released after statement is done. + Short-term share/exclusive page-level locks are used for + read/write access. Locks are released immediately after each + index tuple is fetched or inserted. B-tree indexes provide + the highest concurrency without deadlock conditions. - Hash indexes + GiST and R-tree indexes - Share/exclusive page-level locks are used for read/write access. - Locks are released after page is processed. - - - - Page-level locks provide better concurrency than index-level ones - but are subject to deadlocks. + Share/exclusive index-level locks are used for read/write access. + Locks are released after the statement (command) is done. - B-tree indexes + Hash indexes - Short-term share/exclusive page-level locks are used for - read/write access. Locks are released immediately after each index - tuple is fetched/inserted. - - - - B-tree indexes provide the highest concurrency without deadlock - conditions. + Share/exclusive page-level locks are used for read/write + access. Locks are released after the page is processed. + Page-level locks provide better concurrency than index-level + ones but are liable to deadlocks. diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml index 05727523f0..2b2d71fed1 100644 --- a/doc/src/sgml/perform.sgml +++ b/doc/src/sgml/perform.sgml @@ -1,5 +1,5 @@ @@ -32,30 +32,30 @@ $Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.21 2002/09/21 18:32:53 pet - Estimated start-up cost (time expended before output scan can start, - e.g., time to do the sorting in a SORT node). + Estimated start-up cost (Time expended before output scan can start, + e.g., time to do the sorting in a sort node.) - Estimated total cost (if all tuples are retrieved, which they may not - be --- a query with a LIMIT will stop short of paying the total cost, - for example). + Estimated total cost (If all rows are retrieved, which they may not + be --- a query with a LIMIT clause will stop short of paying the total cost, + for example.) - Estimated number of rows output by this plan node (again, only if - executed to completion). + Estimated number of rows output by this plan node (Again, only if + executed to completion.) Estimated average width (in bytes) of rows output by this plan - node. + node @@ -64,9 +64,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.21 2002/09/21 18:32:53 pet The costs are measured in units of disk page fetches. (CPU effort estimates are converted into disk-page units using some - fairly arbitrary fudge-factors. If you want to experiment with these + fairly arbitrary fudge factors. If you want to experiment with these factors, see the list of run-time configuration parameters in the - Administrator's Guide.) + &cite-admin;.) @@ -74,17 +74,17 @@ $Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.21 2002/09/21 18:32:53 pet the cost of all its child nodes. It's also important to realize that the cost only reflects things that the planner/optimizer cares about. In particular, the cost does not consider the time spent transmitting - result tuples to the frontend --- which could be a pretty dominant + result rows to the frontend --- which could be a pretty dominant factor in the true elapsed time, but the planner ignores it because it cannot change it by altering the plan. (Every correct plan will - output the same tuple set, we trust.) + output the same row set, we trust.) Rows output is a little tricky because it is not the number of rows processed/scanned by the query --- it is usually less, reflecting the - estimated selectivity of any WHERE-clause constraints that are being + estimated selectivity of any WHERE-clause constraints that are being applied at this node. Ideally the top-level rows estimate will approximate the number of rows actually returned, updated, or deleted by the query. @@ -92,44 +92,44 @@ $Header: /cvsroot/pgsql/doc/src/sgml/perform.sgml,v 1.21 2002/09/21 18:32:53 pet Here are some examples (using the regress test database after a - vacuum analyze, and 7.3 development sources): + VACUUM ANALYZE, and 7.3 development sources): - + regression=# EXPLAIN SELECT * FROM tenk1; QUERY PLAN ------------------------------------------------------------- Seq Scan on tenk1 (cost=0.00..333.00 rows=10000 width=148) - + This is about as straightforward as it gets. If you do - + SELECT * FROM pg_class WHERE relname = 'tenk1'; - + you will find out that tenk1 has 233 disk - pages and 10000 tuples. So the cost is estimated at 233 page - reads, defined as 1.0 apiece, plus 10000 * cpu_tuple_cost which is - currently 0.01 (try show cpu_tuple_cost). + pages and 10000 rows. So the cost is estimated at 233 page + reads, defined as costing 1.0 apiece, plus 10000 * cpu_tuple_cost which is + currently 0.01 (try SHOW cpu_tuple_cost). - Now let's modify the query to add a WHERE condition: + Now let's modify the query to add a WHERE condition: - + regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 1000; QUERY PLAN ------------------------------------------------------------ Seq Scan on tenk1 (cost=0.00..358.00 rows=1033 width=148) Filter: (unique1 < 1000) - + - The estimate of output rows has gone down because of the WHERE clause. + The estimate of output rows has gone down because of the WHERE clause. However, the scan will still have to visit all 10000 rows, so the cost hasn't decreased; in fact it has gone up a bit to reflect the extra CPU - time spent checking the WHERE condition. + time spent checking the WHERE condition. @@ -144,26 +144,26 @@ regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 1000; Modify the query to restrict the condition even more: - + regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 50; QUERY PLAN ------------------------------------------------------------------------------- Index Scan using tenk1_unique1 on tenk1 (cost=0.00..179.33 rows=49 width=148) Index Cond: (unique1 < 50) - + - and you will see that if we make the WHERE condition selective + and you will see that if we make the WHERE condition selective enough, the planner will eventually decide that an index scan is cheaper than a sequential scan. - This plan will only have to visit 50 tuples because of the index, + This plan will only have to visit 50 rows because of the index, so it wins despite the fact that each individual fetch is more expensive than reading a whole disk page sequentially. - Add another clause to the WHERE condition: + Add another clause to the WHERE condition: - + regression=# EXPLAIN SELECT * FROM tenk1 WHERE unique1 < 50 AND regression-# stringu1 = 'xxx'; QUERY PLAN @@ -171,11 +171,11 @@ regression-# stringu1 = 'xxx'; Index Scan using tenk1_unique1 on tenk1 (cost=0.00..179.45 rows=1 width=148) Index Cond: (unique1 < 50) Filter: (stringu1 = 'xxx'::name) - + The added clause stringu1 = 'xxx' reduces the output-rows estimate, but not the cost because we still have to visit the - same set of tuples. Notice that the stringu1 clause + same set of rows. Notice that the stringu1 clause cannot be applied as an index condition (since this index is only on the unique1 column). Instead it is applied as a filter on the rows retrieved by the index. Thus the cost has actually gone up @@ -185,7 +185,7 @@ regression-# stringu1 = 'xxx'; Let's try joining two tables, using the fields we have been discussing: - + regression=# EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 < 50 regression-# AND t1.unique2 = t2.unique2; QUERY PLAN @@ -197,30 +197,30 @@ regression-# AND t1.unique2 = t2.unique2; -> Index Scan using tenk2_unique2 on tenk2 t2 (cost=0.00..3.01 rows=1 width=148) Index Cond: ("outer".unique2 = t2.unique2) - + In this nested-loop join, the outer scan is the same index scan we had in the example before last, and so its cost and row count are the same - because we are applying the unique1 < 50 WHERE clause at that node. + because we are applying the unique1 < 50 WHERE clause at that node. The t1.unique2 = t2.unique2 clause is not relevant yet, so it doesn't - affect row count of the outer scan. For the inner scan, the unique2 value of the + affect row count of the outer scan. For the inner scan, the unique2 value of the current - outer-scan tuple is plugged into the inner index scan + outer-scan row is plugged into the inner index scan to produce an index condition like t2.unique2 = constant. So we get the - same inner-scan plan and costs that we'd get from, say, explain select - * from tenk2 where unique2 = 42. The costs of the loop node are then set + same inner-scan plan and costs that we'd get from, say, EXPLAIN SELECT + * FROM tenk2 WHERE unique2 = 42. The costs of the loop node are then set on the basis of the cost of the outer scan, plus one repetition of the - inner scan for each outer tuple (49 * 3.01, here), plus a little CPU + inner scan for each outer row (49 * 3.01, here), plus a little CPU time for join processing. In this example the loop's output row count is the same as the product of the two scans' row counts, but that's not true in general, because - in general you can have WHERE clauses that mention both relations and + in general you can have WHERE clauses that mention both relations and so can only be applied at the join point, not to either input scan. For example, if we added WHERE ... AND t1.hundred < t2.hundred, that would decrease the output row count of the join node, but not change @@ -233,9 +233,9 @@ regression-# AND t1.unique2 = t2.unique2; flags for each plan type. (This is a crude tool, but useful. See also .) - -regression=# set enable_nestloop = off; -SET VARIABLE + +regression=# SET enable_nestloop = off; +SET regression=# EXPLAIN SELECT * FROM tenk1 t1, tenk2 t2 WHERE t1.unique1 < 50 regression-# AND t1.unique2 = t2.unique2; QUERY PLAN @@ -247,25 +247,25 @@ regression-# AND t1.unique2 = t2.unique2; -> Index Scan using tenk1_unique1 on tenk1 t1 (cost=0.00..179.33 rows=49 width=148) Index Cond: (unique1 < 50) - + This plan proposes to extract the 50 interesting rows of tenk1 using ye same olde index scan, stash them into an in-memory hash table, and then do a sequential scan of tenk2, probing into the hash table - for possible matches of t1.unique2 = t2.unique2 at each tenk2 tuple. + for possible matches of t1.unique2 = t2.unique2 at each tenk2 row. The cost to read tenk1 and set up the hash table is entirely start-up - cost for the hash join, since we won't get any tuples out until we can + cost for the hash join, since we won't get any rows out until we can start reading tenk2. The total time estimate for the join also - includes a hefty charge for CPU time to probe the hash table - 10000 times. Note, however, that we are NOT charging 10000 times 179.33; + includes a hefty charge for the CPU time to probe the hash table + 10000 times. Note, however, that we are not charging 10000 times 179.33; the hash table setup is only done once in this plan type. It is possible to check on the accuracy of the planner's estimated costs - by using EXPLAIN ANALYZE. This command actually executes the query, + by using EXPLAIN ANALYZE. This command actually executes the query, and then displays the true run time accumulated within each plan node - along with the same estimated costs that a plain EXPLAIN shows. + along with the same estimated costs that a plain EXPLAIN shows. For example, we might get a result like this: @@ -296,7 +296,7 @@ regression-# WHERE t1.unique1 < 50 AND t1.unique2 = t2.unique2; In some query plans, it is possible for a subplan node to be executed more than once. For example, the inner index scan is executed once per outer - tuple in the above nested-loop plan. In such cases, the + row in the above nested-loop plan. In such cases, the loops value reports the total number of executions of the node, and the actual time and rows values shown are averages per-execution. This is done to make the numbers @@ -307,19 +307,19 @@ regression-# WHERE t1.unique1 < 50 AND t1.unique2 = t2.unique2; The Total runtime shown by EXPLAIN ANALYZE includes - executor start-up and shutdown time, as well as time spent processing - the result tuples. It does not include parsing, rewriting, or planning - time. For a SELECT query, the total run time will normally be just a + executor start-up and shut-down time, as well as time spent processing + the result rows. It does not include parsing, rewriting, or planning + time. For a SELECT query, the total run time will normally be just a little larger than the total time reported for the top-level plan node. - For INSERT, UPDATE, and DELETE queries, the total run time may be + For INSERT, UPDATE, and DELETE commands, the total run time may be considerably larger, because it includes the time spent processing the - result tuples. In these queries, the time for the top plan node - essentially is the time spent computing the new tuples and/or locating + result rows. In these commands, the time for the top plan node + essentially is the time spent computing the new rows and/or locating the old ones, but it doesn't include the time spent making the changes. - It is worth noting that EXPLAIN results should not be extrapolated + It is worth noting that EXPLAIN results should not be extrapolated to situations other than the one you are actually testing; for example, results on a toy-sized table can't be assumed to apply to large tables. The planner's cost estimates are not linear and so it may well choose @@ -333,7 +333,7 @@ regression-# WHERE t1.unique1 < 50 AND t1.unique2 = t2.unique2; - Statistics used by the Planner + Statistics Used by the Planner As we saw in the previous section, the query planner needs to estimate @@ -351,8 +351,8 @@ regression-# WHERE t1.unique1 < 50 AND t1.unique2 = t2.unique2; with queries similar to this one: -regression=# select relname, relkind, reltuples, relpages from pg_class -regression-# where relname like 'tenk1%'; +regression=# SELECT relname, relkind, reltuples, relpages FROM pg_class +regression-# WHERE relname LIKE 'tenk1%'; relname | relkind | reltuples | relpages ---------------+---------+-----------+---------- tenk1 | r | 10000 | 233 @@ -382,10 +382,10 @@ regression-# where relname like 'tenk1%'; Most queries retrieve only a fraction of the rows in a table, due - to having WHERE clauses that restrict the rows to be examined. + to having WHERE clauses that restrict the rows to be examined. The planner thus needs to make an estimate of the - selectivity of WHERE clauses, that is, the fraction of - rows that match each clause of the WHERE condition. The information + selectivity of WHERE clauses, that is, the fraction of + rows that match each clause of the WHERE condition. The information used for this task is stored in the pg_statistic system catalog. Entries in pg_statistic are updated by ANALYZE and VACUUM ANALYZE commands, @@ -406,7 +406,7 @@ regression-# where relname like 'tenk1%'; For example, we might do: -regression=# select attname, n_distinct, most_common_vals from pg_stats where tablename = 'road'; +regression=# SELECT attname, n_distinct, most_common_vals FROM pg_stats WHERE tablename = 'road'; attname | n_distinct | most_common_vals ---------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- name | -0.467008 | {"I- 580 Ramp","I- 880 Ramp","Sp Railroad ","I- 580 ","I- 680 Ramp","I- 80 Ramp","14th St ","5th St ","Mission Blvd","I- 880 "} @@ -414,12 +414,14 @@ regression=# select attname, n_distinct, most_common_vals from pg_stats where ta (2 rows) regression=# + - As of PostgreSQL 7.2 the following columns exist - in pg_stats: + + shows the columns that + exist in pg_stats. - +
<structname>pg_stats</structname> Columns @@ -435,7 +437,7 @@ regression=# tablename name - Name of table containing column + Name of the table containing the column @@ -447,13 +449,13 @@ regression=# null_frac real - Fraction of column's entries that are NULL + Fraction of column's entries that are null avg_width integer - Average width in bytes of column's entries + Average width in bytes of the column's entries @@ -462,7 +464,7 @@ regression=# If greater than zero, the estimated number of distinct values in the column. If less than zero, the negative of the number of distinct values divided by the number of rows. (The negated form - is used when ANALYZE believes that the number of distinct values + is used when ANALYZE believes that the number of distinct values is likely to increase as the table grows; the positive form is used when the column seems to have a fixed number of possible values.) For example, -1 indicates a unique column in which the number of @@ -481,7 +483,7 @@ regression=# most_common_freqs real[] A list of the frequencies of the most common values, - ie, number of occurrences of each divided by total number of rows. + i.e., number of occurrences of each divided by total number of rows. @@ -530,30 +532,32 @@ regression=# Controlling the Planner with Explicit <literal>JOIN</> Clauses - Beginning with PostgreSQL 7.1 it is possible - to control the query planner to some extent by using explicit JOIN + Beginning with PostgreSQL 7.1 it has been possible + to control the query planner to some extent by using the explicit JOIN syntax. To see why this matters, we first need some background. In a simple join query, such as - -SELECT * FROM a,b,c WHERE a.id = b.id AND b.ref = c.id; - - the planner is free to join the given tables in any order. For example, - it could generate a query plan that joins A to B, using the WHERE clause - a.id = b.id, and then joins C to this joined table, using the other - WHERE clause. Or it could join B to C and then join A to that result. - Or it could join A to C and then join them with B --- but that would - be inefficient, since the full Cartesian product of A and C would have - to be formed, there being no applicable WHERE clause to allow optimization - of the join. - (All joins in the PostgreSQL executor happen - between two input tables, so it's necessary to build up the result in one - or another of these fashions.) The important point is that these different - join possibilities give semantically equivalent results but may have hugely - different execution costs. Therefore, the planner will explore all of them - to try to find the most efficient query plan. + +SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id; + + the planner is free to join the given tables in any order. For + example, it could generate a query plan that joins A to B, using + the WHERE condition a.id = b.id, and then + joins C to this joined table, using the other WHERE + condition. Or it could join B to C and then join A to that result. + Or it could join A to C and then join them with B --- but that + would be inefficient, since the full Cartesian product of A and C + would have to be formed, there being no applicable condition in the + WHERE clause to allow optimization of the join. (All + joins in the PostgreSQL executor happen + between two input tables, so it's necessary to build up the result + in one or another of these fashions.) The important point is that + these different join possibilities give semantically equivalent + results but may have hugely different execution costs. Therefore, + the planner will explore all of them to try to find the most + efficient query plan. @@ -567,7 +571,7 @@ SELECT * FROM a,b,c WHERE a.id = b.id AND b.ref = c.id; search to a genetic probabilistic search through a limited number of possibilities. (The switch-over threshold is set by the GEQO_THRESHOLD run-time - parameter described in the Administrator's Guide.) + parameter described in the &cite-admin;.) The genetic search takes less time, but it won't necessarily find the best possible plan. @@ -575,9 +579,9 @@ SELECT * FROM a,b,c WHERE a.id = b.id AND b.ref = c.id; When the query involves outer joins, the planner has much less freedom than it does for plain (inner) joins. For example, consider - + SELECT * FROM a LEFT JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id); - + Although this query's restrictions are superficially similar to the previous example, the semantics are different because a row must be emitted for each row of A that has no matching row in the join of B and C. @@ -587,27 +591,27 @@ SELECT * FROM a LEFT JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id); - In PostgreSQL 7.1, the planner treats all - explicit JOIN syntaxes as constraining the join order, even though + The PostgreSQL query planner treats all + explicit JOIN syntaxes as constraining the join order, even though it is not logically necessary to make such a constraint for inner joins. Therefore, although all of these queries give the same result: - -SELECT * FROM a,b,c WHERE a.id = b.id AND b.ref = c.id; + +SELECT * FROM a, b, c WHERE a.id = b.id AND b.ref = c.id; SELECT * FROM a CROSS JOIN b CROSS JOIN c WHERE a.id = b.id AND b.ref = c.id; SELECT * FROM a JOIN (b JOIN c ON (b.ref = c.id)) ON (a.id = b.id); - - the second and third take less time to plan than the first. This effect + + but the second and third take less time to plan than the first. This effect is not worth worrying about for only three tables, but it can be a lifesaver with many tables. You do not need to constrain the join order completely in order to - cut search time, because it's OK to use JOIN operators in a plain - FROM list. For example, - + cut search time, because it's OK to use JOIN operators in a plain + FROM list. For example, + SELECT * FROM a CROSS JOIN b, c, d, e WHERE ...; - + forces the planner to join A to B before joining them to other tables, but doesn't constrain its choices otherwise. In this example, the number of possible join orders is reduced by a factor of 5. @@ -617,22 +621,22 @@ SELECT * FROM a CROSS JOIN b, c, d, e WHERE ...; If you have a mix of outer and inner joins in a complex query, you might not want to constrain the planner's search for a good ordering of inner joins inside an outer join. You can't do that directly in the - JOIN syntax, but you can get around the syntactic limitation by using + JOIN syntax, but you can get around the syntactic limitation by using subselects. For example, - + SELECT * FROM d LEFT JOIN (SELECT * FROM a, b, c WHERE ...) AS ss ON (...); - + Here, joining D must be the last step in the query plan, but the - planner is free to consider various join orders for A,B,C. + planner is free to consider various join orders for A, B, C. Constraining the planner's search in this way is a useful technique both for reducing planning time and for directing the planner to a good query plan. If the planner chooses a bad join order by default, - you can force it to choose a better order via JOIN syntax --- assuming + you can force it to choose a better order via JOIN syntax --- assuming that you know of a better order, that is. Experimentation is recommended. @@ -658,6 +662,10 @@ SELECT * FROM d LEFT JOIN If you allow each insertion to be committed separately, PostgreSQL is doing a lot of work for each record added. + An additional benefit of doing all insertions in one transaction + is that if the insertion of one record were to fail then the + insertion of all records inserted up to that point would be rolled + back, so you won't be stuck with partially loaded data. @@ -696,7 +704,7 @@ SELECT * FROM d LEFT JOIN - ANALYZE Afterwards + Run ANALYZE Afterwards It's a good idea to run ANALYZE or VACUUM diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml index 12f043b95f..94ff3d0d29 100644 --- a/doc/src/sgml/queries.sgml +++ b/doc/src/sgml/queries.sgml @@ -1,4 +1,4 @@ - + Queries @@ -668,7 +668,7 @@ SELECT select_list order in which the columns are listed does not matter. The purpose is to reduce each group of rows sharing common values into one group row that is representative of all rows in the group. - This is done to eliminate redundancy in the output and/or obtain + This is done to eliminate redundancy in the output and/or compute aggregates that apply to these groups. For instance: => SELECT * FROM test1; @@ -694,7 +694,12 @@ SELECT select_list In the second query, we could not have written SELECT * FROM test1 GROUP BY x, because there is no single value for the column y that could be associated with each - group. In general, if a table is grouped, columns that are not + group. The grouped-by columns can be referenced in the select list since + they have a known constant value per group. + + + + In general, if a table is grouped, columns that are not used in the grouping cannot be referenced except in aggregate expressions. An example with aggregate expressions is: @@ -712,11 +717,6 @@ SELECT select_list linkend="functions-aggregate">. - - The grouped-by columns can be referenced in the select list since - they have a known constant value per group. - - Grouping without aggregate expressions effectively calculates the @@ -740,7 +740,7 @@ SELECT product_id, p.name, (sum(s.units) * p.price) AS sales in the GROUP BY clause since they are referenced in the query select list. (Depending on how exactly the products table is set up, name and price may be fully dependent on the - product ID, so the additional groups could theoretically be + product ID, so the additional groupings could theoretically be unnecessary, but this is not implemented yet.) The column s.units does not have to be in the GROUP BY list since it is only used in an aggregate expression @@ -828,7 +828,7 @@ SELECT product_id, p.name, (sum(s.units) * (p.price - p.cost)) AS profit - Select List Items + Select-List Items The simplest kind of select list is * which diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml index be1a6e764f..e2dbd57c6e 100644 --- a/doc/src/sgml/syntax.sgml +++ b/doc/src/sgml/syntax.sgml @@ -1,5 +1,5 @@ @@ -121,7 +121,7 @@ INSERT INTO MY_TABLE VALUES (3, 'hi there'); characters of an identifier; longer names can be written in commands, but they will be truncated. By default, NAMEDATALEN is 64 so the maximum identifier length - is 63 (but at the time the system is built, + is 63 (but at the time PostgreSQL is built, NAMEDATALEN can be changed in src/include/postgres_ext.h). @@ -170,8 +170,9 @@ UPDATE "my_table" SET "a" = 5; Quoted identifiers can contain any character other than a double - quote itself. This allows constructing table or column names that - would otherwise not be possible, such as ones containing spaces or + quote itself. To include a double quote, write two double quotes. + This allows constructing table or column names that would + otherwise not be possible, such as ones containing spaces or ampersands. The length limitation still applies. @@ -272,7 +273,7 @@ SELECT 'foobar'; SELECT 'foo' 'bar'; is not valid syntax. (This slightly bizarre behavior is specified - by SQL9x; PostgreSQL is + by SQL; PostgreSQL is following the standard.) @@ -298,7 +299,7 @@ SELECT 'foo' 'bar'; Alternatively, bit-string constants can be specified in hexadecimal notation, using a leading X (upper or lower case), e.g., X'1FF'. This notation is equivalent to - a bit-string constant with four binary digits for each hex digit. + a bit-string constant with four binary digits for each hexadecimal digit. @@ -328,7 +329,7 @@ SELECT 'foo' 'bar'; decimal point, if one is used. At least one digit must follow the exponent marker (e), if one is present. There may not be any spaces or other characters embedded in the - constant. Notice that any leading plus or minus sign is not actually + constant. Note that any leading plus or minus sign is not actually considered part of the constant; it is an operator applied to the constant. @@ -650,13 +651,16 @@ CAST ( 'string' AS type ) - The precedence and associativity of the operators is hard-wired - into the parser. Most operators have the same precedence and are - left-associative. This may lead to non-intuitive behavior; for - example the Boolean operators < and > have a different - precedence than the Boolean operators <= and >=. Also, - you will sometimes need to add parentheses when using combinations - of binary and unary operators. For instance + shows the precedence and + associativity of the operators in PostgreSQL. Most operators have + the same precedence and are left-associative. The precedence and + associativity of the operators is hard-wired into the parser. + This may lead to non-intuitive behavior; for example the Boolean + operators < and > have a different + precedence than the Boolean operators <= and + >=. Also, you will sometimes need to add + parentheses when using combinations of binary and unary operators. + For instance SELECT 5 ! - 6; @@ -673,7 +677,7 @@ SELECT (5 !) - 6; This is the price one pays for extensibility. -
+
Operator Precedence (decreasing) @@ -825,7 +829,7 @@ SELECT (5 !) - 6; SELECT 3 OPERATOR(pg_catalog.+) 4; the OPERATOR construct is taken to have the default precedence - shown above for any other operator. This is true no matter + shown in for any other operator. This is true no matter which specific operator name appears inside OPERATOR(). @@ -901,9 +905,8 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; -( expression ) - Parentheses are used to group subexpressions and override precedence. + Another value expression in parentheses, useful to group subexpressions and override precedence. @@ -928,21 +931,30 @@ SELECT 3 OPERATOR(pg_catalog.+) 4; Column References - A column can be referenced in the form: + A column can be referenced in the form -correlation.columnname `['subscript`]' +correlation.columnname + or + +correlation.columnname[subscript] + + (Here, the brackets [ ] are meant to appear literally.) + + correlation is the name of a table (possibly qualified), or an alias for a table defined by means of a - FROM clause, or + FROM clause, or the key words NEW or OLD. - (NEW and OLD can only appear in rules, + (NEW and OLD can only appear in rewrite rules, while other correlation names can be used in any SQL statement.) The correlation name and separating dot may be omitted if the column name - is unique - across all the tables being used in the current query. If - column is of an array type, then the + is unique across all the tables being used in the current query. (See also .) + + + + If column is of an array type, then the optional subscript selects a specific element or elements in the array. If no subscript is provided, then the whole array is selected. (See for more about @@ -968,9 +980,9 @@ $number dept, as -CREATE FUNCTION dept (text) RETURNS dept - AS 'SELECT * FROM dept WHERE name = $1' - LANGUAGE SQL; +CREATE FUNCTION dept(text) RETURNS dept + AS 'SELECT * FROM dept WHERE name = $1' + LANGUAGE SQL; Here the $1 will be replaced by the first @@ -993,7 +1005,7 @@ CREATE FUNCTION dept (text) RETURNS dept keywords AND, OR, and NOT, or is a qualified operator name - OPERATOR(schema.operatorname) +OPERATOR(schema.operatorname) Which particular operators exist and whether they are unary or binary depends on what operators have been @@ -1042,12 +1054,12 @@ sqrt(2) output value, such as the sum or average of the inputs. The syntax of an aggregate expression is one of the following: - - aggregate_name (expression) - aggregate_name (ALL expression) - aggregate_name (DISTINCT expression) - aggregate_name ( * ) - + +aggregate_name (expression) +aggregate_name (ALL expression) +aggregate_name (DISTINCT expression) +aggregate_name ( * ) + where aggregate_name is a previously defined aggregate (possibly a qualified name), and @@ -1101,7 +1113,7 @@ sqrt(2) CAST ( expression AS type ) expression::type - The CAST syntax conforms to SQL92; the syntax with + The CAST syntax conforms to SQL; the syntax with :: is historical PostgreSQL usage. @@ -1123,8 +1135,8 @@ CAST ( expression AS type to the type that a value expression must produce (for example, when it is assigned to a table column); the system will automatically apply a type cast in such cases. However, automatic casting is only done for - cast functions that are marked OK to apply implicitly - in the system catalogs. Other cast functions must be invoked with + casts that are marked OK to apply implicitly + in the system catalogs. Other casts must be invoked with explicit casting syntax. This restriction is intended to prevent surprising conversions from being applied silently. @@ -1143,6 +1155,13 @@ CAST ( expression AS type double-quoted, because of syntactic conflicts. Therefore, the use of the function-like cast syntax leads to inconsistencies and should probably be avoided in new applications. + + (The function-like syntax is in fact just a function call. When + one of the two standard cast syntaxes is used to do a run-time + conversion, it will internally invoke a registered function to + perform the conversion. By convention, these conversion functions + have the same name as their output type, but this is not something + that a portable application should rely on.) @@ -1151,8 +1170,9 @@ CAST ( expression AS type A scalar subquery is an ordinary - SELECT in parentheses that returns exactly one - row with one column. The SELECT query is executed + SELECT query in parentheses that returns exactly one + row with one column. (See for information about writing queries.) + The SELECT query is executed and the single returned value is used in the surrounding value expression. It is an error to use a query that returns more than one row or more than one column as a scalar subquery. @@ -1168,7 +1188,7 @@ CAST ( expression AS type state: SELECT name, (SELECT max(pop) FROM cities WHERE cities.state = states.name) -FROM states; + FROM states; @@ -1202,25 +1222,26 @@ SELECT somefunc() OR true; As a consequence, it is unwise to use functions with side effects as part of complex expressions. It is particularly dangerous to - rely on side effects or evaluation order in WHERE and HAVING clauses, + rely on side effects or evaluation order in WHERE and HAVING clauses, since those clauses are extensively reprocessed as part of developing an execution plan. Boolean - expressions (AND/OR/NOT combinations) in those clauses may be reorganized + expressions (AND/OR/NOT combinations) in those clauses may be reorganized in any manner allowed by the laws of Boolean algebra. - When it is essential to force evaluation order, a CASE construct may - be used. For example, this is an untrustworthy way of trying to - avoid division by zero in a WHERE clause: + When it is essential to force evaluation order, a CASE + construct (see ) may be + used. For example, this is an untrustworthy way of trying to + avoid division by zero in a WHERE clause: SELECT ... WHERE x <> 0 AND y/x > 1.5; - but this is safe: + But this is safe: SELECT ... WHERE CASE WHEN x <> 0 THEN y/x > 1.5 ELSE false END; - A CASE construct used in this fashion will defeat optimization attempts, + A CASE construct used in this fashion will defeat optimization attempts, so it should only be done when necessary. diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml index e6ff564be9..e0a330daef 100644 --- a/doc/src/sgml/typeconv.sgml +++ b/doc/src/sgml/typeconv.sgml @@ -1,9 +1,6 @@ Type Conversion - - Introduction - SQL queries can, intentionally or not, require mixing of different data types in the same expression. @@ -29,10 +26,9 @@ operators. -The Programmer's Guide has more details on the exact algorithms used for +The &cite-programmer; has more details on the exact algorithms used for implicit type conversion and coercion. - Overview @@ -41,7 +37,7 @@ implicit type conversion and coercion. SQL is a strongly typed language. That is, every data item has an associated data type which determines its behavior and allowed usage. PostgreSQL has an extensible type system that is -much more general and flexible than other RDBMS implementations. +much more general and flexible than other SQL implementations. Hence, most type conversion behavior in PostgreSQL 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. @@ -142,13 +138,13 @@ conventions for the SQL standard native types such as -The PostgreSQL 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 these -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. +The system catalogs store information about which conversions, called +casts, between data types are valid, and how to +perform those conversions. Additional casts can be added by the user +with the CREATE CAST command. (This is usually +done in conjunction with defining new data types. The set of casts +between the built-in types has been carefully crafted and should not +be altered.) @@ -169,7 +165,7 @@ types. All type conversion rules are designed with several principles in mind: - + Implicit conversions should never have surprising or unpredictable outcomes. diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 2b5c05e2d1..da7ec20424 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,5 +1,5 @@ @@ -29,7 +29,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.33 2002/10/24 17:48:54 database, and how to query it. The middle part lists the available data types and functions for use in SQL data commands. The rest of the book treats several aspects that are important for - tuning a database for optimial performance. + tuning a database for optimal performance.