Date and Time Functions
This section describes the functions that can be used to manipulate temporal values. See
section 6.2.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 |
SECOND |
SECONDS |
MINUTE |
MINUTES |
HOUR |
HOURS |
DAY |
DAYS |
MONTH |
MONTHS |
YEAR |
YEARS |
MINUTE_SECOND |
'MINUTES:SECONDS' |
HOUR_MINUTE |
'HOURS:MINUTES' |
DAY_HOUR |
'DAYS HOURS' |
YEAR_MONTH |
'YEARS-MONTHS' |
HOUR_SECOND |
'HOURS:MINUTES:SECONDS' |
DAY_MINUTE |
'DAYS HOURS:MINUTES' |
DAY_SECOND |
'DAYS HOURS:MINUTES:SECONDS' |
DAY_MICROSECOND |
'DAYS.MICROSECONDS' |
HOUR_MICROSECOND |
'HOURS.MICROSECONDS' |
MINUTE_MICROSECOND |
'MINUTES.MICROSECONDS' |
SECOND_MICROSECOND |
'SECONDS.MICROSECONDS' |
MICROSECOND |
'MICROSECONDS' |
The type values DAY_MICROSECOND , HOUR_MICROSECOND , MINUTE_MICROSECOND ,
SECOND_MICROSECOND , and MICROSECOND are allowed as of MySQL
4.1.1. 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)
- Formats the
date value according to the format string. The
following specifiers may be used in the format string:
Specifier |
Description |
%M |
Month name (January ..December ) |
%W |
Weekday name (Sunday ..Saturday ) |
%D |
Day of the month with English suffix (0th , 1st , 2nd ,
3rd , etc.) |
%Y |
Year, numeric, 4 digits |
%y |
Year, numeric, 2 digits |
%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 |
%a |
Abbreviated weekday name (Sun ..Sat ) |
%d |
Day of the month, numeric (00 ..31 ) |
%e |
Day of the month, numeric (0 ..31 ) |
%m |
Month, numeric (00 ..12 ) |
%c |
Month, numeric (0 ..12 ) |
%b |
Abbreviated month name (Jan ..Dec ) |
%j |
Day of year (001 ..366 ) |
%H |
Hour (00 ..23 ) |
%k |
Hour (0 ..23 ) |
%h |
Hour (01 ..12 ) |
%I |
Hour (01 ..12 ) |
%l |
Hour (1 ..12 ) |
%i |
Minutes, numeric (00 ..59 ) |
%r |
Time, 12-hour (hh:mm:ss followed by AM or PM ) |
%T |
Time, 24-hour (hh:mm:ss ) |
%S |
Seconds (00 ..59 ) |
%s |
Seconds (00 ..59 ) |
%f |
Microseconds (000000 ..999999 ) |
%p |
AM or PM |
%w |
Day of the week (0 =Sunday..6 =Saturday) |
%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 |
%% |
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)
- Returns the name of the weekday for
date :
mysql> SELECT DAYNAME('1998-02-05');
-> 'Thursday'
DAYOFMONTH(date)
- Returns the day of the month for
date , in the range 1 to 31 :
mysql> SELECT DAYOFMONTH('1998-02-03');
-> 3
DAYOFWEEK(date)
- Returns the weekday index for
date (1 = Sunday, 2
= Monday, ... 7 = Saturday). These index values correspond to the ODBC
standard.
mysql> SELECT DAYOFWEEK('1998-02-03');
-> 3
DAYOFYEAR(date)
- Returns the day of the year for
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)
- Given a daynumber
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)
- Returns a representation of the
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')
- Returns a format string. This function is useful in combination with the
DATE_FORMAT()
and the STR_TO_DATE() functions, and when setting the server variables DATE_FORMAT ,
TIME_FORMAT , and DATETIME_FORMAT . 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' |
ISO format is ISO 9075, not ISO 8601.
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
mysql> SET DATE_FORMAT=GET_FORMAT(DATE, 'USA'); SELECT '2003-10-31';
-> 10-31-2003
GET_FORMAT() is available as of MySQL 4.1.1. See See section 5.5.6 SET Syntax.
HOUR(time)
- Returns the hour for
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)
- Returns the minute for
time , in the range 0 to 59 :
mysql> SELECT MINUTE('98-02-03 10:05:03');
-> 5
MONTH(date)
- Returns the month for
date , in the range 1 to 12 :
mysql> SELECT MONTH('1998-02-03');
-> 2
MONTHNAME(date)
- Returns the name of the month for
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)
- Adds
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)
- Returns the number of months between periods
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)
- Returns the quarter of the year for
date , in the range 1 to 4 :
mysql> SELECT QUARTER('98-04-01');
-> 2
SECOND(time)
- Returns the second for
time , in the range 0 to 59 :
mysql> SELECT SECOND('10:05:03');
-> 3
SEC_TO_TIME(seconds)
- Returns the
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)
- This is the reverse function of the
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.
TIME_FORMAT(time,format)
- This is used like the
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)
- Returns the
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)
- Given a 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)
- If called with no argument, returns a Unix timestamp (seconds since
'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 may want to cast the result to signed integers. See section 6.3.5 Cast Functions.
UTC_DATE
-
UTC_DATE()
- Returns the current UTC 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 UTC_DATE(), UTC_DATE() + 0;
-> '2003-08-14', 20030814
UTC_DATE() is available as of MySQL 4.1.1.
UTC_TIME
-
UTC_TIME()
- Returns the current UTC 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 UTC_TIME(), UTC_TIME() + 0;
-> '18:07:53', 180753
UTC_TIME() is available as of MySQL 4.1.1.
UTC_TIMESTAMP
-
UTC_TIMESTAMP()
- Returns the current UTC 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 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])
- The function returns the week number for
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 5.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)
- Returns the weekday index for
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)
- Returns the year for
date , in the range 1000 to 9999 :
mysql> SELECT YEAR('98-02-03');
-> 1998
YEARWEEK(date)
-
YEARWEEK(date,start)
- Returns year and week for a date. The
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.
|