Functions for Use in SELECT and WHERE Clauses

A select_expression or where_definition in a SQL statement can consist of any expression using the functions described next.

An expression that contains NULL always produces a NULL value unless otherwise indicated in the documentation for the operators and functions involved in the expression.

Note: there must be no whitespace between a function name and the parentheses following it. This helps the MySQL parser distinguish between function calls and references to tables or columns that happen to have the same name as a function. Spaces around arguments are permitted, though.

You can force MySQL to accept spaces after the function name by starting mysqld with --ansi or using the CLIENT_IGNORE_SPACE to mysql_connect( ), but in this case all function names will become reserved words. See Section 1.7.2.

For the sake of brevity, examples display the output from the mysql program in abbreviated form. So this:

mysql> SELECT MOD(29,9);
1 rows in set (0.00 sec)

+-----------+
| mod(29,9) |
+-----------+
|         2 |
+-----------+

is displayed like this:

mysql> SELECT MOD(29,9);
        -> 2

Non-Type-Specific Operators and Functions

Parentheses

( ... )

Use parentheses to force the order of evaluation in an expression. For example:

mysql> SELECT 1+2*3;
        -> 7
mysql> SELECT (1+2)*3;
        -> 9

Comparison operators

Comparison operations result in a value of 1 (TRUE), 0 (FALSE), or NULL. These functions work for both numbers and strings. Strings are automatically converted to numbers and numbers to strings as needed (as in Perl).

MySQL performs comparisons using the following rules:

If one or both arguments are NULL, the result of the comparison is NULL, except for the <=> operator.
If both arguments in a comparison operation are strings, they are compared as strings.
If both arguments are integers, they are compared as integers.
Hexadecimal values are treated as binary strings if not compared to a number.
If one of the arguments is a TIMESTAMP or DATETIME column and the other argument is a constant, the constant is converted to a timestamp before the comparison is performed. This is done to be more ODBC-friendly.
In all other cases, the arguments are compared as floating-point (real) numbers.

By default, string comparisons are done in case-independent fashion using the current character set (ISO-8859-1 Latin1 by default, which also works excellently for English).

The following examples illustrate conversion of strings to numbers for comparison operations:

mysql> SELECT 1 > '6x';
         -> 0
mysql> SELECT 7 > '6x';
         -> 1
mysql> SELECT 0 > 'x6';
         -> 0
mysql> SELECT 0 = 'x6';
         -> 1

=

Equal:

mysql> SELECT 1 = 0;
        -> 0
mysql> SELECT '0' = 0;
        -> 1
mysql> SELECT '0.0' = 0;
        -> 1
mysql> SELECT '0.01' = 0;
        -> 0
mysql> SELECT '.01' = 0.01;
        -> 1

<> , !=

Not equal:

mysql> SELECT '.01' <> '0.01';
        -> 1
mysql> SELECT .01 <> '0.01';
        -> 0
mysql> SELECT 'zapp' <> 'zappp';
        -> 1

<=

Less than or equal:

mysql> SELECT 0.1 <= 2;
        -> 1

<

Less than:

mysql> SELECT 2 < 2;
        -> 0

>=

Greater than or equal:

mysql> SELECT 2 >= 2;
        -> 1

>

Greater than:

mysql> SELECT 2 > 2;
        -> 0

<=>

NULL safe equal:

mysql> SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL;
        -> 1 1 0

IS NULL , IS NOT NULL

Test whether a value is or is not NULL:

mysql> SELECT 1 IS NULL, 0 IS NULL, NULL IS NULL;
        -> 0 0 1
mysql> SELECT 1 IS NOT NULL, 0 IS NOT NULL, NULL IS NOT NULL;
        -> 1 1 0

To be able to work well with other programs, MySQL supports the following extra features when using IS NULL:

You can find the last inserted row with:
```
SELECT * FROM tbl_name WHERE auto_col IS NULL
```
This can be disabled by setting SQL_AUTO_IS_NULL=0. See Section 5.5.6.
For NOT NULL DATE and DATETIME columns you can find the special date 0000-00-00 by using:
```
SELECT * FROM tbl_name WHERE date_column IS NULL
```
This is needed to get some ODBC applications to work (as ODBC doesn’t support a 0000-00-00 date).

