[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section describes the functions that can be used to manipulate temporal values. See 11.2 Date and Time Types for a description of the range of values each date and time type has and the valid formats in which values may be specified.
Here is an example that uses date functions. The following query selects
all records with a date_col
value from within the last 30 days:
mysql> SELECT something FROM tbl_name WHERE TO_DAYS(NOW()) - TO_DAYS(date_col) <= 30; |
(Note that the query will also select records with dates that lie in the future.)
Functions that expect date values usually will accept datetime values and ignore the time part. Functions that expect time values usually will accept datetime values and ignore the date part.
Functions that return the current date or time each are evaluated only once
per query at the start of query execution. This means that multiple references
to a function such as NOW()
within a single query will always produce
the same result. This principle also applies to CURDATE()
,
CURTIME()
, UTC_DATE()
, UTC_TIME()
, UTC_TIMESTAMP()
,
and any of their synonyms.
The return value ranges in the following function descriptions apply for
complete dates. If a date is a "zero" value or an incomplete date such
as '2001-11-00'
, functions that extract a part of a date may return
0
. For example, DAYOFMONTH('2001-11-00')
returns 0
.
ADDDATE(date,INTERVAL expr type)
ADDDATE(expr,days)
When invoked with the INTERVAL
form of the second argument,
ADDDATE()
is a synonym for DATE_ADD()
. The related
function SUBDATE()
is a synonym for DATE_SUB()
.
mysql> SELECT DATE_ADD('1998-01-02', INTERVAL 31 DAY); -> '1998-02-02' mysql> SELECT ADDDATE('1998-01-02', INTERVAL 31 DAY); -> '1998-02-02' |
As of MySQL 4.1.1, the second syntax is allowed, where expr
is a date
or datetime expression and days
is the number of days to be added to
expr
.
mysql> SELECT ADDDATE('1998-01-02', 31); -> '1998-02-02' |
ADDTIME(expr,expr2)
ADDTIME()
adds expr2
to expr
and returns the result.
expr
is a date or datetime expression, and expr2
is a time
expression.
mysql> SELECT ADDTIME("1997-12-31 23:59:59.999999", "1 1:1:1.000002"); -> '1998-01-02 01:01:01.000001' mysql> SELECT ADDTIME("01:00:00.999999", "02:00:00.999998"); -> '03:00:01.999997' |
ADDTIME()
was added in MySQL 4.1.1.
CURDATE()
Returns the current date as a value in 'YYYY-MM-DD'
or YYYYMMDD
format, depending on whether the function is used in a string or numeric
context:
mysql> SELECT CURDATE(); -> '1997-12-15' mysql> SELECT CURDATE() + 0; -> 19971215 |
CURRENT_DATE
CURRENT_DATE()
CURRENT_DATE
and CURRENT_DATE()
are synonyms for
CURDATE()
.
CURTIME()
Returns the current time as a value in 'HH:MM:SS'
or HHMMSS
format, depending on whether the function is used in a string or numeric
context:
mysql> SELECT CURTIME(); -> '23:50:26' mysql> SELECT CURTIME() + 0; -> 235026 |
CURRENT_TIME
CURRENT_TIME()
CURRENT_TIME
and CURRENT_TIME()
are synonyms for
CURTIME()
.
CURRENT_TIMESTAMP
CURRENT_TIMESTAMP()
CURRENT_TIMESTAMP
and CURRENT_TIMESTAMP()
are synonyms for
NOW()
.
DATE(expr)
Extracts the date part of the date or datetime expression expr
.
mysql> SELECT DATE('2003-12-31 01:02:03'); -> '2003-12-31' |
DATE()
is available as of MySQL 4.1.1.
DATEDIFF(expr,expr2)
DATEDIFF()
returns the number of days between the start date
expr
and the end date expr2
.
expr
and expr2
are date or date-and-time expressions.
Only the date parts of the values are used in the calculation.
mysql> SELECT DATEDIFF('1997-12-31 23:59:59','1997-12-30'); -> 1 mysql> SELECT DATEDIFF('1997-11-31 23:59:59','1997-12-31'); -> -30 |
DATEDIFF()
was added in MySQL 4.1.1.
DATE_ADD(date,INTERVAL expr type)
DATE_SUB(date,INTERVAL expr type)
These functions perform date arithmetic.
As of MySQL Version 3.23, INTERVAL expr type
is allowed on either
side of the +
operator if the expression on the other side is a
date or datetime value.
For the -
operator, INTERVAL expr type
is allowed only on
the right side, because
it makes no sense to subtract a date or datetime value from an interval.
(See examples below.)
date
is a DATETIME
or DATE
value specifying the starting
date. expr
is an expression specifying the interval value to be added
or subtracted from the starting date. expr
is a string; it may start
with a `-' for negative intervals. type
is a keyword indicating
how the expression should be interpreted.
The following table shows how the type
and expr
arguments
are related:
type Value | Expected expr Format |
MICROSECOND | MICROSECONDS |
SECOND | SECONDS |
MINUTE | MINUTES |
HOUR | HOURS |
DAY | DAYS |
WEEK | WEEKS |
MONTH | MONTHS |
QUARTER | QUARTERS |
YEAR | YEARS |
SECOND_MICROSECOND | 'SECONDS.MICROSECONDS' |
MINUTE_MICROSECOND | 'MINUTES.MICROSECONDS' |
MINUTE_SECOND | 'MINUTES:SECONDS' |
HOUR_MICROSECOND | 'HOURS.MICROSECONDS' |
HOUR_SECOND | 'HOURS:MINUTES:SECONDS' |
HOUR_MINUTE | 'HOURS:MINUTES' |
DAY_MICROSECOND | 'DAYS.MICROSECONDS' |
DAY_SECOND | 'DAYS HOURS:MINUTES:SECONDS' |
DAY_MINUTE | 'DAYS HOURS:MINUTES' |
DAY_HOUR | 'DAYS HOURS' |
YEAR_MONTH | 'YEARS-MONTHS' |
The type
values DAY_MICROSECOND
, HOUR_MICROSECOND
,
MINUTE_MICROSECOND
, SECOND_MICROSECOND
,
and MICROSECOND
are allowed as of MySQL 4.1.1.
The values QUARTER
and WEEK
are allowed as of MySQL 5.0.0.
MySQL allows any punctuation delimiter in the expr
format.
Those shown in the table are the suggested delimiters. If the date
argument is a DATE
value and your calculations involve only
YEAR
, MONTH
, and DAY
parts (that is, no time parts), the
result is a DATE
value. Otherwise, the result is a DATETIME
value:
mysql> SELECT '1997-12-31 23:59:59' + INTERVAL 1 SECOND; -> '1998-01-01 00:00:00' mysql> SELECT INTERVAL 1 DAY + '1997-12-31'; -> '1998-01-01' mysql> SELECT '1998-01-01' - INTERVAL 1 SECOND; -> '1997-12-31 23:59:59' mysql> SELECT DATE_ADD('1997-12-31 23:59:59', -> INTERVAL 1 SECOND); -> '1998-01-01 00:00:00' mysql> SELECT DATE_ADD('1997-12-31 23:59:59', -> INTERVAL 1 DAY); -> '1998-01-01 23:59:59' mysql> SELECT DATE_ADD('1997-12-31 23:59:59', -> INTERVAL '1:1' MINUTE_SECOND); -> '1998-01-01 00:01:00' mysql> SELECT DATE_SUB('1998-01-01 00:00:00', -> INTERVAL '1 1:1:1' DAY_SECOND); -> '1997-12-30 22:58:59' mysql> SELECT DATE_ADD('1998-01-01 00:00:00', -> INTERVAL '-1 10' DAY_HOUR); -> '1997-12-30 14:00:00' mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY); -> '1997-12-02' mysql> SELECT DATE_ADD('1992-12-31 23:59:59.000002', -> INTERVAL '1.999999' SECOND_MICROSECOND); -> '1993-01-01 00:00:01.000001' |
If you specify an interval value that is too short (does not include all the
interval parts that would be expected from the type
keyword),
MySQL assumes you have left out the leftmost parts of the interval
value. For example, if you specify a type
of DAY_SECOND
, the
value of expr
is expected to have days, hours, minutes, and seconds
parts. If you specify a value like '1:10'
, MySQL assumes
that the days and hours parts are missing and the value represents minutes
and seconds. In other words, '1:10' DAY_SECOND
is interpreted in such
a way that it is equivalent to '1:10' MINUTE_SECOND
. This is
analogous to the way that MySQL interprets TIME
values
as representing elapsed time rather than as time of day.
Note that if you add to or subtract from a date value something that contains a time part, the result is automatically converted to a datetime value:
mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 1 DAY); -> '1999-01-02' mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 1 HOUR); -> '1999-01-01 01:00:00' |
If you use really malformed dates, the result is NULL
. If you add
MONTH
, YEAR_MONTH
, or YEAR
and the resulting date
has a day that is larger than the maximum day for the new month, the day is
adjusted to the maximum days in the new month:
mysql> SELECT DATE_ADD('1998-01-30', interval 1 month); -> '1998-02-28' |
Note from the preceding example that the keyword INTERVAL
and the
type
specifier are not case sensitive.
DATE_FORMAT(date,format)
date
value according to the format
string. The
following specifiers may be used in the format
string:
Specifier | Description |
%a | Abbreviated weekday name (Sun ..Sat ) |
%b | Abbreviated month name (Jan ..Dec ) |
%c | Month, numeric (0 ..12 ) |
%D | Day of the month with English suffix (0th , 1st , 2nd , 3rd , etc.) |
%d | Day of the month, numeric (00 ..31 ) |
%e | Day of the month, numeric (0 ..31 ) |
%f | Microseconds (000000 ..999999 ) |
%H | Hour (00 ..23 ) |
%h | Hour (01 ..12 ) |
%I | Hour (01 ..12 ) |
%i | Minutes, numeric (00 ..59 ) |
%j | Day of year (001 ..366 ) |
%k | Hour (0 ..23 ) |
%l | Hour (1 ..12 ) |
%M | Month name (January ..December ) |
%m | Month, numeric (00 ..12 ) |
%p | AM or PM |
%r | Time, 12-hour (hh:mm:ss followed by AM or PM ) |
%S | Seconds (00 ..59 ) |
%s | Seconds (00 ..59 ) |
%T | Time, 24-hour (hh:mm:ss ) |
%U | Week (00 ..53 ), where Sunday is the first day of the week |
%u | Week (00 ..53 ), where Monday is the first day of the week |
%V | Week (01 ..53 ), where Sunday is the first day of the week; used with %X |
%v | Week (01 ..53 ), where Monday is the first day of the week; used with %x |
%W | Weekday name (Sunday ..Saturday ) |
%w | Day of the week (0 =Sunday..6 =Saturday) |
%X | Year for the week where Sunday is the first day of the week, numeric, 4 digits; used with %V |
%x | Year for the week, where Monday is the first day of the week, numeric, 4 digits; used with %v |
%Y | Year, numeric, 4 digits |
%y | Year, numeric, 2 digits |
%% | A literal `%'. |
All other characters are just copied to the result without interpretation.
The %f
format specifier is available as of MySQL 4.1.1.
As of MySQL Version 3.23, the `%' character is required before format specifier characters. In earlier versions of MySQL, `%' was optional.
The reason the ranges for the month and day specifiers begin with zero
is that MySQL allows incomplete dates such as '2004-00-00'
to be
stored as of MySQL 3.23.
mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%W %M %Y'); -> 'Saturday October 1997' mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%H:%i:%s'); -> '22:23:00' mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%D %y %a %d %m %b %j'); -> '4th 97 Sat 04 10 Oct 277' mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%H %k %I %r %T %S %w'); -> '22 22 10 10:23:00 PM 22:23:00 00 6' mysql> SELECT DATE_FORMAT('1999-01-01', '%X %V'); -> '1998 52' |
DAY(date)
DAY()
is a synonym for DAYOFMONTH()
.
It is available as of MySQL 4.1.1.
DAYNAME(date)
date
:
mysql> SELECT DAYNAME('1998-02-05'); -> 'Thursday' |
DAYOFMONTH(date)
date
, in the range 1
to
31
:
mysql> SELECT DAYOFMONTH('1998-02-03'); -> 3 |
DAYOFWEEK(date)
date
(1
= Sunday, 2
= Monday, ... 7
=
Saturday). These index values correspond to the ODBC standard.
mysql> SELECT DAYOFWEEK('1998-02-03'); -> 3 |
DAYOFYEAR(date)
date
, in the range 1
to
366
:
mysql> SELECT DAYOFYEAR('1998-02-03'); -> 34 |
EXTRACT(type FROM date)
The EXTRACT()
function uses the same kinds of interval type
specifiers as DATE_ADD()
or DATE_SUB()
, but extracts parts
from the date rather than performing date arithmetic.
mysql> SELECT EXTRACT(YEAR FROM "1999-07-02"); -> 1999 mysql> SELECT EXTRACT(YEAR_MONTH FROM "1999-07-02 01:02:03"); -> 199907 mysql> SELECT EXTRACT(DAY_MINUTE FROM "1999-07-02 01:02:03"); -> 20102 mysql> SELECT EXTRACT(MICROSECOND FROM "2003-01-02 10:30:00.00123"); -> 123 |
FROM_DAYS(N)
N
, returns a DATE
value:
mysql> SELECT FROM_DAYS(729669); -> '1997-10-07' |
FROM_DAYS()
is not intended for use with values that precede the
advent of the Gregorian calendar (1582), because it doesn't take into account
the days that were lost when the calendar was changed.
FROM_UNIXTIME(unix_timestamp)
FROM_UNIXTIME(unix_timestamp,format)
unix_timestamp
argument as a value in
'YYYY-MM-DD HH:MM:SS'
or YYYYMMDDHHMMSS
format, depending on
whether the function is used in a string or numeric context:
mysql> SELECT FROM_UNIXTIME(875996580); -> '1997-10-04 22:23:00' mysql> SELECT FROM_UNIXTIME(875996580) + 0; -> 19971004222300 |
If format
is given, the result is formatted according to the
format
string. format
may contain the same specifiers as
those listed in the entry for the DATE_FORMAT()
function:
mysql> SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(), -> '%Y %D %M %h:%i:%s %x'); -> '2003 6th August 06:22:58 2003' |
GET_FORMAT(DATE | TIME | TIMESTAMP, 'EUR' | 'USA' | 'JIS' | 'ISO' | 'INTERNAL')
DATE_FORMAT()
and the STR_TO_DATE()
functions.
The three possible values for the first argument
and the five possible values for the second argument result in 15 possible
format strings (for the specifiers used, see the table in the
DATE_FORMAT()
function description):
Function call | Result |
GET_FORMAT(DATE,'USA') | '%m.%d.%Y' |
GET_FORMAT(DATE,'JIS') | '%Y-%m-%d' |
GET_FORMAT(DATE,'ISO') | '%Y-%m-%d' |
GET_FORMAT(DATE,'EUR') | '%d.%m.%Y' |
GET_FORMAT(DATE,'INTERNAL') | '%Y%m%d' |
GET_FORMAT(TIMESTAMP,'USA') | '%Y-%m-%d-%H.%i.%s' |
GET_FORMAT(TIMESTAMP,'JIS') | '%Y-%m-%d %H:%i:%s' |
GET_FORMAT(TIMESTAMP,'ISO') | '%Y-%m-%d %H:%i:%s' |
GET_FORMAT(TIMESTAMP,'EUR') | '%Y-%m-%d-%H.%i.%s' |
GET_FORMAT(TIMESTAMP,'INTERNAL') | '%Y%m%d%H%i%s' |
GET_FORMAT(TIME,'USA') | '%h:%i:%s %p' |
GET_FORMAT(TIME,'JIS') | '%H:%i:%s' |
GET_FORMAT(TIME,'ISO') | '%H:%i:%s' |
GET_FORMAT(TIME,'EUR') | '%H.%i.%S' |
GET_FORMAT(TIME,'INTERNAL') | '%H%i%s' |
mysql> SELECT DATE_FORMAT('2003-10-03', GET_FORMAT(DATE, 'EUR') -> '03.10.2003' mysql> SELECT STR_TO_DATE('10.31.2003', GET_FORMAT(DATE, 'USA')) -> 2003-10-31 |
GET_FORMAT()
is available as of MySQL 4.1.1.
See See section 7.5.6 SET
Syntax.
HOUR(time)
time
. The range of the return value will be
0
to 23
for time-of-day values:
mysql> SELECT HOUR('10:05:03'); -> 10 |
However, the range of TIME
values actually is much larger, so
HOUR
can return values greater than 23
:
mysql> SELECT HOUR('272:59:59'); -> 272 |
LAST_DAY(date)
Takes a date or datetime value and returns the corresponding value for the
last day of the month. Returns NULL
if the argument is invalid.
mysql> SELECT LAST_DAY('2003-02-05'), LAST_DAY('2004-02-05'); -> '2003-02-28', '2004-02-29' mysql> SELECT LAST_DAY('2004-01-01 01:01:01'); -> '2004-01-31' mysql> SELECT LAST_DAY('2003-03-32'); -> NULL |
LAST_DAY()
is available as of MySQL 4.1.1.
LOCALTIME
LOCALTIME()
LOCALTIME
and LOCALTIME()
are synonyms for
NOW()
.
LOCALTIMESTAMP
LOCALTIMESTAMP()
LOCALTIMESTAMP
and LOCALTIMESTAMP()
are synonyms for
NOW()
.
MAKEDATE(year,dayofyear)
Returns a date, given year and day-of-year values.
dayofyear
must be greater than 0 or the result will NULL
.
mysql> SELECT MAKEDATE(2001,31), MAKEDATE(2001,32); -> '2001-01-31', '2001-02-01' mysql> SELECT MAKEDATE(2001,365), MAKEDATE(2004,365); -> '2001-12-31', '2004-12-30' mysql> SELECT MAKEDATE(2001,0); -> NULL |
MAKEDATE()
is available as of MySQL 4.1.1.
MAKETIME(hour,minute,second)
Returns a time value calculated from the hour
, minute
, and
second
arguments.
mysql> SELECT MAKETIME(12,15,30); -> '12:15:30' |
MAKETIME()
is available as of MySQL 4.1.1.
MICROSECOND(expr)
Returns the microseconds from the time or datetime expression expr
as a
number in the range from 0
to 999999
.
mysql> SELECT MICROSECOND('12:00:00.123456'); -> 123456 mysql> SELECT MICROSECOND('1997-12-31 23:59:59.000010'); -> 10 |
MICROSECOND()
is available as of MySQL 4.1.1.
MINUTE(time)
time
, in the range 0
to 59
:
mysql> SELECT MINUTE('98-02-03 10:05:03'); -> 5 |
MONTH(date)
date
, in the range 1
to 12
:
mysql> SELECT MONTH('1998-02-03'); -> 2 |
MONTHNAME(date)
date
:
mysql> SELECT MONTHNAME('1998-02-05'); -> 'February' |
NOW()
Returns the current date and time as a value in 'YYYY-MM-DD HH:MM:SS'
or YYYYMMDDHHMMSS
format, depending on whether the function is used in
a string or numeric context:
mysql> SELECT NOW(); -> '1997-12-15 23:50:26' mysql> SELECT NOW() + 0; -> 19971215235026 |
PERIOD_ADD(P,N)
N
months to period P
(in the format YYMM
or
YYYYMM
). Returns a value in the format YYYYMM
.
Note that the period argument P
is not a date value:
mysql> SELECT PERIOD_ADD(9801,2); -> 199803 |
PERIOD_DIFF(P1,P2)
P1
and P2
.
P1
and P2
should be in the format YYMM
or YYYYMM
.
Note that the period arguments P1
and P2
are not
date values:
mysql> SELECT PERIOD_DIFF(9802,199703); -> 11 |
QUARTER(date)
date
, in the range 1
to 4
:
mysql> SELECT QUARTER('98-04-01'); -> 2 |
SECOND(time)
time
, in the range 0
to 59
:
mysql> SELECT SECOND('10:05:03'); -> 3 |
SEC_TO_TIME(seconds)
seconds
argument, converted to hours, minutes, and seconds,
as a value in 'HH:MM:SS'
or HHMMSS
format, depending on whether
the function is used in a string or numeric context:
mysql> SELECT SEC_TO_TIME(2378); -> '00:39:38' mysql> SELECT SEC_TO_TIME(2378) + 0; -> 3938 |
STR_TO_DATE(str,format)
DATE_FORMAT()
function. It takes a
string str
, and a format string format
, and returns a
DATETIME value.
The date, time, or datetime values contained in str
should be given
in the format indicated by format
. For the specifiers that can be
used in format
, see the table in the DATE_FORMAT()
function
description. All other characters are just taken verbatim, thus not being
interpreted.
If str
contains an illegal date, time, or datetime value,
STR_TO_DATE()
returns NULL
.
mysql> SELECT STR_TO_DATE('03.10.2003 09.20', '%d.%m.%Y %H.%i') -> 2003-10-03 09:20:00 mysql> SELECT STR_TO_DATE('10rap', '%crap') -> 0000-10-00 00:00:00 mysql> SELECT STR_TO_DATE('2003-15-10 00:00:00', '%Y-%m-%d %H:%i:%s') -> NULL |
STR_TO_DATE()
is available as of MySQL 4.1.1.
SUBDATE(date,INTERVAL expr type)
SUBDATE(expr,days)
When invoked with the INTERVAL
form of the second argument,
SUBDATE()
is a synonym for DATE_SUB()
.
mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY); -> '1997-12-02' mysql> SELECT SUBDATE('1998-01-02', INTERVAL 31 DAY); -> '1997-12-02' |
As of MySQL 4.1.1, the second syntax is allowed, where expr
is a date
or datetime expression and days
is the number of days to be
subtracted from expr
.
mysql> SELECT SUBDATE('1998-01-02 12:00:00', 31); -> '1997-12-02 12:00:00' |
SUBTIME(expr,expr2)
SUBTIME()
subtracts expr2
from expr
and returns the result.
expr
is a date or datetime expression, and expr2
is a time
expression.
mysql> SELECT SUBTIME("1997-12-31 23:59:59.999999", "1 1:1:1.000002"); -> '1997-12-30 22:58:58.999997' mysql> SELECT SUBTIME("01:00:00.999999", "02:00:00.999998"); -> '-00:59:59.999999' |
SUBTIME()
was added in MySQL 4.1.1.
SYSDATE()
SYSDATE()
is a synonym for NOW()
.
TIME(expr)
Extracts the time part of the time or datetime expression expr
.
mysql> SELECT TIME('2003-12-31 01:02:03'); -> '01:02:03' mysql> SELECT TIME('2003-12-31 01:02:03.000123'); -> '01:02:03.000123' |
TIME()
is available as of MySQL 4.1.1.
TIMEDIFF(expr,expr2)
TIMEDIFF()
returns the time between the start time
expr
and the end time expr2
.
expr
and expr2
are time or date-and-time expressions, but both
must be of the same type.
mysql> SELECT TIMEDIFF('2000:01:01 00:00:00', '2000:01:01 00:00:00.000001'); -> '-00:00:00.000001' mysql> SELECT TIMEDIFF('1997-12-31 23:59:59.000001','1997-12-30 01:01:01.000002'); -> '46:58:57.999999' |
TIMEDIFF()
was added in MySQL 4.1.1.
TIMESTAMP(expr)
TIMESTAMP(expr,expr2)
With one argument, returns the date or datetime expression expr
as a datetime value.
With two arguments, adds the time expression expr2
to the
date or datetime expression expr
and returns a datetime value.
mysql> SELECT TIMESTAMP('2003-12-31'); -> '2003-12-31 00:00:00' mysql> SELECT TIMESTAMP('2003-12-31 12:00:00','12:00:00'); -> '2004-01-01 00:00:00' |
TIMESTAMP()
is available as of MySQL 4.1.1.
TIMESTAMPADD(interval,int_expr,datetime_expr)
Adds the integer expression int_expr
to the date or datetime expression
datetime_expr
. The unit for int_expr
is given by the
interval
argument, which should be one of the following values:
FRAC_SECOND
,
SECOND
,
MINUTE
,
HOUR
,
DAY
,
WEEK
,
MONTH
,
QUARTER
,
or
YEAR
.
The interval
value may be specified using one of keywords as shown,
or with a prefix of SQL_TSI_
. For example, DAY
or
SQL_TSI_DAY
both are legal.
mysql> SELECT TIMESTAMPADD(MINUTE,1,'2003-01-02'); -> '2003-01-02 00:01:00' mysql> SELECT TIMESTAMPADD(WEEK,1,'2003-01-02'); -> '2003-01-09' |
TIMESTAMPADD()
is available as of MySQL 5.0.0.
TIMESTAMPDIFF(interval,datetime_expr1,datetime_expr2)
Returns the integer difference between the date or datetime expressions
datetime_expr1
and
datetime_expr2
. The unit for the result is given by the
interval
argument. The legal values for interval
are the same as
those described in the desription of the TIMESTAMPADD()
function.
mysql> SELECT TIMESTAMPDIFF(MONTH,'2003-02-01','2003-05-01'); -> 3 mysql> SELECT TIMESTAMPDIFF(YEAR,'2002-05-01','2001-01-01'); -> -1 |
TIMESTAMPDIFF()
is available as of MySQL 5.0.0.
TIME_FORMAT(time,format)
DATE_FORMAT()
function, but the
format
string may contain only those format specifiers that handle
hours, minutes, and seconds. Other specifiers produce a NULL
value or
0
.
If the time
value contains an hour part that is greater than
23
, the %H
and %k
hour format specifiers produce a
value larger than the usual range of 0..23
. The other hour format
specifiers produce the hour value modulo 12:
mysql> SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l'); -> '100 100 04 04 4' |
TIME_TO_SEC(time)
time
argument, converted to seconds:
mysql> SELECT TIME_TO_SEC('22:23:00'); -> 80580 mysql> SELECT TIME_TO_SEC('00:39:38'); -> 2378 |
TO_DAYS(date)
date
, returns a daynumber (the number of days since year
0):
mysql> SELECT TO_DAYS(950501); -> 728779 mysql> SELECT TO_DAYS('1997-10-07'); -> 729669 |
TO_DAYS()
is not intended for use with values that precede the advent
of the Gregorian calendar (1582), because it doesn't take into account the
days that were lost when the calendar was changed.
UNIX_TIMESTAMP()
UNIX_TIMESTAMP(date)
'1970-01-01 00:00:00'
GMT) as an unsigned integer. If
UNIX_TIMESTAMP()
is called with a date
argument, it
returns the value of the argument as seconds since '1970-01-01
00:00:00'
GMT. date
may be a DATE
string, a
DATETIME
string, a TIMESTAMP
, or a number in the format
YYMMDD
or YYYYMMDD
in local time:
mysql> SELECT UNIX_TIMESTAMP(); -> 882226357 mysql> SELECT UNIX_TIMESTAMP('1997-10-04 22:23:00'); -> 875996580 |
When UNIX_TIMESTAMP
is used on a TIMESTAMP
column, the function
returns the internal timestamp value directly, with no implicit
"string-to-Unix-timestamp" conversion.
If you pass an out-of-range date to UNIX_TIMESTAMP()
, it
returns 0
, but please note that only basic checking is performed
(year 1970-2037, month 01-12, day 01-31).
If you want to subtract UNIX_TIMESTAMP()
columns, you might want to
cast the result to signed integers. See section 12.5 Cast Functions.
UTC_DATE
UTC_DATE()
'YYYY-MM-DD'
or
YYYYMMDD
format, depending on whether the function is used in a
string or numeric context:
mysql> SELECT UTC_DATE(), UTC_DATE() + 0; -> '2003-08-14', 20030814 |
UTC_DATE()
is available as of MySQL 4.1.1.
UTC_TIME
UTC_TIME()
'HH:MM:SS'
or HHMMSS
format, depending on whether the function is used in a string or numeric
context:
mysql> SELECT UTC_TIME(), UTC_TIME() + 0; -> '18:07:53', 180753 |
UTC_TIME()
is available as of MySQL 4.1.1.
UTC_TIMESTAMP
UTC_TIMESTAMP()
'YYYY-MM-DD HH:MM:SS'
or YYYYMMDDHHMMSS
format, depending on whether the function is used in
a string or numeric context:
mysql> SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0; -> '2003-08-14 18:08:04', 20030814180804 |
UTC_TIMESTAMP()
is available as of MySQL 4.1.1.
WEEK(date [,mode])
date
.
The two-argument form of WEEK()
allows you to specify whether the week
starts on Sunday or Monday and whether the return value should be in the range
0-53 or 1-52. When mode
argument is omitted the
value of a default_week_format
server variable (or 0 in
MySQL 4.0 or earlier) is assumed. See section 7.5.6 SET
Syntax.
The following table demonstrates how the mode
argument works:
Value | Meaning |
0 | Week starts on Sunday; return value range is 0 to 53; week 1 is the first week that starts in this year |
1 | Week starts on Monday; return value range is 0 to 53; week 1 is the first week that has more than 3 days in this year |
2 | Week starts on Sunday; return value range is 1 to 53; week 1 is the first week that starts in this year |
3 | Week starts on Monday; return value range is 1 to 53; week 1 is the first week that has more than 3 days in this year |
4 | Week starts on Sunday; return value range is 0 to 53; week 1 is the first week that has more than 3 days in this year |
5 | Week starts on Monday; return value range is 0 to 53; week 1 is the first week that starts in this year |
6 | Week starts on Sunday; return value range is 1 to 53; week 1 is the first week that has more than 3 days in this year |
7 | Week starts on Monday; return value range is 1 to 53; week 1 is the first week that starts in this year |
The mode
value of 3 can be used as of MySQL 4.0.5.
The mode
value of 4 and above can be used as of MySQL 4.0.17.
mysql> SELECT WEEK('1998-02-20'); -> 7 mysql> SELECT WEEK('1998-02-20',0); -> 7 mysql> SELECT WEEK('1998-02-20',1); -> 8 mysql> SELECT WEEK('1998-12-31',1); -> 53 |
Note: In Version 4.0, WEEK(date,0)
was changed to match the
calendar in the USA. Before that, WEEK()
was calculated incorrectly
for dates in USA. (In effect, WEEK(date)
and WEEK(date,0)
was
incorrect for all cases.)
Note that if a date falls in the last week of the previous year, MySQL will
return 0 if you don't use 2, 3, 6, or 7
as the optional mode
argument:
mysql> SELECT YEAR('2000-01-01'), WEEK('2000-01-01',0); -> 2000, 0 |
One might argue that MySQL should return 52 for the WEEK()
function, because the given date actually occurs in the 52nd week of 1999. We
decided to return 0 instead as we want the function to return "the week
number in the given year." This makes the usage of the WEEK()
function reliable when combined with other functions that extract a
date part from a date.
If you would prefer the result to be evaluated with respect to the year
that contains the first day of the week for the given date, you should use
2, 3, 6, or 7 as the optional mode
argument.
mysql> SELECT WEEK('2000-01-01',2); -> 52 |
Alternatively, use the YEARWEEK()
function:
mysql> SELECT YEARWEEK('2000-01-01'); -> 199952 mysql> SELECT MID(YEARWEEK('2000-01-01'),5,2); -> '52' |
WEEKDAY(date)
date
(0
= Monday, 1
= Tuesday, ... 6
= Sunday):
mysql> SELECT WEEKDAY('1998-02-03 22:23:00'); -> 1 mysql> SELECT WEEKDAY('1997-11-05'); -> 2 |
WEEKOFYEAR(date)
Returns the calendar week of the date as a number in the
range from 1
to 53
.
mysql> SELECT WEEKOFYEAR('1998-02-20'); -> 8 |
WEEKOFYEAR()
is available as of MySQL 4.1.1.
YEAR(date)
date
, in the range 1000
to 9999
:
mysql> SELECT YEAR('98-02-03'); -> 1998 |
YEARWEEK(date)
YEARWEEK(date,start)
start
argument works exactly
like the start
argument to WEEK()
. Note that the year in the
result may be
different from the year in the date argument for the first and the last
week of the year:
mysql> SELECT YEARWEEK('1987-01-01'); -> 198653 |
Note that the week number is different from what the WEEK()
function would return (0
) for optional arguments 0
or 1
,
as WEEK()
then returns the week in the context of the given year.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |