SQL Functions

• Overview
• Operator and Function Reference
• Operators
• Operator Precedence
• Type Conversion in Expression Evaluation
• Comparison Functions and Operators
• Logical Operators
• Control Flow Functions
• String Functions
• String Comparison Functions
• Regular Expressions
• Numeric Functions
• Arithmetic Operators
• Mathematical Functions
• Date and Time Functions
• Cast Functions and Operators
• Other Functions
• Bit Functions
• Encryption and Compression Functions
• Information Functions
• Miscellaneous Functions
• GROUP BY (Aggregate) Functions
• GROUP BY Modifiers
• GROUP BY and HAVING with Hidden Fields

Overview

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, built-in functions, stored functions, user-defined 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. However, spaces around function arguments are permitted.

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 become reserved words.

For the sake of brevity, most examples in this chapter display the output from the mysql program in abbreviated form. Rather than showing examples in this format:

(sql sqlHandle {SELECT MOD(29,9)}) Returns
+-----------+
| mod(29,9) |
+-----------+
|         2 |
+-----------+

This format is used instead:

(sql sqlHandle {SELECT MOD(29,9)}) Returns 2

Operator and Function Reference

Operators

Operator Precedence

Operator precedences are shown in the following list, from highest precedence to the lowest. Operators that are shown together on a line have the same precedence.

INTERVAL
BINARY, COLLATE
!
- (unary minus), ~ (unary bit inversion)
^
*, /, DIV, %, MOD
-, +
<<, >>
&
|
=, <=>, >=, >, <=, <, <>, !=, IS, LIKE, REGEXP, IN
BETWEEN, CASE, WHEN, THEN, ELSE
NOT
&&, AND
XOR
||, OR
:=

The || operator has a precedence between ^ and the unary operators if the PIPES_AS_CONCAT SQL mode is enabled.

Note: If the HIGH_NOT_PRECEDENCE SQL mode is enabled, the precedence of NOT is the same as that of the ! operator.

The precedence of operators determines the order of evaluation of terms in an expression. To override this order and group terms explicitly, use parentheses. For example:

(sql sqlHandle {SELECT 1+2*3}) Returns 7

(sql sqlHandle {SELECT (1+2)*3}) Returns 9

Type Conversion in Expression Evaluation

When an operator is used with operands of different types, type conversion occurs to make the operands compatible. Some conversions occur implicitly. For example, MySQL automatically converts numbers to strings as necessary, and vice versa.

(sql sqlHandle {SELECT 1+'1'}) Returns 2

(sql sqlHandle {SELECT CONCAT(2,' test')}) Returns '2 test'

It is also possible to perform explicit conversions. If you want to convert a number to a string explicitly, use the CAST() or CONCAT() function (CAST() is preferable):

(sql sqlHandle {SELECT 38.8, CAST(38.8 AS CHAR)}) Returns 38.8, '38.8'

(sql sqlHandle {SELECT 38.8, CONCAT(38.8)}) Returns 38.8, '38.8'

The following rules describe how conversion occurs for comparison operations:

If one or both arguments are NULL, the result of the comparison is NULL, except for the NULL-safe <=> equality comparison operator. For NULL <=> NULL, the result is true.

If both arguments in a comparison operation are strings, they are compared as strings.

If both arguments are integers, they are compared as integers.

Hexadecimal values are treated as binary strings if not compared to a number.

If one of the arguments is a TIMESTAMP or DATETIME column and the other argument is a constant, the constant is converted to a timestamp before the comparison is performed. This is done to be more ODBC-friendly. Note that this is not done for the arguments to IN()! To be safe, always use complete datetime, date, or time strings when doing comparisons.

In all other cases, the arguments are compared as floating-point (real) numbers.

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

(sql sqlHandle {SELECT 1 > '6x'}) Returns 0

(sql sqlHandle {SELECT 7 > '6x'}) Returns 1

(sql sqlHandle {SELECT 0 > 'x6'}) Returns 0

(sql sqlHandle {SELECT 0 = 'x6'}) Returns 1

Note that when you are comparing a string column with a number, MySQL cannot use an index on the column to look up the value quickly. If str_col is an indexed string column, the index cannot be used when performing the lookup in the following statement:

