From 48d03278a27b9a148c3cf9c895ad1c6289ca1c29 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 18 Feb 2001 17:17:17 +0000 Subject: [PATCH] Enhance documentation of date/time functions. Add extract, current_date, current_time, current_timestamp. Add more examples. Remove age(), because it doesn't work like it is documented, and no one could explain it to me. --- doc/src/sgml/func.sgml | 695 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 609 insertions(+), 86 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 9f2b0c9fc6..196a2e5cce 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,4 +1,4 @@ - + Functions and Operators @@ -17,8 +17,8 @@ If you are concerned about portability then take note that most of the functions and operators described in this chapter, with the exception of the most trivial arithmetic and comparison operators - and some explicitly marked functions, are not specified by the SQL - standard. However, many other RDBMS packages provide a lot of the + and some explicitly marked functions, are not specified by the SQL + standard. However, many other RDBMS packages provide a lot of the same or similar functions, and some of the ones provided in Postgres have in fact been inspired by other implementations. @@ -37,7 +37,7 @@ NOT - SQL uses a three-valued boolean logic where NULL represents + SQL uses a three-valued Boolean logic where NULL represents unknown. Observe the following truth tables: @@ -179,9 +179,9 @@ Comparison operators are available for all data types where this makes sense. All comparison operators are binary operators that - return boolean values; expressions like 1 < 2 < - 3 are not valid (because there is no - < operator to compare a boolean with + return values of type boolean; expressions like + 1 < 2 < 3 are not valid (because there is + no < operator to compare a Boolean value with 3). @@ -685,7 +685,7 @@ - SQL defines some string functions with a special syntax where + SQL defines some string functions with a special syntax where certain keywords rather than commas are used to separate the arguments. Details are in . These functions are also implemented using the regular syntax for @@ -784,7 +784,7 @@ Additional string manipulation functions are available and are listed below. Some of them are used internally to implement the - SQL string functions listed above. + SQL string functions listed above. @@ -1049,7 +1049,7 @@ The keyword ILIKE can be used instead of LIKE to make the match case insensitive according - to the active locale. This is not in the SQL standard but is a + to the active locale. This is not in the SQL standard but is a Postgres extension. @@ -1066,7 +1066,7 @@ - POSIX Regular Expressions + <acronym>POSIX</acronym> Regular Expressions
Regular Expression Match Operators @@ -1106,7 +1106,7 @@
- POSIX regular expressions provide a more powerful means for + POSIX regular expressions provide a more powerful means for pattern matching than the LIKE function. Many Unix tools such as egrep, sed, or awk use a pattern @@ -1131,7 +1131,7 @@ - Regular expressions (REs), as defined in POSIX + Regular expressions (REs), as defined in POSIX 1003.2, come in two forms: modern REs (roughly those of egrep; 1003.2 calls these extended REs) and obsolete REs (roughly those of @@ -1379,7 +1379,7 @@ The Postgres 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 datetypes. + and for converting from formatted strings to specific data types. 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 format. @@ -1713,7 +1713,7 @@ A double quote (") between quotation marks is skipped and is not parsed. If you want to - have a double quote in the output you must preceed it with a + have a double quote in the output you must precede it with a double backslash, for example '\\"YYYY Month\\"'. @@ -1829,7 +1829,7 @@ but to_char(-12, 'MI9999') produces '- 12'. The Oracle implementation does not allow the use of MI ahead of 9, but rather - requires that 9 preceed + requires that 9 precede MI. @@ -2027,125 +2027,648 @@ Date/Time Functions - The date/time functions provide a powerful set of tools - for manipulating various date/time types. + shows the available + functions for date/time value processing. The basic arithmetic + operators (+, *, etc.) are + also available. For formatting functions, refer to . You should be familiar with the + background information on date/time data types (see ). - - +
Date/Time Functions - Function - Returns + Name + Return Type Description Example + Result + - - abstime(timestamp) - abstime - convert to abstime - abstime(timestamp 'now') - + age(timestamp) interval - preserve months and years + Subtract argument from current date, preserve years and months and days age(timestamp '1957-06-13') + 43 years 8 mons 3 days + - age(timestamp,timestamp) + age(timestamp, timestamp) interval preserve months and years age('now', timestamp '1957-06-13') + +]]> + - date_part(text,timestamp) + current_date + date + + returns current date; see also below + + + + + + + current_time + time + + returns current time (of day); see also below + + + + + + + current_timestamp + timestamp + + returns current date and time; see also below + + + + + + + date_part(text, timestamp) double precision - portion of date - date_part('dow',timestamp 'now') + + extract subfield from date/time value (equivalent to + extract); see also below + + date_part('hour', timestamp '2001-02-16 20:38:40') + 20 + - date_part(text,interval) + date_part(text, interval) double precision - portion of time - date_part('hour',interval '4 hrs 3 mins') + + extract subfield from interval value (equivalent to + extract); see also below + + date_part('month', interval '2 years 3 months') + 3 + - date_trunc(text,timestamp) + date_trunc(text, timestamp) timestamp - truncate date - date_trunc('month',abstime 'now') + + truncate date to specified precision; see also below + + date_trunc('hour', timestamp '2001-02-16 20:38:40') + 2001-02-16 20:00:00+00 + - interval(reltime) - interval - convert to interval - interval(reltime '4 hours') + extract(identifier from timestamp) + double precision + + extract subfield from date/time value; see also below + + extract(hour from timestamp '2001-02-16 20:38:40') + 20 + + + extract(identifier from interval) + double precision + + extract subfield from interval value; see also below + + extract(month from interval '2 years 3 months') + 3 + + isfinite(timestamp) - bool - a finite time? - isfinite(timestamp 'now') + boolean + Returns true if the time stamp is finite (neither invalid nor infinity) + isfinite(timestamp '2001-02-16 21:28:30') + true + isfinite(interval) - bool - a finite time? - isfinite(interval '4 hrs') + boolean + Returns true if the interval is finite in length + isfinite(interval '4 hours') + true + - reltime(interval) - reltime - convert to reltime - reltime(interval '4 hrs') + now() + timestamp + + returns current date and time (equivalent to + current_timestamp); see also below + + + + timestamp(date) timestamp - convert to timestamp - timestamp(date 'today') + convert date to timestamp + timestamp(date '2000-12-25') + 2000-12-25 00:00:00 + - timestamp(date,time) + timestamp(date, time) timestamp - convert to timestamp - timestamp(timestamp '1998-02-24',time '23:07'); - - - to_char(timestamp,text) - text - convert to string - to_char(timestamp '1998-02-24','DD'); + combine date and time into a timestamp + timestamp(date '1998-02-24',time '23:07') + 1998-02-24 23:07:00
+ + + + <function>EXTRACT</function>, <function>date_part</function> + + +EXTRACT (field FROM source) + + + + The extract function retrieves sub-fields + from date/time values, such as year or hour. + source is a value expression that + evaluates to type timestamp or interval. + (Expressions of type date or time will + be cast to timestamp and can therefore be used as + well.) field is an identifier (not a + string!) that selects what field to extract from the source value. + The extract function returns values of type + double precision. + The following are valid values: + + + + + century + + + The year field divided by 100 + + + + +SELECT EXTRACT(CENTURY FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 20 + + + + + Note that this is not really the century that the date is in. + + + + + + day + + + The day (of the month) field (1 - 31) + + + + +SELECT EXTRACT(DAY FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 16 + + + + + + + decade + + + The year field divided by 10 + + + + +SELECT EXTRACT(DECADE FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 200 + + + + + + + dow + + + The day of the week (0 - 6; Sunday is 0) (for + timestamp values only) + + + + +SELECT EXTRACT(DOW FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 5 + + + + + + + doy + + + 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 + + + + + + + epoch + + + For date and timestamp values, the + number of seconds since 1970-01-01 00:00:00 (Result may be + negative.); for interval values, the total number + of seconds in the interval + + + + +SELECT EXTRACT(EPOCH FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 982352320 + +SELECT EXTRACT(EPOCH FROM INTERVAL '5 days 3 hours'); +Result: 442800 + + + + + + + hour + + + The hour field (0 - 23) + + + + +SELECT EXTRACT(HOUR FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 20 + + + + + + + microseconds + + + The seconds field, including fractional parts, multiplied by 1 + 000 000. Note that this includes full seconds. + + + + +SELECT EXTRACT(MICROSECONDS FROM TIME '17:12:28.5'); +Result: 28500000 + + + + + + + millennium + + + The year field divided by 1000 + + + + +SELECT EXTRACT(MILLENNIUM FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 2 + + + + + Note that this is not really the millennium that the date is in. + + + + + + milliseconds + + + The seconds field, including fractional parts, multiplied by + 1000. Note that this includes full seconds. + + + + +SELECT EXTRACT(MILLISECONDS FROM TIME '17:12:28.5'); +Result: 28500 + + + + + + + minute + + + The minutes field (0 - 59) + + + + +SELECT EXTRACT(MINUTE FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 38 + + + + + + + month + + + For timestamp values, the number of the month + within the year (1 - 12) ; for interval values + the number of months, modulo 12 (0 - 11) + + + + +SELECT EXTRACT(MONTH FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 2 + +SELECT EXTRACT(MONTH FROM INTERVAL '2 years 3 months'); +Result: 3 + +SELECT EXTRACT(MONTH FROM INTERVAL '2 years 13 months'); +Result: 1 + + + + + + + quarter + + + The quarter of the year (1 - 4) that the day is in (for + timestamp values only) + + + + +SELECT EXTRACT(QUARTER FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 1 + + + + + + + second + + + The seconds field, including fractional parts (0 - + 5960 if leap seconds are + implemented by the operating system) + + + + +SELECT EXTRACT(SECOND FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 40 + +SELECT EXTRACT(SECOND FROM TIME '17:12:28.5'); +Result: 28.5 + + + + + + + week + + + From a timestamp value, calculate the number of + the week of the year that the day is in. By definition + (ISO 8601), the first week of a year + contains January 4 of that year. (The ISO + week starts on Monday.) In other words, the first Thursday of + a year is in week 1 of that year. + + + + +SELECT EXTRACT(WEEK FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 7 + + + + + + + year + + + The year field + + + + +SELECT EXTRACT(YEAR FROM TIMESTAMP '2001-02-16 20:38:40'); +Result: 2001 + + + + + + + + + - For the - date_part and date_trunc - functions, arguments can be - `year', `month', - `day', `hour', - `minute', and `second', - as well as the more specialized quantities - `decade', `century', - `millennium', `millisecond', - and `microsecond'. - date_part allows `dow' - to return day of week, 'week' to return the - ISO-defined week of year, and `epoch' to return - seconds since 1970 (for timestamp) - or 'epoch' to return total elapsed seconds - (for interval). + The extract function is primarily intended + for computational processing. For formatting date/time values for + display, see . - + + + + The date_part function is the traditional + Postgres equivalent to the + SQL-function extract: + +date_part('field', source) + + Note that here the field value needs to + be a string. The valid field values for + date_part are the same as for + extract. + + + + +SELECT date_part('day', TIMESTAMP '2001-02-16 20:38:40'); +Result: 16 + +SELECT date_part('hour', INTERVAL '4 hours 3 minutes') +Result: 4 + + + + + + + <function>date_trunc</function> + + + The function date_trunc is conceptually + similar to the trunc function for numbers. + + + + +date_trunc('field', source) + + source is a value expression of type + timestamp (values of type date and + time are cast automatically). + field selects to which precision to + truncate the time stamp value. The return value is of type + timestamp with all fields that are less than the + selected one set to zero (or one, for day and month). + + + + Valid values for field are: + + microseconds + milliseconds + second + minute + hour + day + month + year + decade + century + millennium + + + + + + +SELECT date_trunc('hour', TIMESTAMP '2001-02-16 20:38:40'); +Result: 2001-02-16 20:00:00+00 + +SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40'); +Result: 2001-01-01 00:00:00+00 + + + + + + + Current Date/Time + + + The following functions are available to select the current date and/or time: + +CURRENT_TIME +CURRENT_DATE +CURRENT_TIMESTAMP + + Note that because of the requirements of the + SQL standard, these functions must not be + called with trailing parentheses. + + + + +SELECT CURRENT_TIME; +19:07:13 + +SELECT CURRENT_DATE; +2001-02-17 + +SELECT CURRENT_TIMESTAMP; +2001-02-17 19:07:32+00 + + + + + The function now() is the traditional + Postgres equivalent to + CURRENT_TIMESTAMP. + Postgres furthermore has special + date/time constants that can be used to specify the + current time. The following three all return the same result: + +SELECT CURRENT_TIMESTAMP; +SELECT now(); +SELECT TIMESTAMP 'now'; + + + + You do not want to use the third form when specifying a DEFAULT + value when creating a table. The system will immediately + evaluate the constant, thus when the default value is needed, + the time of the table creation would be used! The first two + forms will not be evaluated until the default value is used, + because they are function calls. + + + + + @@ -2335,13 +2858,13 @@ isclosed(path) - bool + boolean a closed path? isclosed(path '((0,0),(1,1),(2,0))') isopen(path) - bool + boolean an open path? isopen(path '[(0,0),(1,1),(2,0)]') @@ -2704,7 +3227,7 @@ Not defined by this name. Implements the intersection operator '#' Conditional Expressions - This section descibes the SQL-compliant conditional expressions + This section describes the SQL-compliant conditional expressions available in Postgres. @@ -2728,9 +3251,9 @@ END The SQL CASE expression is a generic conditional expression, similar to if/else statements in - other languages. CASE clauses can be used whereever + other languages. CASE clauses can be used wherever an expression is valid. condition is an - expression that returns a boolean result. If the result is true + expression that returns a boolean result. If the result is true then the value of the CASE expression is result. If the result is false any subsequent WHEN clauses are searched in the same -- GitLab