Join our community in the tech forums for uncut technology discussion.
Expressions can be used at several points in SQL statements, such as in the
ORDER BY or HAVING clauses of SELECT statements, in the
WHERE clause of a SELECT, DELETE, or UPDATE
statement, or in SET statements. Expressions can be written using
literal values, column values, NULL, functions, and operators.
This chapter describes the functions and operators that are allowed for
writing expressions in MySQL.
An expression that contains NULL always produces a NULL value
unless otherwise indicated in the documentation for a particular function or
operator.
Note: By default, there must be no whitespace between a function
name and the parenthesis 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 function
arguments are permitted, though.
You can tell the MySQL server to accept spaces after function names by
starting it with the --sql-mode=IGNORE_SPACE option. Individual client
programs can request this behavior by using the
CLIENT_IGNORE_SPACE option for mysql_real_connect().
In either case, all function names will become reserved words.
See section 5.2.2 The Server SQL Mode.
For the sake of brevity, most examples in this chapter display the output
from the mysql program in abbreviated form. Instead of showing
examples in this format:
mysql> SELECT MOD(29,9);
+-----------+
| mod(29,9) |
+-----------+
| 2 |
+-----------+
1 rows in set (0.00 sec)
This format is used instead:
mysql> SELECT MOD(29,9);
-> 2
Operator precedences are shown in the following list, from lowest precedence
to the highest. Operators that are shown together on a line have the same
precedence.
:=
||, OR, XOR
&&, AND
NOT
BETWEEN, CASE, WHEN, THEN, ELSE
=, <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN
|
&
<<, >>
-, +
*, /, DIV, %, MOD
^
- (unary minus), ~ (unary bit inversion)
!
BINARY, COLLATE
The precedence shown for NOT is as of MySQL 5.0.2. For earlier
versions, or from 5.0.2 on if the HIGH_NOT_PRECEDENCE SQL mode is
enabled, the precedence of NOT is the same as that of the !
operator.
See section 5.2.2 The Server SQL Mode.
( ... )
-
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 operations result in a value of 1 (TRUE), 0 (FALSE),
or NULL. These operations work for both numbers and strings. Strings
are automatically converted to numbers and numbers to strings as necessary.
Some of the functions in this section (such as LEAST() and
GREATEST()) return values other than 1 (TRUE), 0
(FALSE), or NULL. However, the value they return is based on
comparison operations performed as described by the following rules.
MySQL compares values using the following rules:
-
If one or both arguments are
NULL, the result of the comparison is
NULL, except for the NULL-safe <=> equality comparison
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. Note that this is not done for arguments in IN()!
To be safe, always use complete datetime/date/time strings when doing
comparisons.
-
In all other cases, the arguments are compared as floating-point (real)
numbers.
By default, string comparisons are not case sensitive and use the
current character set (ISO-8859-1 Latin1 by default, which also works
excellently for English).
To convert a value to a specific type for comparison purposes, you can
use the CAST() function. String values can be converted to a
different character set using CONVERT().
See section 12.7 Cast Functions and Operators.
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
Note that when you are comparing a string column with a number, MySQL can't
use an index on the column to quickly look up the value. If str_col
is an indexed string column, the index cannot be used when performing the
lookup in the following statement:
SELECT * FROM tbl_name WHERE str_col=1;
The reason for this is that there are many different strings that may
convert to the value 1: '1', ' 1', '1a', ...
=
-
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
<=>
-
NULL-safe equal.
This operator performs an equality comparison like the = operator, but
returns 1 rather than NULL if both operands are NULL,
and 0 rather than NULL if one operand is NULL.
mysql> SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL;
-> 1, 1, 0
mysql> SELECT 1 = 1, NULL = NULL, 1 = NULL;
-> 1, NULL, NULL
<=> was added in MySQL 3.23.0.
<>
-
!=
-
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
IS boolean_value
-
IS NOT boolean_value
-
Tests whether a value against a boolean value, where boolean_value can
be
TRUE, FALSE, or UNKNOWN.
mysql> SELECT 1 IS TRUE, 0 IS FALSE, NULL IS UNKNOWN;
-> 1, 1, 1
mysql> SELECT 1 IS NOT UNKNOWN, 0 IS NOT UNKNOWN, NULL IS NOT UNKNOWN;
-> 1, 1, 0
IS [NOT] boolean_value syntax was added in MySQL 5.0.2.
IS NULL
-
IS NOT NULL
-
Tests 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 ODBC programs, MySQL supports the following
extra features when using IS NULL:
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. Otherwise type conversion takes place according to the rules
described at the beginning of this section, but applied to all the three
arguments. Note: Before MySQL
4.0.5, arguments were converted to the type of expr instead.
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
-
This is the same as
NOT (expr BETWEEN min AND max).
COALESCE(value,...)
-
Returns the first non-
NULL value in the list.
mysql> SELECT COALESCE(NULL,1);
-> 1
mysql> SELECT COALESCE(NULL,NULL,NULL);
-> NULL
COALESCE() was added in MySQL 3.23.3.
GREATEST(value1,value2,...)
-
With two or more arguments, 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'
Before MySQL 3.22.5, you can use MAX()
instead of GREATEST().
expr IN (value,...)
-
Returns
1 if expr is any of the values in the IN list,
else returns 0. If all values are constants, they are
evaluated according to the type of expr and sorted. The search for the
item then is 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
The number of values in the IN list is only limited by the
max_allowed_packet value.
To comply with the SQL standard,
from MySQL 4.1 on
IN returns NULL
not only if the expression on the left hand side is NULL, but also if
no match is found in the list and one of the expressions in the list is
NULL.
From MySQL 4.1 on, IN() syntax also is used to write certain types of
subqueries.
See section 13.1.8.3 Subqueries with ANY, IN, and SOME.
expr NOT IN (value,...)
-
This is the 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!
INTERVAL(N,N1,N2,N3,...)
-
Returns
0 if N < N1, 1 if N < N2
and so on or -1 if N is NULL. 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
LEAST(value1,value2,...)
-
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'
Before MySQL 3.22.5, you can use MIN()
instead of LEAST().
Note that the preceding conversion rules can produce strange results in some
borderline cases:
mysql> SELECT CAST(LEAST(3600, 9223372036854775808.0) as SIGNED);
-> -9223372036854775808
This happens because MySQL reads 9223372036854775808.0 in an
integer context. The integer representation is not good enough to
hold the value, so it wraps to a signed integer.
In SQL, all logical operators evaluate to TRUE, FALSE, or NULL (UNKNOWN).
In MySQL, these are implemented as 1 (TRUE), 0 (FALSE),
and NULL. Most of this is common to different SQL database servers,
although some servers may return any non-zero value for TRUE.
NOT
-
!
-
Logical NOT.
Evaluates to
1 if the operand is 0,
to 0 if the operand is non-zero,
and NOT NULL returns NULL.
mysql> SELECT NOT 10;
-> 0
mysql> SELECT NOT 0;
-> 1
mysql> SELECT NOT NULL;
-> NULL
mysql> SELECT ! (1+1);
-> 0
mysql> SELECT ! 1+1;
-> 1
The last example produces 1 because the expression evaluates
the same way as (!1)+1.
AND
-
&&
-
Logical AND.
Evaluates to
1 if all operands are non-zero and not NULL,
to 0 if one or more operands are 0,
otherwise NULL is returned.
mysql> SELECT 1 && 1;
-> 1
mysql> SELECT 1 && 0;
-> 0
mysql> SELECT 1 && NULL;
-> NULL
mysql> SELECT 0 && NULL;
-> 0
mysql> SELECT NULL && 0;
-> 0
Please note that MySQL versions prior to 4.0.5 stop evaluation when
a NULL is encountered, rather than continuing the process to
check for possible 0 values. This means that in these versions,
SELECT (NULL AND 0) returns NULL instead of 0.
As of MySQL 4.0.5, the code has been re-engineered so that the result is
always as prescribed by the SQL standards while still using the
optimization wherever possible.
OR
-
||
-
Logical OR.
When both operands are non-
NULL, the result is 1 if any
operand is non-zero, and 0 otherwise. With a NULL operand,
the result is 1 if the other operand is non-zero, and NULL
otherwise. If both operands are NULL, the result is NULL.
mysql> SELECT 1 || 1;
-> 1
mysql> SELECT 1 || 0;
-> 1
mysql> SELECT 0 || 0;
-> 0
mysql> SELECT 0 || NULL;
-> NULL
mysql> SELECT 1 || NULL;
-> 1
XOR
-
Logical XOR.
Returns
NULL if either operand is NULL.
For non-NULL operands, evaluates to 1 if an odd number
of operands is non-zero,
otherwise 0 is returned.
mysql> SELECT 1 XOR 1;
-> 0
mysql> SELECT 1 XOR 0;
-> 1
mysql> SELECT 1 XOR NULL;
-> NULL
mysql> SELECT 1 XOR 1 XOR 1;
-> 1
a XOR b is mathematically equal to
(a AND (NOT b)) OR ((NOT a) and b).
XOR was added in MySQL 4.0.2.
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 that is true. If there was no matching result
value, the result after ELSE is returned, or NULL if there is no
ELSE part.
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).
CASE was added in MySQL 3.23.3.
IF(expr1,expr2,expr3)
-
If expr1 is TRUE (
expr1 <> 0 and expr1 <> NULL) then
IF() returns expr2, else 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'
If only one of expr2 or expr3 is explicitly NULL, the
result type of the IF() function is the type of non-NULL
expression. (This behavior is new in MySQL 4.0.3.)
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 shown, 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
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, the result is case
sensitive if either string is case sensitive (starting from MySQL
3.23.51).
IFNULL(expr1,expr2)
-
If expr1 is not
NULL, IFNULL() returns expr1,
else 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'
In MySQL 4.0.6 and above, the default result value of
IFNULL(expr1,expr2) is the more ``general'' of the two expressions,
in the order STRING, REAL, or INTEGER. The difference
from earlier MySQL versions is mostly notable when you create a table
based on expressions or MySQL has to internally store a value from
IFNULL() in a temporary table.
CREATE TABLE tmp SELECT IFNULL(1,'test') AS test;
As of MySQL 4.0.6, the type for the test column is CHAR(4),
whereas in earlier versions the type would be BIGINT.
NULLIF(expr1,expr2)
-
Returns
NULL if expr1 = expr2 is true, else returns expr1.
This is the same as CASE WHEN expr1 = expr2 THEN NULL ELSE expr1 END.
mysql> SELECT NULLIF(1,1);
-> NULL
mysql> SELECT NULLIF(1,2);
-> 1
Note that MySQL evaluates expr1 twice if the arguments are not equal.
NULLIF() was added in MySQL 3.23.15.
String-valued functions return NULL if the length of the result would
be greater than the value of the max_allowed_packet system variable.
See section 7.5.2 Tuning Server Parameters.
For functions that operate on string positions,
the first position is numbered 1.
ASCII(str)
-
Returns the numeric value of the leftmost character of the string
str. Returns
0 if str is the empty string. Returns
NULL if str is NULL.
ASCII() works for characters with numeric values from 0 to
255.
mysql> SELECT ASCII('2');
-> 50
mysql> SELECT ASCII(2);
-> 50
mysql> SELECT ASCII('dx');
-> 100
See also the ORD() function.
BIN(N)
-
Returns a string representation of the binary value of N, where
N is a longlong (
BIGINT) number. This is equivalent to
CONV(N,10,2). Returns NULL if N is NULL.
mysql> SELECT BIN(12);
-> '1100'
BIT_LENGTH(str)
-
Returns the length of the string str in bits.
mysql> SELECT BIT_LENGTH('text');
-> 32
BIT_LENGTH() was added in MySQL 4.0.2.
CHAR(N,...)
-
CHAR() interprets the arguments as integers and returns a string
consisting of the characters given by the code values of those
integers. NULL values are skipped.
mysql> SELECT CHAR(77,121,83,81,'76');
-> 'MySQL'
mysql> SELECT CHAR(77,77.3,'77.3');
-> 'MMM'
CHAR_LENGTH(str)
-
Returns the length of the string str, measured in characters.
A multi-byte character counts as a single character.
This means that for a string containing five two-byte characters,
LENGTH() returns 10, whereas CHAR_LENGTH() returns
5.
CHARACTER_LENGTH(str)
-
CHARACTER_LENGTH() is a synonym for CHAR_LENGTH().
COMPRESS(string_to_compress)
-
Compresses a string. This function requires MySQL to have been compiled
with a compression library such as
zlib. Otherwise, the return
value is always NULL. The compressed string can be uncompressed with
UNCOMPRESS().
mysql> SELECT LENGTH(COMPRESS(REPEAT('a',1000)));
-> 21
mysql> SELECT LENGTH(COMPRESS(''));
-> 0
mysql> SELECT LENGTH(COMPRESS('a'));
-> 13
mysql> SELECT LENGTH(COMPRESS(REPEAT('a',16)));
-> 15
The compressed string contents are stored the following way:
-
Empty strings are stored as empty strings.
-
Non-empty strings are stored as a four-byte length of the uncompressed string
(low byte first), followed by the compressed string. If the
string ends with space, an extra `.' character is added to avoid
problems with endspace trimming should the result be stored in a
CHAR
or VARCHAR column. (Use of CHAR or VARCHAR to store
compressed strings is not recommended. It is better to use a BLOB
column instead.)
COMPRESS() was added in MySQL 4.1.1.
CONCAT(str1,str2,...)
-
Returns the string that results from concatenating the arguments. Returns
NULL if any argument is NULL. May have one or more arguments.
If all arguments are non-binary strings, the result is a non-binary string.
If the arguments include any binary strings, the result is a binary string.
A numeric argument is converted to its equivalent binary string form.
mysql> SELECT CONCAT('My', 'S', 'QL');
-> 'MySQL'
mysql> SELECT CONCAT('My', NULL, 'QL');
-> NULL
mysql> SELECT CONCAT(14.3);
-> '14.3'
CONCAT_WS(separator,str1,str2,...)
-
CONCAT_WS() stands for CONCAT With Separator and is a special form of
CONCAT(). The first argument is the separator for the rest of the
arguments.
The separator is added between the strings to be concatenated.
The separator can be a string as can the rest of the
arguments. If the separator is NULL, the result is NULL.
The function skips any NULL values after the
separator argument.
mysql> SELECT CONCAT_WS(',','First name','Second name','Last Name');
-> 'First name,Second name,Last Name'
mysql> SELECT CONCAT_WS(',','First name',NULL,'Last Name');
-> 'First name,Last Name'
Before MySQL 4.0.14, CONCAT_WS() skips empty strings as well as
NULL values.
CONV(N,from_base,to_base)
-
Converts numbers between different number bases. Returns a string
representation of the number N, converted from base from_base
to base to_base. Returns
NULL if any argument is NULL.
The argument N is interpreted as an integer, but may be specified as
an integer or a string. The minimum base is 2 and the maximum base is
36. If to_base is a negative number, N is regarded as a
signed number. Otherwise, N is treated as unsigned. CONV() works
with 64-bit precision.
mysql> SELECT CONV('a',16,2);
-> '1010'
mysql> SELECT CONV('6E',18,8);
-> '172'
mysql> SELECT CONV(-17,10,-18);
-> '-H'
mysql> SELECT CONV(10+'10'+'10'+0xa,10,10);
-> '40'
ELT(N,str1,str2,str3,...)
-
Returns str1 if N =
1, str2 if N =
2, and so on. Returns NULL if N is less than 1
or greater than the number of arguments. ELT() is the complement of
FIELD().
mysql> SELECT ELT(1, 'ej', 'Heja', 'hej', 'foo');
-> 'ej'
mysql> SELECT ELT(4, 'ej', 'Heja', 'hej', 'foo');
-> 'foo'
EXPORT_SET(bits,on,off[,separator[,number_of_bits]])
-
Returns a string in which for every bit set in the value bits, you
get an on string and for every reset bit you get an off
string. Bits in bits are examined from right to left (from low-order
to high-order bits). Strings are added to the result from left to right,
separated by the separator string (default `,'). The number of
bits examined is given by number_of_bits (default 64).
mysql> SELECT EXPORT_SET(5,'Y','N',',',4);
-> 'Y,N,Y,N'
mysql> SELECT EXPORT_SET(6,'1','0',',',10);
-> '0,1,1,0,0,0,0,0,0,0'
FIELD(str,str1,str2,str3,...)
-
Returns the index of str in the str1, str2,
str3,
... list.
Returns 0 if str is not found.
If str is NULL, the return value is 0 because
NULL fails equality comparison with any value.
FIELD() is the complement of ELT().
mysql> SELECT FIELD('ej', 'Hej', 'ej', 'Heja', 'hej', 'foo');
-> 2
mysql> SELECT FIELD('fo', 'Hej', 'ej', 'Heja', 'hej', 'foo');
-> 0
FIND_IN_SET(str,strlist)
-
Returns a value
1 to N if the string str is in the string list
strlist consisting of N substrings. A string list is a string
composed of substrings separated by `,' characters. If the first
argument is a constant string and the second is a column of type SET,
the FIND_IN_SET() function is optimized to use bit arithmetic.
Returns 0 if str is not in strlist or if strlist
is the empty string. Returns NULL if either argument is NULL.
This function will not work properly if the first argument contains a comma
(`,') character.
mysql> SELECT FIND_IN_SET('b','a,b,c,d');
-> 2
HEX(N_or_S)
-
If N_OR_S is a number, returns a string representation of the hexadecimal
value of N, where N is a longlong (
BIGINT) number.
This is equivalent to CONV(N,10,16).
From MySQL 4.0.1 and up,
if N_OR_S is a string, returns a hexadecimal string of N_OR_S
where each character in N_OR_S is converted to two hexadecimal digits.
mysql> SELECT HEX(255);
-> 'FF'
mysql> SELECT 0x616263;
-> 'abc'
mysql> SELECT HEX('abc');
-> 616263
INSERT(str,pos,len,newstr)
-
Returns the string str, with the substring beginning at position
pos and len characters long replaced by the string
newstr. Returns the original string if pos is not within
the length of the string. Replaces the rest of the string from position
pos is len is not within the length of the rest of the string.
Returns
NULL if any argument is null.
mysql> SELECT INSERT('Quadratic', 3, 4, 'What');
-> 'QuWhattic'
mysql> SELECT INSERT('Quadratic', -1, 4, 'What');
-> 'Quadratic'
mysql> SELECT INSERT('Quadratic', 3, 100, 'What');
-> 'QuWhat'
This function is multi-byte safe.
INSTR(str,substr)
-
Returns the position of the first occurrence of substring substr in
string str. This is the same as the two-argument form of
LOCATE(), except that the arguments are swapped.
mysql> SELECT INSTR('foobarbar', 'bar');
-> 4
mysql> SELECT INSTR('xbar', 'foobar');
-> 0
This function is multi-byte safe. In MySQL 3.23, this function is case
sensitive. For 4.0 on, it is case sensitive only if either argument is a
binary string.
LCASE(str)
-
LCASE() is a synonym for LOWER().
LEFT(str,len)
-
Returns the leftmost len characters from the string str.
mysql> SELECT LEFT('foobarbar', 5);
-> 'fooba'
LENGTH(str)
-
Returns the length of the string str, measured in bytes.
A multi-byte character counts as multiple bytes.
This means that for a string containing five two-byte characters,
LENGTH() returns 10, whereas CHAR_LENGTH() returns
5.
mysql> SELECT LENGTH('text');
-> 4
LOAD_FILE(file_name)
-
Reads the file and returns the file contents as a string. The file
must be located on the server, you must specify the full pathname to the
file, and you must have the
FILE privilege. The file must
be readable by all and be smaller than max_allowed_packet bytes.
If the file doesn't exist or cannot be read because one of the preceding
conditions is not satisfied, the function returns NULL.
mysql> UPDATE tbl_name
SET blob_column=LOAD_FILE('/tmp/picture')
WHERE id=1;
Before MySQL 3.23, you must read the file inside your application and create
an INSERT statement to update the database with the file contents.
If you are using the MySQL++ library, one way to do this can be found in the
MySQL++ manual, available at
http://dev.mysql.com/doc/.
LOCATE(substr,str)
-
LOCATE(substr,str,pos)
-
The first syntax
returns the position of the first occurrence of substring substr
in string str.
The second syntax
returns the position of the first occurrence of substring substr in
string str, starting at position pos.
Returns
0 if substr is not in str.
mysql> SELECT LOCATE('bar', 'foobarbar');
-> 4
mysql> SELECT LOCATE('xbar', 'foobar');
-> 0
mysql> SELECT LOCATE('bar', 'foobarbar',5);
-> 7
This function is multi-byte safe. In MySQL 3.23, this function is case
sensitive. For 4.0 on, it is case sensitive only if either argument is a
binary string.
LOWER(str)
-
Returns the string str with all characters changed to lowercase
according to the current character set mapping (the default is ISO-8859-1
Latin1).
mysql> SELECT LOWER('QUADRATICALLY');
-> 'quadratically'
This function is multi-byte safe.
LPAD(str,len,padstr)
-
Returns the string str, left-padded with the string padstr
to a length of len characters. If str is longer
than len, the return value is shortened to len characters.
mysql> SELECT LPAD('hi',4,'??');
-> '??hi'
mysql> SELECT LPAD('hi',1,'??');
-> 'h'
LTRIM(str)
-
Returns the string str with leading space characters removed.
mysql> SELECT LTRIM(' barbar');
-> 'barbar'
This function is multi-byte safe.
MAKE_SET(bits,str1,str2,...)
-
Returns a set value (a string containing substrings separated by `,'
characters) consisting of the strings that have the corresponding bit in
bits set. str1 corresponds to bit 0, str2 to bit 1,
and so on.
NULL values in str1, str2, ...
are not appended to the result.
mysql> SELECT MAKE_SET(1,'a','b','c');
-> 'a'
mysql> SELECT MAKE_SET(1 | 4,'hello','nice','world');
-> 'hello,world'
mysql> SELECT MAKE_SET(1 | 4,'hello','nice',NULL,'world');
-> 'hello'
mysql> SELECT MAKE_SET(0,'a','b','c');
-> ''
MID(str,pos,len)
-
MID(str,pos,len) is a synonym for
SUBSTRING(str,pos,len).
OCT(N)
-
Returns a string representation of the octal value of N, where
N is a longlong (
BIGINT)number. This is equivalent to
CONV(N,10,8).
Returns NULL if N is NULL.
mysql> SELECT OCT(12);
-> '14'
OCTET_LENGTH(str)
-
OCTET_LENGTH() is a synonym for LENGTH().
ORD(str)
-
If the leftmost character of the string str is a multi-byte character,
returns the code for that character, calculated from the numeric values
of its constituent bytes using this formula:
(1st byte code)
+ (2nd byte code * 256)
+ (3rd byte code * 256^2) ...
If the leftmost character is not a multi-byte character, ORD()
returns the same value as the ASCII() function.
mysql> SELECT ORD('2');
-> 50
POSITION(substr IN str)
-
POSITION(substr IN str) is a synonym for LOCATE(substr,str).
QUOTE(str)
-
Quotes a string to produce a result that can be used as a properly escaped
data value in an SQL statement. The string is returned surrounded by single
quotes and with each instance of single quote (`''), backslash (`\'),
ASCII NUL, and Control-Z preceded by a backslash. If the argument is
NULL, the return value is the word ``NULL'' without surrounding
single quotes.
The QUOTE() function was added in MySQL 4.0.3.
mysql> SELECT QUOTE('Don\'t!');
-> 'Don\'t!'
mysql> SELECT QUOTE(NULL);
-> NULL
REPEAT(str,count)
-
Returns a string consisting of the string str repeated count
times. If
count <= 0, returns an empty string. Returns NULL if
str or count are NULL.
mysql> SELECT REPEAT('MySQL', 3);
-> 'MySQLMySQLMySQL'
REPLACE(str,from_str,to_str)
-
Returns the string str with all occurrences of the string
from_str replaced by the string to_str.
mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww');
-> 'WwWwWw.mysql.com'
This function is multi-byte safe.
REVERSE(str)
-
Returns the string str with the order of the characters reversed.
mysql> SELECT REVERSE('abc');
-> 'cba'
This function is multi-byte safe.
RIGHT(str,len)
-
Returns the rightmost len characters from the string str.
mysql> SELECT RIGHT('foobarbar', 4);
-> 'rbar'
This function is multi-byte safe.
RPAD(str,len,padstr)
-
Returns the string str, right-padded with the string padstr
to a length of len characters. If str is longer
than len, the return value is shortened to len characters.
mysql> SELECT RPAD('hi',5,'?');
-> 'hi???'
mysql> SELECT RPAD('hi',1,'?');
-> 'h'
This function is multi-byte safe.
RTRIM(str)
-
Returns the string str with trailing space characters removed.
mysql> SELECT RTRIM('barbar ');
-> 'barbar'
This function is multi-byte safe.
SOUNDEX(str)
-
Returns a soundex string from str. Two strings that sound almost the
same should have identical soundex strings. A standard soundex string
is four characters long, but the
SOUNDEX() function returns an
arbitrarily long string. You can use SUBSTRING() on the result to get
a standard soundex string. All non-alphabetic characters are ignored in the
given string. All international alphabetic characters outside the A-Z range
are treated as vowels.
mysql> SELECT SOUNDEX('Hello');
-> 'H400'
mysql> SELECT SOUNDEX('Quadratically');
-> 'Q36324'
Note: This function implements the original Soundex algorithm,
not the more popular enhanced version (also described by D. Knuth).
The difference is that original version discards vowels first and then
duplicates, whereas the enhanced version discards duplicates first and
then vowels.
expr1 SOUNDS LIKE expr2
-
This is the same as
SOUNDEX(expr1) = SOUNDEX(expr2). It is
available only in MySQL 4.1 or later.
SPACE(N)
-
Returns a string consisting of N space characters.
mysql> SELECT SPACE(6);
-> ' '
SUBSTRING(str,pos)
-
SUBSTRING(str FROM pos)
-
SUBSTRING(str,pos,len)
-
SUBSTRING(str FROM pos FOR len)
-
The forms without a len argument
return a substring from string str starting at position pos.
The forms with a len argument
return a substring len characters long from string str,
starting at position pos.
The forms that use
FROM are standard SQL syntax.
mysql> SELECT SUBSTRING('Quadratically',5);
-> 'ratically'
mysql> SELECT SUBSTRING('foobarbar' FROM 4);
-> 'barbar'
mysql> SELECT SUBSTRING('Quadratically',5,6);
-> 'ratica'
This function is multi-byte safe.
SUBSTRING_INDEX(str,delim,count)
-
Returns the substring from string str before count
occurrences of the delimiter delim.
If count is positive, everything to the left of the final delimiter
(counting from the left) is returned.
If count is negative, everything to the right of the final delimiter
(counting from the right) is returned.
mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', 2);
-> 'www.mysql'
mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', -2);
-> 'mysql.com'
This function is multi-byte safe.
TRIM([{BOTH | LEADING | TRAILING} [remstr] FROM] str)
-
TRIM(remstr FROM] str)
-
Returns the string str with all remstr prefixes and/or suffixes
removed. If none of the specifiers
BOTH, LEADING, or
TRAILING is given, BOTH is assumed. If remstr is optional
and not specified, spaces are removed.
mysql> SELECT TRIM(' bar ');
-> 'bar'
mysql> SELECT TRIM(LEADING 'x' FROM 'xxxbarxxx');
-> 'barxxx'
mysql> SELECT TRIM(BOTH 'x' FROM 'xxxbarxxx');
-> 'bar'
mysql> SELECT TRIM(TRAILING 'xyz' FROM 'barxxyz');
-> 'barx'
This function is multi-byte safe.
UCASE(str)
-
UCASE() is a synonym for UPPER().
UNCOMPRESS(string_to_uncompress)
-
Uncompresses a string compressed by the
COMPRESS() function.
If the argument is not a compressed value, the result is NULL.
This function requires MySQL to have been compiled with a compression library
such as zlib. Otherwise, the return value is always NULL.
mysql> SELECT UNCOMPRESS(COMPRESS('any string'));
-> 'any string'
mysql> SELECT UNCOMPRESS('any string');
-> NULL
UNCOMPRESS() was added in MySQL 4.1.1.
UNCOMPRESSED_LENGTH(compressed_string)
-
Returns the length of a compressed string before compression.
mysql> SELECT UNCOMPRESSED_LENGTH(COMPRESS(REPEAT('a',30)));
-> 30
UNCOMPRESSED_LENGTH() was added in MySQL 4.1.1.
UNHEX(str)
-
Does the opposite of
HEX(str). That is, it interprets each pair of
hexadecimal digits in the argument as a number and converts it to the
character represented by the number. The resulting characters are returned as
a binary string.
mysql> SELECT UNHEX('4D7953514C');
-> 'MySQL'
mysql> SELECT 0x4D7953514C;
-> 'MySQL'
mysql> SELECT UNHEX(HEX('string'));
-> 'string'
mysql> SELECT HEX(UNHEX('1267'));
-> '1267'
UNHEX() was added in MySQL 4.1.2.
UPPER(str)
-
Returns the string str with all characters changed to uppercase
according to the current character set mapping (the default is ISO-8859-1
Latin1).
mysql> SELECT UPPER('Hej');
-> 'HEJ'
This function is multi-byte safe.
MySQL automatically converts numbers to strings as necessary, and
vice versa.
mysql> SELECT 1+'1';
-> 2
mysql> SELECT CONCAT(2,' test');
-> '2 test'
If you want to convert a number to a string explicitly, use the CAST()
or CONCAT() function:
mysql> SELECT 38.8, CAST(38.8 AS CHAR);
-> 38.8, '38.8'
mysql> SELECT 38.8, CONCAT(38.8);
-> 38.8, '38.8'
CAST() is preferable, but it is unavailable before MySQL 4.0.2.
If a string function is given a binary string as an argument, the resulting
string is also a binary string. A number converted to a string is treated as
a binary string. This affects only comparisons.
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). If either expr or pat is NULL, the result is
NULL.
With LIKE you can use the following two wildcard characters
in the pattern:
| Character | 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
not case sensitive unless one of the operands is a binary string:
mysql> SELECT 'abc' LIKE 'ABC';
-> 1
mysql> SELECT 'abc' LIKE BINARY 'ABC';
-> 0
In MySQL, LIKE is allowed on numeric expressions. (This is an
extension to the standard SQL LIKE.)
mysql> SELECT 10 LIKE '1%';
-> 1
Note: Because MySQL uses the C escape syntax in strings (for example,
`\n' to represent newline), 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']
-
This is the same as
NOT (expr LIKE pat [ESCAPE 'escape-char']).
expr NOT REGEXP pat
-
expr NOT RLIKE pat
-
This is the same as
NOT (expr REGEXP pat).
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.
The syntax for regular expressions is discussed in
section G MySQL Regular Expressions. Returns
1 if expr matches pat, otherwise
returns 0. If either expr or pat is NULL,
the result is NULL. RLIKE is a synonym for REGEXP,
provided for
mSQL compatibility. Note: Because MySQL uses the C escape
syntax in strings (for example, `\n' to represent newline), you must double any `\' that
you use in your REGEXP strings. As of MySQL 3.23.4,
REGEXP is not case sensitive 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.
However, these operators are not multi-byte safe.
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
As of MySQL 4.0,
STRCMP() uses the current character set when performing comparisons.
This makes the default comparison behavior case insensitive unless
one or both of the operands are binary strings.
Before MySQL 4.0, STRCMP() is case sensitive.
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 argument is an unsigned integer, and the other argument
is also an integer, the result will be an unsigned integer.
See section 12.7 Cast Functions and Operators.
+
-
Addition:
mysql> SELECT 3+5;
-> 8
-
-
Subtraction:
mysql> SELECT 3-5;
-> -2
-
-
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!
*
-
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!
DIV
-
Integer division.
Similar to
FLOOR() but safe with BIGINT values.
mysql> SELECT 5 DIV 2;
-> 2
DIV is new in MySQL 4.1.0.
All mathematical functions return NULL in case of an error.
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.
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
CEILING(X)
-
CEIL(X)
-
Returns the smallest integer value not less than X.
mysql> SELECT CEILING(1.23);
-> 2
mysql> SELECT CEIL(-1.23);
-> -1
Note that the return value is converted to a BIGINT!
The CEIL() alias was added in MySQL 4.0.6.
COS(X)
-
Returns the cosine of X, where X is given in radians.
mysql> SELECT COS(PI());
-> -1.000000
COT(X)
-
Returns the cotangent of X.
mysql> SELECT COT(12);
-> -1.57267341
mysql> SELECT COT(0);
-> NULL
CRC32(expr)
-
Computes a cyclic redundancy check value and returns a 32-bit unsigned value.
The result is
NULL if the argument is NULL.
The argument is expected be a string and will be treated as one if it is not.
mysql> SELECT CRC32('MySQL');
-> 3259397556
CRC32() is available as of MySQL 4.1.0.
DEGREES(X)
-
Returns the argument X, converted from radians to degrees.
mysql> SELECT DEGREES(PI());
-> 180.000000
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
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!
LN(X)
-
Returns the natural logarithm of X.
mysql> SELECT LN(2);
-> 0.693147
mysql> SELECT LN(-2);
-> NULL
This function was added in MySQL 4.0.3.
It is synonymous with LOG(X) in MySQL.
LOG(X)
-
LOG(B,X)
-
If called with one parameter, this function returns the natural logarithm
of X.
mysql> SELECT LOG(2);
-> 0.693147
mysql> SELECT LOG(-2);
-> NULL
If called with two parameters, this function returns the logarithm of
X for an arbitrary base B.
mysql> SELECT LOG(2,65536);
-> 16.000000
mysql> SELECT LOG(1,100);
-> NULL
The arbitrary base option was added in MySQL 4.0.3.
LOG(B,X) is equivalent to LOG(X)/LOG(B).
LOG2(X)
-
Returns the base-2 logarithm of
X.
mysql> SELECT LOG2(65536);
-> 16.000000
mysql> SELECT LOG2(-100);
-> NULL
LOG2() is useful for finding out how many bits a number would
require for storage.
This function was added in MySQL 4.0.3.
In earlier versions, you can use LOG(X)/LOG(2) instead.
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
MOD(N,M)
-
N % M
-
N MOD M
-
Modulo operation.
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
mysql> SELECT 29 MOD 9;
-> 2
This function is safe to use with BIGINT values.
The N MOD M syntax works only as of MySQL 4.1.
As of MySQL 4.1.7, MOD() works on values with a fractional part and
returns the exact remainder after division:
mysql> SELECT MOD(34.5,3);
-> 1.5
Before MySQL 4.1.7, MOD() rounds arguments with a fractional value
to integers and returns an integer result:
mysql> SELECT MOD(34.5,3);
-> 2
PI()
-
Returns the value of PI. The default number of decimals displayed is five, but
MySQL internally uses the full double-precision value for PI.
mysql> SELECT PI();
-> 3.141593
mysql> SELECT PI()+0.000000000000000000;
-> 3.141592653589793116
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
RADIANS(X)
-
Returns the argument X, converted from degrees to radians.
mysql> SELECT RADIANS(90);
-> 1.570796
RAND()
-
RAND(N)
-
Returns a random floating-point value in the range from
0 to 1.0.
If an integer argument N is specified, it is used as the seed value
(producing a repeatable sequence).
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.
As of MySQL 3.23, you can retrieve rows in random order like this:
mysql> SELECT * FROM tbl_name ORDER BY RAND();
ORDER BY RAND() combined with LIMIT is useful for selecting
a random sample of a set of rows:
mysql> SELECT * FROM table1, table2 WHERE a=b AND c<d
-> ORDER BY RAND() LIMIT 1000;
Note that RAND() in a WHERE clause is 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.
ROUND(X)
-
ROUND(X,D)
-
Returns the argument X, rounded to the nearest integer.
With two arguments, returns X rounded to D decimals.
If D is negative, the integer part of the number is zeroed out.
mysql> SELECT ROUND(-1.23);
-> -1
mysql> SELECT ROUND(-1.58);
-> -2
mysql> SELECT ROUND(1.58);
-> 2
mysql> SELECT ROUND(1.298, 1);
-> 1.3
mysql> SELECT ROUND(1.298, 0);
-> 1
mysql> SELECT ROUND(23.298, -1);
-> 20
Note that the behavior of ROUND() when the argument
is halfway between two integers depends on the C library
implementation. Different implementations 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
such as TRUNCATE() or FLOOR() instead.
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
SIN(X)
-
Returns the sine of X, where X is given in radians.
mysql> SELECT SIN(PI());
-> 0.000000
SQRT(X)
-
Returns the non-negative square root of X.
mysql> SELECT SQRT(4);
-> 2.000000
mysql> SELECT SQRT(20);
-> 4.472136
TAN(X)
-
Returns the tangent of X, where X is given in radians.
mysql> SELECT TAN(PI()+1);
-> 1.557408
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.
If D is negative, the integer part of the number is zeroed out.
mysql> SELECT TRUNCATE(1.223,1);
-> 1.2
mysql> SELECT TRUNCATE(1.999,1);
-> 1.9
mysql> SELECT TRUNCATE(1.999,0);
-> 1
mysql> SELECT TRUNCATE(-1.999,1);
-> -1.9
mysql> SELECT TRUNCATE(122,-2);
-> 100
Starting from MySQL 3.23.51, all numbers are rounded toward zero.
Note that decimal numbers are normally not stored as exact numbers in
computers, but as double-precision values, so you may be surprised 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.
This section describes the functions that can be used to manipulate
temporal values.
See section 11.3 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 DATE_SUB(CURDATE(),INTERVAL 30 DAY) <= date_col;
Note that the query also will 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 to any of their synonyms.
Beginning with MySQL 4.1.3, the CURRENT_TIMESTAMP(),
CURRENT_TIME(), CURRENT_DATE(), and FROM_UNIXTIME()
functions return values in the connection's current time zone, which is
available as the value of the time_zone system variable. Also,
UNIX_TIMESTAMP() assumes that its argument is a datetime value in
the current time zone. See section 5.8.8 MySQL Server Time Zone Support.
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().
For information on the INTERVAL argument, see the
discussion for DATE_ADD().
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 time 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.
CONVERT_TZ(dt,from_tz,to_tz)
-
CONVERT_TZ()
converts a datetime value dt from time zone given by from_tz
to the time zone given by to_tz and returns the resulting value.
Time zones may be specified as described in section 5.8.8 MySQL Server Time Zone Support.
This function returns NULL if the arguments are invalid.
If the value falls out of the supported range of the TIMESTAMP
type when converted fom from_tz to UTC, no conversion occurs.
The TIMESTAMP range is described at
section 11.1.2 Overview of Date and Time Types.
mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','GMT','MET');
-> '2004-01-01 13:00:00'
mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','+00:00','-07:00');
-> '2004-01-01 05:00:00'
To use named time zones such as 'MET' or 'Europe/Moscow',
the time zone tables must be properly set up. See
section 5.8.8 MySQL Server Time Zone Support for instructions.
CONVERT_TZ() was added in MySQL 4.1.3.
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-30 23:59:59','1997-12-31');
-> -31
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.
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 INTERVAL keyword and the type specifier are not case
sensitive.
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.
As of MySQL 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.)
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 that 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.
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'
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
|
%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, ...)
|
%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, four digits; used with %V
|
%x | Year for the week, where Monday is the first day of the week, numeric, four digits; used with %v
|
%Y | Year, numeric, four digits
|
%y | Year, numeric, two digits
|
%% | A literal `%'.
|
All other characters are copied to the result without interpretation.
The %v, %V, %x, and %X format specifiers are
available as of MySQL 3.23.8. %f is available as of MySQL 4.1.1.
As of MySQL 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
EXTRACT() was added in MySQL 3.23.0.
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 does not 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|DATETIME, '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.
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(DATETIME,'USA') | '%Y-%m-%d-%H.%i.%s'
|
GET_FORMAT(DATETIME,'JIS') | '%Y-%m-%d %H:%i:%s'
|
GET_FORMAT(DATETIME,'ISO') | '%Y-%m-%d %H:%i:%s'
|
GET_FORMAT(DATETIME,'EUR') | '%Y-%m-%d-%H.%i.%s'
|
GET_FORMAT(DATETIME,'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.
As of MySQL 4.1.4, TIMESTAMP can also be used;
GET_FORMAT() returns the same values as for DATETIME.
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 section 13.5.3 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');
-> '2003-02-28'
mysql> SELECT LAST_DAY('2004-02-05');
-> '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().
They were added in MySQL 4.0.6.
LOCALTIMESTAMP
-
LOCALTIMESTAMP()
-
LOCALTIMESTAMP and LOCALTIMESTAMP() are synonyms for
NOW().
They were added in MySQL 4.0.6.
MAKEDATE(year,dayofyear)
-
Returns a date, given year and day-of-year values.
dayofyear must be greater than 0 or the result will be
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 full 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.
STR_TO_DATE() returns a DATETIME value if the format
string contains both date and time parts, or a DATE or TIME
value if the string contains only date or time parts.
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('10arp', '%carp');
-> '0000-10-00 00:00:00'
mysql> SELECT STR_TO_DATE('2003-15-10 00:00:00',
-> '%Y-%m-%d %H:%i:%s');
-> NULL
Range checking on the parts of date values is as described in
section 11.3.1 The DATETIME, DATE, and TIMESTAMP Types. This means, for example, that a date with
a day part larger than the number of days in a month is allowable as long
as the day part is in the range from 1 to 31. Also, ``zero'' dates or dates
with part values of 0 are allowed.
mysql> SELECT STR_TO_DATE('00/00/0000', '%m/%d/%Y');
-> '0000-00-00'
mysql> SELECT STR_TO_DATE('04/31/2004', '%m/%d/%Y');
-> '2004-04-31'
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().
For information on the INTERVAL argument, see the
discussion for DATE_ADD().
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 time 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 listed in the description 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)
-
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 does not take into account the
days that were lost when the calendar was changed.
Remember that MySQL converts two-digit year values in dates to
four-digit form using the rules in section 11.3 Date and Time Types. For example,
'1997-10-07' and '97-10-07' are seen as identical dates:
mysql> SELECT TO_DAYS('1997-10-07'), TO_DAYS('97-10-07');
-> 729669, 729669
For other dates before 1582, results from this function are undefined.
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 range checking is performed
(year from 1970 to 2037, month from 01 to 12, day
from 01 from 31).
If you want to subtract UNIX_TIMESTAMP() columns, you might want to
cast the result to signed integers. See section 12.7 Cast Functions and Operators.
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 from 0 to
53 or from 1 to 52. If the mode argument is
omitted, the value of the default_week_format system variable is
used (or 0 before MySQL 4.0.14).
See section 5.2.3 Server System Variables.
The following table describes 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 three 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 three 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 three days in this year
|
5 | Week starts on Monday; return value range is 0 to
53; week 1 is | |