(sql sqlHandle {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, such as '1', ' 1', or '1a'.

Comparisons that use floating-point numbers (or values that are converted to floating-point numbers) are approximate because such numbers are inexact. This might lead to results that appear inconsistent:

(sql sqlHandle {SELECT '18015376320243458' = 18015376320243458}) Returns 1

(sql sqlHandle {SELECT '18015376320243459' = 18015376320243459}) Returns 0

Such results can occur because the values are converted to floating-point numbers, which have only 53 bits of precision and are subject to rounding:

(sql sqlHandle {SELECT '18015376320243459'+0.0}) Returns 1.8015376320243e+16

Furthermore, the conversion from string to floating-point and from integer to floating-point do not necessarily occur the same way. The integer may be converted to floating-point by the CPU, whereas the string is converted digit by digit in an operation that involves floating-point multiplications.

The results shown will vary on different systems, and can be affected by factors such as computer architecture or the compiler version or optimization level. One way to avoid such problems is to use CAST() so that a value will not be converted implicitly to a float-point number:

(sql sqlHandle {SELECT CAST('18015376320243459' AS UNSIGNED) = 18015376320243459}) Returns 1

Comparison Functions and Operators

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 return values other than 1 (TRUE), 0 (FALSE), or NULL. For example, LEAST() and GREATEST(). However, the value they return is based on comparison operations performed.

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().

By default, string comparisons are not case sensitive and use the current character set. The default is latin1 (cp1252 West European), which also works well for English.

• =

  Equal:

  (sql sqlHandle {SELECT 1 = 0}) Returns 0

  (sql sqlHandle {SELECT '0' = 0}) Returns 1

  (sql sqlHandle {SELECT '0.0' = 0}) Returns 1

  (sql sqlHandle {SELECT '0.01' = 0}) Returns 0

  (sql sqlHandle {SELECT '.01' = 0.01}) Returns 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.

  (sql sqlHandle {SELECT 1 <=> 1, NULL <=> NULL, 1 <=> NULL}) Returns 1, 1, 0

  (sql sqlHandle {SELECT 1 = 1, NULL = NULL, 1 = NULL}) Returns 1, NULL, NULL

• <>, !=

  Not equal:

  (sql sqlHandle {SELECT '.01' <> '0.01'}) Returns 1

  (sql sqlHandle {SELECT .01 <> '0.01'}) Returns 0

  (sql sqlHandle {SELECT 'zapp' <> 'zappp'}) Returns 1

• <=

  Less than or equal:

  (sql sqlHandle {SELECT 0.1 <= 2}) Returns 1

• <

  Less than:

  (sql sqlHandle {SELECT 2 < 2}) Returns 0

• >=

  Greater than or equal:

  (sql sqlHandle {SELECT 2 >= 2}) Returns 1

• >

  Greater than:

  (sql sqlHandle {SELECT 2 > 2}) Returns 0

• IS boolean_value

  Tests a value against a boolean value, where boolean_value can be TRUE, FALSE, or UNKNOWN.

  (sql sqlHandle {SELECT 1 IS TRUE, 0 IS FALSE, NULL IS UNKNOWN}) Returns 1, 1, 1

• IS NOT boolean_value

  Tests a value against a boolean value, where boolean_value can be TRUE, FALSE, or UNKNOWN.

  (sql sqlHandle {SELECT 1 IS NOT UNKNOWN, 0 IS NOT UNKNOWN, NULL IS NOT UNKNOWN}) Returns 1, 1, 0

• IS NULL

  Tests whether a value is NULL.

  (sql sqlHandle {SELECT 1 IS NULL, 0 IS NULL, NULL IS NULL}) Returns 0, 0, 1

  To work well with ODBC programs, MySQL supports the following extra features when using IS NULL:

  • You can find the row that contains the most recent AUTO_INCREMENT value by issuing a statement of the following form immediately after generating the value:

    (sql sqlHandle {SELECT * FROM tbl_name WHERE auto_col IS NULL})

    This behavior can be disabled by setting SQL_AUTO_IS_NULL=0.

  • For 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:

    (sql sqlHandle {SELECT * FROM tbl_name WHERE date_column IS NULL})

    This is needed to get some ODBC applications to work because ODBC does not support a '0000-00-00' date value.

• IS NOT NULL

  Tests whether a value is not NULL.

  (sql sqlHandle {SELECT 1 IS NOT NULL, 0 IS NOT NULL, NULL IS NOT NULL}) Returns 1, 1, 0

• expr BETWEEN min AND max

  If expr is greater than or equal to min and expr is less than or equal to max, BETWEEN returns 1, otherwise it returns 0. This is equivalent to the expression (min <= expr AND expr <= max) if all the arguments are of the same type.

  (sql sqlHandle {SELECT 1 BETWEEN 2 AND 3}) Returns 0

  (sql sqlHandle {SELECT 'b' BETWEEN 'a' AND 'c'}) Returns 1

  (sql sqlHandle {SELECT 2 BETWEEN 2 AND '3'}) Returns 1

  (sql sqlHandle {SELECT 2 BETWEEN 2 AND 'x-3'}) Returns 0

  For best results when using BETWEEN with date or time values, you should use CAST() to explicitly convert the values to the desired data type. Examples: If you compare a DATETIME to two DATE values, convert the DATE values to DATETIME values. If you use a string constant such as '2001-1-1' in a comparison to a DATE, cast the string to a DATE.

• expr NOT BETWEEN min AND max

  This is the same as NOT (expr BETWEEN min AND max).

• COALESCE(value,...)

  Returns the first non-NULL value in the list, or NULL if there are no non-NULL values.

  (sql sqlHandle {SELECT COALESCE(NULL,1)}) Returns 1

  (sql sqlHandle {SELECT COALESCE(NULL,NULL,NULL)}) Returns NULL

• GREATEST(value1,value2,...)

  With two or more arguments, returns the largest (maximum-valued) argument. The arguments are compared using the same rules as for LEAST().

  (sql sqlHandle {SELECT GREATEST(2,0)}) Returns 2

  (sql sqlHandle {SELECT GREATEST(34.0,3.0,5.0,767.0)}) Returns 767.0

  (sql sqlHandle {SELECT GREATEST('B','A','C')}) Returns 'C'

  GREATEST() returns NULL if any argument is NULL.

• expr IN (value,...)

  Returns 1 if expr is equal to 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.

  (sql sqlHandle {SELECT 2 IN (0,3,5,7)}) Returns 0

  (sql sqlHandle {SELECT 'wefwf' IN ('wee','wefwf','weg')}) Returns 1

  You should never mix quoted and unquoted values in an IN list because the comparison rules for quoted values (such as strings) and unquoted values (such as numbers) differ. Mixing types may therefore lead to inconsistent results. For example, do not write an IN expression like this:

  (sql sqlHandle {SELECT val1 FROM tbl1 WHERE val1 IN (1,2,'a')})

  Instead, write it like this:

  (sql sqlHandle {SELECT val1 FROM tbl1 WHERE val1 IN ('1','2','a')})

  The number of values in the IN list is only limited by the max_allowed_packet value.

  To comply with the SQL standard, 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.

  IN() syntax can also be used to write certain types of subqueries.

• expr NOT IN (value,...)

  This is the same as NOT (expr IN (value,...)).

• ISNULL(expr)

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

  (sql sqlHandle {SELECT ISNULL(1+1)}) Returns 0

  (sql sqlHandle {SELECT ISNULL(1/0)}) Returns 1

  ISNULL() can be used instead of = to test whether a value is NULL. (Comparing a value to NULL using = always yields false.)

  The ISNULL() function shares some special behaviors with the IS NULL comparison operator. See the description of IS NULL.

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

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

  (sql sqlHandle {SELECT INTERVAL(23, 1, 15, 17, 30, 44, 200)}) Returns 3

  (sql sqlHandle {SELECT INTERVAL(10, 1, 10, 100, 1000)}) Returns 2

  (sql sqlHandle {SELECT INTERVAL(22, 23, 30, 44, 200)}) Returns 0

• LEAST(value1,value2,...)

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

  • If the return value is used in an INTEGER context or all arguments are integer-valued, they are compared as integers.

  If the return value is used in a REAL context or all arguments are real-valued, they are compared as reals.

  • If any argument is a case-sensitive string, the arguments are compared as case-sensitive strings.

  • In all other cases, the arguments are compared as case-insensitive strings.

  LEAST() returns NULL if any argument is NULL.

  (sql sqlHandle {SELECT LEAST(2,0)}) Returns 0

  >

  (sql sqlHandle {SELECT LEAST(34.0,3.0,5.0,767.0)}) Returns 3.0

  (sql sqlHandle {SELECT LEAST('B','A','C')}) Returns 'A'

  Note that the preceding conversion rules can produce strange results in some borderline cases:

  (sql sqlHandle {SELECT CAST(LEAST(3600, 9223372036854775808.0) as SIGNED)}) Returns -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.

Logical Operators

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.

Note that MySQL evaluates any non-zero or non-NULL value to TRUE. For example, the following statements all assess to TRUE:

(sql sqlHandle {SELECT 10 IS TRUE}) Returns 1

(sql sqlHandle {SELECT -10 IS TRUE}) Returns 1

(sql sqlHandle {SELECT 'string' IS NOT NULL}) Returns 1

• NOT, !

  Logical NOT. Evaluates to 1 if the operand is 0, to 0 if the operand is non-zero, and NOT NULL returns NULL.

  (sql sqlHandle {SELECT NOT 10}) Returns 0

  (sql sqlHandle {SELECT NOT 0}) Returns 1

  (sql sqlHandle {SELECT NOT NULL}) Returns NULL

  (sql sqlHandle {SELECT ! (1+1)}) Returns 0

  (sql sqlHandle {SELECT ! 1+1}) Returns 1

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

• AND, &&

  Logical AND. Evaluates to 1 if all operands are non-zero and not NULL, to 0 if one or more operands are 0, otherwise NULL is returned.

  (sql sqlHandle {SELECT 1 && 1}) Returns 1

  (sql sqlHandle {SELECT 1 && 0}) Returns 0

  (sql sqlHandle {SELECT 1 && NULL}) Returns NULL

  (sql sqlHandle {SELECT 0 && NULL}) Returns 0

  (sql sqlHandle {SELECT NULL && 0}) Returns 0

• OR, ||

  Logical OR. When both operands are non-NULL, the result is 1 if any operand is non-zero, and 0 otherwise. With a NULL operand, the result is 1 if the other operand is non-zero, and NULL otherwise. If both operands are NULL, the result is NULL.

  (sql sqlHandle {SELECT 1 || 1}) Returns 1

  (sql sqlHandle {SELECT 1 || 0}) Returns 1

  (sql sqlHandle {SELECT 0 || 0}) Returns 0

  (sql sqlHandle {SELECT 0 || NULL}) Returns NULL

  (sql sqlHandle {SELECT 1 || NULL}) Returns 1

• XOR

  Logical XOR. Returns NULL if either operand is NULL. For non-NULL operands, evaluates to 1 if an odd number of operands is non-zero, otherwise 0 is returned.

  (sql sqlHandle {SELECT 1 XOR 1}) Returns 0

  (sql sqlHandle {SELECT 1 XOR 0}) Returns 1

  (sql sqlHandle {SELECT 1 XOR NULL}) Returns NULL

  (sql sqlHandle {SELECT 1 XOR 1 XOR 1}) Returns 1

  a XOR b is mathematically equal to (a AND (NOT b)) OR ((NOT a) and b).

Control Flow Functions

• CASE value WHEN [compare_value] THEN result [WHEN [compare_value] THEN result ...] [ELSE result] END

  CASE WHEN [condition] THEN result [WHEN [condition] THEN result ...] [ELSE result] END

  The first version returns the result where value=compare_value. The second version returns the result for the first condition that is true. If there was no matching result value, the result after ELSE is returned, or NULL if there is no ELSE part.

  (sql sqlHandle {SELECT CASE 1 WHEN 1 THEN 'one' WHEN 2 THEN 'two' ELSE 'more' END}) Returns 'one'

  (sql sqlHandle {SELECT CASE WHEN 1>0 THEN 'true' ELSE 'false' END}) Returns 'true'

  (sql sqlHandle {SELECT CASE BINARY 'B' WHEN 'a' THEN 1 WHEN 'b' THEN 2 END}) Returns NULL

  The default return type of a CASE expression is the compatible aggregated type of all return values, but also depends on the context in which it is used. If used in a string context, the result is returned as a string. If used in a numeric context, then the result is returned as a decimal, real, or integer value.

  Note: The syntax of the CASE expression shown here differs slightly from that of the SQL CASE statement, for use inside stored routines. The CASE statement cannot have an ELSE NULL clause, and it is terminated with END CASE instead of END.

• IF(expr1,expr2,expr3)

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

  (sql sqlHandle {SELECT IF(1>2,2,3)}) Returns 3

  (sql sqlHandle {SELECT IF(1<2,'yes','no')}) Returns 'yes'

  (sql sqlHandle {SELECT IF(STRCMP('test','test1'),'no','yes')}) Returns 'no'

  If only one of expr2 or expr3 is explicitly NULL, the result type of the IF() function is the type of the non-NULL expression.

  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.

  (sql sqlHandle {SELECT IF(0.1,1,0)}) Returns 0

  (sql sqlHandel {SELECT IF(0.1<>0,1,0)}) Returns 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 as follows:

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

  If expr2 and expr3 are both strings, the result is case sensitive if either string is case sensitive.

  Note: There is also an IF statement, which differs from the IF() function described here.

• IFNULL(expr1,expr2)

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

  (sql sqlHandle {SELECT IFNULL(1,0)}) Returns 1

  (sql sqlHandle {SELECT IFNULL(NULL,10)}) Returns 10

  (sql sqlHandle {SELECT IFNULL(1/0,10)}) Returns 10

  (sql sqlHandel {SELECT IFNULL(1/0,'yes')}) Returns 'yes'

  The default result value of IFNULL(expr1,expr2) is the more "general" of the two expressions, in the order STRING, REAL, or INTEGER. Consider the case of a table based on expressions or where MySQL must internally store a value returned by IFNULL() in a temporary table:

  (sql sqlHandle {CREATE TABLE tmp SELECT IFNULL(1,'test') AS test})

  (sql sqlHandle {DESCRIBE tmp}) Returns
  +-------+---------+------+-----+---------+-------+
  | Field | Type    | Null | Key | Default | Extra |
  +-------+---------+------+-----+---------+-------+
  | test  | char(4) |      |     |         |       |
  +-------+---------+------+-----+---------+-------+

  In this example, the type of the test column is CHAR(4).

• NULLIF(expr1,expr2)

  Returns NULL if expr1 = expr2 is true, otherwise returns expr1. This is the same as CASE WHEN expr1 = expr2 THEN NULL ELSE expr1 END.

  (sql sqlHandle {SELECT NULLIF(1,1)}) Returns NULL

  (sql sqlHandle {SELECT NULLIF(1,2)}) Returns 1

  Note that MySQL evaluates expr1 twice if the arguments are not equal.

String Functions

String-valued functions return NULL if the length of the result would be greater than the value of the max_allowed_packet system variable.

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

For functions that take length arguments, non-integer arguments are rounded to the nearest integer.

• ASCII(str)

  Returns the numeric value of the leftmost character of the string str. Returns 0 if str is the empty string. Returns NULL if str is NULL. ASCII() works for 8-bit characters.

  (sql sqlHandle {SELECT ASCII('2')}) Returns 50

  (sql sqlHandle {SELECT ASCII(2)}) Returns 50

  (sql sqlHandle {SELECT ASCII('dx')}) Returns 100

  See also the ORD() function.

• BIN(N)

  Returns a string representation of the binary value of N, where N is a longlong (BIGINT) number. This is equivalent to CONV(N,10,2). Returns NULL if N is NULL.

  (sql sqlHandle {SELECT BIN(12)}) Returns '1100'

• BIT_LENGTH(str)

  Returns the length of the string str in bits.

  (sql sqlHandle {SELECT BIT_LENGTH('text')}) Returns 32

• CHAR(N,... [USING charset_name])

  CHAR() interprets each argument N as an integer and returns a string consisting of the characters given by the code values of those integers. NULL values are skipped.

  (sql sqlHandle {SELECT CHAR(77,121,83,81,'76')}) Returns 'MySQL'

  (sql sqlHandle {SELECT CHAR(77,77.3,'77.3')}) Returns 'MMM'

  CHAR() arguments larger than 255 are converted into multiple result bytes. For example, CHAR(256) is equivalent to CHAR(1,0), and CHAR(256*256) is equivalent to CHAR(1,0,0):

  (sql sqlHandle {SELECT HEX(CHAR(1,0)), HEX(CHAR(256))}) Returns
  +----------------+----------------+
  | HEX(CHAR(1,0)) | HEX(CHAR(256)) |
  +----------------+----------------+
  | 0100           | 0100           |
  +----------------+----------------+

  (sql sqlHandle {SELECT HEX(CHAR(1,0,0)), HEX(CHAR(256*256))}) Returns
  +------------------+--------------------+
  | HEX(CHAR(1,0,0)) | HEX(CHAR(256*256)) |
  +------------------+--------------------+
  | 010000           | 010000             |
  +------------------+--------------------+

  By default, CHAR() returns a binary string. To produce a string in a given character set, use the optional USING clause:

  (sql sqlHandle {SELECT CHARSET(CHAR(0x65)), CHARSET(CHAR(0x65 USING utf8))}) Returns
  +---------------------+--------------------------------+
  | CHARSET(CHAR(0x65)) | CHARSET(CHAR(0x65 USING utf8)) |
  +---------------------+--------------------------------+
  | binary              | utf8                           |
  +---------------------+--------------------------------+

  If USING is given and the result string is illegal for the given character set, a warning is issued. Also, if strict SQL mode is enabled, the result from CHAR() becomes NULL.

• CHAR_LENGTH(str)

  Returns the length of the string str, measured in characters. A multi-byte character counts as a single character. This means that for a string containing five two-byte characters, LENGTH() returns 10, whereas CHAR_LENGTH() returns 5.

• CHARACTER_LENGTH(str)

  CHARACTER_LENGTH() is a synonym for CHAR_LENGTH().

• CONCAT(str1,str2,...)

  Returns the string that results from concatenating the arguments. 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; if you want to avoid that, you can use an explicit type cast, as in this example:

  SELECT CONCAT(CAST(int_col AS CHAR), char_col);

  CONCAT() returns NULL if any argument is NULL.

  (sql sqlHandle {SELECT CONCAT('My', 'S', 'QL')}) Returns 'MySQL'

  (sql sqlHandle {SELECT CONCAT('My', NULL, 'QL')}) Returns NULL

  (sql sqlHandle {SELECT CONCAT(14.3)}) Returns '14.3'

• CONCAT_WS(separator,str1,str2,...)

  CONCAT_WS() stands for Concatenate 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.

  (sql sqlHandle {SELECT CONCAT_WS(',','First name','Second name','Last Name')}) Returns 'First name,Second name,Last Name'

  (sql sqlHandle {SELECT CONCAT_WS(',','First name',NULL,'Last Name')}) Returns 'First name,Last Name'

  CONCAT_WS() does not skip empty strings. However, it does skip any NULL values after the separator argument.

• ELT(N,str1,str2,str3,...)

  Returns str1 if N = 1, str2 if N = 2, and so on. Returns NULL if N is less than 1 or greater than the number of arguments. ELT() is the complement of FIELD().

  (sql sqlHandle {SELECT ELT(1, 'ej', 'Heja', 'hej', 'foo')}) Returns 'ej'

  (sql sqlHandle {SELECT ELT(4, 'ej', 'Heja', 'hej', 'foo')}) Returns 'foo'

• EXPORT_SET(bits,on,off[,separator[,number_of_bits]])

  Returns a string such that for every bit set in the value bits, you get an on string and for every bit not set in the value, you get an off string. Bits in bits are examined from right to left (from low-order to high-order bits). Strings are added to the result from left to right, separated by the separator string (the default being the comma character ","). The number of bits examined is given by number_of_bits (defaults to 64).

  (sql sqlHandle {SELECT EXPORT_SET(5,'Y','N',',',4)}) Returns 'Y,N,Y,N'

  (sql sqlHandle {SELECT EXPORT_SET(6,'1','0',',',10)}) Returns '0,1,1,0,0,0,0,0,0,0'

• FIELD(str,str1,str2,str3,...)

  Returns the index (position) of str in the str1, str2, str3, ... list. Returns 0 if str is not found.

  If all arguments to FIELD() are strings, all arguments are compared as strings. If all arguments are numbers, they are compared as numbers. Otherwise, the arguments are compared as double.

  If str is NULL, the return value is 0 because NULL fails equality comparison with any value. FIELD() is the complement of ELT().

  (sql sqlHandle {SELECT FIELD('ej', 'Hej', 'ej', 'Heja', 'hej', 'foo')}) Returns 2

  (sql sqlHandle {SELECT FIELD('fo', 'Hej', 'ej', 'Heja', 'hej', 'foo')}) Returns 0

• FIND_IN_SET(str,strlist)

  Returns a value in the range of 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 does not work properly if the first argument contains a comma (",") character.

  (sql sqlHandle {SELECT FIND_IN_SET('b','a,b,c,d')}) Returns 2

• FORMAT(X,D)

  Formats the number X to a format like '#,###,###.##', rounded to D decimal places, and returns the result as a string. If D is 0, the result has no decimal point or fractional part.

  (sql sqlHandle {SELECT FORMAT(12332.123456, 4)}) Returns '12,332.1235'

  (sql sqlHandle {SELECT FORMAT(12332.1,4)}) Returns '12,332.1000'

  (sql sqlHandle {SELECT FORMAT(12332.2,0)}) Returns '12,332'

• HEX(N_or_S)

  If N_or_S is a number, returns a string representation of the hexadecimal value of N, where N is a longlong (BIGINT) number. This is equivalent to CONV(N,10,16).

  If N_or_S is a string, returns a hexadecimal string representation of N_or_S where each character in N_or_S is converted to two hexadecimal digits. The inverse of this operation is performed by the UNHEX() function.

  (sql sqlHandle {SELECT HEX(255)}) Returns 'FF'

  (sql sqlHandle {SELECT 0x616263)}) Returns 'abc'

  (sql sqlHandle {SELECT HEX('abc')}) Returns 616263

• INSERT(str,pos,len,newstr)

  Returns the string str, with the substring beginning at position pos and len characters long replaced by the string newstr. Returns the original string if pos is not within the length of the string. Replaces the rest of the string from position pos if len is not within the length of the rest of the string. Returns NULL if any argument is NULL.

  (sql sqlHandle {SELECT INSERT('Quadratic', 3, 4, 'What')}) Returns 'QuWhattic'

  (sql sqlHandle {SELECT INSERT('Quadratic', -1, 4, 'What')}) Returns 'Quadratic'

  (sql sqlHandle {SELECT INSERT('Quadratic', 3, 100, 'What')}) Returns 'QuWhat'

  This function is multi-byte safe.

• INSTR(str,substr)

  Returns the position of the first occurrence of substring substr in string str. This is the same as the two-argument form of LOCATE(), except that the order of the arguments is reversed.

  (sql sqlHandle {SELECT INSTR('foobarbar', 'bar')}) Returns 4

  (sql sqlHandle {SELECT INSTR('xbar', 'foobar')}) Returns 0

  This function is multi-byte safe, and is case sensitive only if at least one argument is a binary string.

• LCASE(str)

  LCASE() is a synonym for LOWER().

• LEFT(str,len)

  Returns the leftmost len characters from the string str, or NULL if any argument is NULL.

  (sql sqlHandle {SELECT LEFT('foobarbar', 5)}) Returns 'fooba'

• LENGTH(str)

  Returns the length of the string str, measured in bytes. A multi-byte character counts as multiple bytes. This means that for a string containing five two-byte characters, LENGTH() returns 10, whereas CHAR_LENGTH() returns 5.

  (sql sqlHandle {SELECT LENGTH('text')}) Returns 4

• LOAD_FILE(file_name)

  Reads the file and returns the file contents as a string. To use this function, the file must be located on the server host, you must specify the full pathname to the file, and you must have the FILE privilege. The file must be readable by all and its size less than max_allowed_packet bytes.

  If the file does not exist or cannot be read because one of the preceding conditions is not satisfied, the function returns NULL.

  As of MySQL 5.1.6, the character_set_filesystem system variable controls interpretation of filenames that are given as literal strings.

  (sql sqlHandle {UPDATE t SET blob_col=LOAD_FILE('/tmp/picture') WHERE id=1})

• LOCATE(substr,str), LOCATE(substr,str,pos)

  The first syntax returns the position of the first occurrence of substring substr in string str. The second syntax returns the position of the first occurrence of substring substr in string str, starting at position pos. Returns 0 if substr is not in str.

  (sql sqlHandle {SELECT LOCATE('bar', 'foobarbar')}) Returns 4

  (sql sqlHandle {SELECT LOCATE('xbar', 'foobar')}) Returns 0

  (sql sqlHandle {SELECT LOCATE('bar', 'foobarbar', 5)}) Returns 7

  This function is multi-byte safe, and is case-sensitive only if at least one argument is a binary string.

• LOWER(str)

  Returns the string str with all characters changed to lowercase according to the current character set mapping. The default is latin1 (cp1252 West European).

  (sql sqlHandle {SELECT LOWER('QUADRATICALLY')}) Returns 'quadratically'

  LOWER() (and UPPER()) are ineffective when applied to binary strings (BINARY, VARBINARY, BLOB). To perform lettercase conversion, convert the string to a non-binary string:

  (sql sqlHandle {SET @str = BINARY 'New York'})

  (sql sqlHandle {SELECT LOWER(@str), LOWER(CONVERT(@str USING latin1))}) Returns
  +-------------+-----------------------------------+
  | LOWER(@str) | LOWER(CONVERT(@str USING latin1)) |
  +-------------+-----------------------------------+
  | New York    | new york                          | 
  +-------------+-----------------------------------+

  This function is multi-byte safe.

• LPAD(str,len,padstr)

  Returns the string str, left-padded with the string padstr to a length of len characters. If str is longer than len, the return value is shortened to len characters.

  (sql sqlHandle {SELECT LPAD('hi',4,'??')}) Returns '??hi'

  (sql sqlHandle {SELECT LPAD('hi',1,'??')}) Returns 'h'

• LTRIM(str)

  Returns the string str with leading space characters removed.

  (sql sqlHandle {SELECT LTRIM('  barbar')}) Returns 'barbar'

  This function is multi-byte safe.

• MAKE_SET(bits,str1,str2,...)

  Returns a set value (a string containing substrings separated by "," characters) consisting of the strings that have the corresponding bit in bits set. str1 corresponds to bit 0, str2 to bit 1, and so on. NULL values in str1, str2, ... are not appended to the result.

  (sql sqlHandle {SELECT MAKE_SET(1,'a','b','c')}) Returns 'a'

  (sql sqlHandle {SELECT MAKE_SET(1 | 4,'hello','nice','world')}) Returns 'hello,world'

  (sql sqlHandle {SELECT MAKE_SET(1 | 4,'hello','nice',NULL,'world')}) Returns 'hello'

  (sql sqlHandle {SELECT MAKE_SET(0,'a','b','c')}) Returns ''

• MID(str,pos,len)

  MID(str,pos,len) is a synonym for SUBSTRING(str,pos,len).

• OCTET_LENGTH(str)

  OCTET_LENGTH() is a synonym for LENGTH().

• ORD(str)

  If the leftmost character of the string str is a multi-byte character, returns the code for that character, calculated from the numeric values of its constituent bytes using this formula:

  (1st byte code) + (2nd byte code × 256) + (3rd byte code × 2562) ...

  If the leftmost character is not a multi-byte character, ORD() returns the same value as the ASCII() function.

  (sql sqlHandle {SELECT ORD('2')}) Returns 50

• POSITION(substr IN str)

  POSITION(substr IN str) is a synonym for LOCATE(substr,str).

• QUOTE(str)

  Quotes a string to produce a result that can be used as a properly escaped data value in an SQL statement. The string is returned enclosed by single quotes and with each instance of single quote ("'"), backslash ("\"), ASCII NUL, and Control-Z preceded by a backslash. If the argument is NULL, the return value is the word "NULL" without enclosing single quotes.

  (sql sqlHandle {SELECT QUOTE('Don\'t!')}) Returns 'Don\'t!'

  (sql sqlHandle {SELECT QUOTE(NULL)}) Returns NULL

• REPEAT(str,count)

  Returns a string consisting of the string str repeated count times. If count is less than 1, returns an empty string. Returns NULL if str or count are NULL.

  (sql sqlHandle {SELECT REPEAT('MySQL', 3)}) Returns 'MySQLMySQLMySQL'

• REPLACE(str,from_str,to_str)

  Returns the string str with all occurrences of the string from_str replaced by the string to_str. REPLACE() performs a case-sensitive match when searching for from_str.

  (sql sqlHandle {SELECT REPLACE('www.mysql.com', 'w', 'Ww')}) Returns 'WwWwWw.mysql.com'

  This function is multi-byte safe.

• REVERSE(str)

  Returns the string str with the order of the characters reversed.

  (sql sqlHandle {SELECT REVERSE('abc')}) Returns 'cba'

  This function is multi-byte safe.

• RIGHT(str,len)

  Returns the rightmost len characters from the string str, or NULL if any argument is NULL.

  (sql sqlHandle {SELECT RIGHT('foobarbar', 4)}) Returns 'rbar'

  This function is multi-byte safe.

• RPAD(str,len,padstr)

  Returns the string str, right-padded with the string padstr to a length of len characters. If str is longer than len, the return value is shortened to len characters.

  (sql sqlHandle {SELECT RPAD('hi',5,'?')}) Returns 'hi???'

  (sql sqlHandle {SELECT RPAD('hi',1,'?')}) Returns 'h'

  This function is multi-byte safe.

• RTRIM(str)

  Returns the string str with trailing space characters removed.

  (sql sqlHandle {SELECT RTRIM('barbar   ')}) Returns 'barbar'

  This function is multi-byte safe.

• SOUNDEX(str)

  Returns a soundex string from str. Two strings that sound almost the same should have identical soundex strings. A standard soundex string is four characters long, but the SOUNDEX() function returns an arbitrarily long string. You can use SUBSTRING() on the result to get a standard soundex string. All non-alphabetic characters in str are ignored. All international alphabetic characters outside the A-Z range are treated as vowels.

  Important: When using SOUNDEX(), you should be aware of the following limitations:

  • This function, as currently implemented, is intended to work well with strings that are in the English language only. Strings in other languages may not produce reliable results.

  • This function is not guaranteed to provide consistent results with strings that use multi-byte character sets, including utf-8.

  We hope to remove these limitations in a future release. See Bug#22638 for more information.

  (sql sqlHandle {SELECT SOUNDEX('Hello')}) Returns 'H400'

  (sql sqlHandle {SELECT SOUNDEX('Quadratically')}) Returns '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 duplicates second, whereas the enhanced version discards duplicates first and vowels second.

• expr1 SOUNDS LIKE expr2

  This is the same as SOUNDEX(expr1) = SOUNDEX(expr2).

• SPACE(N)

  Returns a string consisting of N space characters.

  (sql sqlHandle {SELECT SPACE(6)}) Returns '      '

• SUBSTR(str,pos), SUBSTR(str FROM pos), SUBSTR(str,pos,len), SUBSTR(str FROM pos FOR len)

  SUBSTR() is a synonym for SUBSTRING().

• SUBSTRING(str,pos), SUBSTRING(str FROM pos), SUBSTRING(str,pos,len), SUBSTRING(str FROM pos FOR len)

  The forms without a len argument return a substring from string str starting at position pos. The forms with a len argument return a substring len characters long from string str, starting at position pos. The forms that use FROM are standard SQL syntax. It is also possible to use a negative value for pos. In this case, the beginning of the substring is pos characters from the end of the string, rather than the beginning. A negative value may be used for pos in any of the forms of this function.

  For all forms of SUBSTRING(), the position of the first character in the string from which the substring is to be extracted is reckoned as 1.

  (sql sqlHandle {SELECT SUBSTRING('Quadratically',5)}) Returns 'ratically'

  (sql sqlHandle {SELECT SUBSTRING('foobarbar' FROM 4)}) Returns 'barbar'

  (sql sqlHandle {SELECT SUBSTRING('Quadratically',5,6)}) Returns 'ratica'

  (sql sqlHandle {SELECT SUBSTRING('Sakila', -3)}) Returns 'ila'

  (sql sqlHandle {SELECT SUBSTRING('Sakila', -5, 3)}) Returns 'aki'

  (sql sqlHandle {SELECT SUBSTRING('Sakila' FROM -4 FOR 2)}) Returns 'ki'

  This function is multi-byte safe.

  If len is less than 1, the result is the empty string.

• SUBSTRING_INDEX(str,delim,count)

  Returns the substring from string str before count occurrences of the delimiter delim. If count is positive, everything to the left of the final delimiter (counting from the left) is returned. If count is negative, everything to the right of the final delimiter (counting from the right) is returned. SUBSTRING_INDEX() performs a case-sensitive match when searching for delim.

  (sql sqlHandle {SELECT SUBSTRING_INDEX('www.mysql.com', '.', 2)}) Returns 'www.mysql'

  (sql sqlHandle {SELECT SUBSTRING_INDEX('www.mysql.com', '.', -2)}) Returns 'mysql.com'

  This function is multi-byte safe.

• TRIM([{BOTH | LEADING | TRAILING} [remstr] FROM] str), TRIM([remstr FROM] str)

  Returns the string str with all remstr prefixes or suffixes removed. If none of the specifiers BOTH, LEADING, or TRAILING is given, BOTH is assumed. remstr is optional and, if not specified, spaces are removed.

  (sql sqlHandle {SELECT TRIM('  bar   ')}) Returns 'bar'

  (sql sqlHandle {SELECT TRIM(LEADING 'x' FROM 'xxxbarxxx')}) Returns 'barxxx'

  (sql sqlHandle {SELECT TRIM(BOTH 'x' FROM 'xxxbarxxx')}) Returns 'bar'

  (sql sqlHandle {SELECT TRIM(TRAILING 'xyz' FROM 'barxxyz')}) Returns 'barx'

  This function is multi-byte safe.

• UCASE(str)

  UCASE() is a synonym for UPPER().

• UNHEX(str)

  Performs the inverse operation of HEX(str). That is, it interprets each pair of hexadecimal digits in the argument as a number and converts it to the character represented by the number. The resulting characters are returned as a binary string.

  (sql sqlHandle {SELECT UNHEX('4D7953514C')}) Returns 'MySQL'

  (sql sqlHandle {SELECT 0x4D7953514C})}) Returns 'MySQL'

  (sql sqlHandle {SELECT UNHEX(HEX('string'))}) Returns 'string'

  (sql sqlHandle {SELECT HEX(UNHEX('1267'))}) Returns '1267'

  The characters in the argument string must be legal hexadecimal digits: '0' .. '9', 'A' .. 'F', 'a' .. 'f'. If UNHEX() encounters any non-hexadecimal digits in the argument, it returns NULL:

  (sql sqlHandle {SELECT UNHEX('GG')}) Returns
  +-------------+
  | UNHEX('GG') |
  +-------------+
  | NULL        | 
  +-------------+

  A NULL result can occur if the argument to UNHEX() is a BINARY column, because values are padded with 0x00 bytes when stored but those bytes are not stripped on retrieval. For example 'aa' is stored into a CHAR(3) column as 'aa ' and retrieved as 'aa' (with the trailing pad space stripped), so UNHEX() for the column value returns 'A'. By contrast 'aa' is stored into a BINARY(3) column as 'aa\0' and retrieved as 'aa\0' (with the trailing pad 0x00 byte not stripped). '\0' is not a legal hexadecimal digit, so UNHEX() for the column value returns NULL.