expr BETWEEN min AND max

If expr is greater than or equal to min and expr is less than or equal to max, BETWEEN returns 1, otherwise it returns 0. This is equivalent to the expression (min <= expr AND expr <= max) if all the arguments are of the same type. The first argument (expr) determines how the comparison is performed as follows:

If expr is a TIMESTAMP, DATE, or DATETIME column, MIN( ) and MAX( ) are formatted to the same format if they are constants.
If expr is a case-insensitive string expression, a case-insensitive string comparison is done.
If expr is a case-sensitive string expression, a case-sensitive string comparison is done.
If expr is an integer expression, an integer comparison is done.

Otherwise, a floating-point (real) comparison is done.

mysql> SELECT 1 BETWEEN 2 AND 3;
        -> 0
mysql> SELECT 'b' BETWEEN 'a' AND 'c';
        -> 1
mysql> SELECT 2 BETWEEN 2 AND '3';
        -> 1
mysql> SELECT 2 BETWEEN 2 AND 'x-3';
        -> 0

expr NOT BETWEEN min AND max

Same as NOT (expr BETWEEN min AND max).

expr IN (value,...)

Returns 1 if expr is any of the values in the IN list, otherwise returns 0. If all values are constants, all values are evaluated according to the type of expr and sorted. The search for the item is then done using a binary search. This means IN is very quick if the IN value list consists entirely of constants. If expr is a case-sensitive string expression, the string comparison is performed in case-sensitive fashion:

mysql> SELECT 2 IN (0,3,5,'wefwf');
        -> 0
mysql> SELECT 'wefwf' IN (0,3,5,'wefwf');
        -> 1

expr NOT IN (value,...)

Same as NOT (expr IN (value,...)).

ISNULL(expr)

If expr is NULL, ISNULL( ) returns 1, otherwise it returns 0:

mysql> SELECT ISNULL(1+1);
        -> 0
mysql> SELECT ISNULL(1/0);
        -> 1

Note that a comparison of NULL values using = will always be false!

COALESCE(list)

Returns first non-NULL element in list:

mysql> SELECT COALESCE(NULL,1);
        -> 1
mysql> SELECT COALESCE(NULL,NULL,NULL);
        -> NULL

INTERVAL(N,N1,N2,N3,...)

Returns 0 if N < N1, 1 if N < N2, and so on. All arguments are treated as integers. It is required that N1 < N2 < N3 < ... < Nn for this function to work correctly. This is because a binary search is used (very fast):

mysql> SELECT INTERVAL(23, 1, 15, 17, 30, 44, 200);
        -> 3
mysql> SELECT INTERVAL(10, 1, 10, 100, 1000);
        -> 2
mysql> SELECT INTERVAL(22, 23, 30, 44, 200);
        -> 0

If you are comparing a case-sensitive string with any of the standard operators (=, <>..., but not LIKE) the end space will be ignored.

mysql> SELECT "a" ="A ";
        -> 1

Logical operators

All logical functions return 1 (TRUE), 0 (FALSE), or NULL (unknown, which is in most cases the same as FALSE):

NOT , !

Logical NOT. Returns 1 if the argument is 0, otherwise returns 0. Exception: NOT NULL returns NULL:

mysql> SELECT NOT 1;
        -> 0
mysql> SELECT NOT NULL;
        -> NULL
mysql> SELECT ! (1+1);
        -> 0
mysql> SELECT ! 1+1;
        -> 1

The last example returns 1 because the expression evaluates the same way as (!1)+1.

OR , ||

Logical OR. Returns 1 if either argument is not 0 and not NULL:

mysql> SELECT 1 || 0;
        -> 1
mysql> SELECT 0 || 0;
        -> 0
mysql> SELECT 1 || NULL;
        -> 1

AND , &&

Logical AND. Returns 0 if either argument is 0 or NULL, otherwise returns 1:

mysql> SELECT 1 && NULL;
        -> 0
mysql> SELECT 1 && 0;
        -> 0

Control flow functions

IFNULL(expr1,expr2)

If expr1 is not NULL, IFNULL( ) returns expr1, otherwise it returns expr2. IFNULL( ) returns a numeric or string value, depending on the context in which it is used:

