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.
( ... )
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:
NULL, the result of the comparison is
NULL, except for the NULL-safe <=> equality comparison
operator.
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.
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', ...
=
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.
<>
!=
mysql> SELECT '.01' <> '0.01';
-> 1
mysql> SELECT .01 <> '0.01';
-> 0
mysql> SELECT 'zapp' <> 'zappp';
-> 1
<=
mysql> SELECT 0.1 <= 2;
-> 1
<
mysql> SELECT 2 < 2;
-> 0
>=
mysql> SELECT 2 >= 2;
-> 1
>
mysql> SELECT 2 > 2;
-> 0
IS boolean_value
IS NOT boolean_value
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
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:
AUTO_INCREMENT value
by issuing a statement of the following form immediately after generating the
value:
SELECT * FROM tbl_name WHERE auto_col IS NULLThis behavior can be disabled by setting
SQL_AUTO_IS_NULL=0.
See section 13.5.3 SET Syntax.
DATE and DATETIME columns that are declared as NOT
NULL, you can find the special date '0000-00-00' by using a statement
like this:
SELECT * FROM tbl_name WHERE date_column IS NULLThis is needed to get some ODBC applications to work because ODBC doesn't support a
'0000-00-00' date value.
expr BETWEEN min AND 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
NOT (expr BETWEEN min AND max).
COALESCE(value,...)
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,...)
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,...)
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,...)
NOT (expr IN (value,...)).
ISNULL(expr)
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,...)
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,...)
INTEGER context or all arguments
are integer-valued, they are compared as integers.
REAL context or all arguments are
real-valued, they are compared as reals.
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
!
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
&&
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
||
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
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
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)
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 |
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)
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)
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)
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)
BIGINT) number. This is equivalent to
CONV(N,10,2). Returns NULL if N is NULL.
mysql> SELECT BIN(12);
-> '1100'
BIT_LENGTH(str)
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)
LENGTH() returns 10, whereas CHAR_LENGTH() returns
5.
CHARACTER_LENGTH(str)
CHARACTER_LENGTH() is a synonym for CHAR_LENGTH().
COMPRESS(string_to_compress)
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:
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,...)
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)
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,...)
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]])
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,...)
... 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)
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)
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)
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)
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)
mysql> SELECT LEFT('foobarbar', 5);
-> 'fooba'
LENGTH(str)
LENGTH() returns 10, whereas CHAR_LENGTH() returns
5.
mysql> SELECT LENGTH('text');
-> 4
LOAD_FILE(file_name)
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)
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)
mysql> SELECT LOWER('QUADRATICALLY');
-> 'quadratically'
This function is multi-byte safe.
LPAD(str,len,padstr)
mysql> SELECT LPAD('hi',4,'??');
-> '??hi'
mysql> SELECT LPAD('hi',1,'??');
-> 'h'
LTRIM(str)
mysql> SELECT LTRIM(' barbar');
-> 'barbar'
This function is multi-byte safe.
MAKE_SET(bits,str1,str2,...)
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)
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)
(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)
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)
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)
mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww');
-> 'WwWwWw.mysql.com'
This function is multi-byte safe.
REVERSE(str)
mysql> SELECT REVERSE('abc');
-> 'cba'
This function is multi-byte safe.
RIGHT(str,len)
mysql> SELECT RIGHT('foobarbar', 4);
-> 'rbar'
This function is multi-byte safe.
RPAD(str,len,padstr)
mysql> SELECT RPAD('hi',5,'?');
-> 'hi???'
mysql> SELECT RPAD('hi',1,'?');
-> 'h'
This function is multi-byte safe.
RTRIM(str)
mysql> SELECT RTRIM('barbar ');
-> 'barbar'
This function is multi-byte safe.
SOUNDEX(str)
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
SOUNDEX(expr1) = SOUNDEX(expr2). It is
available only in MySQL 4.1 or later.
SPACE(N)
mysql> SELECT SPACE(6);
-> ' '
SUBSTRING(str,pos)
SUBSTRING(str FROM pos)
SUBSTRING(str,pos,len)
SUBSTRING(str FROM pos FOR len)
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)
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)
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)
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)
mysql> SELECT UNCOMPRESSED_LENGTH(COMPRESS(REPEAT('a',30)));
-> 30
UNCOMPRESSED_LENGTH() was added in MySQL 4.1.1.
UNHEX(str)
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)
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']
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']
NOT (expr LIKE pat [ESCAPE 'escape-char']).
expr NOT REGEXP pat
expr NOT RLIKE pat
NOT (expr REGEXP pat).
expr REGEXP pat
expr RLIKE pat
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.
+
mysql> SELECT 3+5;
-> 8
-
mysql> SELECT 3-5;
-> -2
-
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!
*
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.
/
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
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)
mysql> SELECT ABS(2);
-> 2
mysql> SELECT ABS(-32);
-> 32
This function is safe to use with BIGINT values.
ACOS(X)
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)
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)
mysql> SELECT ATAN(2);
-> 1.107149
mysql> SELECT ATAN(-2);
-> -1.107149
ATAN(Y,X)
ATAN2(Y,X)
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)
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)
mysql> SELECT COS(PI());
-> -1.000000
COT(X)
mysql> SELECT COT(12);
-> -1.57267341
mysql> SELECT COT(0);
-> NULL
CRC32(expr)
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)
mysql> SELECT DEGREES(PI());
-> 180.000000
EXP(X)
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)
mysql> SELECT FLOOR(1.23);
-> 1
mysql> SELECT FLOOR(-1.23);
-> -2
Note that the return value is converted to a BIGINT!
LN(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)
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)
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)
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
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()
mysql> SELECT PI();
-> 3.141593
mysql> SELECT PI()+0.000000000000000000;
-> 3.141592653589793116
POW(X,Y)
POWER(X,Y)
mysql> SELECT POW(2,2);
-> 4.000000
mysql> SELECT POW(2,-2);
-> 0.250000
RADIANS(X)
mysql> SELECT RADIANS(90);
-> 1.570796
RAND()
RAND(N)
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)
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)
-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)
mysql> SELECT SIN(PI());
-> 0.000000
SQRT(X)
mysql> SELECT SQRT(4);
-> 2.000000
mysql> SELECT SQRT(20);
-> 4.472136
TAN(X)
mysql> SELECT TAN(PI()+1);
-> 1.557408
TRUNCATE(X,D)
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)
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()
'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()
'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)
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)
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'
|
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)
| 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 `%'. |
%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)
mysql> SELECT DAYNAME('1998-02-05');
-> 'Thursday'
DAYOFMONTH(date)
1 to
31.
mysql> SELECT DAYOFMONTH('1998-02-03');
-> 3
DAYOFWEEK(date)
1 = Sunday, 2 = Monday, ..., 7 =
Saturday). These index values correspond to the ODBC standard.
mysql> SELECT DAYOFWEEK('1998-02-03');
-> 3
DAYOFYEAR(date)
1 to
366.
mysql> SELECT DAYOFYEAR('1998-02-03');
-> 34
EXTRACT(type FROM date)
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)
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)
'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')
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'
|
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)
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)
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)
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)
mysql> SELECT MAKETIME(12,15,30);
-> '12:15:30'
MAKETIME() is available as of MySQL 4.1.1.
MICROSECOND(expr)
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)
0 to 59.
mysql> SELECT MINUTE('98-02-03 10:05:03');
-> 5
MONTH(date)
1 to 12.
mysql> SELECT MONTH('1998-02-03');
-> 2
MONTHNAME(date)
mysql> SELECT MONTHNAME('1998-02-05');
-> 'February'
NOW()
'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)
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)
YYMM or YYYYMM.
Note that the period arguments P1 and P2 are not
date values.
mysql> SELECT PERIOD_DIFF(9802,199703);
-> 11
QUARTER(date)
1
to 4.
mysql> SELECT QUARTER('98-04-01');
-> 2
SECOND(time)
0 to 59.
mysql> SELECT SECOND('10:05:03');
-> 3
SEC_TO_TIME(seconds)
'HH:MM:SS' or HHMMSS format, depending on whether
the function is used in a string or numeric context.
mysql> SELECT SEC_TO_TIME(2378);
-> '00:39:38'
mysql> SELECT SEC_TO_TIME(2378) + 0;
-> 3938
STR_TO_DATE(str,format)
DATE_FORMAT() function. It takes a
string str and a format string format.
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)
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)
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)
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)
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)
TIMESTAMPADD() function.
mysql> SELECT TIMESTAMPDIFF(MONTH,'2003-02-01','2003-05-01');
-> 3
mysql> SELECT TIMESTAMPDIFF(YEAR,'2002-05-01','2001-01-01');
-> -1
TIMESTAMPDIFF() is available as of MySQL 5.0.0.
TIME_FORMAT(time,format)
DATE_FORMAT() function, but the
format string may contain only those format specifiers that handle
hours, minutes, and seconds. Other specifiers produce a NULL value or
0.
If the time value contains an hour part that is greater than
23, the %H and %k hour format specifiers produce a
value larger than the usual range of 0..23. The other hour format
specifiers produce the hour value modulo 12.
mysql> SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l');
-> '100 100 04 04 4'
TIME_TO_SEC(time)
mysql> SELECT TIME_TO_SEC('22:23:00');
-> 80580
mysql> SELECT TIME_TO_SEC('00:39:38');
-> 2378
TO_DAYS(date)
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)
'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()
'YYYY-MM-DD' or
YYYYMMDD format, depending on whether the function is used in a
string or numeric context.
mysql> SELECT UTC_DATE(), UTC_DATE() + 0;
-> '2003-08-14', 20030814
UTC_DATE() is available as of MySQL 4.1.1.
UTC_TIME
UTC_TIME()
'HH:MM:SS' or HHMMSS
format, depending on whether the function is used in a string or numeric
context.
mysql> SELECT UTC_TIME(), UTC_TIME() + 0;
-> '18:07:53', 180753
UTC_TIME() is available as of MySQL 4.1.1.
UTC_TIMESTAMP
UTC_TIMESTAMP()
'YYYY-MM-DD HH:MM:SS'
or YYYYMMDDHHMMSS format, depending on whether the function is used in
a string or numeric context.
mysql> SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0;
-> '2003-08-14 18:08:04', 20030814180804
UTC_TIMESTAMP() is available as of MySQL 4.1.1.
WEEK(date[,mode])
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 the first week that starts in this year
|
6 | Week starts on Sunday; return value range is 1 to
53; week 1 is the first week that has more than three days in this year
|
7 | Week starts on Monday; return value range is 1 to
53; week 1 is the first week that starts in this year
|
3 can be used as of MySQL 4.0.5.
Values of 4 and above can be used as of MySQL 4.0.17.
mysql> SELECT WEEK('1998-02-20');
-> 7
mysql> SELECT WEEK('1998-02-20',0);
-> 7
mysql> SELECT WEEK('1998-02-20',1);
-> 8
mysql> SELECT WEEK('1998-12-31',1);
-> 53
Note: In MySQL 4.0, WEEK(date,0) was changed to match the
calendar in the USA. Before that, WEEK() was calculated incorrectly
for dates in the USA. (In effect, WEEK(date) and WEEK(date,0) were
incorrect for all cases.)
Note that if a date falls in the last week of the previous year, MySQL
returns 0 if you don't use 2, 3, 6, or 7
as the optional mode argument:
mysql> SELECT YEAR('2000-01-01'), WEEK('2000-01-01',0);
-> 2000, 0
One might argue that MySQL should return 52 for the WEEK()
function, because the given date actually occurs in the 52nd week of 1999. We
decided to return 0 instead because we want the function to return ``the week
number in the given year.'' This makes use of the WEEK()
function reliable when combined with other functions that extract a
date part from a date.
If you would prefer the result to be evaluated with respect to the year
that contains the first day of the week for the given date, you should use
2, 3, 6, or 7 as the optional mode argument.
mysql> SELECT WEEK('2000-01-01',2);
-> 52
Alternatively, use the YEARWEEK() function:
mysql> SELECT YEARWEEK('2000-01-01');
-> 199952
mysql> SELECT MID(YEARWEEK('2000-01-01'),5,2);
-> '52'
WEEKDAY(date)
0 = Monday, 1 = Tuesday, ... 6 = Sunday).
mysql> SELECT WEEKDAY('1998-02-03 22:23:00');
-> 1
mysql> SELECT WEEKDAY('1997-11-05');
-> 2
WEEKOFYEAR(date)
1 to 53.
mysql> SELECT WEEKOFYEAR('1998-02-20');
-> 8
WEEKOFYEAR() is available as of MySQL 4.1.1.
YEAR(date)
1000 to 9999.
mysql> SELECT YEAR('98-02-03');
-> 1998
YEARWEEK(date)
YEARWEEK(date,start)
WEEK(). The year in the
result may be
different from the year in the date argument for the first and the last
week of the year.
mysql> SELECT YEARWEEK('1987-01-01');
-> 198653
Note that the week number is different from what the WEEK()
function would return (0) for optional arguments 0 or 1,
as WEEK() then returns the week in the context of the given year.
YEARWEEK() was added in MySQL 3.23.8.
MATCH (col1,col2,...) AGAINST (expr [IN BOOLEAN MODE | WITH QUERY EXPANSION])
FULLTEXT. FULLTEXT indexes are used with MyISAM tables
only and can be created from CHAR, VARCHAR,
or TEXT columns at CREATE TABLE time or added later with
ALTER TABLE or CREATE INDEX. For large datasets, it will be
much faster to load your data into a table that has no FULLTEXT
index, then create the index with ALTER TABLE (or
CREATE INDEX). Loading data into a table that already has a
FULLTEXT index could be significantly slower.
Constraints on full-text searching are listed in section 12.6.3 Full-Text Restrictions.
Full-text searching is performed with the MATCH() function.
mysql> CREATE TABLE articles (
-> id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
-> title VARCHAR(200),
-> body TEXT,
-> FULLTEXT (title,body)
-> );
Query OK, 0 rows affected (0.00 sec)
mysql> INSERT INTO articles (title,body) VALUES
-> ('MySQL Tutorial','DBMS stands for DataBase ...'),
-> ('How To Use MySQL Well','After you went through a ...'),
-> ('Optimizing MySQL','In this tutorial we will show ...'),
-> ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
-> ('MySQL vs. YourSQL','In the following database comparison ...'),
-> ('MySQL Security','When configured properly, MySQL ...');
Query OK, 6 rows affected (0.00 sec)
Records: 6 Duplicates: 0 Warnings: 0
mysql> SELECT * FROM articles
-> WHERE MATCH (title,body) AGAINST ('database');
+----+-------------------+------------------------------------------+
| id | title | body |
+----+-------------------+------------------------------------------+
| 5 | MySQL vs. YourSQL | In the following database comparison ... |
| 1 | MySQL Tutorial | DBMS stands for DataBase ... |
+----+-------------------+------------------------------------------+
2 rows in set (0.00 sec)
The MATCH() function performs a natural language search for a string
against a text collection. A collection is a set of one or more columns
included in a FULLTEXT index. The search string is given as the
argument to AGAINST().
For every row in the table, MATCH() returns a relevance
value, that is, a similarity measure between the search string and the text
in that row in the columns named in the MATCH() list.
By default, the search is performed in case-insensitive fashion. In MySQL
4.1 and up, you can make a full-text search by using a binary collation for
the indexed columns. For example, a column that has a character set of
latin1 can be assigned a collation of latin1_bin to make it
case sensitive for full-text searches.
When MATCH() is used in a WHERE clause, as in the preceding
example,
the rows returned are automatically sorted with the highest relevance first.
Relevance values are non-negative floating-point numbers. Zero relevance
means no similarity. Relevance is computed based on the number of words
in the row, the number of unique words in that row, the total number of
words in the collection, and the number of documents (rows) that contain
a particular word.
For natural-language full-text searches, it is a requirement that the
columns named in the MATCH() function be the same columns included in
some FULLTEXT index in your table. For the preceding query, note
that the columns named in the MATCH() function (title and
body) are the same as those named in the definition of the
article table's FULLTEXT index. If you wanted to search the
title or body separately, you would need to create
FULLTEXT indexes for each column.
It is also possible to perform a boolean search or a search with query expansion. These search types are described in section 12.6.1 Boolean Full-Text Searches and section 12.6.2 Full-Text Searches with Query Expansion.
The preceding example is a basic illustration showing how to use the
MATCH() function where rows are returned in order of decreasing
relevance. The next example shows how to retrieve the relevance values
explicitly. Returned rows are not ordered because the SELECT
statement includes neither WHERE nor ORDER BY clauses:
mysql> SELECT id, MATCH (title,body) AGAINST ('Tutorial')
-> FROM articles;
+----+-----------------------------------------+
| id | MATCH (title,body) AGAINST ('Tutorial') |
+----+-----------------------------------------+
| 1 | 0.65545833110809 |
| 2 | 0 |
| 3 | 0.66266459226608 |
| 4 | 0 |
| 5 | 0 |
| 6 | 0 |
+----+-----------------------------------------+
6 rows in set (0.00 sec)
The following example is more complex. The query returns the relevance values
and it also sorts the rows in order of decreasing relevance. To achieve
this result, you should specify MATCH() twice: once in the
SELECT list and once in the WHERE clause. This causes no
additional overhead, because the MySQL optimizer notices that the
two MATCH() calls are identical and invokes the full-text search
code only once.
mysql> SELECT id, body, MATCH (title,body) AGAINST
-> ('Security implications of running MySQL as root') AS score
-> FROM articles WHERE MATCH (title,body) AGAINST
-> ('Security implications of running MySQL as root');
+----+-------------------------------------+-----------------+
| id | body | score |
+----+-------------------------------------+-----------------+
| 4 | 1. Never run mysqld as root. 2. ... | 1.5219271183014 |
| 6 | When configured properly, MySQL ... | 1.3114095926285 |
+----+-------------------------------------+-----------------+
2 rows in set (0.00 sec)
MySQL uses a very simple parser to split text into words. A ``word'' is any
sequence of true word characters (letters, digits, and underscores),
optionally separated by no more than one sequential `'' character.
For example, wasn't is parsed as a single word, but wasn''t
is parsed as two words wasn and t. (And then t would
be ignored as too short according to the rules following.) Also, single
quotes at the ends of words are stripped; only embedded single quotes
are retained.
Some words are ignored in full-text searches:
The default minimum word length and stopword list can be changed as described in section 12.6.4 Fine-Tuning MySQL Full-Text Search.
Every correct word in the collection and in the query is weighted according to its significance in the collection or query. This way, a word that is present in many documents has a lower weight (and may even have a zero weight), because it has lower semantic value in this particular collection. Conversely, if the word is rare, it receives a higher weight. The weights of the words are then combined to compute the relevance of the row.
Such a technique works best with large collections (in fact, it was
carefully tuned this way). For very small tables, word distribution
does not adequately reflect their semantic value, and this model
may sometimes produce bizarre results. For example, although the word
``MySQL'' is present in every row of the articles table, a search for
the word produces no results:
mysql> SELECT * FROM articles
-> WHERE MATCH (title,body) AGAINST ('MySQL');
Empty set (0.00 sec)
The search result is empty because the word ``MySQL'' is present in at least 50% of the rows. As such, it is effectively treated as a stopword. For large datasets, this is the most desirable behavior--a natural language query should not return every second row from a 1GB table. For small datasets, it may be less desirable.
A word that matches half of rows in a table is less likely to locate relevant documents. In fact, it will most likely find plenty of irrelevant documents. We all know this happens far too often when we are trying to find something on the Internet with a search engine. It is with this reasoning that rows containing the word are assigned a low semantic value for the particular dataset in which they occur. A given word may exceed the 50% threshold in one dataset but not another.
The 50% threshold has a significant implication when you first try full-text searching to see how it works: If you create a table and insert only one or two rows of text into it, every word in the text occurs in at least 50% of the rows. As a result, no search returns any results. Be sure to insert at least three rows, and preferably many more.
As of Version 4.0.1, MySQL can also perform boolean full-text searches using
the IN BOOLEAN MODE modifier.
mysql> SELECT * FROM articles WHERE MATCH (title,body)
-> AGAINST ('+MySQL -YourSQL' IN BOOLEAN MODE);
+----+-----------------------+-------------------------------------+
| id | title | body |
+----+-----------------------+-------------------------------------+
| 1 | MySQL Tutorial | DBMS stands for DataBase ... |
| 2 | How To Use MySQL Well | After you went through a ... |
| 3 | Optimizing MySQL | In this tutorial we will show ... |
| 4 | 1001 MySQL Tricks | 1. Never run mysqld as root. 2. ... |
| 6 | MySQL Security | When configured properly, MySQL ... |
+----+-----------------------+-------------------------------------+
This query retrieves all the rows that contain the word ``MySQL'' but that do not contain the word ``YourSQL''.
Boolean full-text searches have these characteristics:
FULLTEXT index, although this would be
slow.
The boolean full-text search capability supports the following operators:
+
-
(no operator)
+ nor - is specified) the word is optional,
but the rows that contain it will be rated higher. This mimics the
behavior of MATCH() ... AGAINST() without the IN BOOLEAN
MODE modifier.
> <
> operator
increases the contribution and the < operator decreases it.
See the example below.
( )
~
- operator.
*
"
The following examples demonstrate some search strings that use boolean full-text operators:
'apple banana'
'+apple +juice'
'+apple macintosh'
'+apple -macintosh'
'+apple +(>turnover <strudel)'
'apple*'
'"some words"'
As of MySQL 4.1.1, full-text search supports query expansion (in particular, its variant ``blind query expansion''). This is generally useful when a search phrase is too short, which often means that the user is relying on implied knowledge that the full-text search engine usually lacks. For example, a user searching for ``database'' may really mean that ``MySQL'', ``Oracle'', ``DB2'', and ``RDBMS'' all are phrases that should match ``databases'' and should be returned, too. This is implied knowledge.
Blind query expansion (also known as automatic relevance feedback) is
enabled by adding WITH QUERY EXPANSION following the search phrase.
It works by performing the search twice, where the search phrase for the
second search is the original search phrase concatenated with the few top
found documents from the first search. Thus, if one of these documents
contains the word ``databases'' and the word ``MySQL'', the second search
will find the documents that contain the word ``MySQL'' even if they do not
contain the word ``database''. The following example shows this difference:
mysql> SELECT * FROM articles
-> WHERE MATCH (title,body) AGAINST ('database');
+----+-------------------+------------------------------------------+
| id | title | body |
+----+-------------------+------------------------------------------+
| 5 | MySQL vs. YourSQL | In the following database comparison ... |
| 1 | MySQL Tutorial | DBMS stands for DataBase ... |
+----+-------------------+------------------------------------------+
2 rows in set (0.00 sec)
mysql> SELECT * FROM articles
-> WHERE MATCH (title,body)
-> AGAINST ('database' WITH QUERY EXPANSION);
+----+-------------------+------------------------------------------+
| id | title | body |
+----+-------------------+------------------------------------------+
| 1 | MySQL Tutorial | DBMS stands for DataBase ... |
| 5 | MySQL vs. YourSQL | In the following database comparison ... |
| 3 | Optimizing MySQL | In this tutorial we will show ... |
+----+-------------------+------------------------------------------+
3 rows in set (0.00 sec)
Another example could be searching for books by Georges Simenon about Maigret, when a user is not sure how to spell ``Maigret''. A search for ``Megre and the reluctant witnesses'' will find only ``Maigret and the Reluctant Witnesses'' without query expansion. A search with query expansion will find all books with the word ``Maigret'' on the second pass.
Note: Because blind query expansion tends to increase noise significantly by returning non-relevant documents, it's only meaningful to use when a search phrase is rather short.
MyISAM tables only.
utf8 character
set can be used, but not the ucs2 character set.
FULLTEXT index must have
the same character set and collation.
MATCH() column list must exactly match the column list in some
FULLTEXT index definition for the table, unless this MATCH()
is IN BOOLEAN MODE.
AGAINST() must be a constant string.
The MySQL full-text search capability has few user-tunable parameters yet, although adding more is very high on the TODO. You can exert more control over full-text searching behavior if you have a MySQL source distribution because some changes require source code modfications. See section 2.8 MySQL Installation Using a Source Distribution.
Note that full-text search was carefully tuned for the best searching effectiveness. Modifying the default behavior will, in most cases, make the search results worse. Do not alter the MySQL sources unless you know what you are doing!
Most full-text variables described in the following items must be set at server startup time. For these variables, a server restart is required to change them and you cannot modify them dynamically while the server is running.
Some variable changes require that you rebuild the FULLTEXT indexes
in your tables. Instructions for doing this are given at the end of this
section.
ft_min_word_len and ft_max_word_len system variables
(available as of MySQL 4.0.0).
See section 5.2.3 Server System Variables.
The default minimum value is four characters. The default maximum depends
on your version of MySQL. If you change either value, you must rebuild your
FULLTEXT indexes. For example, if you want three-character words to
be searchable, you can set the ft_min_word_len variable by putting
the following lines in an option file:
[mysqld] ft_min_word_len=3Then restart the server and rebuild your
FULLTEXT indexes.
Also note particularly the remarks regarding myisamchk in the
instructions following this list.
ft_stopword_file
system variable (available as of MySQL 4.0.10).
See section 5.2.3 Server System Variables.
The variable value should be the pathname of the file containing the stopword
list, or the empty string to disable stopword filtering. After changing the value, rebuild your FULLTEXT indexes.
#define GWS_IN_USE GWS_PROBChange the line to this:
#define GWS_IN_USE GWS_FREQThen recompile MySQL. There is no need to rebuild the indexes in this case. Note: By doing this you severely decrease MySQL's ability to provide adequate relevance values for the
MATCH() function.
If you really need to search for such common words, it would be better to
search using IN BOOLEAN MODE instead, which does not observe the 50%
threshold.
ft_boolean_syntax system variable (available as of MySQL 4.0.1). The
variable also can be changed while the server is running, but you must have
the SUPER privilege to do so.
No index rebuilding is necessary.
section 5.2.3 Server System Variables describes the rules that define how to set this
variable.
If you modify full-text variables that affect indexing
(ft_min_word_len, ft_max_word_len, or
ft_stopword_file), you must rebuild your FULLTEXT indexes
after making the changes and restarting the server. To rebuild the indexes
in this case, it's sufficient to do a QUICK repair operation:
mysql> REPAIR TABLE tbl_name QUICK;
With regard specifically to using the IN BOOLEAN MODE capability, if
you upgrade from MySQL 3.23 to 4.0 or later, it's necessary to replace the
index header as well. To do this, do a USE_FRM repair operation:
mysql> REPAIR TABLE tbl_name USE_FRM;
This is necessary because boolean full-text searches require a flag in the
index header that was not present in MySQL 3.23, and that is not added if
you do only a QUICK repair. If you attempt a boolean full-text
search without rebuilding the indexes this way, the search will return
incorrect results.
Note that if you use myisamchk to perform an operation that modifies
table indexes (such as repair or analyze), the FULLTEXT indexes
are rebuilt using the default full-text parameter values for minimum and
maximum word length and the stopword file unless you specify otherwise.
This can result in queries failing.
The problem occurs because these parameters are known only by the server.
They are not stored in MyISAM index files. To avoid the problem if
you have modified the minimum or maximum word length or the stopword file in
the server, specify the same ft_min_word_len, ft_max_word_len,
and ft_stopword_file values to myisamchk that you use for
mysqld. For example, if you have set the minimum word length to 3,
you can repair a table with myisamchk like this:
shell> myisamchk --recover --ft_min_word_len=3 tbl_name.MYI
To ensure that myisamchk and the server use the same values for
full-text parameters, you can place each one in both the [mysqld]
and [myisamchk] sections of an option file:
[mysqld] ft_min_word_len=3 [myisamchk] ft_min_word_len=3
An alternative to using myisamchk is to use the REPAIR TABLE,
ANALYZE TABLE, OPTIMIZE TABLE, or ALTER TABLE.
These statements are performed by the server, which knows the proper
full-text parameter values to use.
FULLTEXT operations.
MERGE tables.
ucs2 character set.
FULLTEXT in CREATE TABLE and ALTER TABLE
statements).
BINARY
BINARY operator casts the string following it to a binary string.
This is an easy way to force a column comparison to be done byte by byte
rather than character by character. This causes the comparison to be
case sensitive even
if the column isn't defined as BINARY or BLOB.
BINARY also causes trailing spaces to be significant.
mysql> SELECT 'a' = 'A';
-> 1
mysql> SELECT BINARY 'a' = 'A';
-> 0
mysql> SELECT 'a' = 'a ';
-> 1
mysql> SELECT BINARY 'a' = 'a ';
-> 0
BINARY affects the entire comparison; it can be given before
either operand with the same result.
BINARY was added in MySQL 3.23.0. As of MySQL 4.0.2,
BINARY str is a shorthand for CAST(str AS BINARY).
Note that in some contexts, if you cast an indexed column to BINARY,
MySQL will not be able to use the index efficiently.
If you want to compare a BLOB value or other binary string
in case-insensitive fashion, you can do so as follows:
UPPER() function to convert the binary
string to uppercase before performing the comparison:
SELECT 'A' LIKE UPPER(blob_col) FROM tbl_name;If the comparison value is lowercase, convert the string value using
LOWER() instead.
CONVERT() function to
convert the string value to a character set that
is not case sensitive. The result is a non-binary string, so the
LIKE operation is not case sensitive:
SELECT 'A' LIKE CONVERT(blob_col USING latin1) FROM tbl_name;To use a different character set, substitute its name for
latin1
in the preceding statement.
CONVERT() can be used more generally for comparing strings that
are represented in different character sets.
CAST(expr AS type)
CONVERT(expr,type)
CONVERT(expr USING transcoding_name)
CAST() and CONVERT() functions can be used to take a
value of one type and produce a value of another type.
The type can be one of the following values:
BINARY
CHAR
DATE
DATETIME
SIGNED [INTEGER]
TIME
UNSIGNED [INTEGER]
BINARY produces a binary string. See the entry for the BINARY
operator in this section for a description of how this affects comparisons.
CAST() and CONVERT() are available as of MySQL 4.0.2.
The CHAR conversion type is available as of 4.0.6.
The USING form of CONVERT() is available as of 4.1.0.
CAST() and CONVERT(... USING ...) are standard SQL syntax.
The non-USING form of CONVERT() is ODBC syntax.
CONVERT() with USING is used to convert data between different
character sets. In MySQL, transcoding names are the same as the
corresponding character set names. For example, this statement converts
the string 'abc' in the server's default character set to the
corresponding string in the utf8 character set:
SELECT CONVERT('abc' USING utf8);
The cast functions are useful when you want to create a column with
a specific type in a CREATE ... SELECT statement:
CREATE TABLE new_table SELECT CAST('2000-01-01' AS DATE);
The functions also can be useful for sorting ENUM columns in lexical
order. Normally sorting of ENUM columns occurs using the internal
numeric values. Casting the values to CHAR results in a lexical
sort:
SELECT enum_col FROM tbl_name ORDER BY CAST(enum_col AS CHAR);
CAST(str AS BINARY) is the same thing as BINARY str.
CAST(expr AS CHAR) treats the expression as a string with the
default character set.
Note: In MysQL 4.0, a CAST() to DATE,
DATETIME, or TIME only marks the column to be a specific
type but doesn't change the value of the column.
As of MySQL 4.1.0, the value is converted to the correct column type when it's sent to the user (this is a feature of how the new protocol in 4.1 sends date information to the client):
mysql> SELECT CAST(NOW() AS DATE);
-> 2003-05-26
As of MySQL 4.1.1, CAST()
also changes the result if you use it as part of a more complex expression
such as CONCAT('Date: ',CAST(NOW() AS DATE)).
You should not use CAST() to extract data in different formats but
instead use string functions like LEFT() or
EXTRACT(). See section 12.5 Date and Time Functions.
To cast a string to a numeric value in numeric context, you don't normally have to do anything. Just use the string value as though it were a number:
mysql> SELECT 1+'1';
-> 2
If you use a number in string context, the number automatically is
converted to a BINARY string.
mysql> SELECT CONCAT('hello you ',2);
-> 'hello you 2'
MySQL supports arithmetic with both signed and unsigned 64-bit values.
If you are using numeric operators (such as +) and one of the
operands is an unsigned integer, the result is unsigned.
You can override this by using the SIGNED and UNSIGNED
cast operators to 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 operand is a floating-point value, the result is
a floating-point value and is not affected by the preceding rule.
(In this context, DECIMAL column values are regarded as
floating-point values.)
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 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, you probably can't
use the CAST() function. You can use the following technique to get
a signed result when subtracting two unsigned integer columns ucol1 and
ucol2:
mysql> SELECT (ucol1+0.0)-(ucol2+0.0) FROM ...;
The idea is that the columns are converted to floating-point values before the subtraction occurs.
If you have a problem with UNSIGNED columns in old MySQL
applications when porting them to MySQL 4.0, you can use the
--sql-mode=NO_UNSIGNED_SUBTRACTION option when starting
mysqld. However, as long as you use this option, you will not
be able to make efficient use of the BIGINT UNSIGNED column type.
MySQL uses BIGINT (64-bit) arithmetic for bit operations, so
these operators have a maximum range of 64 bits.
|
mysql> SELECT 29 | 15;
-> 31
The result is an unsigned 64-bit integer.
&
mysql> SELECT 29 & 15;
-> 13
The result is an unsigned 64-bit integer.
^
mysql> SELECT 1 ^ 1;
-> 0
mysql> SELECT 1 ^ 0;
-> 1
mysql> SELECT 11 ^ 3;
-> 8
The result is an unsigned 64-bit integer.
Bitwise XOR was added in MySQL 4.0.2.
<<
BIGINT) number to the left.
mysql> SELECT 1 << 2;
-> 4
The result is an unsigned 64-bit integer.
>>
BIGINT) number to the right.
mysql> SELECT 4 >> 2;
-> 1
The result is an unsigned 64-bit integer.
~
mysql> SELECT 5 & ~1;
-> 4
The result is an unsigned 64-bit integer.
BIT_COUNT(N)
mysql> SELECT BIT_COUNT(29);
-> 4
The functions in this section encrypt and decrypt data values.
If you want to store results from an encryption function that might contain
arbitrary byte values, use a BLOB column rather than a CHAR
or VARCHAR column to avoid potential problems with trailing
space removal that would change data values.
AES_ENCRYPT(str,key_str)
AES_DECRYPT(crypt_str,key_str)
NULL,
the result of this function is also NULL.
Because AES is a block-level algorithm, padding is used to encode uneven length
strings and so the result string length may be calculated as
16*(trunc(string_length/16)+1).
If AES_DECRYPT() detects invalid data or incorrect padding, it
returns NULL. However, it is possible for AES_DECRYPT()
to return a non-NULL value (possibly garbage) if the input data or
the key is invalid.
You can use the AES functions to store data in an encrypted form by
modifying your queries:
INSERT INTO t VALUES (1,AES_ENCRYPT('text','password'));
You can get even more security by not transferring the key over the
connection for each query, which can be accomplished by storing it in a
server-side variable at connection time. For example:
SELECT @password:='my password';
INSERT INTO t VALUES (1,AES_ENCRYPT('text',@password));
AES_ENCRYPT() and AES_DECRYPT() were added in MySQL 4.0.2,
and can be considered the most cryptographically secure encryption
functions currently available in MySQL.
DECODE(crypt_str,pass_str)
ENCODE().
ENCODE(str,pass_str)
DECODE().
The result is a binary string of the same length as str.
If you want to save it in a column, use a BLOB column type.
DES_DECRYPT(crypt_str[,key_str])
DES_ENCRYPT().
On error, this function returns NULL.
Note that this function works only if MySQL has been configured with
SSL support. See section 5.6.7 Using Secure Connections.
If no key_str argument is given, DES_DECRYPT() examines
the first byte of the encrypted string to determine the DES key number
that was used to encrypt the original string, and then reads the key
from the DES key file to decrypt the message. For this to work,
the user must have the SUPER privilege. The key file can be specified
with the --des-key-file server option.
If you pass this function a key_str argument, that string
is used as the key for decrypting the message.
If the crypt_str argument doesn't look like an encrypted string,
MySQL will return the given crypt_str.
DES_DECRYPT() was added in MySQL 4.0.1.
DES_ENCRYPT(str[,(key_num|key_str)])
NULL.
Note that this function works only if MySQL has been configured with
SSL support. See section 5.6.7 Using Secure Connections.
The encryption key to use is chosen based on the second argument to
DES_ENCRYPT(), if one was given:
| Argument | Description |
| No argument | The first key from the DES key file is used. |
| key_num | The given key number (0-9) from the DES key file is used. |
| key_str | The given key string is used to encrypt str. |
--des-key-file server option.
The return string is a binary string where the first character
is CHAR(128 | key_num).
The 128 is added to make it easier to recognize an encrypted key.
If you use a string key, key_num will be 127.
The string length for the result will be
new_len = orig_len + (8-(orig_len % 8))+1.
Each line in the DES key file has the following format:
key_num des_key_strEach key_num must be a number in the range from
0 to 9. Lines in
the file may be in any order. des_key_str is the string that
will be used to encrypt the message. Between the number and the key there
should be at least one space. The first key is the default key that is
used if you don't specify any key argument to DES_ENCRYPT()
You can tell MySQL to read new key values from the key file with the
FLUSH DES_KEY_FILE statement. This requires the RELOAD
privilege.
One benefit of having a set of default keys is that it gives applications
a way to check for the existence of encrypted column values, without giving
the end user the right to decrypt those values.
mysql> SELECT customer_address FROM customer_table WHERE
crypted_credit_card = DES_ENCRYPT('credit_card_number');
DES_ENCRYPT() was added in MySQL 4.0.1.
ENCRYPT(str[,salt])
crypt() system call. The
salt argument should be a string with two characters.
(As of MySQL 3.22.16, salt may be longer than two characters.)
If no salt argument is given, a random value is used.
mysql> SELECT ENCRYPT('hello');
-> 'VxuFAJXVARROc'
ENCRYPT() ignores all but the first eight characters of str, at
least on some systems. This behavior is determined by the implementation
of the underlying crypt() system call.
If crypt() is not available on your system, ENCRYPT() always
returns NULL. Because of this, we recommend that you use MD5()
or SHA1() instead, because those two functions exist on all platforms.
MD5(str)
NULL if the argument was NULL.
The return value can, for example, be used as a hash key.
mysql> SELECT MD5('testing');
-> 'ae2b1fca515949e5d54fb22b8ed95575'
This is the "RSA Data Security, Inc. MD5 Message-Digest Algorithm."
If you want to convert the value to uppercase, see the description of binary
string conversion given in the entry for the BINARY operator in
section 12.7 Cast Functions and Operators.
MD5() was added in MySQL 3.23.2.
OLD_PASSWORD(str)
OLD_PASSWORD() is available as of MySQL 4.1, when the implementation of
PASSWORD() was changed to improve security. OLD_PASSWORD()
returns the value of the pre-4.1 implementation of PASSWORD().
section 5.5.9 Password Hashing in MySQL 4.1.
PASSWORD(str)
NULL if the argument was NULL. This is
the function that is used for encrypting MySQL passwords for storage
in the Password column of the user grant table.
mysql> SELECT PASSWORD('badpwd');
-> '7f84554057dd964b'
PASSWORD() encryption is one-way (not reversible).
PASSWORD() does not perform password encryption in the same way that
Unix passwords are encrypted. See ENCRYPT().
Note:
The PASSWORD() function is used by the authentication system in
MySQL Server, you should not use it in your own applications.
For that purpose, use MD5() or SHA1() instead.
Also see RFC 2195 for more information about handling passwords
and authentication securely in your application.
SHA1(str)
SHA(str)
NULL if the argument was NULL.
One of the possible uses for this function is as a hash key. You can
also use it as a cryptographically safe function for storing passwords.
mysql> SELECT SHA1('abc');
-> 'a9993e364706816aba3e25717850c26c9cd0d89d'
SHA1() was added in MySQL 4.0.2, and can be considered
a cryptographically more secure equivalent of MD5().
SHA() is synonym for SHA1().
BENCHMARK(count,expr)
BENCHMARK() function executes the expression expr
repeatedly count times. It may be used to time how fast MySQL
processes the expression. The result value is always 0. The intended
use is from within the mysql client, which reports query execution times:
mysql> SELECT BENCHMARK(1000000,ENCODE('hello','goodbye'));
+----------------------------------------------+
| BENCHMARK(1000000,ENCODE('hello','goodbye')) |
+----------------------------------------------+
| 0 |
+----------------------------------------------+
1 row in set (4.74 sec)
The time reported is elapsed time on the client end, not CPU time on the
server end. It is advisable to execute BENCHMARK() several
times, and to interpret the result with regard to how heavily loaded the
server machine is.
CHARSET(str)
mysql> SELECT CHARSET('abc');
-> 'latin1'
mysql> SELECT CHARSET(CONVERT('abc' USING utf8));
-> 'utf8'
mysql> SELECT CHARSET(USER());
-> 'utf8'
CHARSET() was added in MySQL 4.1.0.
COERCIBILITY(str)
mysql> SELECT COERCIBILITY('abc' COLLATE latin1_swedish_ci);
-> 0
mysql> SELECT COERCIBILITY('abc');
-> 3
mysql> SELECT COERCIBILITY(USER());
-> 2
The return values have the following meanings:
| Coercibility | Meaning |
0 | Explicit collation |
1 | No collation |
2 | Implicit collation |
3 | Coercible |
COERCIBILITY() was added in MySQL 4.1.1.
COLLATION(str)
mysql> SELECT COLLATION('abc');
-> 'latin1_swedish_ci'
mysql> SELECT COLLATION(_utf8'abc');
-> 'utf8_general_ci'
COLLATION() was added in MySQL 4.1.0.
CONNECTION_ID()
mysql> SELECT CONNECTION_ID();
-> 23786
CONNECTION_ID() was added in MySQL 3.23.14.
CURRENT_USER()
USER().
mysql> SELECT USER();
-> 'davida@localhost'
mysql> SELECT * FROM mysql.user;
ERROR 1044: Access denied for user ''@'localhost' to
database 'mysql'
mysql> SELECT CURRENT_USER();
-> '@localhost'
The example illustrates that although the client specified a username of
davida (as indicated by the value of the USER() function),
the server authenticated the client using an anonymous user account (as seen by
the empty username part of the CURRENT_USER() value). One way this might
occur is that there is no account listed in the grant tables for
davida.
CURRENT_USER() was added in MySQL 4.0.6.
DATABASE()
mysql> SELECT DATABASE();
-> 'test'
If there is no default database, DATABASE() returns NULL as
of MySQL 4.1.1, and the empty string before that.
FOUND_ROWS()
SELECT statement may include a LIMIT clause to restrict the
number of rows the server returns to the client.
In some cases, it is desirable to know how many rows the statement would have
returned without the LIMIT, but without running the statement again.
To get this row count, include a SQL_CALC_FOUND_ROWS option in the
SELECT statement, then invoke FOUND_ROWS() afterward:
mysql> SELECT SQL_CALC_FOUND_ROWS * FROM tbl_name
-> WHERE id > 100 LIMIT 10;
mysql> SELECT FOUND_ROWS();
The second SELECT will return a number indicating how many rows the
first SELECT would have returned had it been written without the
LIMIT clause.
(If the preceding SELECT statement does not include the
SQL_CALC_FOUND_ROWS option, then FOUND_ROWS() may return
a different result when LIMIT is used than when it is not.)
Note that if you are using SELECT SQL_CALC_FOUND_ROWS, MySQL must
calculate how many rows are in the full result set. However, this is
faster than running the query again without LIMIT, because the result
set need not be sent to the client.
SQL_CALC_FOUND_ROWS and FOUND_ROWS() can be useful in situations
when you want to restrict the number of rows that a query returns, but also
determine the number of rows in the full result set without running the query
again. An example is a Web script that presents a paged display containing
links to the pages that show other sections of a search result. Using
FOUND_ROWS() allows you to determine how many other pages are needed
for the rest of the result.
The use of SQL_CALC_FOUND_ROWS and FOUND_ROWS() is more complex
for UNION queries than for simple SELECT statements, because
LIMIT may occur at multiple places in a UNION. It may be applied
to individual SELECT statements in the UNION, or global to the
UNION result as a whole.
The intent of SQL_CALC_FOUND_ROWS for UNION is that it should
return the row count that would be returned without a global LIMIT.
The conditions for use of SQL_CALC_FOUND_ROWS with UNION are:
SQL_CALC_FOUND_ROWS keyword must appear in the first SELECT
of the UNION.
FOUND_ROWS() is exact only if UNION ALL is used.
If UNION without ALL is used, duplicate removal occurs and the
value of FOUND_ROWS() is only approximate.
LIMIT is present in the UNION, SQL_CALC_FOUND_ROWS
is ignored and returns the number of rows in the temporary table that is
created to process the UNION.
SQL_CALC_FOUND_ROWS and FOUND_ROWS() are available starting
at MySQL 4.0.0.
LAST_INSERT_ID()
LAST_INSERT_ID(expr)
AUTO_INCREMENT column.
mysql> SELECT LAST_INSERT_ID();
-> 195
The last ID that was generated is maintained in the server on a
per-connection basis. This means the value the function returns to a given
client is the most recent AUTO_INCREMENT value generated by that
client. The value cannot be affected by other clients, even if they generate
AUTO_INCREMENT values of their own. This behavior ensures that you can
retrieve your own ID without concern for the activity of other clients, and
without the need for locks or transactions.
The value of LAST_INSERT_ID() is not changed if you
update the AUTO_INCREMENT column of a row with a
non-magic value (that is, a value that is not NULL and not 0).
If you insert many rows at the same time with an insert statement,
LAST_INSERT_ID() returns the value for the first inserted row.
The reason for this is to make it possible to easily reproduce
the same INSERT statement against some other server.
If you use INSERT IGNORE and the record is ignored, the
AUTO_INCREMENT counter still is incremented and
LAST_INSERT_ID() returns the new value.
If expr is given as an argument to LAST_INSERT_ID(),
the value of the argument is returned by the function and is remembered as the
next value to be returned by LAST_INSERT_ID(). This can be used
to simulate sequences:
mysql> CREATE TABLE sequence (id INT NOT NULL); mysql> INSERT INTO sequence VALUES (0);
mysql> UPDATE sequence SET id=LAST_INSERT_ID(id+1); mysql> SELECT LAST_INSERT_ID();The
UPDATE statement increments the sequence counter and causes the
next call to LAST_INSERT_ID() to return the updated value.
The SELECT statement retrieves that value.
The mysql_insert_id() C API function
can also be used to get the value.
See section 21.2.3.33 mysql_insert_id().
LAST_INSERT_ID(), but the
utility of using the function this way is that the ID value is maintained in
the server as the last automatically generated value.
It is multi-user safe because multiple clients can issue the UPDATE
statement and get their own sequence value with the SELECT statement
(or mysql_insert_id()), without affecting or being affected by other
clients that generate their own sequence values.
Note that mysql_insert_id() is only updated after INSERT
and UPDATE statements, so you cannot use the C API function to
retrieve the value for LAST_INSERT_ID(expr) after executing other
SQL statements like SELECT or SET.
ROW_COUNT()
ROW_COUNT() returns the number of rows updated, inserted, or deleted
by the preceding statement. This is the same as the row count that the
mysql client displays and the value from the
mysql_affected_rows() C API function.
mysql> INSERT INTO t VALUES(1),(2),(3); Query OK, 3 rows affected (0.00 sec) Records: 3 Duplicates: 0 Warnings: 0 mysql> SELECT ROW_COUNT(); +-------------+ | ROW_COUNT() | +-------------+ | 3 | +-------------+ 1 row in set (0.00 sec) mysql> DELETE FROM t WHERE i IN(1,2); Query OK, 2 rows affected (0.00 sec) mysql> SELECT ROW_COUNT(); +-------------+ | ROW_COUNT() | +-------------+ | 2 | +-------------+ 1 row in set (0.00 sec)
ROW_COUNT() was added in MySQL 5.0.1.
SESSION_USER()
SESSION_USER() is a synonym for USER().
SYSTEM_USER()
SYSTEM_USER() is a synonym for USER().
USER()
mysql> SELECT USER();
-> 'davida@localhost'
The value indicates the username you specified when connecting to
the server, and the client host from which you connected. The value can be
different than that of CURRENT_USER().
Prior to MySQL 3.22.11, the function value does not include the client
hostname. You can extract just the username part, regardless of whether the
value includes a hostname part, like this:
mysql> SELECT SUBSTRING_INDEX(USER(),'@',1);
-> 'davida'
As of MySQL 4.1, USER() returns a value in the utf8 character
set, so you should also make sure that the '@' string literal is
interpreted in that character set:
mysql> SELECT SUBSTRING_INDEX(USER(),_utf8'@',1);
-> 'davida'
VERSION()
mysql> SELECT VERSION();
-> '4.1.3-beta-log'
Note that if your version string ends with -log this means that
logging is enabled.
DEFAULT(col_name)
mysql> UPDATE t SET i = DEFAULT(i)+1 WHERE id < 100;
DEFAULT() was added in MySQL 4.1.0.
FORMAT(X,D)
'#,###,###.##', rounded
to D decimals, and returns the result as a string.
If D is 0, the result will have no
decimal point or fractional part.
mysql> SELECT FORMAT(12332.123456, 4);
-> '12,332.1235'
mysql> SELECT FORMAT(12332.1,4);
-> '12,332.1000'
mysql> SELECT FORMAT(12332.2,0);
-> '12,332'
GET_LOCK(str,timeout)
1 if the lock was obtained
successfully, 0 if the attempt timed out (for example, because another
client has already locked the name), or NULL if an error
occurred (such as running out of memory or the thread was killed with
mysqladmin kill). If you have a lock obtained with GET_LOCK(),
it is released when you execute
RELEASE_LOCK(), execute a new GET_LOCK(), or your connection
terminates (either normally or abnormally).
This function can be used to implement application locks or to
simulate record locks. Names are locked on a server-wide basis.
If a name has been locked by one client, GET_LOCK() blocks
any request by another client for a lock with the same name. This
allows clients that agree on a given lock name to use the name to
perform cooperative advisory locking.
mysql> SELECT GET_LOCK('lock1',10);
-> 1
mysql> SELECT IS_FREE_LOCK('lock2');
-> 1
mysql> SELECT GET_LOCK('lock2',10);
-> 1
mysql> SELECT RELEASE_LOCK('lock2');
-> 1
mysql> SELECT RELEASE_LOCK('lock1');
-> NULL
Note that the second RELEASE_LOCK() call returns NULL because
the lock 'lock1' was automatically released by the second
GET_LOCK() call.
INET_ATON(expr)
mysql> SELECT INET_ATON('209.207.224.40');
-> 3520061480
The generated number is always in network byte order. For the example
just shown, the number is calculated as 209*256^3 + 207*256^2 +
224*256 + 40.
As of MySQL 4.1.2, INET_ATON() also understands short-form IP
addresses:
mysql> SELECT INET_ATON('127.0.0.1'), INET_ATON('127.1');
-> 2130706433, 2130706433
INET_ATON() was added in MySQL 3.23.15.
INET_NTOA(expr)
mysql> SELECT INET_NTOA(3520061480);
-> '209.207.224.40'
INET_NTOA() was added in MySQL 3.23.15.
IS_FREE_LOCK(str)
1 if the lock is free (no one is using the lock),
0 if the lock is in use, and
NULL on errors (such as incorrect arguments).
IS_FREE_LOCK() was added in MySQL 4.0.2.
IS_USED_LOCK(str)
NULL.
IS_USED_LOCK() was added in MySQL 4.1.0.
MASTER_POS_WAIT(log_name,log_pos[,timeout])
NULL if the slave SQL thread
is not started, the slave's master information is not initialized, the
arguments are incorrect, or an error occurs. It returns -1 if the
timeout has been exceeded. If the slave SQL thread stops while
MASTER_POS_WAIT() is waiting, the function returns NULL.
If the slave is already past the specified position, the function returns
immediately.
If a timeout value is specified, MASTER_POS_WAIT()
stops waiting when timeout seconds have elapsed. timeout must
be greater than 0; a zero or negative timeout means no timeout.
MASTER_POS_WAIT() was added in MySQL 3.23.32.
The timeout argument was added in 4.0.10.
RELEASE_LOCK(str)
GET_LOCK(). Returns 1 if the lock was released, 0 if the
lock wasn't locked by this thread (in which case the lock is not released),
and NULL if the named lock didn't exist. The lock will not exist if
it was never obtained by a call to GET_LOCK() or if it already has
been released.
The DO statement is convenient to use with RELEASE_LOCK().
See section 13.1.2 DO Syntax.
UUID()
UUID() are expected to generate two different
values, even if these calls are performed on two separate computers that are
not connected to each other.
A UUID is a 128-bit number represented by a string
of five hexadecimal numbers in aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
format:
mysql> SELECT UUID();
-> '6ccd780c-baba-1026-9564-0040f4311e29'
Note that UUID() does not yet work with replication.
UUID() was added in MySQL 4.1.2.
GROUP BY ClausesGROUP BY (Aggregate) Functions
If you use a group function in a statement containing no GROUP BY
clause, it is equivalent to grouping on all rows.
AVG(expr)
expr.
mysql> SELECT student_name, AVG(test_score)
-> FROM student
-> GROUP BY student_name;
BIT_AND(expr)
AND of all bits in expr. The calculation is
performed with 64-bit (BIGINT) precision.
As of MySQL 4.0.17, this function returns
18446744073709551615 if there were no matching rows.
(This is an unsigned BIGINT value with all bits set to 1.)
Before 4.0.17, the function returns -1 if there were no matching rows.
BIT_OR(expr)
OR of all bits in expr. The calculation is
performed with 64-bit (BIGINT) precision.
This function returns 0 if there were no matching rows.
BIT_XOR(expr)
XOR of all bits in expr. The calculation is
performed with 64-bit (BIGINT) precision.
This function returns 0 if there were no matching rows.
This function is available as of MySQL 4.1.1.
COUNT(expr)
NULL values in the rows
retrieved by a SELECT statement.
mysql> SELECT student.student_name,COUNT(*)
-> FROM student,course
-> WHERE student.student_id=course.student_id
-> GROUP BY student_name;
COUNT(*) is somewhat different in that it returns a count of
the number of rows retrieved, whether or not they contain NULL
values.
COUNT(*) is optimized to
return very quickly if the SELECT retrieves from one table, no
other columns are retrieved, and there is no WHERE clause.
For example:
mysql> SELECT COUNT(*) FROM student;This optimization applies only to
MyISAM and ISAM tables
only, because an exact record count is stored for these table types and
can be accessed very quickly. For transactional storage engines
(InnoDB, BDB), storing an exact row count is more problematic
because multiple transactions may be occurring, each of which may affect the
count.
COUNT(DISTINCT expr,[expr...])
NULL values.
mysql> SELECT COUNT(DISTINCT results) FROM student;In MySQL, you can get the number of distinct expression combinations that don't contain
NULL by giving a list of expressions.
In standard SQL, you would have to do a concatenation of all expressions
inside COUNT(DISTINCT ...).
COUNT(DISTINCT ...) was added in MySQL 3.23.2.
GROUP_CONCAT(expr)
NULL
values from a group. It returns NULL if there are no non-NULL
values. The full syntax is as follows:
GROUP_CONCAT([DISTINCT] expr [,expr ...]
[ORDER BY {unsigned_integer | col_name | expr}
[ASC | DESC] [,col_name ...]]
[SEPARATOR str_val])
mysql> SELECT student_name,
-> GROUP_CONCAT(test_score)
-> FROM student
-> GROUP BY student_name;
Or:
mysql> SELECT student_name,
-> GROUP_CONCAT(DISTINCT test_score
-> ORDER BY test_score DESC SEPARATOR ' ')
-> FROM student
-> GROUP BY student_name;
In MySQL, you can get the concatenated values of expression combinations.
You can eliminate duplicate values by using DISTINCT.
If you want to sort values in the result, you should use ORDER BY
clause.
To sort in reverse order, add the DESC (descending) keyword to the
name of the column you are sorting by in the ORDER BY clause. The
default is ascending order; this may be specified explicitly using the
ASC keyword.
SEPARATOR is followed by the string value that should be inserted between
values of result. The default is a comma (`,'). You can remove
the separator altogether by specifying SEPARATOR ''.
You can set a maximum allowed length with the
group_concat_max_len system variable.
The syntax to do this at runtime is as follows, where val is an
unsigned integer:
SET [SESSION | GLOBAL] group_concat_max_len = val;If a maximum length has been set, the result is truncated to this maximum length.
GROUP_CONCAT() was added in MySQL 4.1.
Note: Before MySQL 4.1.6, there are some small limitations with
GROUP_CONCAT() for BLOB and TEXT values when it comes
to using DISTINCT together with ORDER BY. To work around
this limitation, use MID(expr,1,255) instead.
MIN(expr)
MAX(expr)
MIN() and
MAX() may take a string argument; in such cases they return the
minimum or maximum string value. See section 7.4.5 How MySQL Uses Indexes.
mysql> SELECT student_name, MIN(test_score), MAX(test_score)
-> FROM student
-> GROUP BY student_name;
For MIN(), MAX(), and other aggregate functions, MySQL
currently compares ENUM and SET columns by their string
value rather than by the string's relative position in the set.
This differs from how ORDER BY compares them.
This will be rectified.
STD(expr)
STDDEV(expr)
VARIANCE()). This is an extension to standard SQL. The STDDEV()
form of this function is provided for Oracle compatibility.
SUM(expr)
SUM() returns NULL.
VARIANCE(expr)
GROUP BY Modifiers
As of MySQL 4.1.1, the GROUP BY clause allows a WITH
ROLLUP modifier that causes extra rows to be added to the summary
output. These rows represent higher-level (or super-aggregate) summary
operations. ROLLUP thus allows you to answer questions at multiple
levels of analysis with a single query. It can be used, for example,
to provide support for OLAP (Online Analytical Processing) operations.
As an illustration, suppose that a table named sales has year,
country,
product, and profit columns for recording sales profitability:
CREATE TABLE sales
(
year INT NOT NULL,
country VARCHAR(20) NOT NULL,
product VARCHAR(32) NOT NULL,
profit INT
);
The table's contents can be summarized per year with a simple GROUP BY
like this:
mysql> SELECT year, SUM(profit) FROM sales GROUP BY year; +------+-------------+ | year | SUM(profit) | +------+-------------+ | 2000 | 4525 | | 2001 | 3010 | +------+-------------+
This output shows the total profit for each year, but if you also want to determine the total profit summed over all years, you must add up the individual values yourself or run an additional query.
Or you can use ROLLUP, which provides both levels of analysis with a
single query.
Adding a WITH ROLLUP modifier to the GROUP BY clause causes the query
to produce another row that shows the grand total over all year values:
mysql> SELECT year, SUM(profit) FROM sales GROUP BY year WITH ROLLUP; +------+-------------+ | year | SUM(profit) | +------+-------------+ | 2000 | 4525 | | 2001 | 3010 | | NULL | 7535 | +------+-------------+
The grand total super-aggregate line is identified by the value NULL in
the year column.
ROLLUP has a more complex effect when there are multiple GROUP BY
columns. In this case, each time there is a ``break'' (change in value)
in any but the last grouping column, the query produces an extra
super-aggregate summary row.
For example, without ROLLUP, a summary on the sales table based
on year,
country, and product might look like this:
mysql> SELECT year, country, product, SUM(profit)
-> FROM sales
-> GROUP BY year, country, product;
+------+---------+------------+-------------+
| year | country | product | SUM(profit) |
+------+---------+------------+-------------+
| 2000 | Finland | Computer | 1500 |
| 2000 | Finland | Phone | 100 |
| 2000 | India | Calculator | 150 |
| 2000 | India | Computer | 1200 |
| 2000 | USA | Calculator | 75 |
| 2000 | USA | Computer | 1500 |
| 2001 | Finland | Phone | 10 |
| 2001 | USA | Calculator | 50 |
| 2001 | USA | Computer | 2700 |
| 2001 | USA | TV | 250 |
+------+---------+------------+-------------+
The output indicates summary values only at the year/country/product level of
analysis. When ROLLUP is added, the query produces several extra rows:
mysql> SELECT year, country, product, SUM(profit)
-> FROM sales
-> GROUP BY year, country, product WITH ROLLUP;
+------+---------+------------+-------------+
| year | country | product | SUM(profit) |
+------+---------+------------+-------------+
| 2000 | Finland | Computer | 1500 |
| 2000 | Finland | Phone | 100 |
| 2000 | Finland | NULL | 1600 |
| 2000 | India | Calculator | 150 |
| 2000 | India | Computer | 1200 |
| 2000 | India | NULL | 1350 |
| 2000 | USA | Calculator | 75 |
| 2000 | USA | Computer | 1500 |
| 2000 | USA | NULL | 1575 |
| 2000 | NULL | NULL | 4525 |
| 2001 | Finland | Phone | 10 |
| 2001 | Finland | NULL | 10 |
| 2001 | USA | Calculator | 50 |
| 2001 | USA | Computer | 2700 |
| 2001 | USA | TV | 250 |
| 2001 | USA | NULL | 3000 |
| 2001 | NULL | NULL | 3010 |
| NULL | NULL | NULL | 7535 |
+------+---------+------------+-------------+
For this query, adding ROLLUP causes the output to include summary
information at four levels of analysis, not just one. Here's how to
interpret the ROLLUP output:
product column set to NULL.
country and products columns set to NULL.
year, country, and products columns set to
NULL.
Other Considerations When using ROLLUP
The following items list some behaviors specific to the MySQL implementation
of ROLLUP:
When you use ROLLUP, you cannot also use an ORDER BY clause to
sort the results. In other words, ROLLUP and ORDER BY are mutually
exclusive. However, you still have some control over sort order.
GROUP BY
in MySQL sorts results, and you can use explicit ASC and DESC keywords
with columns named in the GROUP BY list to specify sort order for
individual columns. (The higher-level summary rows added by ROLLUP
still appear after the rows from which they are calculated, regardless
of the sort order.)
LIMIT can be used to restrict the number of rows returned to the
client. LIMIT is applied after ROLLUP, so the limit applies
against the extra rows added by ROLLUP. For example:
mysql> SELECT year, country, product, SUM(profit)
-> FROM sales
-> GROUP BY year, country, product WITH ROLLUP
-> LIMIT 5;
+------+---------+------------+-------------+
| year | country | product | SUM(profit) |
+------+---------+------------+-------------+
| 2000 | Finland | Computer | 1500 |
| 2000 | Finland | Phone | 100 |
| 2000 | Finland | NULL | 1600 |
| 2000 | India | Calculator | 150 |
| 2000 | India | Computer | 1200 |
+------+---------+------------+-------------+
Using LIMIT with ROLLUP may produce results
that are more difficult to interpret, because you have less context
for understanding the super-aggregate rows.
The NULL indicators in each super-aggregate row are produced when the
row is sent to the client. The server looks at the columns named in
the GROUP BY clause following the leftmost one that has changed value.
For any column in the result set with a name that is a lexical match to
any of those names, its value is set to NULL. (If you specify grouping
columns by column number, the server identifies which columns to set to
NULL by number.)
Because the NULL values in the super-aggregate rows are placed into the
result set at such a late stage in query processing, you cannot test them
as NULL values within the query itself. For example, you cannot add
HAVING product IS NULL to the query to eliminate from the output all
but the super-aggregate rows.
On the other hand, the NULL values do appear as NULL
on the client side and can be tested as such using any MySQL client
programming interface.
GROUP BY with Hidden Fields
MySQL extends the use of GROUP BY so that you can use columns or
calculations in the SELECT list that don't appear in
the GROUP BY clause. This stands for any possible value for this
group. You can use this to get better performance by avoiding sorting and
grouping on unnecessary items. For example, you don't need to group on
customer.name in the following query:
mysql> SELECT order.custid, customer.name, MAX(payments)
-> FROM order,customer
-> WHERE order.custid = customer.custid
-> GROUP BY order.custid;
In standard SQL, you would have to add customer.name to the
GROUP BY clause. In MySQL, the name is redundant if you don't run in
ANSI mode.
Do not use this feature if the columns you omit from the
GROUP BY part are not unique in the group! You will get
unpredictable results.
In some cases, you can use MIN() and MAX() to obtain a specific
column value even if it isn't unique. The following gives the value of
column from the row containing the smallest value in the sort
column:
SUBSTR(MIN(CONCAT(RPAD(sort,6,' '),column)),7)
See section 3.6.4 The Rows Holding the Group-wise Maximum of a Certain Field.
Note that if you are using MySQL 3.22 (or earlier) or if
you are trying to follow standard SQL, you can't use expressions in GROUP
BY or ORDER BY clauses. You can work around this limitation by
using an alias for the expression:
mysql> SELECT id,FLOOR(value/100) AS val FROM tbl_name
-> GROUP BY id, val ORDER BY val;
In MySQL 3.23 and up, aliases are unnecessary. You can use expressions
in GROUP BY and ORDER BY clauses. For example:
mysql> SELECT id, FLOOR(value/100) FROM tbl_name ORDER BY RAND();
Go to the first, previous, next, last section, table of contents.