• UPPER(str)

  Returns the string str with all characters changed to uppercase according to the current character set mapping. The default is latin1 (cp1252 West European).

  (sql sqlHandle {SELECT UPPER('Hej')}) Returns 'HEJ'

  UPPER() is ineffective when applied to binary strings (BINARY, VARBINARY, BLOB). The description of LOWER() shows how to perform lettercase conversion of binary strings.

  This function is multi-byte safe.

String Comparison Functions

If a string function is given a binary string as an argument, the resulting string is also a binary string. A number converted to a string is treated as a binary string. This affects only comparisons.

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

• expr LIKE pat [ESCAPE 'escape_char']

  Pattern matching using SQL simple regular expression comparison. Returns 1 (TRUE) or 0 (FALSE). If either expr or pat is NULL, the result is NULL.

  The pattern need not be a literal string. For example, it can be specified as a string expression or table column.

  Per the SQL standard, LIKE performs matching on a per-character basis, thus it can produce results different from the = comparison operator:

  (sql sqlHandle {SELECT 'ä' LIKE 'ae' COLLATE latin1_german2_ci}) Returns
  +-----------------------------------------+
  | 'ä' LIKE 'ae' COLLATE latin1_german2_ci |
  +-----------------------------------------+
  |                                       0 |
  +-----------------------------------------+

  (sql sqlHandle {SELECT 'ä' = 'ae' COLLATE latin1_german2_ci}) Returns
  +--------------------------------------+
  | 'ä' = 'ae' COLLATE latin1_german2_ci |
  +--------------------------------------+
  |                                    1 |
  +--------------------------------------+

  In particular, trailing spaces are significant, which is not true for CHAR or VARCHAR comparisons performed with the = operator:

  (sql sqlHandle {SELECT 'a' = 'a ', 'a' LIKE 'a '}) Returns
  +------------+---------------+
  | 'a' = 'a ' | 'a' LIKE 'a ' |
  +------------+---------------+
  |          1 |             0 | 
  +------------+---------------+

  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

  (sql sqlHandle {SELECT 'David!' LIKE 'David_'}) Returns 1

  (sql sqlHandle {SELECT 'David!' LIKE '%D%v%'}) Returns 1

  To test for literal instances of a wildcard character, precede it by the escape character. If you do not specify the ESCAPE character, "\" is assumed.

  Matches one "_" character

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

  (sql sqlHandle {SELECT 'David!' LIKE 'David\_'}) Returns 0

  (sql sqlHandle {SELECT 'David_' LIKE 'David\_'}) Returns 1

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

  (sql sqlHandle {SELECT 'David_' LIKE 'David|_' ESCAPE '|'}) Returns 1

  The escape sequence should be empty or one character long. As of MySQL 5.1.2, if the NO_BACKSLASH_ESCAPES SQL mode is enabled, the sequence cannot be empty.

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

  (sql sqlHandle {SELECT 'abc' LIKE 'ABC'}) Returns 1

  (sql sqlHandle {SELECT 'abc' LIKE BINARY 'ABC'}) Returns 0

  In MySQL, LIKE is allowed on numeric expressions. (This is an extension to the standard SQL LIKE.)

  (sql sqlHandle {SELECT 10 LIKE '1%'}) Returns 1

  Note: Because MySQL uses C escape syntax in strings (for example, "\n" to represent a newline character), you must double any "\" that you use in LIKE strings. For example, to search for "\n", specify it as "\\n". To search for "\", specify it as "\\\\"; this is because the backslashes are stripped once by the parser and again when the pattern match is made, leaving a single backslash to be matched against. (Exception: At the end of the pattern string, backslash can be specified as "\\". At the end of the string, backslash stands for itself because there is nothing following to escape.)

• expr NOT LIKE pat [ESCAPE 'escape_char']

  This is the same as NOT (expr LIKE pat [ESCAPE 'escape_char']).

  Note: Aggregate queries involving NOT LIKE comparisons with columns containing NULL may yield unexpected results. For example, consider the following table and data:

  (sql sqlHandle {CREATE TABLE foo (bar VARCHAR(10))})

  (sql sqlHandle {INSERT INTO foo VALUES (NULL), (NULL)})

  The query SELECT COUNT(*) FROM foo WHERE bar LIKE '%baz%'; returns 0. You might assume that SELECT COUNT(*) FROM foo WHERE bar NOT LIKE '%baz%'; would return 2. However, this is not the case: The second query returns 0. This is because NULL NOT LIKE expr always returns NULL, regardless of the value of expr. The same is true for aggregate queries involving NULL and comparisons using NOT RLIKE or NOT REGEXP. In such cases, you must test explicitly for NOT NULL using OR (and not AND), as shown here:

  (sql sqlHandle {SELECT COUNT(*) FROM foo WHERE bar NOT LIKE '%baz%' OR bar IS NULL})

• expr NOT REGEXP pat, expr NOT RLIKE pat

  This is the same as NOT (expr REGEXP pat).

• expr REGEXP pat, expr RLIKE pat

  Performs a pattern match of a string expression expr against a pattern pat. The pattern can be an extended regular expression. Returns 1 if expr matches pat; otherwise it returns 0. If either expr or pat is NULL, the result is NULL. RLIKE is a synonym for REGEXP, provided for mSQL compatibility.

  The pattern need not be a literal string. For example, it can be specified as a string expression or table column.

  Note: Because MySQL uses the C escape syntax in strings (for example, "\n" to represent the newline character), you must double any "\" that you use in your REGEXP strings.

  REGEXP is not case sensitive, except when used with binary strings.

  (sql sqlHandle {SELECT 'Monty!' REGEXP 'm%y%%'}) Returns 0

  (sql sqlHandle {SELECT 'Monty!' REGEXP '.*'}) Returns 1

  (sql sqlHandle {SELECT 'new*\n*line' REGEXP 'new\\*.\\*line'}) Returns 1

  (sql sqlHandle {SELECT 'a' REGEXP 'A', 'a' REGEXP BINARY 'A'}) Returns 1  0

  (sql sqlHandle {SELECT 'a' REGEXP '^[a-d]'}) Returns 1

  REGEXP and RLIKE use the current character set when deciding the type of a character. The default is latin1 (cp1252 West European).

  Warning: The REGEXP and RLIKE operators work in byte-wise fashion, so they are not multi-byte safe and may produce unexpected results with multi-byte character sets. In addition, these operators compare characters by their byte values and accented characters may not compare as equal even if a given collation treats them as equal.

• 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.

  (sql sqlHandle {SELECT STRCMP('text', 'text2')}) Returns -1

  (sql sqlHandle {SELECT STRCMP('text2', 'text')}) Returns 1

  (sql sqlHandle {SELECT STRCMP('text', 'text')}) Returns 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.

Regular Expressions

A regular expression is a powerful way of specifying a pattern for a complex search.

MySQL uses Henry Spencer's implementation of regular expressions, which is aimed at conformance with POSIX 1003.2. MySQL uses the extended version to support pattern-matching operations performed with the REGEXP operator in SQL statements.

This section is a summary, with examples, of the special characters and constructs that can be used in MySQL for REGEXP operations. It does not contain all the details that can be found in Henry Spencer's regex(7) manual page.

A regular expression describes a set of strings. The simplest regular expression is one that has no special characters in it. For example, the regular expression hello matches hello and nothing else.

Non-trivial regular expressions use certain special constructs so that they can match more than one string. For example, the regular expression hello|word matches either the string hello or the string word.

As a more complex example, the regular expression B[an]*s matches any of the strings Bananas, Baaaaas, Bs, and any other string starting with a B, ending with an s, and containing any number of a or n characters in between.

A regular expression for the REGEXP operator may use any of the following special characters and constructs:

• ^

  Match the beginning of a string.

  (sql sqlHandle {SELECT 'fo\nfo' REGEXP '^fo$'}) Returns 0

  (sql sqlHandle {SELECT 'fofo' REGEXP '^fo'}) Returns 1

• $

  Match the end of a string.

  (sql sqlHandle {SELECT 'fo\no' REGEXP '^fo\no$'}) Returns 1

  (sql sqlHandle {SELECT 'fo\no' REGEXP '^fo$'}) Returns 0

• .

  Match any character (including carriage return and newline).

  (sql sqlHandle {SELECT 'fofo' REGEXP '^f.*$'}) Returns 1

  (sql sqlHandle {SELECT 'fo\r\nfo' REGEXP '^f.*$'}) Returns 1

• a*

  Match any sequence of zero or more a characters.

  (sql sqlHandle {SELECT 'Ban' REGEXP '^Ba*n'}) Returns 1

  (sql sqlHandle {SELECT 'Baaan' REGEXP '^Ba*n'}) Returns 1

  (sql sqlHandle {SELECT 'Bn' REGEXP '^Ba*n'}) Returns 1

• a+

  Match any sequence of one or more a characters.

  (sql sqlHandle {SELECT 'Ban' REGEXP '^Ba+n'}) Returns 1

  (sql sqlHandle {SELECT 'Bn' REGEXP '^Ba+n'}) Returns 0

• a?

  Match either zero or one a character.

  (sql sqlHandle {SELECT 'Bn' REGEXP '^Ba?n'}) Returns 1

  (sql sqlHandle {SELECT 'Ban' REGEXP '^Ba?n'}) Returns 1

  (sql sqlHandle {SELECT 'Baan' REGEXP '^Ba?n'}) Returns 0

• de|abc

  Match either of the sequences de or abc.

  (sql sqlHandle {SELECT 'pi' REGEXP 'pi|apa'}) Returns 1

  (sql sqlHandle {SELECT 'axe' REGEXP 'pi|apa'}) Returns 0

  (sql sqlHandle {SELECT 'apa' REGEXP 'pi|apa'}) Returns 1

  (sql sqlHandle {SELECT 'apa' REGEXP '^(pi|apa)$'}) Returns 1

  (sql sqlHandle {SELECT 'pi' REGEXP '^(pi|apa)$'}) Returns 1

  (sql sqlHandle {SELECT 'pix' REGEXP '^(pi|apa)$'}) Returns 0

• (abc)*

  Match zero or more instances of the sequence abc.

  (sql sqlHandle {SELECT 'pi' REGEXP '^(pi)*$'}) Returns 1

  (sql sqlHandle {SELECT 'pip' REGEXP '^(pi)*$'}) Returns 0

  (sql sqlHandle {SELECT 'pipi' REGEXP '^(pi)*$'}) Returns 1

• {1}, {2,3}

  {n} or {m,n} notation provides a more general way of writing regular expressions that match many occurrences of the previous atom (or "piece") of the pattern. m and n are integers.

• a*

  Can be written as a{0,}.

• a+

  Can be written as a{1,}.

• a?

  Can be written as a{0,1}.

  To be more precise, a{n} matches exactly n instances of a. a{n,} matches n or more instances of a. a{m,n} matches m through n instances of a, inclusive.

  m and n must be in the range from 0 to RE_DUP_MAX (default 255), inclusive. If both m and n are given, m must be less than or equal to n.

  (sql sqlHandle {SELECT 'abcde' REGEXP 'a[bcd]{2}e'}) Returns 0

  (sql sqlHandle {SELECT 'abcde' REGEXP 'a[bcd]{3}e'}) Returns 1

  (sql sqlHandle {SELECT 'abcde' REGEXP 'a[bcd]{1,10}e'}) Returns 1