mysql> SELECT IFNULL(1,0);
        -> 1
mysql> SELECT IFNULL(NULL,10);
        -> 10
mysql> SELECT IFNULL(1/0,10);
        -> 10
mysql> SELECT IFNULL(1/0,'yes');
        -> 'yes'

NULLIF(expr1,expr2)

If expr1 = expr2 is true, return NULL, otherwise return expr1. This is the same as CASE WHEN x = y THEN NULL ELSE x END:

mysql> SELECT NULLIF(1,1);
        -> NULL
mysql> SELECT NULLIF(1,2);
        -> 1

Note that expr1 is evaluated twice in MySQL if the arguments are equal.

IF(expr1,expr2,expr3)

If expr1 is TRUE (expr1 <> 0 and expr1 <> NULL), IF( ) returns expr2, otherwise it returns expr3. IF( ) returns a numeric or string value, depending on the context in which it is used:

mysql> SELECT IF(1>2,2,3);
        -> 3
mysql> SELECT IF(1<2,'yes','no');
        -> 'yes'
mysql> SELECT IF(STRCMP('test','test1'),'no','yes');
        -> 'no'

expr1 is evaluated as an integer value, which means that if you are testing floating-point or string values, you should do so using a comparison operation:

mysql> SELECT IF(0.1,1,0);
        -> 0
mysql> SELECT IF(0.1<>0,1,0);
        -> 1

In the first case, IF(0.1) returns 0 because 0.1 is converted to an integer value, resulting in a test of IF(0). This may not be what you expect. In the second case, the comparison tests the original floating-point value to see whether it is non-zero. The result of the comparison is used as an integer.

The default return type of IF( ) (which may matter when it is stored into a temporary table) is calculated in MySQL Version 3.23 as follows:

Expression	Return value
expr2 or expr3 returns a string	string
expr2 or expr3 returns a floating-point value	floating-point
expr2 or expr3 returns an integer	integer

If expr2 and expr3 are strings, then the result is case-sensitive if both strings are case-sensitive. (Starting from 3.23.51)

CASE value WHEN [compare-value] THEN result [WHEN [compare-value] THEN result ...] [ELSE result] END , CASE WHEN [condition] THEN result [WHEN [condition] THEN result ...] [ELSE result] END

The first version returns the result where value=compare-value. The second version returns the result for the first condition, which is true. If there was no matching result value, the result after ELSE is returned. If there is no ELSE part, NULL is returned:

mysql> SELECT CASE 1 WHEN 1 THEN "one"
           WHEN 2 THEN "two" ELSE "more" END;
       -> "one"
mysql> SELECT CASE WHEN 1>0 THEN "true" ELSE "false" END;
       -> "true"
mysql> SELECT CASE BINARY "B" WHEN "a" THEN 1 WHEN "b" THEN 2 END;
       -> NULL

The type of the return value (INTEGER, DOUBLE or STRING) is the same as the type of the first returned value (the expression after the first THEN).

String Functions

String-valued functions return NULL if the length of the result would be greater than the max_allowed_packet server parameter. See Section 5.5.2.

For functions that operate on string positions, the first position is numbered 1.

ASCII(str)

Returns the ASCII code value of the leftmost character of the string str. Returns 0 if str is the empty string. Returns NULL if str is NULL:

mysql> SELECT ASCII('2');
        -> 50
mysql> SELECT ASCII(2);
        -> 50
mysql> SELECT ASCII('dx');
        -> 100

String comparison functions

Normally, if any expression in a string comparison is case-sensitive, the comparison is performed in case-sensitive fashion.

expr LIKE pat [ESCAPE 'escape-char']

Pattern matching using SQL simple regular expression comparison. Returns 1 (TRUE) or 0 (FALSE). With LIKE you can use the following two wildcard characters in the pattern:

Char	Description
%	Matches any number of characters, even zero characters
_	Matches exactly one character

mysql> SELECT 'David!' LIKE 'David_';
        -> 1
mysql> SELECT 'David!' LIKE '%D%v%';
        -> 1

To test for literal instances of a wildcard character, precede the character with the escape character. If you don’t specify the ESCAPE character, \ is assumed:

String	Description
\%	Matches one % character
\_	Matches one _ character

mysql> SELECT 'David!' LIKE 'David\_';
        -> 0
mysql> SELECT 'David_' LIKE 'David\_';
        -> 1

To specify a different escape character, use the ESCAPE clause:

mysql> SELECT 'David_' LIKE 'David|_' ESCAPE '|';
        -> 1

The following two statements illustrate that string comparisons are case-insensitive unless one of the operands is a binary string:

mysql> SELECT 'abc' LIKE 'ABC';
        -> 1
mysql> SELECT 'abc' LIKE BINARY 'ABC';
        -> 0

LIKE is allowed on numeric expressions! (This is a MySQL extension to the ANSI SQL LIKE.)

mysql> SELECT 10 LIKE '1%';
        -> 1

Note: because MySQL uses the C escape syntax in strings (for example, \n), you must double any \ that you use in your LIKE strings. For example, to search for \n, specify it as \\n. To search for \, specify it as \\\\ (the backslashes are stripped once by the parser and another time when the pattern match is done, leaving a single backslash to be matched).

expr NOT LIKE pat [ESCAPE 'escape-char']

Same as NOT (expr LIKE pat [ESCAPE 'escape-char']).

expr REGEXP pat , expr RLIKE pat

Performs a pattern match of a string expression expr against a pattern pat. The pattern can be an extended regular expression. See Appendix F. Returns 1 if expr matches pat, otherwise returns 0. RLIKE is a synonym for REGEXP, provided for mSQL compatibility. Note: because MySQL uses the C escape syntax in strings (for example, \n), you must double any \ that you use in your REGEXP strings. As of MySQL Version 3.23.4, REGEXP is case-insensitive for normal (not binary) strings:

mysql> SELECT 'Monty!' REGEXP 'm%y%%';
        -> 0
mysql> SELECT 'Monty!' REGEXP '.*';
        -> 1
mysql> SELECT 'new*\n*line' REGEXP 'new\\*.\\*line';
        -> 1
mysql> SELECT "a" REGEXP "A", "a" REGEXP BINARY "A";
        -> 1  0
mysql> SELECT "a" REGEXP "^[a-d]";
        -> 1

REGEXP and RLIKE use the current character set (ISO-8859-1 Latin1 by default) when deciding the type of a character.

expr NOT REGEXP pat , expr NOT RLIKE pat

Same as NOT (expr REGEXP pat).

STRCMP(expr1,expr2)

STRCMP( ) returns 0 if the strings are the same, -1 if the first argument is smaller than the second according to the current sort order, and 1 otherwise:

mysql> SELECT STRCMP('text', 'text2');
        -> -1
mysql> SELECT STRCMP('text2', 'text');
        -> 1
mysql> SELECT STRCMP('text', 'text');
        -> 0

MATCH (col1,col2,...) AGAINST (expr) , MATCH (col1,col2,...) AGAINST (expr IN BOOLEAN MODE)

MATCH ... AGAINST( ) is used for full-text search and returns a relevance similarity measure between the text in columns (col1,col2,...) and the query expr. Relevance is a positive floating-point number. Zero relevance means no similarity. MATCH ... AGAINST( ) is available in MySQL Versions 3.23.23 or later. IN BOOLEAN MODE extension was added in Version 4.0.1. For details and usage examples, see Section 6.8.

Case sensitivity

BINARY

The BINARY operator casts the string following it to a binary string. This is an easy way to force a column comparison to be case-sensitive even if the column isn’t defined as BINARY or BLOB:

mysql> SELECT "a" = "A";
        -> 1
mysql> SELECT BINARY "a" = "A";
        -> 0

BINARY string is shorthand for CAST(string AS BINARY). See Section 6.3.5. BINARY was introduced in MySQL Version 3.23.0.

Note that in some context MySQL will not be able to use the index efficiently when you cast an indexed column to BINARY.

If you want to compare a blob case-insensitively you can always convert the blob to uppercase before doing the comparison:

SELECT 'A' LIKE UPPER(blob_col) FROM table_name;

We plan to soon introduce casting between different character sets to make string comparison even more flexible.

Numeric Functions

Arithmetic operations