• [a-dX], [^a-dX]

  Matches any character that is (or is not, if ^ is used) either a, b, c, d or X. A - character between two other characters forms a range that matches all characters from the first character to the second. For example, [0-9] matches any decimal digit. To include a literal ] character, it must immediately follow the opening bracket [. To include a literal - character, it must be written first or last. Any character that does not have a defined special meaning inside a [] pair matches only itself.

  (sql sqlHandle {SELECT 'aXbc' REGEXP '[a-dXYZ]'}) Returns 1

  (sql sqlHandle {SELECT 'aXbc' REGEXP '^[a-dXYZ]$'}) Returns 0

  (sql sqlHandle {SELECT 'aXbc' REGEXP '^[a-dXYZ]+$'}) Returns 1

  (sql sqlHandle {SELECT 'aXbc' REGEXP '^[^a-dXYZ]+$'}) Returns 0

  (sql sqlHandle {SELECT 'gheis' REGEXP '^[^a-dXYZ]+$'}) Returns 1

  (sql sqlHandle {SELECT 'gheisa' REGEXP '^[^a-dXYZ]+$'}) Returns 0

• [.characters.]

  Within a bracket expression (written using [ and ]), matches the sequence of characters of that collating element. characters is either a single character or a character name like newline. The following table lists the allowable character names.

  The following table shows the allowable character names and the characters that they match. For characters given as numeric values, the values are represented in octal.

  Name	Character	Name	Character
  NUL	0	SOH	001
  STX	002	ETX	003
  EOT	004	ENQ	005
  ACK	006	BEL	007
  alert	007	BS	010
  backspace	'\b'	HT	011
  tab	'\t'	LF	012
  newline	'\n'	VT	013
  vertical-tab	'\v'	FF	014
  form-feed	'\f'	CR	015
  carriage-return	'\r'	SO	016
  SI	017	DLE	020
  DC1	021	DC2	022
  DC3	023	DC4	024
  NAK	025	SYN	026
  ETB	027	CAN	030
  EM	031	SUB	032
  ESC	033	IS4	034
  FS	034	IS3	035
  GS	035	IS2	036
  RS	036	IS1	037
  US	037	space	' '
  exclamation-mark	'!'	quotation-mark	'"'
  number-sign	'#'	dollar-sign	'$'
  percent-sign	'%'	ampersand	'&'
  apostrophe	'\''	left-parenthesis	'('
  right-parenthesis	')'	asterisk	'*'
  plus-sign	'+'	comma	','
  hyphen	'-'	hyphen-minus	'-'
  period	'.'	full-stop	'.'
  slash	'/'	solidus	'/'
  zero	'0'	one	'1'
  two	'2'	three	'3'
  four	'4'	five	'5'
  six	'6'	seven	'7'
  eight	'8'	nine	'9'
  colon	':'	semicolon	';'
  less-than-sign	'<'	equals-sign	'='
  greater-than-sign	'>'	question-mark	'?'
  commercial-at	'@'	left-square-bracket	'['
  backslash	'\\'	reverse-solidus	'\\'
  right-square-bracket	']'	circumflex	'^'
  circumflex-accent	'^'	underscore	'_'
  low-line	'_'	grave-accent	'`'
  left-brace	'{'	left-curly-bracket	'{'
  vertical-line	'|'	right-brace	'}'
  right-curly-bracket	'}'	tilde	'~'
  DEL	177

  (sql sqlHandle {SELECT '~' REGEXP '[[.~.]]'}) Returns 1

  (sql sqlHandle {SELECT '~' REGEXP '[[.tilde.]]'}) Returns 1

• [=character_class=]

  Within a bracket expression (written using [ and ]), [=character_class=] represents an equivalence class. It matches all characters with the same collation value, including itself. For example, if o and (+) are the members of an equivalence class, then [[=o=]], [[=(+)=]], and [o(+)] are all synonymous. An equivalence class may not be used as an endpoint of a range.

• [:character_class:]

  Within a bracket expression (written using [ and ]), [:character_class:] represents a character class that matches all characters belonging to that class. The following table lists the standard class names. These names stand for the character classes defined in the ctype(3) manual page. A particular locale may provide other class names. A character class may not be used as an endpoint of a range.

  alnum	Alphanumeric characters
  alpha	Alphabetic characters
  blank	Whitespace characters
  cntrl	Control characters
  digit	Digit characters
  graph	Graphic characters
  lower	Lowercase alphabetic characters
  print	Graphic or space characters
  punct	Punctuation characters
  space	Space, tab, newline, and carriage return
  upper	Uppercase alphabetic characters
  xdigit	Hexadecimal digit characters

  (sql sqlHandle {SELECT 'justalnums' REGEXP '[[:alnum:]]+'}) Returns 1

  (sql sqlHandle {SELECT '!!' REGEXP '[[:alnum:]]+'}) Returns 0

• [[:<:]], [[:>:]]

  These markers stand for word boundaries. They match the beginning and end of words, respectively. A word is a sequence of word characters that is not preceded by or followed by word characters. A word character is an alphanumeric character in the alnum class or an underscore (_).

  (sql sqlHandle {SELECT 'a word a' REGEXP '[[:<:]]word[[:>:]]'}) Returns 1

  (sql sqlHandle {SELECT 'a xword a' REGEXP '[[:<:]]word[[:>:]]'}) Returns 0

  To use a literal instance of a special character in a regular expression, precede it by two backslash (\) characters. The MySQL parser interprets one of the backslashes, and the regular expression library interprets the other. For example, to match the string 1+2 that contains the special + character, only the last of the following regular expressions is the correct one:

  (sql sqlHandle {SELECT '1+2' REGEXP '1+2'}) Returns 0

  (sql sqlHandle {SELECT '1+2' REGEXP '1\+2'}) Returns 0

  (sql sqlHandle {SELECT '1+2' REGEXP '1\\+2'}) Returns 1

Numeric Functions

Arithmetic Operators

The usual arithmetic operators are available. The result is determined according to the following rules:

• In the case of -, +, and *, the result is calculated with BIGINT (64-bit) precision if both arguments are integers.

• If one of the arguments is an unsigned integer, and the other argument is also an integer, the result is an unsigned integer.

• If any of the operands of a +, -, /, *, % is a real or string value, then the precision of the result is the precision of the argument with the maximum precision.

• In division performed with /, the scale of the result when using two exact values is the scale of the first argument plus the value of the div_precision_increment system variable (which is 4 by default). For example, the result of the expression 5.05 / 0.014 has a scale of six decimal places (360.714286).

These rules are applied for each operation, such that nested calculations imply the precision of each component. Hence, (14620 / 9432456) / (24250 / 9432456), would resolve first to (0.0014) / (0.0026), with the final result having 8 decimal places (0.60288653).

Because of these rules and the way they are applied, care should be taken to ensure that components and sub-components of a calculation use the appropriate level of precision.

• +

  Addition:

  (sql sqlHandle {SELECT 3+5}) Returns 8

• -

  Subtraction:

  (sql sqlHandle {SELECT 3-5}) Returns -2

• -

  Unary minus. This operator changes the sign of the argument.

  (sql sqlHandle {SELECT - 2}) Returns -2

  Note: If this operator is used with a BIGINT, the return value is also a BIGINT. This means that you should avoid using – on integers that may have the value of –263.

• *

  Multiplication:

  (sql sqlHandle {SELECT 3*5}) Returns 15

  (sql sqlHandle {SELECT 18014398509481984*18014398509481984.0}) Returns 324518553658426726783156020576256.0

  (sql sqlHandle {SELECT 18014398509481984*18014398509481984}) Returns 0

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

• /

  Division:

  (sql sqlHandle {SELECT 3/5}) Returns 0.60

  Division by zero produces a NULL result:

  (sql sqlHandle {SELECT 102/(1-1)}) Returns NULL

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

• DIV

  Integer division. Similar to FLOOR(), but is safe with BIGINT values.

  (sql sqlHandle {SELECT 5 DIV 2}) Returns 2

• N % M

  Modulo operation. Returns the remainder of N divided by M.

Mathematical Functions

All mathematical functions return NULL in the event of an error.

• ABS(X)

  Returns the absolute value of X.

  (sql sqlHandle {SELECT ABS(2)}) Returns 2

  (sql sqlHandle {SELECT ABS(-32)}) Returns 32

  This function is safe to use with BIGINT values.

• ACOS(X)

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

  (sql sqlHandle {SELECT ACOS(1)}) Returns 0

  (sql sqlHandle {SELECT ACOS(1.0001)}) Returns NULL

  (sql sqlHandle {SELECT ACOS(0)}) Returns 1.5707963267949

• ASIN(X)

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

  (sql sqlHandle {SELECT ASIN(0.2)}) Returns 0.20135792079033

  (sql sqlHandle {SELECT ASIN('foo')}) Returns
  +-------------+
  | ASIN('foo') |
  +-------------+
  |           0 |
  +-------------+

  (sql sqlHandle {SHOW WARNINGS}) Returns
  +---------+------+-----------------------------------------+
  | Level   | Code | Message                                 |
  +---------+------+-----------------------------------------+
  | Warning | 1292 | Truncated incorrect DOUBLE value: 'foo' |
  +---------+------+-----------------------------------------+

• ATAN(X)

  Returns the arc tangent of X, that is, the value whose tangent is X.

  (sql sqlHandle {SELECT ATAN(2)}) Returns 1.1071487177941

  (sql sqlHandle {SELECT ATAN(-2)}) Returns -1.1071487177941

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

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

  (sql sqlHandle {SELECT ATAN(-2,2)}) Returns -0.78539816339745

  (sql sqlHandle {SELECT ATAN2(PI(),0)}) Returns 1.5707963267949

• CEIL(X)

  CEIL() is a synonym for CEILING().

• CEILING(X)

  Returns the smallest integer value not less than X.

  (sql sqlHandle { SELECT CEILING(1.23)}) Returns 2

  (sql sqlHandle { SELECT CEILING(-1.23)}) Returns -1

  For exact-value numeric arguments, the return value has an exact-value numeric type. For string or floating-point arguments, the return value has a floating-point type.

• CONV(N,from_base,to_base)

  Converts numbers between different number bases. Returns a string representation of the number N, converted from base from_base to base to_base. Returns NULL if any argument is NULL. The argument N is interpreted as an integer, but may be specified as an integer or a string. The minimum base is 2 and the maximum base is 36. If to_base is a negative number, N is regarded as a signed number. Otherwise, N is treated as unsigned. CONV() works with 64-bit precision.

  (sql sqlHandle {SELECT CONV('a',16,2)}) Returns '1010'

  (sql sqlHandle {SELECT CONV('6E',18,8)}) Returns '172'

  (sql sqlHandle {SELECT CONV(-17,10,-18)}) Returns '-H'

  (sql sqlHandle {SELECT CONV(10+'10'+'10'+0xa,10,10)}) Returns '40'

• COS(X)

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

  (sql sqlHandle { SELECT COS(PI())}) Returns -1

• COT(X)

  Returns the cotangent of X.

  (sql sqlHandle {SELECT COT(12)}) Returns -1.5726734063977

  (sql sqlHandle {SELECT COT(0)}) Returns NULL

• CRC32(expr)

  Computes a cyclic redundancy check value and returns a 32-bit unsigned value. The result is NULL if the argument is NULL. The argument is expected to be a string and (if possible) is treated as one if it is not.

  (sql sqlHandle {SELECT CRC32('MySQL')}) Returns 3259397556

  (sql sqlHandle {SELECT CRC32('mysql')}) Returns 2501908538

• DEGREES(X)

  Returns the argument X, converted from radians to degrees.

  (sql sqlHandle {SELECT DEGREES(PI())}) Returns 180

  (sql sqlHandle {SELECT DEGREES(PI() / 2)}) Returns 90

• EXP(X)

  Returns the value of e (the base of natural logarithms) raised to the power of X. The inverse of this function is LOG() (using a single argument only) or LN().

  (sql sqlHandle {SELECT EXP(2)}) Returns 7.3890560989307

  (sql sqlHandle {SELECT EXP(-2)}) Returns 0.13533528323661

  (sql sqlHandle {SELECT EXP(0)}) Returns 1

• FLOOR(X)

  Returns the largest integer value not greater than X.

  (sql sqlHandle {SELECT FLOOR(1.23)}) Returns 1

  (sql sqlHandle {SELECT FLOOR(-1.23)}) Returns -2

  For exact-value numeric arguments, the return value has an exact-value numeric type. For string or floating-point arguments, the return value has a floating-point type.

• FORMAT(X,D)

  Formats the number X to a format like '#,###,###.##', rounded to D decimal places, and returns the result as a string.

• HEX(N_or_S)

  This function can be used to obtain a hexadecimal representation of a decimal number or a string; the manner in which it does so varies according to the argument's type.

• LN(X)

  Returns the natural logarithm of X; that is, the base-e logarithm of X. If X is less than or equal to 0, then NULL is returned.

  (sql sqlHandle {SELECT LN(2)}) Returns 0.69314718055995

  (sql sqlHandle {SELECT LN(-2)}) Returns NULL

  This function is synonymous with LOG(X). The inverse of this function is the EXP() function.

• LOG(X), LOG(B,X)

  If called with one parameter, this function returns the natural logarithm of X. If X is less than or equal to 0, then NULL is returned.

  The inverse of this function (when called with a single argument) is the EXP() function.

  (sql sqlHandle {SELECT LOG(2)}) Returns 0.69314718055995

  (sql sqlHandle {SELECT LOG(-2)}) Returns NULL

  If called with two parameters, this function returns the logarithm of X to the base B. If X is less than or equal to 0, or if B is less than or equal to 1, then NULL is returned.

  (sql sqlHandle {SELECT LOG(2,65536)}) Returns 16

  (sql sqlHandle {SELECT LOG(10,100)}) Returns 2

  (sql sqlHandle {SELECT LOG(1,100)}) Returns NULL

  LOG(B,X) is equivalent to LOG(X) / LOG(B).

• LOG2(X)

  Returns the base-2 logarithm of X.

  (sql sqlHandle {SELECT LOG2(65536)}) Returns 16

  (sql sqlHandle {SELECT LOG2(-100)}) Returns NULL

  LOG2() is useful for finding out how many bits a number requires for storage. This function is equivalent to the expression LOG(X) / LOG(2).

• LOG10(X)

  Returns the base-10 logarithm of X.

  (sql sqlHandle {SELECT LOG10(2)}) Returns 0.30102999566398

  (sql sqlHandle {SELECT LOG10(100)}) Returns 2

  (sql sqlHandle {SELECT LOG10(-100)}) Returns NULL

  LOG10(X) is equivalent to LOG(10,X).

• MOD(N,M), N % M, N MOD M

  Modulo operation. Returns the remainder of N divided by M.

  (sql sqlHandle {SELECT MOD(234, 10)}) Returns 4

  (sql sqlHandle {SELECT 253 % 7}) Returns 1

  (sql sqlHandle {SELECT MOD(29,9)}) Returns 2

  (sql sqlHandle {SELECT 29 MOD 9}) Returns 2

  This function is safe to use with BIGINT values.

  MOD() also works on values that have a fractional part and returns the exact remainder after division:

  (sql sqlHandle {SELECT MOD(34.5,3)}) Returns 1.5

  MOD(N,0) returns NULL.

• OCT(N)

  Returns a string representation of the octal value of N, where N is a longlong (BIGINT) number. This is equivalent to CONV(N,10,8). Returns NULL if N is NULL.

  (sql sqlHandle {SELECT OCT(12)}) Returns '14'

• PI()

  Returns the value of p (pi). The default number of decimal places displayed is seven, but MySQL uses the full double-precision value internally.

  (sql sqlHandle {SELECT PI()}) Returns 3.141593

  (sql sqlHandle {SELECT PI()+0.000000000000000000}) Returns 3.141592653589793116

• POW(X,Y)

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

  (sql sqlHandle {SELECT POW(2,2)}) Returns 4

  (sql sqlHandle {SELECT POW(2,-2)}) Returns 0.25

• POWER(X,Y)

  This is a synonym for POW().

• RADIANS(X)

  Returns the argument X, converted from degrees to radians. (Note that p radians equals 180 degrees.)

  (sql sqlHandle {SELECT RADIANS(90)}) Returns 1.5707963267949

• RAND(), RAND(N)

  Returns a random floating-point value v in the range 0 <= v < 1.0. If a constant integer argument N is specified, it is used as the seed value, which produces a repeatable sequence of column values. In the following example, note that the sequences of values produced by RAND(3) is the same both places where it occurs.

  (sql sqlHandle {CREATE TABLE t (i INT)})

  (sql sqlHandle {INSERT INTO t VALUES(1),(2),(3)})

  (sql sqlHandle {SELECT i, RAND() FROM t}) Returns
  +------+------------------+
  | i    | RAND()           |
  +------+------------------+
  |    1 | 0.61914388706828 | 
  |    2 | 0.93845168309142 | 
  |    3 | 0.83482678498591 | 
  +------+------------------+

  (sql sqlHandle {SELECT i, RAND(3) FROM t}) Returns
  +------+------------------+
  | i    | RAND(3)          |
  +------+------------------+
  |    1 | 0.90576975597606 | 
  |    2 | 0.37307905813035 | 
  |    3 | 0.14808605345719 | 
  +------+------------------+

  (sql sqlHandle {SELECT i, RAND() FROM t}) Returns
  +------+------------------+
  | i    | RAND()           |
  +------+------------------+
  |    1 | 0.35877890638893 | 
  |    2 | 0.28941420772058 | 
  |    3 | 0.37073435016976 | 
  +------+------------------+

  (sql sqlHandle {SELECT i, RAND(3) FROM t}) Returns
  +------+------------------+
  | i    | RAND(3)          |
  +------+------------------+
  |    1 | 0.90576975597606 | 
  |    2 | 0.37307905813035 | 
  |    3 | 0.14808605345719 | 
  +------+------------------+

  With a constant initializer, the seed is initialized once when the statement is compiled, prior to execution. If a non-constant initializer (such as a column name) is used as the argument, the seed is initialized with the value for each invocation of RAND(). (One implication of this is that for equal argument values, RAND() will return the same value each time.)

  To obtain a random integer R in the range i <= R < j, use the expression FLOOR(i + RAND() * (j – i)). For example, to obtain a random integer in the range the range 7 <= R < 12, you could use the following statement:

  (sql sqlHandle {SELECT FLOOR(7 + (RAND() * 5))})

  You cannot use a column with RAND() values in an ORDER BY clause, because ORDER BY would evaluate the column multiple times. However, you can retrieve rows in random order like this:

  (sql sqlHandle {SELECT * FROM tbl_name ORDER BY RAND()})

  ORDER BY RAND() combined with LIMIT is useful for selecting a random sample from a set of rows:

  (sql sqlHandle {SELECT * FROM table1, table2 WHERE a=b AND c 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 is a fast way to generate ad hoc random numbers which is portable between platforms for the same MySQL version.

• ROUND(X), ROUND(X,D)

  Rounds the argument X to D decimal places. The rounding algorithm depends on the data type of X. D defaults to 0 if not specified. D can be negative to cause D digits left of the decimal point of the value X to become zero.

  (sql sqlHandle {SELECT ROUND(-1.23)}) Returns -1

  (sql sqlHandle {SELECT ROUND(-1.58)}) Returns -2

  (sql sqlHandle {SELECT ROUND(1.58)}) Returns 2

  (sql sqlHandle {SELECT ROUND(1.298, 1)}) Returns 1.3

  (sql sqlHandle {SELECT ROUND(1.298, 0)}) Returns 1

  (sql sqlHandle {SELECT ROUND(23.298, -1)}) Returns 20

  The return type is the same type as that of the first argument (assuming that it is integer, double, or decimal). This means that for an integer argument, the result is an integer (no decimal places):

  (sql sqlHandle {SELECT ROUND(150.000,2), ROUND(150,2)}) Returns
  +------------------+--------------+
  | ROUND(150.000,2) | ROUND(150,2) |
  +------------------+--------------+
  |           150.00 |          150 |
  +------------------+--------------+

  ROUND() uses the following rules depending on the type of the first argument:

  For exact-value numbers, ROUND() uses the "round half up" or "round toward nearest" rule: A value with a fractional part of .5 or greater is rounded up to the next integer if positive or down to the next integer if negative. (In other words, it is rounded away from zero.) A value with a fractional part less than .5 is rounded down to the next integer if positive or up to the next integer if negative.

  For approximate-value numbers, the result depends on the C library. On many systems, this means that ROUND() uses the "round to nearest even" rule: A value with any fractional part is rounded to the nearest even integer.

  The following example shows how rounding differs for exact and approximate values:

  (sql sqlHandle {SELECT ROUND(2.5), ROUND(25E-1)}) Returns
  +------------+--------------+
  | ROUND(2.5) | ROUND(25E-1) |
  +------------+--------------+
  | 3          |            2 |
  +------------+--------------+

• SIGN(X)

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

  (sql sqlHandle {SELECT SIGN(-32)}) Returns -1

  (sql sqlHandle {SELECT SIGN(0)}) Returns 0

  (sql sqlHandle {SELECT SIGN(234)}) Returns 1

• SIN(X)

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

  (sql sqlHandle {SELECT SIN(PI())}) Returns 1.2246063538224e-16

  (sql sqlHandle {SELECT ROUND(SIN(PI()))}) Returns 0

• SQRT(X)

  Returns the square root of a non-negative number X.

  (sql sqlHandle {SELECT SQRT(4)}) Returns 2

  (sql sqlHandle {SELECT SQRT(20)}) Returns 4.4721359549996

  (sql sqlHandle {SELECT SQRT(-16)}) Returns NULL

• TAN(X)

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

  (sql sqlHandle {SELECT TAN(PI())}) Returns -1.2246063538224e-16

  (sql sqlHandle {SELECT TAN(PI()+1)}) Returns 1.5574077246549

• TRUNCATE(X,D)

  Returns the number X, truncated to D decimal places. If D is 0, the result has no decimal point or fractional part. D can be negative to cause D digits left of the decimal point of the value X to become zero.

  (sql sqlHandle {SELECT TRUNCATE(1.223,1)}) Returns 1.2

  (sql sqlHandle {SELECT TRUNCATE(1.999,1)}) Returns 1.9

  (sql sqlHandle {SELECT TRUNCATE(1.999,0)}) Returns 1

  (sql sqlHandle {SELECT TRUNCATE(-1.999,1)}) Returns -1.9

  (sql sqlHandle {SELECT TRUNCATE(122,-2)}) Returns 100

  (sql sqlHandle {SELECT TRUNCATE(10.28*100,0)}) Returns 1028

  All numbers are rounded toward zero.

Date and Time Functions

This section describes the functions that can be used to manipulate temporal values.

Here is an example that uses date functions. The following query selects all rows with a date_col value from within the last 30 days:

(sql sqlHandle {SELECT something FROM tbl_name WHERE DATE_SUB(CURDATE(),INTERVAL 30 DAY) <= date_col})

The query also selects rows with dates that lie in the future.

Functions that expect date values usually accept datetime values and ignore the time part. Functions that expect time values usually 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 always produce the same result. (For our purposes, a single query also includes a call to a stored program (stored routine, trigger, or event) and all sub-programs called by that program.) This principle also applies to CURDATE(), CURTIME(), UTC_DATE(), UTC_TIME(), UTC_TIMESTAMP(), and to any of their synonyms.

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. In addition, UNIX_TIMESTAMP() assumes that its argument is a datetime value in the current time zone.

Some date functions can be used with "zero" dates or incomplete dates such as '2001-11-00', whereas others cannot. Functions that extract parts of dates typically work with incomplete dates and thus can return 0 when you might otherwise expect a non-zero value. For example:

(sql sqlHandle {SELECT DAYOFMONTH('2001-11-00'), MONTH('2005-00-00')}) Returns 0, 0

Other functions expect complete dates and return NULL for incomplete dates. These include functions that perform date arithmetic or that map parts of dates to names. For example:

(sql sqlHandle {SELECT DATE_ADD('2006-05-00',INTERVAL 1 DAY)}) Returns NULL

(sql sqlHandle {SELECT DAYNAME('2006-05-00')}) Returns NULL

• ADDDATE(date,INTERVAL expr unit), ADDDATE(expr,days)

  When invoked with the INTERVAL form of the second argument, ADDDATE() is a synonym for DATE_ADD(). The related function SUBDATE() is a synonym for DATE_SUB(). For information on the INTERVAL unit argument, see the discussion for DATE_ADD().

  (sql sqlHandle {SELECT DATE_ADD('2008-01-02', INTERVAL 31 DAY)}) Returns '2008-02-02'

  (sql sqlHandle {SELECT ADDDATE('2008-01-02', INTERVAL 31 DAY)}) Returns '2008-02-02'

  When invoked with the days form of the second argument, MySQL treats it as an integer number of days to be added to expr.

  (sql sqlHandle {SELECT ADDDATE('2008-01-02', 31)}) Returns '2008-02-02'

• ADDTIME(expr1,expr2)

  ADDTIME() adds expr2 to expr1 and returns the result. expr1 is a time or datetime expression, and expr2 is a time expression.

  (sql sqlHandle {SELECT ADDTIME('2007-12-31 23:59:59.999999', '1 1:1:1.000002')}) Returns '2008-01-02 01:01:01.000001'

  (sql sqlHandle {SELECT ADDTIME('01:00:00.999999', '02:00:00.999998')}) Returns '03:00:01.999997'

• CONVERT_TZ(dt,from_tz,to_tz)

  CONVERT_TZ() converts a datetime value dt from the time zone given by from_tz to the time zone given by to_tz and returns the resulting value. This function returns NULL if the arguments are invalid.

  If the value falls out of the supported range of the TIMESTAMP type when converted from from_tz to UTC, no conversion occurs.

  (sql sqlHandle {SELECT CONVERT_TZ('2004-01-01 12:00:00','GMT','MET')}) Returns '2004-01-01 13:00:00'

  (sql sqlHandle {SELECT CONVERT_TZ('2004-01-01 12:00:00','+00:00','+10:00')}) Returns '2004-01-01 22:00:00'

  Note: To use named time zones such as 'MET' or 'Europe/Moscow', the time zone tables must be properly set up.

• CURDATE()

  Returns the current date as a value in 'YYYY-MM-DD' or YYYYMMDD format, depending on whether the function is used in a string or numeric context.

  (sql sqlHandle {SELECT CURDATE()}) Returns '2008-06-13'

  (sql sqlHandle {SELECT CURDATE() + 0}) Returns 20080613

• CURRENT_DATE, CURRENT_DATE()

  CURRENT_DATE and CURRENT_DATE() are synonyms for CURDATE().

• CURTIME()

  Returns the current time as a value in 'HH:MM:SS' or HHMMSS.uuuuuu format, depending on whether the function is used in a string or numeric context. The value is expressed in the current time zone.

  (sql sqlHandle {SELECT CURTIME()}) Returns '23:50:26'

  (sql sqlHandle {SELECT CURTIME() + 0}) Returns 235026.000000

• CURRENT_TIME, CURRENT_TIME()

  CURRENT_TIME and CURRENT_TIME() are synonyms for CURTIME().

• CURRENT_TIMESTAMP, CURRENT_TIMESTAMP()

  CURRENT_TIMESTAMP and CURRENT_TIMESTAMP() are synonyms for NOW().

• DATE(expr)

  Extracts the date part of the date or datetime expression expr.

  (sql sqlHandle {SELECT DATE('2003-12-31 01:02:03')}) Returns '2003-12-31'

• DATEDIFF(expr1,expr2)

  DATEDIFF() returns expr1 – expr2 expressed as a value in days from one date to the other. expr1 and expr2 are date or date-and-time expressions. Only the date parts of the values are used in the calculation.

  (sql sqlHandle {SELECT DATEDIFF('2007-12-31 23:59:59','2007-12-30')}) Returns 1

  (sql sqlHandle {SELECT DATEDIFF('2010-11-30 23:59:59','2010-12-31')}) Returns -31

• DATE_ADD(date,INTERVAL expr unit), DATE_SUB(date,INTERVAL expr unit)

  These functions perform date arithmetic. The date argument specifies the starting date or datetime value. 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. unit is a keyword indicating the units in which the expression should be interpreted.

  The INTERVAL keyword and the unit specifier are not case sensitive.

  The following table shows the expected form of the expr argument for each unit value.

  unit Value	Expected expr Format
  MICROSECOND	MICROSECONDS
  SECOND	SECONDS
  MINUTE	MINUTES
  HOUR	HOURS
  DAY	DAYS
  WEEK	WEEKS
  MONTH	MONTHS
  QUARTER	QUARTERS
  YEAR	YEARS
  SECOND_MICROSECOND	'SECONDS.MICROSECONDS'
  MINUTE_MICROSECOND	'MINUTES.MICROSECONDS'
  MINUTE_SECOND	'MINUTES:SECONDS'
  HOUR_MICROSECOND	'HOURS.MICROSECONDS'
  HOUR_SECOND	'HOURS:MINUTES:SECONDS'
  HOUR_MINUTE	'HOURS:MINUTES'
  DAY_MICROSECOND	'DAYS.MICROSECONDS'
  DAY_SECOND	'DAYS HOURS:MINUTES:SECONDS'
  DAY_MINUTE	'DAYS HOURS:MINUTES'
  DAY_HOUR	'DAYS HOURS'
  YEAR_MONTH	'YEARS-MONTHS'

  The return value depends on the arguments:

  DATETIME if the first argument is a DATETIME (or TIMESTAMP) value, or if the first argument is a DATE and the unit value uses HOURS, MINUTES, or SECONDS.

  String otherwise.

  To ensure that the result is DATETIME, you can use CAST() to convert the first argument to DATETIME.

  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.

  Date arithmetic also can be performed using INTERVAL together with the + or - operator:

  date + INTERVAL expr unit

  date - INTERVAL expr unit

  INTERVAL expr unit 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 unit is allowed only on the right side, because it makes no sense to subtract a date or datetime value from an interval.

  (sql sqlHandle {SELECT '2008-12-31 23:59:59' + INTERVAL 1 SECOND}) Returns '2009-01-01 00:00:00'

  (sql sqlHandle {SELECT INTERVAL 1 DAY + '2008-12-31'}) Returns '2009-01-01'

  (sql sqlHandle {SELECT '2005-01-01' - INTERVAL 1 SECOND}) Returns '2004-12-31 23:59:59'

  (sql sqlHandle {SELECT DATE_ADD('2000-12-31 23:59:59', INTERVAL 1 SECOND)}) Returns '2001-01-01 00:00:00'

  (sql sqlHandle {SELECT DATE_ADD('2010-12-31 23:59:59', INTERVAL 1 DAY)}) Returns '2011-01-01 23:59:59'

  (sql sqlHandle {SELECT DATE_ADD('2100-12-31 23:59:59', INTERVAL '1:1' MINUTE_SECOND)}) Returns '2101-01-01 00:01:00'

  (sql sqlHandle {SELECT DATE_SUB('2005-01-01 00:00:00', INTERVAL '1 1:1:1' DAY_SECOND)}) Returns '2004-12-30 22:58:59'

  (sql sqlHandle {SELECT DATE_ADD('1900-01-01 00:00:00', INTERVAL '-1 10' DAY_HOUR)}) Returns '1899-12-30 14:00:00'

  (sql sqlHandle {SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY)}) Returns '1997-12-02'

  (sql sqlHandle {SELECT DATE_ADD('1992-12-31 23:59:59.000002', INTERVAL '1.999999' SECOND_MICROSECOND)}) Returns '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 unit keyword), MySQL assumes that you have left out the leftmost parts of the interval value. For example, if you specify a unit 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 a time of day.

  Because expr is treated as a string, be careful if you specify a non-string value with INTERVAL. For example, with an interval specifier of HOUR_MINUTE, 6/4 evaluates to 1.5000 and is treated as 1 hour, 5000 minutes:

  (sql sqlHandle {SELECT 6/4}) Returns 1.5000

  (sql sqlHandle {SELECT DATE_ADD('2009-01-01', INTERVAL 6/4 HOUR_MINUTE)}) Returns '2009-01-04 12:20:00'

  To ensure interpretation of the interval value as you expect, a CAST() operation may be used. To treat 6/4 as 1 hour, 5 minutes, cast it to a DECIMAL value with a single fractional digit:

  (sql sqlHandle {SELECT CAST(6/4 AS DECIMAL(3,1))}) Returns 1.5

  (sql sqlHandle {SELECT DATE_ADD('1970-01-01 12:00:00', INTERVAL CAST(6/4 AS DECIMAL(3,1)) HOUR_MINUTE)}) Returns '1970-01-01 13:05:00'

  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:

  (sql sqlHandle {SELECT DATE_ADD('2013-01-01', INTERVAL 1 DAY)}) Returns '2013-01-02'

  (sql sqlHandle {SELECT DATE_ADD('2013-01-01', INTERVAL 1 HOUR)}) Returns '2013-01-01 01:00:00'

  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:

  (sql sqlHandle {SELECT DATE_ADD('2009-01-30', INTERVAL 1 MONTH)}) Returns '2009-02-28'

  Date arithmetic operations require complete dates and do not work with incomplete dates such as '2006-07-00' or badly malformed dates:

  (sql sqlHandle {SELECT DATE_ADD('2006-07-00', INTERVAL 1 DAY)}) Returns NULL

  (sql sqlHandle {SELECT '2005-03-32' + INTERVAL 1 MONTH}) Returns NULL

• DATE_FORMAT(date,format)

  Formats the date value according to the format string.

  The following specifiers may be used in the format string. The "%" character is required before format specifier characters.

  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 "%" character
  %x	x, for any "x" not listed above

  Ranges for the month and day specifiers begin with zero due to the fact that MySQL allows the storing of incomplete dates such as '2014-00-00'.

  The language used for day and month names and abbreviations is controlled by the value of the lc_time_names system variable.

  DATE_FORMAT() returns a string with a character set and collation given by character_set_connection and collation_connection so that it can return month and weekday names containing non-ASCII characters.

  (sql sqlHandle {SELECT DATE_FORMAT('2009-10-04 22:23:00', '%W %M %Y')}) Returns 'Sunday October 2009'

  (sql sqlHandle {SELECT DATE_FORMAT('2007-10-04 22:23:00', '%H:%i:%s')}) Returns '22:23:00'

  (sql sqlHandle {SELECT DATE_FORMAT('1900-10-04 22:23:00', '%D %y %a %d %m %b %j')}) Returns '4th 00 Thu 04 10 Oct 277'

  (sql sqlHandle {SELECT DATE_FORMAT('1997-10-04 22:23:00', '%H %k %I %r %T %S %w')}) Returns '22 22 10 10:23:00 PM 22:23:00 00 6'

  (sql sqlHandle {SELECT DATE_FORMAT('1999-01-01', '%X %V')}) Returns '1998 52'

  (sql sqlHandle {SELECT DATE_FORMAT('2006-06-00', '%d')}) Returns '00'

• DATE_SUB(date,INTERVAL expr unit)

  See the description for DATE_ADD().

• DAY(date)

  DAY() is a synonym for DAYOFMONTH().

• DAYNAME(date)

  Returns the name of the weekday for date. The language used for the name is controlled by the value of the lc_time_names system variable.

  (sql sqlHandle {SELECT DAYNAME('2007-02-03')}) Returns 'Saturday'

• DAYOFMONTH(date)

  Returns the day of the month for date, in the range 1 to 31, or 0 for dates such as '0000-00-00' or '2008-00-00' that have a zero day part.

  (sql sqlHandle {SELECT DAYOFMONTH('2007-02-03')}) Returns 3

• DAYOFWEEK(date)

  Returns the weekday index for date (1 = Sunday, 2 = Monday, …, 7 = Saturday). These index values correspond to the ODBC standard.

  (sql sqlHandle {SELECT DAYOFWEEK('2007-02-03')}) Returns 7

• DAYOFYEAR(date)

  Returns the day of the year for date, in the range 1 to 366.

  (sql sqlHandle {SELECT DAYOFYEAR('2007-02-03')}) Returns 34

• EXTRACT(unit FROM date)

  The EXTRACT() function uses the same kinds of unit specifiers as DATE_ADD() or DATE_SUB(), but extracts parts from the date rather than performing date arithmetic.

  (sql sqlHandle {SELECT EXTRACT(YEAR FROM '2009-07-02')}) Returns 2009

  (sql sqlHandle {SELECT EXTRACT(YEAR_MONTH FROM '2009-07-02 01:02:03')}) Returns 200907

  (sql sqlHandle {SELECT EXTRACT(DAY_MINUTE FROM '2009-07-02 01:02:03')}) Returns 20102

  (sql sqlHandle {SELECT EXTRACT(MICROSECOND FROM '2003-01-02 10:30:00.000123')}) Returns 123

• FROM_DAYS(N)

  Given a day number N, returns a DATE value.

  (sql sqlHandle {SELECT FROM_DAYS(730669)}) Returns '2007-07-03'

  Use FROM_DAYS() with caution on old dates. It is not intended for use with values that precede the advent of the Gregorian calendar (1582).

• FROM_UNIXTIME(unix_timestamp), FROM_UNIXTIME(unix_timestamp,format)

  Returns a representation of the unix_timestamp argument as a value in 'YYYY-MM-DD HH:MM:SS' or YYYYMMDDHHMMSS.uuuuuu format, depending on whether the function is used in a string or numeric context. The value is expressed in the current time zone. unix_timestamp is an internal timestamp value such as is produced by the UNIX_TIMESTAMP() function.

  If format is given, the result is formatted according to the format string, which is used the same way as listed in the entry for the DATE_FORMAT() function.

  (sql sqlHandle {SELECT FROM_UNIXTIME(1196440219)}) Returns '2007-11-30 10:30:19'

  (sql sqlHandle {SELECT FROM_UNIXTIME(1196440219) + 0}) Returns 20071130103019.000000

  (sql sqlHandle {SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(), %Y %D %M %h:%i:%s %x')}) Returns '2007 30th November 10:30:59 2007'

  Note: If you use UNIX_TIMESTAMP() and FROM_UNIXTIME() to convert between TIMESTAMP values and Unix timestamp values, the conversion is lossy because the mapping is not one-to-one in both directions. For details, see the description of the UNIX_TIMESTAMP() function.

• GET_FORMAT({DATE|TIME|DATETIME}, {'EUR'|'USA'|'JIS'|'ISO'|'INTERNAL'})

  Returns a format string. This function is useful in combination with the DATE_FORMAT() and the STR_TO_DATE() functions.

  The possible values for the first and second arguments result in several possible format strings (for the specifiers used, see the table in the DATE_FORMAT() function description). ISO format refers to ISO 9075, not ISO 8601.

  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 as the first argument to GET_FORMAT(), in which case the function returns the same values as for DATETIME.

  (sql sqlHandle {SELECT DATE_FORMAT('2003-10-03',GET_FORMAT(DATE,'EUR'))}) Returns '03.10.2003'

  (sql sqlHandle {SELECT STR_TO_DATE('10.31.2003',GET_FORMAT(DATE,'USA'))}) Returns '2003-10-31'

• HOUR(time)

  Returns the hour for time. The range of the return value is 0 to 23 for time-of-day values. However, the range of TIME values actually is much larger, so HOUR can return values greater than 23.

  (sql sqlHandle {SELECT HOUR('10:05:03')}) Returns 10

  (sql sqlHandle {SELECT HOUR('272:59:59')}) Returns 272

• LAST_DAY(date)

  Takes a date or datetime value and returns the corresponding value for the last day of the month. Returns NULL if the argument is invalid.

  (sql sqlHandle {SELECT LAST_DAY('2003-02-05')}) Returns '2003-02-28'

  (sql sqlHandle {SELECT LAST_DAY('2004-02-05')}) Returns '2004-02-29'

  (sql sqlHandle {SELECT LAST_DAY('2004-01-01 01:01:01')}) Returns '2004-01-31'

  (sql sqlHandle {SELECT LAST_DAY('2003-03-32')}) Returns NULL

• LOCALTIME, LOCALTIME()

  LOCALTIME and LOCALTIME() are synonyms for NOW().

• LOCALTIMESTAMP, LOCALTIMESTAMP()

  LOCALTIMESTAMP and LOCALTIMESTAMP() are synonyms for NOW().

• MAKEDATE(year,dayofyear)

  Returns a date, given year and day-of-year values. dayofyear must be greater than 0 or the result is NULL.

  (sql sqlHandle {SELECT MAKEDATE(2011,31), MAKEDATE(2011,32)}) Returns '2011-01-31', '2011-02-01'

  (sql sqlHandle {SELECT MAKEDATE(2011,365), MAKEDATE(2014,365)}) Returns '2011-12-31', '2014-12-31'

  (sql sqlHandle {SELECT MAKEDATE(2011,0)}) Returns NULL

• MAKETIME(hour,minute,second)

  Returns a time value calculated from the hour, minute, and second arguments.

  (sql sqlHandle {SELECT MAKETIME(12,15,30)}) Returns '12:15:30'

• MICROSECOND(expr)

  Returns the microseconds from the time or datetime expression expr as a number in the range from 0 to 999999.

  (sql sqlHandle {SELECT MICROSECOND('12:00:00.123456')}) Returns 123456

  (sql sqlHandle {SELECT MICROSECOND('2009-12-31 23:59:59.000010')}) Returns 10

• MINUTE(time)

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

  (sql sqlHandle {SELECT MINUTE('2008-02-03 10:05:03')}) Returns 5

• MONTH(date)

  Returns the month for date, in the range 1 to 12 for January to December, or 0 for dates such as '0000-00-00' or '2008-00-00' that have a zero month part.

  (sql sqlHandle {SELECT MONTH('2008-02-03')}) Returns 2

• MONTHNAME(date)

  Returns the full name of the month for date. The language used for the name is controlled by the value of the lc_time_names system variable.

  (sql sqlHandle {SELECT MONTHNAME('2008-02-03')}) Returns 'February'

• NOW()

  Returns the current date and time as a value in 'YYYY-MM-DD HH:MM:SS' or YYYYMMDDHHMMSS.uuuuuu format, depending on whether the function is used in a string or numeric context. The value is expressed in the current time zone.

  (sql sqlHandle {SELECT NOW()}) Returns '2007-12-15 23:50:26'

  (sql sqlHandle {SELECT NOW() + 0}) Returns 20071215235026.000000

  NOW() returns a constant time that indicates the time at which the statement began to execute. (Within a stored routine or trigger, NOW() returns the time at which the routine or triggering statement began to execute.) This differs from the behavior for SYSDATE(), which returns the exact time at which it executes.

  (sql sqlHandle {SELECT NOW(), SLEEP(2), NOW()})
  +---------------------+----------+---------------------+
  | NOW()               | SLEEP(2) | NOW()               |
  +---------------------+----------+---------------------+
  | 2006-04-12 13:47:36 |        0 | 2006-04-12 13:47:36 |
  +---------------------+----------+---------------------+

  (sql sqlHandle {SELECT SYSDATE(), SLEEP(2), SYSDATE()})
  +---------------------+----------+---------------------+
  | SYSDATE()           | SLEEP(2) | SYSDATE()           |
  +---------------------+----------+---------------------+
  | 2006-04-12 13:47:44 |        0 | 2006-04-12 13:47:46 |
  +---------------------+----------+---------------------+

  In addition, the SET TIMESTAMP statement affects the value returned by NOW() but not by SYSDATE(). This means that timestamp settings in the binary log have no effect on invocations of SYSDATE().

  See the description for SYSDATE() for additional information about the differences between the two functions.

• PERIOD_ADD(P,N)

  Adds N months to period P (in the format YYMM or YYYYMM). Returns a value in the format YYYYMM. Note that the period argument P is not a date value.

  (sql sqlHandle {SELECT PERIOD_ADD(200801,2)}) Returns 200803

• PERIOD_DIFF(P1,P2)

  Returns the number of months between periods P1 and P2. P1 and P2 should be in the format YYMM or YYYYMM. Note that the period arguments P1 and P2 are not date values.

  (sql sqlHandle {SELECT PERIOD_DIFF(200802,200703)}) Returns 11

• QUARTER(date)

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

  (sql sqlHandle {SELECT QUARTER('2008-04-01')}) Returns 2

• SECOND(time)

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

  (sql sqlHandle {SELECT SECOND('10:05:03')}) Returns 3

• SEC_TO_TIME(seconds)

  Returns the seconds argument, converted to hours, minutes, and seconds, as a TIME value. The range of the result is constrained to that of the TIME data type. A warning occurs if the argument corresponds to a value outside that range.

  (sql sqlHandle {SELECT SEC_TO_TIME(2378)}) Returns '00:39:38'

  (sql sqlHandle {SELECT SEC_TO_TIME(2378) + 0}) Returns 3938

• STR_TO_DATE(str,format)

  This is the inverse of the DATE_FORMAT() function. It takes a string str and a format string format. STR_TO_DATE() returns a DATETIME value if the format string contains both date and time parts, or a DATE or TIME value if the string contains only date or time parts.

  The date, time, or datetime values contained in str should be given in the format indicated by format. For the specifiers that can be used in format, see the DATE_FORMAT() function description. If str contains an illegal date, time, or datetime value, STR_TO_DATE() returns NULL. An illegal value also produces a warning.

  This means, for example, that "zero" dates or dates with part values of 0 are allowed unless the SQL mode is set to disallow such values.

  (sql sqlHandle {SELECT STR_TO_DATE('00/00/0000', '%m/%d/%Y')}) Returns '0000-00-00'

  (sql sqlHandle {SELECT STR_TO_DATE('04/31/2004', '%m/%d/%Y')}) Returns '2004-04-31'

  Note: You cannot use format "%X%V" to convert a year-week string to a date because the combination of a year and week does not uniquely identify a year and month if the week crosses a month boundary. To convert a year-week to a date, then you should also specify the weekday:

  (sql sqlHandle {SELECT STR_TO_DATE('200442 Monday', '%X%V %W')}) Returns '2004-10-18'

• SUBDATE(date,INTERVAL expr unit), SUBDATE(expr,days)

  When invoked with the INTERVAL form of the second argument, SUBDATE() is a synonym for DATE_SUB(). For information on the INTERVAL unit argument, see the discussion for DATE_ADD().

  (sql sqlHandle {SELECT DATE_SUB('2008-01-02', INTERVAL 31 DAY)}) Returns '2007-12-02'

  (sql sqlHandle {SELECT SUBDATE('2008-01-02', INTERVAL 31 DAY)}) Returns '2007-12-02'

  The second form allows the use of an integer value for days. In such cases, it is interpreted as the number of days to be subtracted from the date or datetime expression expr.

  (sql sqlHandle {SELECT SUBDATE('2008-01-02 12:00:00', 31)}) Returns '2007-12-02 12:00:00'

• SUBTIME(expr1,expr2)

  SUBTIME() returns expr1 – expr2 expressed as a value in the same format as expr1. expr1 is a time or datetime expression, and expr2 is a time expression.

  (sql sqlHandle {SELECT SUBTIME('2007-12-31 23:59:59.999999','1 1:1:1.000002')}) Returns '2007-12-30 22:58:58.999997'

  (sql sqlHandle {SELECT SUBTIME('01:00:00.999999', '02:00:00.999998')}) Returns '-00:59:59.999999'

• SYSDATE()

  Returns the current date and time as a value in 'YYYY-MM-DD HH:MM:SS' or YYYYMMDDHHMMSS.uuuuuu format, depending on whether the function is used in a string or numeric context.

  SYSDATE() returns the time at which it executes. This differs from the behavior for NOW(), which returns a constant time that indicates the time at which the statement began to execute. (Within a stored routine or trigger, NOW() returns the time at which the routine or triggering statement began to execute.)

  (sql sqlHandle {SELECT NOW(), SLEEP(2), NOW()}) Returns
  +---------------------+----------+---------------------+
  | NOW()               | SLEEP(2) | NOW()               |
  +---------------------+----------+---------------------+
  | 2006-04-12 13:47:36 |        0 | 2006-04-12 13:47:36 |
  +---------------------+----------+---------------------+

  (sql sqlHandle {SELECT SYSDATE(), SLEEP(2), SYSDATE()}) Returns
  +---------------------+----------+---------------------+
  | SYSDATE()           | SLEEP(2) | SYSDATE()           |
  +---------------------+----------+---------------------+
  | 2006-04-12 13:47:44 |        0 | 2006-04-12 13:47:46 |
  +---------------------+----------+---------------------+

  In addition, the SET TIMESTAMP statement affects the value returned by NOW() but not by SYSDATE(). This means that timestamp settings in the binary log have no effect on invocations of SYSDATE().

  Because SYSDATE() can return different values even within the same statement, and is not affected by SET TIMESTAMP, it is non-deterministic and therefore unsafe for replication if statement-based binary logging is used. If that is a problem, you can use row-based logging, or start the server with the --sysdate-is-now option to cause SYSDATE() to be an alias for NOW(). The non-deterministic nature of SYSDATE() also means that indexes cannot be used for evaluating expressions that refer to it.

• TIME(expr)

  Extracts the time part of the time or datetime expression expr and returns it as a string.

  (sql sqlHandle {SELECT TIME('2003-12-31 01:02:03')}) Returns '01:02:03'

  (sql sqlHandle {SELECT TIME('2003-12-31 01:02:03.000123')}) Returns '01:02:03.000123'

• TIMEDIFF(expr1,expr2)

  TIMEDIFF() returns expr1 – expr2 expressed as a time value. expr1 and expr2 are time or date-and-time expressions, but both must be of the same type.

  (sql sqlHandle {SELECT TIMEDIFF('2000:01:01 00:00:00', '2000:01:01 00:00:00.000001')}) Returns '-00:00:00.000001'

  (sql sqlHandle {SELECT TIMEDIFF('2008-12-31 23:59:59.000001', '2008-12-30 01:01:01.000002')}) Returns '46:58:57.999999'

• TIMESTAMP(expr), TIMESTAMP(expr1,expr2)

  With a single argument, this function returns the date or datetime expression expr as a datetime value. With two arguments, it adds the time expression expr2 to the date or datetime expression expr1 and returns the result as a datetime value.

  (sql sqlHandle {SELECT TIMESTAMP('2003-12-31')}) Returns '2003-12-31 00:00:00'

  (sql sqlHandle {SELECT TIMESTAMP('2003-12-31 12:00:00','12:00:00')}) Returns '2004-01-01 00:00:00'

• TIMESTAMPADD(unit,interval,datetime_expr)

  Adds the integer expression interval to the date or datetime expression datetime_expr. The unit for interval is given by the unit argument, which should be one of the following values: FRAC_SECOND (microseconds), SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.

  It is possible to use MICROSECOND in place of FRAC_SECOND with this function, and FRAC_SECOND is deprecated.

  The unit value may be specified using one of keywords as shown, or with a prefix of SQL_TSI_. For example, DAY and SQL_TSI_DAY both are legal.

  (sql sqlHandle {SELECT TIMESTAMPADD(MINUTE,1,'2003-01-02')}) Returns '2003-01-02 00:01:00'

  (sql sqlHandle {SELECT TIMESTAMPADD(WEEK,1,'2003-01-02')}) Returns '2003-01-09'

• TIMESTAMPDIFF(unit,datetime_expr1,datetime_expr2)

  Returns the integer difference between the date or datetime expressions datetime_expr1 and datetime_expr2. The unit for the result is given by the unit argument. The legal values for unit are the same as those listed in the description of the TIMESTAMPADD() function.

  (sql sqlHandle {SELECT TIMESTAMPDIFF(MONTH,'2003-02-01','2003-05-01')}) Returns 3

  (sql sqlHandle {SELECT TIMESTAMPDIFF(YEAR,'2002-05-01','2001-01-01')}) Returns -1

• TIME_FORMAT(time,format)

  This is used like the DATE_FORMAT() function, but the format string may contain format specifiers only for 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.

  (sql sqlHandle {SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l')}) Returns '100 100 04 04 4'

• TIME_TO_SEC(time)

  Returns the time argument, converted to seconds.

  (sql sqlHandle {SELECT TIME_TO_SEC('22:23:00')}) Returns 80580

  (sql sqlHandle {SELECT TIME_TO_SEC('00:39:38')}) Returns 2378

• TO_DAYS(date)

  Given a date date, returns a day number (the number of days since year 0).

  (sql sqlHandle {SELECT TO_DAYS(950501)}) Returns 728779

  (sql sqlHandle {SELECT TO_DAYS('2007-10-07')}) Returns 733321

  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. For dates before 1582 (and possibly a later year in other locales), results from this function are not reliable.

  Remember that MySQL converts two-digit year values in dates to four-digit form For example, '2008-10-07' and '08-10-07' are seen as identical dates:

  (sql sqlHandle {SELECT TO_DAYS('2008-10-07'), TO_DAYS('08-10-07')}) Returns 733687, 733687

• UNIX_TIMESTAMP(), UNIX_TIMESTAMP(date)

  If called with no argument, returns a Unix timestamp (seconds since '1970-01-01 00:00:00' UTC) 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' UTC. date may be a DATE string, a DATETIME string, a TIMESTAMP, or a number in the format YYMMDD or YYYYMMDD. The server interprets date as a value in the current time zone and converts it to an internal value in UTC. Clients can set their time zone.

  (sql sqlHandle {SELECT UNIX_TIMESTAMP()}) Returns 1196440210

  (sql sqlHandle {SELECT UNIX_TIMESTAMP('2007-11-30 10:30:19')}) Returns 1196440219

  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.

  Note: If you use UNIX_TIMESTAMP() and FROM_UNIXTIME() to convert between TIMESTAMP values and Unix timestamp values, the conversion is lossy because the mapping is not one-to-one in both directions. For example, due to conventions for local time zone changes, it is possible for two UNIX_TIMESTAMP() to map two TIMESTAMP values to the same Unix timestamp value. FROM_UNIXTIME() will map that value back to only one of the original TIMESTAMP values. Here is an example, using TIMESTAMP values in the CET time zone:

  (sql sqlHandle {SELECT UNIX_TIMESTAMP('2005-03-27 03:00:00')}) Returns
  +---------------------------------------+
  | UNIX_TIMESTAMP('2005-03-27 03:00:00') |
  +---------------------------------------+
  |                            1111885200 |
  +---------------------------------------+

  (sql sqlHandle {SELECT UNIX_TIMESTAMP('2005-03-27 02:00:00')}) Returns
  +---------------------------------------+
  | UNIX_TIMESTAMP('2005-03-27 02:00:00') |
  +---------------------------------------+
  |                            1111885200 |
  +---------------------------------------+

  (sql sqlHandle {SELECT FROM_UNIXTIME(1111885200)}) Returns
  +---------------------------+
  | FROM_UNIXTIME(1111885200) |
  +---------------------------+
  | 2005-03-27 03:00:00       |
  +---------------------------+

  If you want to subtract UNIX_TIMESTAMP() columns, you might want to cast the result to signed integers.

• UTC_DATE, UTC_DATE()

  Returns the current UTC date as a value in 'YYYY-MM-DD' or YYYYMMDD format, depending on whether the function is used in a string or numeric context.

  (sql sqlHandle {SELECT UTC_DATE(), UTC_DATE() + 0}) Returns '2003-08-14', 20030814

• UTC_TIME, UTC_TIME()

  Returns the current UTC time as a value in 'HH:MM:SS' or HHMMSS.uuuuuu format, depending on whether the function is used in a string or numeric context.

  (sql sqlHandle {SELECT UTC_TIME(), UTC_TIME() + 0}) Returns '18:07:53', 180753.000000

• UTC_TIMESTAMP, UTC_TIMESTAMP()

  Returns the current UTC date and time as a value in 'YYYY-MM-DD HH:MM:SS' or YYYYMMDDHHMMSS.uuuuuu format, depending on whether the function is used in a string or numeric context.

  (sql sqlHandle {SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0}) Returns '2003-08-14 18:08:04', 20030814180804.000000

• WEEK(date[,mode])

  This function returns the week number for date. The two-argument form of WEEK() allows you to specify whether the week starts on Sunday or Monday and whether the return value should be in the range from 0 to 53 or from 1 to 53. If the mode argument is omitted, the value of the default_week_format system variable is used.

  The following table describes how the mode argument works.

  Mode	First day of week	Range	Week 1 is the first week ...
  0	Sunday	0-53	with a Sunday in this year
  1	Monday	0-53	with more than 3 days this year
  2	Sunday	1-53	with a Sunday in this year
  3	Monday	1-53	with more than 3 days this year
  4	Sunday	0-53	with more than 3 days this year
  5	Monday	0-53	with a Monday in this year
  6	Sunday	1-53	with more than 3 days this year
  7	Monday	1-53	with a Monday in this year

  (sql sqlHandle {SELECT WEEK('2008-02-20')}) Returns 7

  (sql sqlHandle {SELECT WEEK('2008-02-20',0)}) Returns 7

  (sql sqlHandle {SELECT WEEK('2008-02-20',1)}) Returns 8

  (sql sqlHandle {SELECT WEEK('2008-12-31',1)}) Returns 53

  Note that if a date falls in the last week of the previous year, MySQL returns 0 if you do not use 2, 3, 6, or 7 as the optional mode argument:

  (sql sqlHandle {SELECT YEAR('2000-01-01'), WEEK('2000-01-01',0)}) Returns 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, use 0, 2, 5, or 7 as the optional mode argument.

  (sql sqlHandle {SELECT WEEK('2000-01-01',2)}) Returns 52

  Alternatively, use the YEARWEEK() function:

  (sql sqlHandle {SELECT YEARWEEK('2000-01-01')}) Returns 199952

  (sql sqlHandle {SELECT MID(YEARWEEK('2000-01-01'),5,2)}) Returns '52'

• WEEKDAY(date)

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

  (sql sqlHandle {SELECT WEEKDAY('2008-02-03 22:23:00')}) Returns 6

  (sql sqlHandle {SELECT WEEKDAY('2007-11-06')}) Returns 1

• WEEKOFYEAR(date)

  Returns the calendar week of the date as a number in the range from 1 to 53. WEEKOFYEAR() is a compatibility function that is equivalent to WEEK(date,3).

  (sql sqlHandle {SELECT WEEKOFYEAR('2008-02-20')}) Returns 8

• YEAR(date)

  Returns the year for date, in the range 1000 to 9999, or 0 for the "zero" date.

  (sql sqlHandle {SELECT YEAR('1987-01-01')}) Returns 1987

• YEARWEEK(date), YEARWEEK(date,mode)

  Returns year and week for a date. The mode argument works exactly like the mode argument to 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.

  (sql sqlHandle {SELECT YEARWEEK('1987-01-01')}) Returns 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.

Cast Functions and Operators

• BINARY

  The BINARY operator casts the string following it to a binary string. This is an easy way to force a column comparison to be 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.

  (sql sqlHandle {SELECT 'a' = 'A'}) Returns 1

  (sql sqlHandle {SELECT BINARY 'a' = 'A'}) Returns 0

  (sql sqlHandle {SELECT 'a' = 'a '}) Returns 1

  (sql sqlHandle {SELECT BINARY 'a' = 'a '}) Returns 0

  In a comparison, BINARY affects the entire operation; it can be given before either operand with the same result.

  BINARY str is shorthand for CAST(str AS BINARY).

  Note that in some contexts, if you cast an indexed column to BINARY, MySQL is not able to use the index efficiently.

• CAST(expr AS type)

  The CAST() function takes a value of one type and produce a value of another type, similar to CONVERT(). See the description of CONVERT() for more information.

• CONVERT(expr,type), CONVERT(expr USING transcoding_name)

  The CONVERT() and CAST() functions take a value of one type and produce a value of another type.

  The type can be one of the following values:

  • BINARY[(N)]

  • CHAR[(N)]

  • DATE

  • DATETIME

  • DECIMAL[(M[,D])]

  • SIGNED [INTEGER]

  • TIME

  • UNSIGNED [INTEGER]

  BINARY produces a string with the BINARY data type. If the optional length N is given, BINARY(N) causes the cast to use no more than N bytes of the argument. Values shorter than N bytes are padded with 0x00 bytes to a length of N.

  CHAR(N) causes the cast to use no more than N characters of the argument.

  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 default character set to the corresponding string in the utf8 character set:

  (sql sqlHandle {SELECT CONVERT('abc' USING utf8)})

Normally, you cannot compare a BLOB value or other binary string in case-insensitive fashion because binary strings have no character set, and thus no concept of lettercase. To perform a case-insensitive comparison, use the CONVERT() function to convert the value to a non-binary string. If the character set of the result has a case-insensitive collation, the LIKE operation is not case sensitive:

(sql sqlHandle {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. To ensure that a case-insensitive collation is used, specify a COLLATE clause following the CONVERT() call.

CONVERT() can be used more generally for comparing strings that are represented in different character sets.

The cast functions are useful when you want to create a column with a specific type in a CREATE ... SELECT statement:

(sql sqlHandle {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:

(sql sqlHandle {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.

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().

To cast a string to a numeric value in numeric context, you normally do not have to do anything other than to use the string value as though it were a number:

(sql sqlHandle {SELECT 1+'1'}) Returns 2

If you use a number in string context, the number automatically is converted to a BINARY string.

(sql sqlHandle {SELECT CONCAT('hello you ',2)}) Returns 'hello you 2'

MySQL supports arithmetic with both signed and unsigned 64-bit values. If you are using numeric operators (such as + or -) 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.

(sql sqlHandle {SELECT CAST(1-2 AS UNSIGNED)}) Returns 18446744073709551615

(sql sqlHandle {SELECT CAST(CAST(1-2 AS UNSIGNED) AS SIGNED)}) Returns -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.)

(sql sqlHandle {SELECT CAST(1 AS UNSIGNED) - 2.0}) Returns -1.0

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

If you convert a "zero" date string to a date, CONVERT() and CAST() return NULL and produce a warning when the NO_ZERO_DATE SQL mode is enabled.

Other Functions

Bit Functions

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

• |

  Bitwise OR:

  (sql sqlHandle {SELECT 29 | 15}) Returns 31

  The result is an unsigned 64-bit integer.

• &

  Bitwise AND:

  (sql sqlHandle {SELECT 29 & 15}) Returns 13

  The result is an unsigned 64-bit integer.

• ^

  Bitwise XOR:

  (sql sqlHandle {SELECT 1 ^ 1}) Returns 0

  (sql sqlHandle {SELECT 1 ^ 0}) Returns 1

  (sql sqlHandle {SELECT 11 ^ 3}) Returns 8

  The result is an unsigned 64-bit integer.

• <<

  Shifts a longlong (BIGINT) number to the left.

  (sql sqlHandle {SELECT 1 << 2}) Returns 4

  The result is an unsigned 64-bit integer.

• >>

  Shifts a longlong (BIGINT) number to the right.

  (sql sqlHandle {SELECT 4 >> 2}) Returns 1

  The result is an unsigned 64-bit integer.

• ~

  Invert all bits.

  (sql sqlHandle {SELECT 5 & ~1}) Returns 4

  The result is an unsigned 64-bit integer.

• BIT_COUNT(N)

  Returns the number of bits that are set in the argument N.

  (sql sqlHandle {SELECT BIT_COUNT(29), BIT_COUNT(b'101010')}) Returns 4, 3

Encryption and Compression Functions

Note: The encryption and compression functions return binary strings. For many of these functions, the result might contain arbitrary byte values. If you want to store these results, use a column with a VARBINARY or BLOB binary string data type. This will avoid potential problems with trailing space removal or character set conversion that would change data values, such as may occur if you use a non-binary string data type (CHAR, VARCHAR, TEXT).

Note: Exploits for the MD5 and SHA-1 algorithms have become known. You may wish to consider using one of the other encryption functions described in this section instead.

• AES_DECRYPT(crypt_str,key_str)

  This function allows decryption of data using the official AES (Advanced Encryption Standard) algorithm. For more information, see the description of AES_ENCRYPT().

• AES_ENCRYPT(str,key_str)

  AES_ENCRYPT() and AES_DECRYPT() allow encryption and decryption of data using the official AES (Advanced Encryption Standard) algorithm, previously known as "Rijndael." Encoding with a 128-bit key length is used, but you can extend it up to 256 bits by modifying the source. We chose 128 bits because it is much faster and it is secure enough for most purposes.

  AES_ENCRYPT() encrypts a string and returns a binary string. AES_DECRYPT() decrypts the encrypted string and returns the original string. The input arguments may be any length. If either argument is 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 using this formula:

  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'));

  AES_ENCRYPT() and AES_DECRYPT() can be considered the most cryptographically secure encryption functions currently available in MySQL.

• COMPRESS(string_to_compress)

  Compresses a string and returns the result as a binary string. This function requires MySQL to have been compiled with a compression library such as zlib. Otherwise, the return value is always NULL. The compressed string can be uncompressed with UNCOMPRESS().

  (sql sqlHandle {SELECT LENGTH(COMPRESS(REPEAT('a',1000)))}) Returns 21

  (sql sqlHandle {SELECT LENGTH(COMPRESS(''))}) Returns 0

  (sql sqlHandle {SELECT LENGTH(COMPRESS('a'))}) Returns 13

  (sql sqlHandle {SELECT LENGTH(COMPRESS(REPEAT('a',16)))}) Returns 15

  The compressed string contents are stored the following way:

  Empty strings are stored as empty strings.

  Non-empty strings are stored as a four-byte length of the uncompressed string (low byte first), followed by the compressed string. If the string ends with space, an extra "." character is added to avoid problems with endspace trimming should the result be stored in a CHAR or VARCHAR column. (However, use of non-binary string data types such as CHAR or VARCHAR to store compressed strings is not recommended anyway because character set conversion may occur. Use a VARBINARY or BLOB binary string column instead.)

• DECODE(crypt_str,pass_str)

  Decrypts the encrypted string crypt_str using pass_str as the password. crypt_str should be a string returned from ENCODE().

• ENCODE(str,pass_str)

  Encrypt str using pass_str as the password. To decrypt the result, use DECODE().

  The result is a binary string of the same length as str.

  The strength of the encryption is based on how good the random generator is. It should suffice for short strings.

• DES_DECRYPT(crypt_str[,key_str])

  Decrypts a string encrypted with DES_ENCRYPT(). If an error occurs, this function returns NULL.

  This function works only if MySQL has been configured with SSL support.

  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 does not appear to be an encrypted string, MySQL returns the given crypt_str.

• DES_ENCRYPT(str[,{key_num|key_str}])

  Encrypts the string with the given key using the Triple-DES algorithm.

  This function works only if MySQL has been configured with SSL support.

  The encryption key to use is chosen based on the second argument to DES_ENCRYPT(), if one was given. With no argument, the first key from the DES key file is used. With a key_num argument, the given key number (0-9) from the DES key file is used. With a key_str argument, the given key string is used to encrypt str.

  The key file can be specified with the --des-key-file server option.

  The return string is a binary string where the first character is CHAR(128 | key_num). If an error occurs, DES_ENCRYPT() returns NULL.

  The 128 is added to make it easier to recognize an encrypted key. If you use a string key, key_num is 127.

  The string length for the result is given by this formula:

  new_len = orig_len + (8 - (orig_len % 8)) + 1

  Each line in the DES key file has the following format:

  key_num des_key_str

  Each key_num value 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 is used to encrypt the message. There should be at least one space between the number and the key. The first key is the default key that is used if you do not 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.

  (sql sqlHandle {SELECT customer_address FROM customer_table > WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number')}) 

• ENCRYPT(str[,salt])

  Encrypts str using the Unix crypt() system call and returns a binary string. The salt argument should be a string with at least two characters. If no salt argument is given, a random value is used.

  (sql sqlHandle {SELECT ENCRYPT('hello')}) Returns '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.

  The use of ENCRYPT() with multi-byte character sets other than utf8 is not recommended because the system call expects a string terminated by a zero byte.

  If crypt() is not available on your system (as is the case with Windows), ENCRYPT() always returns NULL.

• MD5(str)

  Calculates an MD5 128-bit checksum for the string. The value is returned as a binary string of 32 hex digits, or NULL if the argument was NULL. The return value can, for example, be used as a hash key.

  (sql sqlHandle {SELECT MD5('testing')}) Returns 'ae2b1fca515949e5d54fb22b8ed95575'

  This is the "RSA Data Security, Inc. MD5 Message-Digest Algorithm."

  See the note regarding the MD5 algorithm at the beginning this section.

• OLD_PASSWORD(str)

  OLD_PASSWORD() was added to MySQL when the implementation of PASSWORD() was changed to improve security. OLD_PASSWORD() returns the value of the old (pre-4.1) implementation of PASSWORD() as a binary string, and is intended to permit you to reset passwords for any pre-4.1 clients that need to connect to your version 5.1 MySQL server without locking them out.

• PASSWORD(str)

  Calculates and returns a password string from the plaintext password str and returns a binary string, or 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.

  (sql sqlHandle {SELECT PASSWORD('badpwd')}) Returns '*AAB3E285149C0135D51A520E1940DD3263DC008C'

  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, consider MD5() or SHA1() instead. Also see RFC 2195, section 2 (Challenge-Response Authentication Mechanism (CRAM)), for more information about handling passwords and authentication securely in your applications.

• SHA1(str), SHA(str)

  Calculates an SHA-1 160-bit checksum for the string, as described in RFC 3174 (Secure Hash Algorithm). The value is returned as a binary string of 40 hex digits, or 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 cryptographic function for storing passwords. SHA() is synonymous with SHA1().

  (sql sqlHandle {SELECT SHA1('abc')}) Returns 'a9993e364706816aba3e25717850c26c9cd0d89d'

  SHA1() can be considered a cryptographically more secure equivalent of MD5(). However, see the note regarding the MD5 and SHA-1 algorithms at the beginning this section.

• UNCOMPRESS(string_to_uncompress)

  Uncompresses a string compressed by the COMPRESS() function. If the argument is not a compressed value, the result is NULL. This function requires MySQL to have been compiled with a compression library such as zlib. Otherwise, the return value is always NULL.

  (sql sqlHandle {SELECT UNCOMPRESS(COMPRESS('any string'))}) Returns 'any string'

  (sql sqlHandle {SELECT UNCOMPRESS('any string')}) Returns NULL

• UNCOMPRESSED_LENGTH(compressed_string)

  Returns the length that the compressed string had before being compressed.

  (sql sqlHandle {SELECT UNCOMPRESSED_LENGTH(COMPRESS(REPEAT('a',30)))}) Returns 30

Information Functions

• BENCHMARK(count,expr)

  The BENCHMARK() function executes the expression expr repeatedly count times. It may be used to time how quickly MySQL processes the expression. The result value is always 0. The intended use is from within the mysql client, which reports query execution times:

  (sql sqlHandle {SELECT BENCHMARK(1000000,ENCODE('hello','goodbye'))}) Returns
  +----------------------------------------------+
  | BENCHMARK(1000000,ENCODE('hello','goodbye')) |
  +----------------------------------------------+
  |                                            0 |
  +----------------------------------------------+

  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.

  BENCHMARK() is intended for measuring the runtime performance of scalar expressions, which has some significant implications for the way that you use it and interpret the results:

  Only scalar expressions can be used. Although the expression can be a subquery, it must return a single column and at most a single row. For example, BENCHMARK(10, (SELECT * FROM t)) will fail if the table t has more than one column or more than one row.

  Executing a SELECT expr statement N times differs from executing SELECT BENCHMARK(N, expr) in terms of the amount of overhead involved. The two have very different execution profiles and you should not expect them to take the same amount of time. The former involves the parser, optimizer, table locking, and runtime evaluation N times each. The latter involves only runtime evaluation N times, and all the other components just once. Memory structures already allocated are reused, and runtime optimizations such as local caching of results already evaluated for aggregate functions can alter the results. Use of BENCHMARK() thus measures performance of the runtime component by giving more weight to that component and removing the "noise" introduced by the network, parser, optimizer, and so forth.

• CHARSET(str)

  Returns the character set of the string argument.

  (sql sqlHandle {SELECT CHARSET('abc')}) Returns 'latin1'

  (sql sqlHandle {SELECT CHARSET(CONVERT('abc' USING utf8))}) Returns 'utf8'

  (sql sqlHandle {SELECT CHARSET(USER())}) Returns 'utf8'

• COERCIBILITY(str)

  Returns the collation coercibility value of the string argument.

  (sql sqlHandle {SELECT COERCIBILITY('abc' COLLATE latin1_swedish_ci)}) Returns 0

  (sql sqlHandle {SELECT COERCIBILITY(USER())}) Returns 3

  (sql sqlHandle {SELECT COERCIBILITY('abc')}) Returns 4

  The return values have the meanings shown in the following table. Lower values have higher precedence.

  Coercibility	Meaning	Example
  0	Explicit collation	Value with COLLATE clause
  1	No collation	Concatenation of strings with different collations
  2	Implicit collation	Column value, stored routine parameter or local variable
  3	System constant	USER() return value
  4	Coercible	Literal string
  5	Ignorable	NULL or an expression derived from NULL

• COLLATION(str)

  Returns the collation of the string argument.

  (sql sqlHandle {SELECT COLLATION('abc')}) Returns 'latin1_swedish_ci'

  (sql sqlHandle {SELECT COLLATION(_utf8'abc')}) Returns 'utf8_general_ci'

• CONNECTION_ID()

  Returns the connection ID (thread ID) for the connection. Every connection has an ID that is unique among the set of currently connected clients.

  (sql sqlHandle {SELECT CONNECTION_ID()}) Returns 23786

• CURRENT_USER, CURRENT_USER()

  Returns the username and hostname combination for the MySQL account that the server used to authenticate the current client. This account determines your access privileges. Within a stored routine that is defined with the SQL SECURITY DEFINER characteristic, CURRENT_USER() returns the creator of the routine. The return value is a string in the utf8 character set.

  The value of CURRENT_USER() can differ from the value of USER().

  (sql sqlHandle {SELECT USER()}) Returns 'davida@localhost'

  (sql sqlHandle {SELECT * FROM mysql.user}) Returns ERROR 1044: Access denied for user ''@'localhost' to database 'mysql'

  (sql sqlHandle {SELECT CURRENT_USER()}) Returns '@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.

• DATABASE()

  Returns the default (current) database name as a string in the utf8 character set. If there is no default database, DATABASE() returns NULL. Within a stored routine, the default database is the database that the routine is associated with, which is not necessarily the same as the database that is the default in the calling context.

  (sql sqlHandle {SELECT DATABASE()}) Returns 'test'

  If there is no default database, DATABASE() returns NULL.

• FOUND_ROWS()

  A 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 obtain this row count, include a SQL_CALC_FOUND_ROWS option in the SELECT statement, and then invoke FOUND_ROWS() afterward:

  (sql sqlHandle {SELECT SQL_CALC_FOUND_ROWS * FROM tbl_name WHERE id > 100 LIMIT 10})

  (sql sqlHandle {SELECT FOUND_ROWS()})

  The second SELECT returns a number indicating how many rows the first SELECT would have returned had it been written without the LIMIT clause.

  In the absence of the SQL_CALC_FOUND_ROWS option in the most recent successful SELECT statement, FOUND_ROWS() returns the number of rows in the result set returned by that statement.

  The row count available through FOUND_ROWS() is transient and not intended to be available past the statement following the SELECT SQL_CALC_FOUND_ROWS statement. If you need to refer to the value later, save it:

  (sql sqlHandle {SELECT SQL_CALC_FOUND_ROWS * FROM ... })

  (sql sqlHandle {SET @rows = FOUND_ROWS()})

  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 statements 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:

  The SQL_CALC_FOUND_ROWS keyword must appear in the first SELECT of the UNION.

  The value of 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.

  If no 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.

  Beyond the cases described here, the behavior of FOUND_ROWS() is undefined (for example, its value following a SELECT statement that fails with an error).

  Important: FOUND_ROWS() is not replicated reliably using statement-based replication. Starting with MySQL 5.1.23, this function is automatically replicated using row-based replication.

• LAST_INSERT_ID(), LAST_INSERT_ID(expr)

  For MySQL 5.1.12 and later, LAST_INSERT_ID() (no arguments) returns the first automatically generated value successfully inserted for an AUTO_INCREMENT column as a result of the most recently executed INSERT statement. The value of LAST_INSERT_ID() remains unchanged if no rows are successfully inserted.

  For example, after inserting a row that generates an AUTO_INCREMENT value, you can get the value like this:

  (sql sqlHandle {SELECT LAST_INSERT_ID()}) Returns 195

  In MySQL 5.1.11 and earlier, LAST_INSERT_ID() (no arguments) returns the first automatically generated value if any rows were successfully inserted or updated. This means that the returned value could be a value that was not successfully inserted into the table. If no rows were successfully inserted, LAST_INSERT_ID() returns 0.

  The value of LAST_INSERT_ID() will be consistent across all versions if all rows in the INSERT or UPDATE statement were successful.

  if a table contains an AUTO_INCREMENT column and INSERT ... ON DUPLICATE KEY UPDATE updates (rather than inserts) a row, the value of LAST_INSERT_ID() is not meaningful prior to MySQL 5.1.12.

  The currently executing statement does not affect the value of LAST_INSERT_ID(). Suppose that you generate an AUTO_INCREMENT value with one statement, and then refer to LAST_INSERT_ID() in a multiple-row INSERT statement that inserts rows into a table with its own AUTO_INCREMENT column. The value of LAST_INSERT_ID() will remain stable in the second statement; its value for the second and later rows is not affected by the earlier row insertions. (However, if you mix references to LAST_INSERT_ID() and LAST_INSERT_ID(expr), the effect is undefined.)

  If the previous statement returned an error, the value of LAST_INSERT_ID() is undefined. For transactional tables, if the statement is rolled back due to an error, the value of LAST_INSERT_ID() is left undefined. For manual ROLLBACK, the value of LAST_INSERT_ID() is not restored to that before the transaction; it remains as it was at the point of the ROLLBACK.

  Within the body of a stored routine (procedure or function) or a trigger, the value of LAST_INSERT_ID() changes the same way as for statements executed outside the body of these kinds of objects. The effect of a stored routine or trigger upon the value of LAST_INSERT_ID() that is seen by following statements depends on the kind of routine:

  If a stored procedure executes statements that change the value of LAST_INSERT_ID(), the changed value will be seen by statements that follow the procedure call.

  For stored functions and triggers that change the value, the value is restored when the function or trigger ends, so following statements will not see a changed value.

  The ID that was generated is maintained in the server on a per-connection basis. This means that the value returned by the function to a given client is the first AUTO_INCREMENT value generated for most recent statement affecting an AUTO_INCREMENT column by that client. This value cannot be affected by other clients, even if they generate AUTO_INCREMENT values of their own. This behavior ensures that each client can retrieve its 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 set the AUTO_INCREMENT column of a row to a non-"magic" value (that is, a value that is not NULL and not 0).

  Important: If you insert multiple rows using a single INSERT statement, LAST_INSERT_ID() returns the value generated for the first inserted row only. The reason for this is to make it possible to reproduce easily the same INSERT statement against some other server.

  For example:

  (sql sqlHandle {USE test})

  (sql sqlHandle {CREATE TABLE t (id INT AUTO_INCREMENT NOT NULL PRIMARY KEY, name VARCHAR(10) NOT NULL)})

  (sql sqlHandle {INSERT INTO t VALUES (NULL, 'Bob')})

  (sql sqlHandle {SELECT * FROM t}) Returns
  +----+------+
  | id | name |
  +----+------+
  |  1 | Bob  |
  +----+------+

  (sql sqlHandle {SELECT LAST_INSERT_ID()}) Returns
  +------------------+
  | LAST_INSERT_ID() |
  +------------------+
  |                1 |
  +------------------+

  (sql sqlHandle {INSERT INTO t VALUES (NULL, 'Mary'), (NULL, 'Jane'), (NULL, 'Lisa')})

  (sql sqlHandle {SELECT * FROM t}) Returns
  +----+------+
  | id | name |
  +----+------+
  |  1 | Bob  |
  |  2 | Mary |
  |  3 | Jane |
  |  4 | Lisa |
  +----+------+

  (sql sqlHandle {SELECT LAST_INSERT_ID()}) Returns
  +------------------+
  | LAST_INSERT_ID() |
  +------------------+
  |                2 |
  +------------------+

  Although the second INSERT statement inserted three new rows into t, the ID generated for the first of these rows was 2, and it is this value that is returned by LAST_INSERT_ID() for the following SELECT statement.

  If you use INSERT IGNORE and the row is ignored, the AUTO_INCREMENT counter is not incremented and LAST_INSERT_ID() returns 0, which reflects that no row was inserted.

  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:

  Create a table to hold the sequence counter and initialize it:

  (sql sqlHandle {CREATE TABLE sequence (id INT NOT NULL)})

  (sql sqlHandle {INSERT INTO sequence VALUES (0)})

  Use the table to generate sequence numbers like this:

  (sql sqlHandle {UPDATE sequence SET id=LAST_INSERT_ID(id+1)})

  (sql sqlHandle {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.

  You can generate sequences without calling 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.

  (sql sqlHandle {INSERT INTO t VALUES(1),(2),(3)})

  (sql sqlHandle {SELECT ROW_COUNT()}) Returns
  +-------------+
  | ROW_COUNT() |
  +-------------+
  |           3 |
  +-------------+

  (sql sqlHandle {DELETE FROM t WHERE i IN(1,2)})

  (sql sqlHandle {SELECT ROW_COUNT()}) Returns
  +-------------+
  | ROW_COUNT() |
  +-------------+
  |           2 |
  +-------------+

  Important: ROW_COUNT() is not replicated reliably using statement-based replication. Beginning with MySQL 5.1.23, this function is automatically replicated using row-based replication.

• SCHEMA()

  This function is a synonym for DATABASE().

• SESSION_USER()

  SESSION_USER() is a synonym for USER().

• SYSTEM_USER()

  SYSTEM_USER() is a synonym for USER().

• USER()

  Returns the current MySQL username and hostname as a string in the utf8 character set.

  (sql sqlHandle {SELECT USER()}) Returns '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 from that of CURRENT_USER().

  You can extract only the username part like this:

  (sql sqlHandle {SELECT SUBSTRING_INDEX(USER(),'@',1)}) Returns 'davida'

• VERSION()

  Returns a string that indicates the MySQL server version. The string uses the utf8 character set.

  (sql sqlHandle {SELECT VERSION()}) Returns '5.1.30-standard'

  Note that if your version string ends with -log this means that logging is enabled.

Miscellaneous Functions

• DEFAULT(col_name)

  Returns the default value for a table column. An error results if the column has no default value.

  (sql sqlHandle {UPDATE t SET i = DEFAULT(i)+1 WHERE id < 100})

• FORMAT(X,D)

  Formats the number X to a format like '#,###,###.##', rounded to D decimal places, and returns the result as a string.

• GET_LOCK(str,timeout)

  Tries to obtain a lock with a name given by the string str, using a timeout of timeout seconds. Returns 1 if the lock was obtained successfully, 0 if the attempt timed out (for example, because another client has previously 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). Locks obtained with GET_LOCK() do not interact with transactions. That is, committing a transaction does not release any such locks obtained during the transaction.

  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. But be aware that it also allows a client that is not among the set of cooperating clients to lock a name, either inadvertently or deliberately, and thus prevent any of the cooperating clients from locking that name. One way to reduce the likelihood of this is to use lock names that are database-specific or application-specific. For example, use lock names of the form db_name.str or app_name.str.

  (sql sqlHandle {SELECT GET_LOCK('lock1',10)}) Returns 1

  (sql sqlHandle {SELECT IS_FREE_LOCK('lock2')}) Returns 1

  (sql sqlHandle {SELECT GET_LOCK('lock2',10)}) Returns 1

  (sql sqlHandle {SELECT RELEASE_LOCK('lock2')}) Returns 1

  (sql sqlHandle {SELECT RELEASE_LOCK('lock1')}) Returns NULL

  The second RELEASE_LOCK() call returns NULL because the lock 'lock1' was automatically released by the second GET_LOCK() call.

  Note: If a client attempts to acquire a lock that is already held by another client, it blocks according to the timeout argument. If the blocked client terminates, its thread does not die until the lock request times out. This is a known bug (fixed in MySQL 6.0).

• INET_ATON(expr)

  Given the dotted-quad representation of a network address as a string, returns an integer that represents the numeric value of the address. Addresses may be 4- or 8-byte addresses.

  (sql sqlHandle {SELECT INET_ATON('209.207.224.40')}) Returns 3520061480

  The generated number is always in network byte order. For the example just shown, the number is calculated as 209×2563 + 207×2562 + 224×256 + 40.

  INET_ATON() also understands short-form IP addresses:

  (sql sqlHandle {SELECT INET_ATON('127.0.0.1'), INET_ATON('127.1')}) Returns 2130706433, 2130706433

  Note: When storing values generated by INET_ATON(), it is recommended that you use an INT UNSIGNED column. If you use a (signed) INT column, values corresponding to IP addresses for which the first octet is greater than 127 cannot be stored correctly.

• INET_NTOA(expr)

  Given a numeric network address (4 or 8 byte), returns the dotted-quad representation of the address as a string.

  (sql sqlHandle {SELECT INET_NTOA(3520061480)}) Returns '209.207.224.40'

• IS_FREE_LOCK(str)

  Checks whether the lock named str is free to use (that is, not locked). Returns 1 if the lock is free (no one is using the lock), 0 if the lock is in use, and NULL if an error occurs (such as an incorrect argument).

• IS_USED_LOCK(str)

  Checks whether the lock named str is in use (that is, locked). If so, it returns the connection identifier of the client that holds the lock. Otherwise, it returns NULL.

• MASTER_POS_WAIT(log_name,log_pos[,timeout])

  This function is useful for control of master/slave synchronization. It blocks until the slave has read and applied all updates up to the specified position in the master log. The return value is the number of log events the slave had to wait for to advance to the specified position. The function returns 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 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.

• NAME_CONST(name,value)

  Returns the given value. When used to produce a result set column, NAME_CONST() causes the column to have the given name. The arguments should be constants.

  (sql sqlHandle {SELECT NAME_CONST('myname', 14)}) Returns
  +--------+
  | myname |
  +--------+
  |     14 |
  +--------+

  This function was added in MySQL 5.0.12. It is for internal use only. The server uses it when writing statements from stored routines that contain references to local routine variables, You might see this function in the output from mysqlbinlog.

• RELEASE_LOCK(str)

  Releases the lock named by the string str that was obtained with GET_LOCK(). Returns 1 if the lock was released, 0 if the lock was not established by this thread (in which case the lock is not released), and NULL if the named lock did not exist. The lock does not exist if it was never obtained by a call to GET_LOCK() or if it has previously been released.

  The DO statement is convenient to use with RELEASE_LOCK().

• SLEEP(duration)

  Sleeps (pauses) for the number of seconds given by the duration argument, then returns 0. If SLEEP() is interrupted, it returns 1. The duration may have a fractional part given in microseconds.

• UUID()

  Returns a Universal Unique Identifier (UUID) generated according to "DCE 1.1: Remote Procedure Call" (Appendix A) CAE (Common Applications Environment) Specifications published by The Open Group in October 1997 (Document Number C706, http://www.opengroup.org/public/pubs/catalog/c706.htm).

  A UUID is designed as a number that is globally unique in space and time. Two calls to 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 utf8 string of five hexadecimal numbers in aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee format:

  The first three numbers are generated from a timestamp.

  The fourth number preserves temporal uniqueness in case the timestamp value loses monotonicity (for example, due to daylight saving time).

  The fifth number is an IEEE 802 node number that provides spatial uniqueness. A random number is substituted if the latter is not available (for example, because the host computer has no Ethernet card, or we do not know how to find the hardware address of an interface on your operating system). In this case, spatial uniqueness cannot be guaranteed. Nevertheless, a collision should have very low probability.

  Currently, the MAC address of an interface is taken into account only on FreeBSD and Linux. On other operating systems, MySQL uses a randomly generated 48-bit number.

  (sql sqlHandle {SELECT UUID()}) Returns '6ccd780c-baba-1026-9564-0040f4311e29'

  Warning: The UUID() function returns a string using the character set defined by the character_set_server parameter. If you are using UUID values in your tables and these columns are indexed the character set of your column or table should match the character set used when the UUID() was called. If you do not use the same character set for the column and the UUID value, then the indexes on those columns will not be used, which may lead to a reduction in performance and locked tables during operations as the table is searched sequentially for the value.

  You can convert between different character sets when using UUID-based strings using the CONVERT() function.

  Note: UUID() does not work with statement-based replication.

• UUID_SHORT()

  Returns a "short" universal identifier as a 64-bit unsigned integer (rather than a string-form 128-bit identifier as returned by the UUID() function).

  The value of UUID_SHORT() is guaranteed to be unique if the following conditions hold:

  The server_id of the current host is unique among your set of master and slave servers

  server_id is between 0 and 255

  You don't set back your system time for your server between mysqld restarts

  You do not invoke UUID_SHORT() on average more than 16 million times per second between mysqld restarts

  The UUID_SHORT() return value is constructed this way:

  (server_id & 255) << 56 + (server_startup_time_in_seconds << 24) + incremented_variable++;

  (sql sqlHandle {SELECT UUID_SHORT()}) Returns 92395783831158784

  Note that UUID_SHORT() does not work with statement-based replication.

  This function was added in MySQL 5.1.20.

• VALUES(col_name)

  In an INSERT ... ON DUPLICATE KEY UPDATE statement, you can use the VALUES(col_name) function in the UPDATE clause to refer to column values from the INSERT portion of the statement. In other words, VALUES(col_name) in the UPDATE clause refers to the value of col_name that would be inserted, had no duplicate-key conflict occurred. This function is especially useful in multiple-row inserts. The VALUES() function is meaningful only in INSERT ... ON DUPLICATE KEY UPDATE statements and returns NULL otherwise.

  (sql sqlHandle {INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6) ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b)})

GROUP BY (Aggregate) Functions

This section describes group (aggregate) functions that operate on sets of values. Unless otherwise stated, group functions ignore NULL values.

If you use a group function in a statement containing no GROUP BY clause, it is equivalent to grouping on all rows.

For numeric arguments, the variance and standard deviation functions return a DOUBLE value. The SUM() and AVG() functions return a DECIMAL value for exact-value arguments (integer or DECIMAL), and a DOUBLE value for approximate-value arguments (FLOAT or DOUBLE).

The SUM() and AVG() aggregate functions do not work with temporal values. (They convert the values to numbers, losing everything after the first non-numeric character.) To work around this problem, you can convert to numeric units, perform the aggregate operation, and convert back to a temporal value. Examples:

SELECT SEC_TO_TIME(SUM(TIME_TO_SEC(time_col))) FROM tbl_name

SELECT FROM_DAYS(SUM(TO_DAYS(date_col))) FROM tbl_name

Functions such as SUM() or AVG() that expect a numeric argument cast the argument to a number if necessary. For SET or ENUM values, the cast operation causes the underlying numeric value to be used.

• AVG([DISTINCT] expr)

  Returns the average value of expr. The DISTINCT option can be used to return the average of the distinct values of expr.

  AVG() returns NULL if there were no matching rows.

  (sql sqlHandle {SELECT student_name, AVG(test_score) FROM student GROUP BY student_name})

• BIT_AND(expr)

  Returns the bitwise AND of all bits in expr. The calculation is performed with 64-bit (BIGINT) precision.

  This function returns 18446744073709551615 if there were no matching rows. (This is the value of an unsigned BIGINT value with all bits set to 1.)

• BIT_OR(expr)

  Returns the bitwise 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)

  Returns the bitwise 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.

• COUNT(expr)

  Returns a count of the number of non-NULL values of expr in the rows retrieved by a SELECT statement. The result is a BIGINT value.

  COUNT() returns 0 if there were no matching rows.

  (sql sqlHandle {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:

  (sql sqlHandle {SELECT COUNT(*) FROM student})

  This optimization applies only to MyISAM tables only, because an exact row count is stored for this storage engine and can be accessed very quickly. For transactional storage engines such as InnoDB, 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...])

  Returns a count of the number of different non-NULL values.

  COUNT(DISTINCT) returns 0 if there were no matching rows.

  (sql sqlHandle {SELECT COUNT(DISTINCT results) FROM student})

  In MySQL, you can obtain the number of distinct expression combinations that do not contain NULL by giving a list of expressions. In standard SQL, you would have to do a concatenation of all expressions inside COUNT(DISTINCT ...).

• GROUP_CONCAT(expr)

  This function returns a string result with the concatenated non-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])

  (sql sqlHandle {SELECT student_name, GROUP_CONCAT(test_score) FROM student GROUP BY student_name})

  Or:

  (sql sqlHandle {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 eliminate the separator altogether by specifying SEPARATOR ''.

  The result is truncated to the maximum length that is given by the group_concat_max_len system variable, which has a default value of 1024. The value can be set higher, although the effective maximum length of the return value is constrained by the value of max_allowed_packet. The syntax to change the value of group_concat_max_len at runtime is as follows, where val is an unsigned integer:

  SET [SESSION | GLOBAL] group_concat_max_len = val;

  The type returned by GROUP_CONCAT() is always VARCHAR unless group_concat_max_len is greater than 512, in which case, it returns a BLOB.

• MAX([DISTINCT] expr)

  Returns the maximum value of expr. MAX() may take a string argument; in such cases, it returns the maximum string value. The DISTINCT keyword can be used to find the maximum of the distinct values of expr, however, this produces the same result as omitting DISTINCT.

  MAX() returns NULL if there were no matching rows.

  (sql sqlHandle {SELECT student_name, MIN(test_score), MAX(test_score) FROM student GROUP BY student_name})

  For MAX(), 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 is expected to be rectified in a future MySQL release.

• MIN([DISTINCT] expr)

  Returns the minimum value of expr. MIN() may take a string argument; in such cases, it returns the minimum string value. The DISTINCT keyword can be used to find the minimum of the distinct values of expr, however, this produces the same result as omitting DISTINCT.

  MIN() returns NULL if there were no matching rows.

  (sql sqlHandle {SELECT student_name, MIN(test_score), MAX(test_score) FROM student GROUP BY student_name})

  For MIN(), 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 is expected to be rectified in a future MySQL release.

• STD(expr)

  Returns the population standard deviation of expr. This is an extension to standard SQL. The standard SQL function STDDEV_POP() can be used instead.

  This function returns NULL if there were no matching rows.

• STDDEV(expr)

  Returns the population standard deviation of expr. This function is provided for compatibility with Oracle. The standard SQL function STDDEV_POP() can be used instead.

  This function returns NULL if there were no matching rows.

• STDDEV_POP(expr)

  Returns the population standard deviation of expr (the square root of VAR_POP()). You can also use STD() or STDDEV(), which are equivalent but not standard SQL.

  STDDEV_POP() returns NULL if there were no matching rows.

• STDDEV_SAMP(expr)

  Returns the sample standard deviation of expr (the square root of VAR_SAMP().

  STDDEV_SAMP() returns NULL if there were no matching rows.

• SUM([DISTINCT] expr)

  Returns the sum of expr. If the return set has no rows, SUM() returns NULL. The DISTINCT keyword can be used in MySQL 5.1 to sum only the distinct values of expr.

  SUM() returns NULL if there were no matching rows.

• VAR_POP(expr)

  Returns the population standard variance of expr. It considers rows as the whole population, not as a sample, so it has the number of rows as the denominator. You can also use VARIANCE(), which is equivalent but is not standard SQL.

  VAR_POP() returns NULL if there were no matching rows.

• VAR_SAMP(expr)

  Returns the sample variance of expr. That is, the denominator is the number of rows minus one.

  VAR_SAMP() returns NULL if there were no matching rows.

• VARIANCE(expr)

  Returns the population standard variance of expr. This is an extension to standard SQL. The standard SQL function VAR_POP() can be used instead.

  VARIANCE() returns NULL if there were no matching rows.

GROUP BY Modifiers

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.

Suppose that a table named sales has year, country, product, and profit columns for recording sales profitability:

(sql sqlHandle {
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:

(sql sqlHandle {SELECT year, SUM(profit) FROM sales GROUP BY year}) Returns
+------+-------------+
| 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:

(sql sqlHandle {SELECT year, SUM(profit) FROM sales GROUP BY year WITH ROLLUP}) Returns
+------+-------------+
| 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:

(sql sqlHandle {SELECT year, country, product, SUM(profit) FROM sales GROUP BY year, country, product}) Returns
+------+---------+------------+-------------+
| 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:

(sql sqlHandle {SELECT year, country, product, SUM(profit) FROM sales GROUP BY year, country, product WITH ROLLUP}) Returns
+------+---------+------------+-------------+
| 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:

• Following each set of product rows for a given year and country, an extra summary row is produced showing the total for all products. These rows have the product column set to NULL.

• Following each set of rows for a given year, an extra summary row is produced showing the total for all countries and products. These rows have the country and products columns set to NULL.

• Finally, following all other rows, an extra summary row is produced showing the grand total for all years, countries, and products. This row has the 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:

(sql sqlHandle {SELECT year, country, product, SUM(profit) FROM sales GROUP BY year, country, product WITH ROLLUP LIMIT 5}) Returns
+------+---------+------------+-------------+
| 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 and HAVING with Hidden Fields

MySQL extends the use of GROUP BY so that you can use non-aggregated columns or calculations in the SELECT list that do not appear in the GROUP BY clause. You can use this feature to get better performance by avoiding unnecessary column sorting and grouping. For example, you do not need to group on customer.name in the following query:

(sql sqlHandle {
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.

Do not use this feature if the columns you omit from the GROUP BY part are not constant in the group. The server is free to return any value from the group, so the results are indeterminate unless all values are the same.

A similar MySQL extension applies to the HAVING clause. The SQL standard does not allow the HAVING clause to name any column that is not found in the GROUP BY clause if it is not enclosed in an aggregate function. MySQL allows the use of such columns to simplify calculations. This extension assumes that the non-grouped columns will have the same group-wise values. Otherwise, the result is indeterminate.

If the ONLY_FULL_GROUP_BY SQL mode is enabled, the MySQL extension to GROUP BY does not apply. That is, columns not named in the GROUP BY clause cannot be used in the SELECT list or HAVING clause if not used in an aggregate function.

The select list extension also applies to ORDER BY. That is, you can use non-aggregated columns or calculations in the ORDER BY clause that do not appear in the GROUP BY clause. This extension does not apply if the ONLY_FULL_GROUP_BY SQL mode is enabled.

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:

(sql sqlHandle {SUBSTR(MIN(CONCAT(RPAD(sort,6,' '),column)),7)})

Note that if you are trying to follow standard SQL, you can't use expressions in GROUP BY clauses. You can work around this limitation by using an alias for the expression:

(sql sqlHandle {
SELECT id,FLOOR(value/100) AS val
  FROM tbl_name
  GROUP BY id, val})

MySQL does allow expressions in GROUP BY clauses. For example:

(sql sqlHandle {
SELECT id,FLOOR(value/100)
  FROM tbl_name
  GROUP BY id, FLOOR(value/100)})