The usual arithmetic operators are available. Note that in the case of -, +, and *, the result is calculated with BIGINT (64-bit) precision if both arguments are integers! If one of the arguments is an unsigned integer, and the other argument is also an integer, the result will be an unsigned integer. See Section 6.3.5.

+

Addition:

mysql> SELECT 3+5;
        -> 8

-

Subtraction:

mysql> SELECT 3-5;
        -> -2

*

Multiplication:

mysql> SELECT 3*5;
        -> 15
mysql> SELECT 18014398509481984*18014398509481984.0;
        -> 324518553658426726783156020576256.0
mysql> SELECT 18014398509481984*18014398509481984;
        -> 0

The result of the last expression is incorrect because the result of the integer multiplication exceeds the 64-bit range of BIGINT calculations.

/

Division:

mysql> SELECT 3/5;
        -> 0.60

Division by zero produces a NULL result:

mysql> SELECT 102/(1-1);
        -> NULL

A division will be calculated with BIGINT arithmetic only if performed in a context where its result is converted to an integer!

Mathematical functions

All mathematical functions return NULL in case of an error.

-

Unary minus. Changes the sign of the argument:

mysql> SELECT - 2;
        -> -2

Note that if this operator is used with a BIGINT, the return value is a BIGINT! This means that you should avoid using - on integers that may have the value of -2^63!

ABS(X)

Returns the absolute value of X:

mysql> SELECT ABS(2);
        -> 2
mysql> SELECT ABS(-32);
        -> 32

This function is safe to use with BIGINT values.

SIGN(X)

Returns the sign of the argument as -1, 0, or 1, depending on whether X is negative, zero, or positive:

mysql> SELECT SIGN(-32);
        -> -1
mysql> SELECT SIGN(0);
        -> 0
mysql> SELECT SIGN(234);
        -> 1

MOD(N,M) , %

Modulo (like the % operator in C). Returns the remainder of N divided by M:

mysql> SELECT MOD(234, 10);
        -> 4
mysql> SELECT 253 % 7;
        -> 1
mysql> SELECT MOD(29,9);
        -> 2

This function is safe to use with BIGINT values.

FLOOR(X)

Returns the largest integer value not greater than X:

mysql> SELECT FLOOR(1.23);
        -> 1
mysql> SELECT FLOOR(-1.23);
        -> -2

Note that the return value is converted to a BIGINT!

CEILING(X)

Returns the smallest integer value not less than X:

mysql> SELECT CEILING(1.23);
        -> 2
mysql> SELECT CEILING(-1.23);
        -> -1

Note that the return value is converted to a BIGINT!

ROUND(X)

Returns the argument X, rounded to the nearest integer:

mysql> SELECT ROUND(-1.23);
        -> -1
mysql> SELECT ROUND(-1.58);
        -> -2
mysql> SELECT ROUND(1.58);
        -> 2

Note that the behavior of ROUND( ) when the argument is halfway between two integers depends on the C library implementation. Some round to the nearest even number, always up, always down, or always toward zero. If you need one kind of rounding, you should use a well-defined function like TRUNCATE( ) or FLOOR( ) instead.

ROUND(X,D)

Returns the argument X, rounded to a number with D decimals. If D is 0, the result will have no decimal point or fractional part:

mysql> SELECT ROUND(1.298, 1);
        -> 1.3
mysql> SELECT ROUND(1.298, 0);
        -> 1

EXP(X)

Returns the value of e (the base of natural logarithms) raised to the power of X:

mysql> SELECT EXP(2);
        -> 7.389056
mysql> SELECT EXP(-2);
        -> 0.135335

LOG(X)

Returns the natural logarithm of X:

mysql> SELECT LOG(2);
        -> 0.693147
mysql> SELECT LOG(-2);
        -> NULL

If you want the log of a number X to some arbitary base B, use the formula LOG(X)/LOG(B).

LOG10(X)

Returns the base-10 logarithm of X:

mysql> SELECT LOG10(2);
        -> 0.301030
mysql> SELECT LOG10(100);
        -> 2.000000
mysql> SELECT LOG10(-100);
        -> NULL

POW(X,Y) , POWER(X,Y)

Returns the value of X raised to the power of Y:

mysql> SELECT POW(2,2);
        -> 4.000000
mysql> SELECT POW(2,-2);
        -> 0.250000

SQRT(X)

Returns the non-negative square root of X:

mysql> SELECT SQRT(4);
        -> 2.000000
mysql> SELECT SQRT(20);
        -> 4.472136

PI( )

Returns the value of PI. The default shown number of decimals is 5, but MySQL internally uses the full double precision for PI.

mysql> SELECT PI( );
        -> 3.141593
mysql> SELECT PI( )+0.000000000000000000;
        -> 3.141592653589793116

COS(X)

Returns the cosine of X, where X is given in radians:

mysql> SELECT COS(PI( ));
        -> -1.000000

SIN(X)

Returns the sine of X, where X is given in radians:

mysql> SELECT SIN(PI( ));
        -> 0.000000

TAN(X)

Returns the tangent of X, where X is given in radians:

mysql> SELECT TAN(PI( )+1);
        -> 1.557408

ACOS(X)

Returns the arc cosine of X—that is, the value whose cosine is X. Returns NULL if X is not in the range -1 to 1:

mysql> SELECT ACOS(1);
        -> 0.000000
mysql> SELECT ACOS(1.0001);
        -> NULL
mysql> SELECT ACOS(0);
        -> 1.570796

ASIN(X)

Returns the arc sine of X—that is, the value whose sine is X. Returns NULL if X is not in the range -1 to 1:

mysql> SELECT ASIN(0.2);
        -> 0.201358
mysql> SELECT ASIN('foo');
        -> 0.000000

ATAN(X)

Returns the arc tangent of X—that is, the value whose tangent is X:

mysql> SELECT ATAN(2);
        -> 1.107149
mysql> SELECT ATAN(-2);
        -> -1.107149

ATAN(Y,X) , ATAN2(Y,X)

Returns the arc tangent of the two variables X and Y. It is similar to calculating the arc tangent of Y / X, except that the signs of both arguments are used to determine the quadrant of the result:

mysql> SELECT ATAN(-2,2);
        -> -0.785398
mysql> SELECT ATAN2(PI( ),0);
        -> 1.570796

COT(X)

Returns the cotangent of X:

mysql> SELECT COT(12);
        -> -1.57267341
mysql> SELECT COT(0);
        -> NULL

RAND( ) , RAND(N)

Returns a random floating-point value in the range 0 to 1.0. If an integer argument N is specified, it is used as the seed value:

mysql> SELECT RAND( );
        -> 0.9233482386203
mysql> SELECT RAND(20);
        -> 0.15888261251047
mysql> SELECT RAND(20);
        -> 0.15888261251047
mysql> SELECT RAND( );
        -> 0.63553050033332
mysql> SELECT RAND( );
        -> 0.70100469486881

You can’t use a column with RAND( ) values in an ORDER BY clause because ORDER BY would evaluate the column multiple times. In MySQL Version 3.23, you can, however, do SELECT * FROM table_name ORDER BY RAND( ).

This is useful to get a random sample of a set SELECT * FROM table1,table2 WHERE a=b AND c<d ORDER BY RAND( ) LIMIT 1000.

Note that a RAND( ) in a WHERE clause will be re-evaluated every time the WHERE is executed.

RAND( ) is not meant to be a perfect random generator, but instead a fast way to generate ad hoc random numbers that will be portable between platforms for the same MySQL version.

LEAST(X,Y,...)

With two or more arguments, returns the smallest (minimum-valued) argument. The arguments are compared using the following rules:

If the return value is used in an INTEGER context, or all arguments are integer-valued, they are compared as integers.
If the return value is used in a REAL context, or all arguments are real-valued, they are compared as reals.
If any argument is a case-sensitive string, the arguments are compared as case-sensitive strings.
In other cases, the arguments are compared as case-insensitive strings:
```
mysql> SELECT LEAST(2,0);
        -> 0
mysql> SELECT LEAST(34.0,3.0,5.0,767.0);
        -> 3.0
mysql> SELECT LEAST("B","A","C");
        -> "A"
```
In MySQL versions prior to Version 3.22.5, you can use MIN( ) instead of LEAST.

GREATEST(X,Y,...)

Returns the largest (maximum-valued) argument. The arguments are compared using the same rules as for LEAST:

mysql> SELECT GREATEST(2,0);
        -> 2
mysql> SELECT GREATEST(34.0,3.0,5.0,767.0);
        -> 767.0
mysql> SELECT GREATEST("B","A","C");
        -> "C"

In MySQL versions prior to Version 3.22.5, you can use MAX( ) instead of GREATEST.

DEGREES(X)

Returns the argument X, converted from radians to degrees:

mysql> SELECT DEGREES(PI( ));
        -> 180.000000

RADIANS(X)

Returns the argument X, converted from degrees to radians:

mysql> SELECT RADIANS(90);
        -> 1.570796

TRUNCATE(X,D)

Returns the number X, truncated to D decimals. If D is 0, the result will have no decimal point or fractional part:

mysql> SELECT TRUNCATE(1.223,1);
        -> 1.2
mysql> SELECT TRUNCATE(1.999,1);
        -> 1.9
mysql> SELECT TRUNCATE(1.999,0);
        -> 1

Note that as decimal numbers are normally not stored as exact numbers in computers, but as double values, you may be fooled by the following result:

mysql> SELECT TRUNCATE(10.28*100,0);
       -> 1027

This happens because 10.28 is actually stored as something like 10.2799999999999999.

Date and Time Functions

See Section 6.2.2, for a description of the range of values each type has and the valid formats in which date and time 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;

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

WEEKDAY(date)

Returns the weekday index for date (0 = Monday, 1 = Tuesday, ... 6 = Sunday):

mysql> SELECT WEEKDAY('1997-10-04 22:23:00');
        -> 5
mysql> SELECT WEEKDAY('1997-11-05');
        -> 2

DAYOFMONTH(date)

Returns the day of the month for date, in the range 1 to 31:

mysql> SELECT DAYOFMONTH('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

MONTH(date)

Returns the month for date, in the range 1 to 12:

mysql> SELECT MONTH('1998-02-03');
        -> 2

DAYNAME(date)

Returns the name of the weekday for date:

mysql> SELECT DAYNAME("1998-02-05");
        -> 'Thursday'

MONTHNAME(date)

Returns the name of the month for date:

mysql> SELECT MONTHNAME("1998-02-05");
        -> 'February'

QUARTER(date)

Returns the quarter of the year for date, in the range 1 to 4:

mysql> SELECT QUARTER('98-04-01');
        -> 2

WEEK(date) , WEEK(date,first)

With a single argument, returns the week for date, in the range 0 to 53 (yes, there may be the beginnings of a week 53), for locations where Sunday is the first day of the week. The two-argument form of WEEK( ) allows you to specify whether the week starts on Sunday or Monday. The week starts on Sunday if the second argument is 0, on Monday if the second argument is 1:

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(#,0) was changed to match the calendar in the USA.

YEAR(date)

Returns the year for date, in the range 1000 to 9999:

mysql> SELECT YEAR('98-02-03');
        -> 1998

YEARWEEK(date) , YEARWEEK(date,first)

Returns year and week for a date. The second arguments works exactly like the second argument to WEEK( ). Note that the year 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

HOUR(time)

Returns the hour for time, in the range 0 to 23:

mysql> SELECT HOUR('10:05:03');
        -> 10

MINUTE(time)

Returns the minute for time, in the range 0 to 59:

mysql> SELECT MINUTE('98-02-03 10:05:03');
        -> 5

SECOND(time)

Returns the second for time, in the range 0 to 59:

mysql> SELECT SECOND('10:05:03');
        -> 3

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

DATE_ADD(date,INTERVAL expr type) , DATE_SUB(date,INTERVAL expr type) , ADDDATE(date,INTERVAL expr type) , SUBDATE(date,INTERVAL expr type)

These functions perform date arithmetic. They are new for MySQL Version 3.22. ADDDATE( ) and SUBDATE( ) are synonyms for DATE_ADD( ) and DATE_SUB( ).

In MySQL Version 3.23, you can use + and - instead of DATE_ADD( ) and DATE_SUB( ) if the expression on the right side is a date or datetime column. (See example 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 related function EXTRACT(type FROM date) returns the ‘type’ interval from the date.

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"

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

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 or subtract a date value against something that contains a time part, the date value will be 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 incorrect 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 word INTERVAL and the type keyword are not case-sensitive.

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

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.

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.

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 (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 (01..12)
%c	Month, numeric (1..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 [AP]M)
%T	Time, 24-hour (hh:mm:ss)
%S	Seconds (00..59)
%s	Seconds (00..59)
%p	AM or PM
%w	Day of the week (0=Sunday..6=Saturday)
%U	Week (0..53), where Sunday is the first day of the week
%u	Week (0..53), where Monday is the first day of the week
%V	Week (1..53), where Sunday is the first day of the week; used with '%X’
%v	Week (1..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:

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'

As of MySQL Version 3.23, the % character is required before format specifier characters. In earlier versions of MySQL, % was optional.

TIME_FORMAT(time,format)

This is used like the preceding 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.

CURDATE( ) , CURRENT_DATE

Returns today’s 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

CURTIME( ) , CURRENT_TIME

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

NOW( ) , SYSDATE( ) , CURRENT_TIMESTAMP

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

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 will return the internal timestamp value directly, with no implicit “string-to-unix-time- stamp” conversion. If you give UNIX_TIMESTAMP( ) a wrong or out-of-range date, it will return 0.

If you want to subtract UNIX_TIMESTAMP( ) columns, you may want to cast the result to signed integers. See Section 6.3.5.

FROM_UNIXTIME(unix_timestamp)

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

FROM_UNIXTIME(unix_timestamp,format)

Returns a string representation of the Unix timestamp, 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');
        -> '1997 23rd December 03:43:30 1997'

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

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

Cast Functions

The syntax of the CAST function is:

CAST(expression AS type)

CONVERT(expression,type)

Where type is one of:

BINARY
DATE
DATETIME
SIGNED {INTEGER}
TIME
UNSIGNED {INTEGER}

CAST( ) is ANSI SQL99 syntax and CONVERT( ) is ODBC syntax.

The cast function is mainly useful when you want to create a column with a specific type in a CREATE ... SELECT:

CREATE TABLE new_table SELECT CAST('2000-01-01' AS DATE);

CAST(string AS BINARY) is the same thing as BINARY string.

To cast a string to a numeric value, you don’t normally have to do anything; just use the string value as if it were a number:

mysql> SELECT 1+'1';
        -> 2

MySQL supports arithmetic with both signed and unsigned 64-bit values. If you are using numerical operations (like +) and one of the operands is unsigned integer, the result will be unsigned. You can override this by using the SIGNED and UNSIGNED cast operators, which will cast the operation to a signed or unsigned 64-bit integer, respectively.

mysql> SELECT CAST(1-2 AS UNSIGNED)
        -> 18446744073709551615
mysql> SELECT CAST(CAST(1-2 AS UNSIGNED) AS SIGNED);
        -> -1

Note that if either operation is a floating-point value (in this context DECIMAL( ) is regarded as a floating-point value), the result will be a floating-point value and is not affected by the preceding rule.

mysql> SELECT CAST(1 AS UNSIGNED) -2.0
        -> -1.0

If you are using a string in an arithmetic operation, this is converted to a floating-point number.

The CAST( ) and CONVERT( ) functions were added in MySQL 4.0.2.

The handing of unsigned values was changed in MySQL 4.0 to be able to support BIGINT values properly. If you have some code that you want to run in both MySQL 4.0 and 3.23 (in which case you probably can’t use the CAST function), you can use the following trick to get a signed result when subtracting two unsigned integer columns:

SELECT (unsigned_column_1+0.0)-(unsigned_column_2+0.0);

The idea is that the columns are converted to floating-point before doing the subtraction.

If you get a problem with UNSIGNED columns in your old MySQL application when porting to MySQL 4.0, you can use the --sql-mode=NO_UNSIGNED_SUBTRACTION option when starting mysqld. Note, however, that as long as you use this, you will not be able to make efficient use of the UNSIGNED BIGINT column type.

Other Functions

Bit functions

MySQL uses BIGINT (64-bit) arithmetic for bit operations, so these operators have a maximum range of 64 bits:

|

Bitwise OR:

mysql> SELECT 29 | 15;
        -> 31