Chapter 11. Functions and Operators
Prev |  | Next

## Chapter 11. Functions and Operators

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, user-defined functions, and operators. This chapter describes the functions and operators that are allowed for writing expressions in MySQL. Instructions for writing user-defined functions are given in Section 19.2, “Adding New Functions to MySQL”. See Section 8.2.3, “Function Name Parsing and Resolution”, for the rules describing how the server interprets references to different kinds of functions.

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. (See Section 5.1.6, “SQL Modes”.) 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:

    mysql> SELECT MOD(29,9);
    +-----------+
    | mod(29,9) |
    +-----------+
    |         2 |
    +-----------+
    1 rows in set (0.00 sec)

This format is used instead:

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

## 11.1. Operator and Function Reference

### Note

This table is part of an ongoing process to expand and simplify the information provided on these elements. Further improvements to the table, and corresponding descriptions will be applied over the coming months.

Name | Description
--- | ---
`ABS()` | Return the absolute value
`ACOS()` | Return the arc cosine
`ADDDATE()`(v4.1.1) | Add dates
`ADDTIME()`(v4.1.1) | Add time
`AES_DECRYPT()` | Decrypt using AES
`AES_ENCRYPT()` | Encrypt using AES
`AND`, `&&` | Logical AND
`ASCII()` | Return numeric value of left-most character
`ASIN()` | Return the arc sine
`ATAN2()`, `ATAN()` | Return the arc tangent of the two arguments
`ATAN()` | Return the arc tangent
`AVG()` | Return the average value of the argument
`BENCHMARK()` | Repeatedly execute an expression
`BETWEEN ... AND ...` | Check whether a value is within a range of values
`BIN()` | Return a string representation of the argument
`BINARY` | Cast a string to a binary string
`BIT_AND()` | Return bitwise and
`BIT_COUNT()` | Return the number of bits that are set
`BIT_LENGTH()` | Return length of argument in bits
`BIT_OR()` | Return bitwise or
`BIT_XOR()`(v4.1.1) | Return bitwise xor
`&` | Bitwise AND
`~` | Invert bits
`|` | Bitwise OR
`^` | Bitwise XOR
`CASE` | Case operator
`CAST()` | Cast a value as a certain type
`CEIL()` | Return the smallest integer value not less than the argument
`CEILING()` | Return the smallest integer value not less than the argument
`CHAR_LENGTH()` | Return number of characters in argument
`CHAR()` | Return the character for each integer passed
`CHARACTER_LENGTH()` | A synonym for CHAR_LENGTH()
`CHARSET()`(v4.1.0) | Return the character set of the argument
`COALESCE()` | Return the first non-NULL argument
`COERCIBILITY()`(v4.1.1) | Return the collation coercibility value of the string argument
`COLLATION()`(v4.1.0) | Return the collation of the string argument
`COMPRESS()`(v4.1.1) | Return result as a binary string
`CONCAT_WS()` | Return concatenate with separator
`CONCAT()` | Return concatenated string
`CONNECTION_ID()` | Return the connection ID (thread ID) for the connection
`CONV()` | Convert numbers between different number bases
`CONVERT_TZ()`(v4.1.3) | Convert from one timezone to another
`Convert()` | Cast a value as a certain type
`COS()` | Return the cosine
`COT()` | Return the cotangent
`COUNT(DISTINCT)` | Return the count of a number of different values
`COUNT()` | Return a count of the number of rows returned
`CRC32()`(v4.1.0) | Compute a cyclic redundancy check value
`CURDATE()` | Return the current date
`CURRENT_DATE()`, `CURRENT_DATE` | Synonyms for CURDATE()
`CURRENT_TIME()`, `CURRENT_TIME` | Synonyms for CURTIME()
`CURRENT_TIMESTAMP()`, `CURRENT_TIMESTAMP` | Synonyms for NOW()
`CURRENT_USER()`, `CURRENT_USER` | Return the username and hostname combination
`CURTIME()` | Return the current time
`DATABASE()` | Return the default (current) database name
`DATE_ADD()` | Add two dates
`DATE_FORMAT()` | Format date as specified
`DATE_SUB()` | Subtract two dates
`DATE()`(v4.1.1) | Extract the date part of a date or datetime expression
`DATEDIFF()`(v4.1.1) | Subtract two dates
`DAY()`(v4.1.1) | Synonym for DAYOFMONTH()
`DAYNAME()`(v4.1.21) | Return the name of the weekday
`DAYOFMONTH()` | Return the day of the month (1-31)
`DAYOFWEEK()` | Return the weekday index of the argument
`DAYOFYEAR()` | Return the day of the year (1-366)
`DECODE()` | Decodes a string encrypted using ENCODE()
`DEFAULT()` | Return the default value for a table column
`DEGREES()` | Convert radians to degrees
`DES_DECRYPT()` | Decrypt a string
`DES_ENCRYPT()` | Decrypt a string
`DIV`(v4.1.0) | Integer division
`/` | Division operator
`ELT()` | Return string at index number
`ENCODE()` | Encode a string
`ENCRYPT()` | Encrypt a string
`<=>` | NULL-safe equal to operator
`=` | Equal operator
`EXP()` | Raise to the power of
`EXPORT_SET()` | Return a string such that for every bit set in the value bits, you get an on string and for every unset bit, you get an off string
`EXTRACT` | Extract part of a date
`FIELD()` | Return the index (position) of the first argument in the subsequent arguments
`FIND_IN_SET()` | Return the index position of the first argument within the second argument
`FLOOR()` | Return the largest integer value not greater than the argument
`FORMAT()` | Return a number formatted to specified number of decimal places
`FOUND_ROWS()` | For a SELECT with a LIMIT clause, the number of rows that would be returned were there no LIMIT clause
`FROM_DAYS()` | Convert a day number to a date
`FROM_UNIXTIME()` | Format date as a UNIX timestamp
`MOD()` | Return the remainder
`GET_FORMAT()`(v4.1.1) | Return a date format string
`GET_LOCK()` | Get a named lock
`>=` | Greater than or equal operator
`>` | Greater than operator
`GREATEST()` | Return the largest argument
`GROUP_CONCAT()`(v4.1) | Return a concatenated string
`HEX()` | Return a hexadecimal representation of a decimal or string value
`HOUR()` | Extract the hour
`IF()` | If/else construct
`IFNULL()` | Null if/else construct
`IN()` | Check whether a value is within a set of values
`INET_ATON()` | Return the numeric value of an IP address
`INET_NTOA()` | Return the IP address from a numeric value
`INSERT()` | Insert a substring at the specified position up to the specified number of characters
`INSTR()` | Return the index of the first occurrence of substring
`INTERVAL()` | Return the index of the argument that is less than the first argument
`IS_FREE_LOCK()` | Checks whether the named lock is free
`IS NOT NULL` | NOT NULL value test
`IS NULL` | NULL value test
`IS_USED_LOCK()`(v4.1.0) | Checks whether the named lock is in use. Return connection identifier if true.
`ISNULL()` | Test whether the argument is NULL
`LAST_DAY`(v4.1.1) | Return the last day of the month for the argument
`LAST_INSERT_ID()` | Value of the AUTOINCREMENT column for the last INSERT
`LCASE()` | Synonym for LOWER()
`LEAST()` | Return the smallest argument
`<<` | Left shift
`LEFT()` | Return the leftmost number of characters as specified
`LENGTH()` | Return the length of a string in bytes
`<=` | Less than or equal operator
`<` | Less than operator
`LIKE` | Simple pattern matching
`LN()` | Return the natural logarithm of the argument
`LOAD_FILE()` | Load the named file
`LOCALTIME()`, `LOCALTIME` | Synonym for NOW()
`LOCALTIMESTAMP`, `LOCALTIMESTAMP()`(v4.0.6) | Synonym for NOW()
`LOCATE()` | Return the position of the first occurrence of substring
`LOG10()` | Return the base-10 logarithm of the argument
`LOG2()` | Return the base-2 logarithm of the argument
`LOG()` | Return the natural logarithm of the first argument
`LOWER()` | Return the argument in lowercase
`LPAD()` | Return the string argument, left-padded with the specified string
`LTRIM()` | Remove leading spaces
`MAKE_SET()` | Return a set of comma-separated strings that have the corresponding bit in bits set
`MAKEDATE()`(v4.1.1) | Create a date from the year and day of year
`MAKETIME`(v4.1.1) | MAKETIME()
`MASTER_POS_WAIT()` | Block until the slave has read and applied all updates up to the specified position
`MATCH` | Perform full-text search
`MAX()` | Return the maximum value
`MD5()` | Calculate MD5 checksum
`MICROSECOND()`(v4.1.1) | Return the microseconds from argument
`MID()` | Return a substring starting from the specified position
`MIN()` | Return the minimum value
`-` | Minus operator
`MINUTE()` | Return the minute from the argument
`MONTH()` | Return the month from the date passed
`MONTHNAME()`(v4.1.21) | Return the name of the month
`NOT BETWEEN ... AND ...` | Check whether a value is not within a range of values
`!=`, `<>` | Not equal operator
`NOT IN()` | Check whether a value is not within a set of values
`NOT LIKE` | Negation of simple pattern matching
`NOT REGEXP` | Negation of REGEXP
`NOT`, `!` | Negates value
`NOW()` | Return the current date and time
`NULLIF()` | Return NULL if expr1 = expr2
`OCT()` | Return an octal representation of a decimal number
`OCTET_LENGTH()` | A synonym for LENGTH()
`OLD_PASSWORD()`(v4.1) | Return the value of the old (pre-4.1) implementation of PASSWORD
`%` | Modulo operator
`||`, `OR` | Logical OR
`ORD()` | If the leftmost character of the argument is a multi-byte character, returns the code for that character
`PASSWORD()` | Calculate and return a password string
`PERIOD_ADD()` | Add a period to a year-month
`PERIOD_DIFF()` | Return the number of months between periods
`PI()` | Return the value of pi
`+` | Addition operator
`POSITION()` | A synonym for LOCATE()
`POW()` | Return the argument raised to the specified power
`POWER()` | Return the argument raised to the specified power
`PROCEDURE ANALYSE()` | Analyze the results of a query
`QUARTER()` | Return the quarter from a date argument
`QUOTE()` | Escape the argument for use in an SQL statement
`RADIANS()` | Return argument converted to radians
`RAND()` | Return a random floating-point value
`REGEXP` | Pattern matching using regular expressions
`RELEASE_LOCK()` | Releases the named lock
`REPEAT()` | Repeat a string the specified number of times
`REPLACE()` | Replace occurrences of a specified string
`REVERSE()` | Reverse the characters in a string
`>>` | Right shift
`RIGHT()` | Return the specified rightmost number of characters
`RLIKE` | Synonym for REGEXP
`ROUND()` | Round the argument
`RPAD()` | Append string the specified number of times
`RTRIM()` | Remove trailing spaces
`SEC_TO_TIME()` | Converts seconds to 'HH:MM:SS' format
`SECOND()` | Return the second (0-59)
`SESSION_USER()` | Synonym for USER()
`SHA1()`, `SHA()` | Calculate an SHA-1 160-bit checksum
`SIGN()` | Return the sign of the argument
`SIN()` | Return the sine of the argument
`SOUNDEX()` | Return a soundex string
`SOUNDS LIKE`(v4.1.0) | Compare sounds
`SPACE()` | Return a string of the specified number of spaces
`SQRT()` | Return the square root of the argument
`STD()` | Return the population standard deviation
`STDDEV()` | Return the population standard deviation
`STR_TO_DATE()`(v4.1.1) | Convert a string to a date
`STRCMP()` | Compare two strings
`SUBDATE()` | When invoked with three arguments a synonym for DATE_SUB()
`SUBSTR()` | Return the substring as specified
`SUBSTRING_INDEX()` | Return a substring from a string before the specified number of occurrences of the delimiter
`SUBSTRING()` | Return the substring as specified
`SUBTIME()`(v4.1.1) | Subtract times
`SUM()` | Return the sum
`SYSDATE()` | Return the time at which the function executes
`SYSTEM_USER()` | Synonym for USER()
`TAN()` | Return the tangent of the argument
`TIME_FORMAT()` | Format as time
`TIME_TO_SEC()` | Return the argument converted to seconds
`TIME()`(v4.1.1) | Extract the time portion of the expression passed
`TIMEDIFF()`(v4.1.1) | Subtract time
`*` | Times operator
`TIMESTAMP()`(v4.1.1) | With a single argument, this function returns the date or datetime expression. With two arguments, the sum of the arguments
`TO_DAYS()` | Return the date argument converted to days
`TRIM()` | Remove leading and trailing spaces
`TRUNCATE()` | Truncate to specified number of decimal places
`UCASE()` | Synonym for UPPER()
`-` | Change the sign of the argument
`UNCOMPRESS()`(v4.1.1) | Uncompress a string compressed
`UNCOMPRESSED_LENGTH()`(v4.1.1) | Return the length of a string before compression
`UNHEX()`(v4.1.2) | Convert each pair of hexadecimal digits to a character
`UNIX_TIMESTAMP()` | Return a UNIX timestamp
`UPPER()` | Convert to uppercase
`USER()` | Return the current username and hostname
`UTC_DATE()`(v4.1.1) | Return the current UTC date
`UTC_TIME()`(v4.1.1) | Return the current UTC time
`UTC_TIMESTAMP()`(v4.1.1) | Return the current UTC date and time
`UUID()`(v4.1.2) | Return a Universal Unique Identifier (UUID)
`VALUES()`(v4.1.1) | Defines the values to be used during an INSERT
`VARIANCE()`(v4.1) | Return the population standard variance
`VERSION()` | Returns a string that indicates the MySQL server version
`WEEK()` | Return the week number
`WEEKDAY()` | Return the weekday index
`WEEKOFYEAR()`(v4.1.1) | Return the calendar week of the date (1-53)
`XOR` | Logical XOR
`YEAR()` | Return the year
`YEARWEEK()` | Return the year and week

## 11.2. Operators

Name | Description
--- | ---
`AND`, `&&` | Logical AND
`BETWEEN ... AND ...` | Check whether a value is within a range of values
`BINARY` | Cast a string to a binary string
`&` | Bitwise AND
`~` | Invert bits
`|` | Bitwise OR
`^` | Bitwise XOR
`CASE` | Case operator
`DIV`(v4.1.0) | Integer division
`/` | Division operator
`<=>` | NULL-safe equal to operator
`=` | Equal operator
`>=` | Greater than or equal operator
`>` | Greater than operator
`IS NOT NULL` | NOT NULL value test
`IS NULL` | NULL value test
`<<` | Left shift
`<=` | Less than or equal operator
`<` | Less than operator
`LIKE` | Simple pattern matching
`-` | Minus operator
`NOT BETWEEN ... AND ...` | Check whether a value is not within a range of values
`!=`, `<>` | Not equal operator
`NOT LIKE` | Negation of simple pattern matching
`NOT REGEXP` | Negation of REGEXP
`NOT`, `!` | Negates value
`%` | Modulo operator
`||`, `OR` | Logical OR
`+` | Addition operator
`REGEXP` | Pattern matching using regular expressions
`>>` | Right shift
`RLIKE` | Synonym for REGEXP
`SOUNDS LIKE`(v4.1.0) | Compare sounds
`*` | Times operator
`-` | Change the sign of the argument
`XOR` | Logical XOR

### 11.2.1. 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.

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

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

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:

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

### 11.2.2. 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.

    mysql> SELECT 1+'1';
            -> 2
    mysql> SELECT CONCAT(2,' test');
            -> '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, but is unavailable before MySQL 4.0.2):

    mysql> SELECT 38.8, CAST(38.8 AS CHAR);
            -> 38.8, '38.8'
    mysql> SELECT 38.8, CONCAT(38.8);
            -> 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:

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

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

    SELECT * FROM tbl_name WHERE str_col=1;

The reason for this is that there are many different strings that may convert to the value `1`, 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:

    mysql> SELECT '18015376320243458' = 18015376320243458;
            -> 1
    mysql> SELECT '18015376320243459' = 18015376320243459;
            -> 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:

    mysql> SELECT '18015376320243459'+0.0;
            -> 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:

    mysql> SELECT CAST('18015376320243459' AS UNSIGNED) = 18015376320243459;
            -> 1

For more information about floating-point comparisons, see Section A.1.5.8, “Problems with Floating-Point Comparisons”.

### 11.2.3. Comparison Functions and Operators

Name | Description
--- | ---
`BETWEEN ... AND ...` | Check whether a value is within a range of values
`COALESCE()` | Return the first non-NULL argument
`<=>` | NULL-safe equal to operator
`=` | Equal operator
`>=` | Greater than or equal operator
`>` | Greater than operator
`GREATEST()` | Return the largest argument
`IN()` | Check whether a value is within a set of values
`INTERVAL()` | Return the index of the argument that is less than the first argument
`IS NOT NULL` | NOT NULL value test
`IS NULL` | NULL value test
`ISNULL()` | Test whether the argument is NULL
`LEAST()` | Return the smallest argument
`<=` | Less than or equal operator
`<` | Less than operator
`LIKE` | Simple pattern matching
`NOT BETWEEN ... AND ...` | Check whether a value is not within a range of values
`!=`, `<>` | Not equal operator
`NOT IN()` | Check whether a value is not within a set of values
`NOT LIKE` | Negation of simple pattern matching
`SOUNDS LIKE`(v4.1.0) | Compare sounds

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

Some of the functions in this section (such as `LEAST()` and `GREATEST()`) return values other than `1` (`TRUE`), `0` (`FALSE`), or `NULL`. However, the value they return is based on comparison operations performed according to the rules described in Section 11.2.2, “Type Conversion in Expression Evaluation”.

To convert a value to a specific type for comparison purposes, you can use the `CAST()` function. String values can be converted to a different character set using `CONVERT()`. See Section 11.9, “Cast Functions and Operators”.

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:

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

- `<=>`

  `NULL`-safe equal. This operator performs an equality comparison like the `=` operator, but returns `1` rather than `NULL` if both operands are `NULL`, and `0` rather than `NULL` if one operand is `NULL`.

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

  `<=>` was added in MySQL 3.23.0.

- `<>`, `!=`

  Not equal:

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

- `<=`

  Less than or equal:

      mysql> SELECT 0.1 <= 2;
              -> 1

- `<`

  Less than:

      mysql> SELECT 2 < 2;
              -> 0

- `>=`

  Greater than or equal:

      mysql> SELECT 2 >= 2;
              -> 1

- `>`

  Greater than:

      mysql> SELECT 2 > 2;
              -> 0

- `IS NULL`

  Tests whether a value is `NULL`.

      mysql> SELECT 1 IS NULL, 0 IS NULL, NULL IS NULL;
              -> 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:

        SELECT * FROM tbl_name WHERE auto_col IS NULL

    This behavior can be disabled by setting `SQL_AUTO_IS_NULL=0`. See Section 12.5.3, “`SET` Syntax”.

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

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

      mysql> SELECT 1 IS NOT NULL, 0 IS NOT NULL, NULL IS NOT NULL;
              -> 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. Otherwise type conversion takes place according to the rules described in Section 11.2.2, “Type Conversion in Expression Evaluation”, but applied to all the three arguments.

  ### Note

  Before MySQL 4.0.5, arguments were converted to the type of `expr` instead.

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

  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.

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

  `COALESCE()` was added in MySQL 3.23.3.

- `GREATEST(`value1`,`value2`,...)`

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

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

  `GREATEST()` returns `NULL` only if all arguments are `NULL`.

  Before MySQL 3.22.5, you can use `MAX()` instead of `GREATEST()`.

- ``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. Otherwise, type conversion takes place according to the rules described in Section 11.2.2, “Type Conversion in Expression Evaluation”, but applied to all the arguments.

      mysql> SELECT 2 IN (0,3,5,7);
              -> 0
      mysql> SELECT 'wefwf' IN ('wee','wefwf','weg');
              -> 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:

      SELECT val1 FROM tbl1 WHERE val1 IN (1,2,'a');

  Instead, write it like this:

      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, from MySQL 4.1.0 on `IN` returns `NULL` not only if the expression on the left hand side is `NULL`, but also if no match is found in the list and one of the expressions in the list is `NULL`.

  From MySQL 4.1.0 on, `IN()` syntax can also be used to write certain types of subqueries. See Section 12.2.8.3, “Subqueries with `ANY`, `IN`, and `SOME`”.

- ``expr` NOT IN (`value`,...)`

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

- `ISNULL(`expr`)`

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

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

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

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

- `LEAST(`value1`,`value2`,...)`

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

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

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

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

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

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

  `LEAST()` returns `NULL` only if all arguments are `NULL`.

  Before MySQL 3.22.5, you can use `MIN()` instead of `LEAST()`.

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

      mysql> SELECT CAST(LEAST(3600, 9223372036854775808.0) as SIGNED);
              -> -9223372036854775808

  This happens because MySQL reads `9223372036854775808.0` in an integer context. The integer representation is not good enough to hold the value, so it wraps to a signed integer.

### 11.2.4. Logical Operators

Name | Description
--- | ---
`AND`, `&&` | Logical AND
`NOT`, `!` | Negates value
`||`, `OR` | Logical OR
`XOR` | Logical XOR

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`:

    mysql> SELECT 10 IS TRUE;
    -> 1
    mysql> SELECT -10 IS TRUE;
    -> 1
    mysql> SELECT 'string' IS NOT NULL;
    -> 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`.

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

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

- `AND`, `&&`

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

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

  Please note that MySQL versions prior to 4.0.5 stop evaluation when a `NULL` is encountered, rather than continuing the process to check for possible `0` values. This means that in these versions, `SELECT (NULL AND 0)` returns `NULL` instead of `0`. As of MySQL 4.0.5, the code has been re-engineered so that the result is always as prescribed by the SQL standards while still using the optimization wherever possible.

- `OR`, `||`

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

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

- `XOR`

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

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

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

  `XOR` was added in MySQL 4.0.2.

## 11.3. Control Flow Functions

Name | Description
--- | ---
`CASE` | Case operator
`IF()` | If/else construct
`IFNULL()` | Null if/else construct
`NULLIF()` | Return NULL if expr1 = expr2

- `CASE `value` WHEN [`compare_value`] THEN `result` [WHEN [`compare_value`] THEN `result` ...] [ELSE `result`] END`

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

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

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

  Before MySQL 4.1, the type of the return value (`INTEGER`, `DOUBLE`, or `STRING`) is the same as the type of the first returned value (the expression after the first `THEN`). From MySQL 4.1.0, the default return type is the compatible aggregated type of all return values.

  Note that `CASE` evaluation depends also on the context in which it is used. If used in string context, the result is returned as a string. If used in numeric context, the result is returned decimal, real, or integer value.

  `CASE` was added in MySQL 3.23.3.

- `IF(`expr1`,`expr2`,`expr3`)`

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

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

  If only one of `expr2` or `expr3` is explicitly `NULL`, the result type of the `IF()` function is the type of non-`NULL` expression. (This behavior was implemented in MySQL 4.0.3.)

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

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

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

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

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

  If `expr2` and `expr3` are both strings, the result is case sensitive if either string is case sensitive (starting from MySQL 3.23.51).

- `IFNULL(`expr1`,`expr2`)`

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

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

  In MySQL 4.0.6 and above, the default result value of `IFNULL(`expr1`,`expr2`)` is the more “general” of the two expressions, in the order `STRING`, `REAL`, or `INTEGER`. The difference from earlier MySQL versions is mostly notable when you create a table based on expressions or MySQL has to internally store a value from `IFNULL()` in a temporary table.

      mysql> CREATE TABLE tmp SELECT IFNULL(1,'test') AS test;
      mysql> DESCRIBE tmp;
      +-------+---------+------+-----+---------+-------+
      | Field | Type    | Null | Key | Default | Extra |
      +-------+---------+------+-----+---------+-------+
      | test  | char(4) |      |     |         |       |
      +-------+---------+------+-----+---------+-------+

  As of MySQL 4.0.6, the type for the `test` column is `CHAR(4)`, whereas in earlier versions the type would be `BIGINT`.

- `NULLIF(`expr1`,`expr2`)`

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

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

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

  `NULLIF()` was added in MySQL 3.23.15.

## 11.4. String Functions

Name | Description
--- | ---
`ASCII()` | Return numeric value of left-most character
`BIN()` | Return a string representation of the argument
`BIT_LENGTH()` | Return length of argument in bits
`CHAR_LENGTH()` | Return number of characters in argument
`CHAR()` | Return the character for each integer passed
`CHARACTER_LENGTH()` | A synonym for CHAR_LENGTH()
`CONCAT_WS()` | Return concatenate with separator
`CONCAT()` | Return concatenated string
`ELT()` | Return string at index number
`EXPORT_SET()` | Return a string such that for every bit set in the value bits, you get an on string and for every unset bit, you get an off string
`FIELD()` | Return the index (position) of the first argument in the subsequent arguments
`FIND_IN_SET()` | Return the index position of the first argument within the second argument
`FORMAT()` | Return a number formatted to specified number of decimal places
`HEX()` | Return a hexadecimal representation of a decimal or string value
`INSERT()` | Insert a substring at the specified position up to the specified number of characters
`INSTR()` | Return the index of the first occurrence of substring
`LCASE()` | Synonym for LOWER()
`LEFT()` | Return the leftmost number of characters as specified
`LENGTH()` | Return the length of a string in bytes
`LIKE` | Simple pattern matching
`LOAD_FILE()` | Load the named file
`LOCATE()` | Return the position of the first occurrence of substring
`LOWER()` | Return the argument in lowercase
`LPAD()` | Return the string argument, left-padded with the specified string
`LTRIM()` | Remove leading spaces
`MAKE_SET()` | Return a set of comma-separated strings that have the corresponding bit in bits set
`MATCH` | Perform full-text search
`MID()` | Return a substring starting from the specified position
`NOT LIKE` | Negation of simple pattern matching
`NOT REGEXP` | Negation of REGEXP
`OCTET_LENGTH()` | A synonym for LENGTH()
`ORD()` | If the leftmost character of the argument is a multi-byte character, returns the code for that character
`POSITION()` | A synonym for LOCATE()
`QUOTE()` | Escape the argument for use in an SQL statement
`REGEXP` | Pattern matching using regular expressions
`REPEAT()` | Repeat a string the specified number of times
`REPLACE()` | Replace occurrences of a specified string
`REVERSE()` | Reverse the characters in a string
`RIGHT()` | Return the specified rightmost number of characters
`RLIKE` | Synonym for REGEXP
`RPAD()` | Append string the specified number of times
`RTRIM()` | Remove trailing spaces
`SOUNDEX()` | Return a soundex string
`SOUNDS LIKE`(v4.1.0) | Compare sounds
`SPACE()` | Return a string of the specified number of spaces
`STRCMP()` | Compare two strings
`SUBSTR()` | Return the substring as specified
`SUBSTRING_INDEX()` | Return a substring from a string before the specified number of occurrences of the delimiter
`SUBSTRING()` | Return the substring as specified
`TRIM()` | Remove leading and trailing spaces
`UCASE()` | Synonym for UPPER()
`UNHEX()`(v4.1.2) | Convert each pair of hexadecimal digits to a character
`UPPER()` | Convert to uppercase

String-valued functions return `NULL` if the length of the result would be greater than the value of the `max_allowed_packet` system variable. See Section 7.5.2, “Tuning Server Parameters”.

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

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.

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

  See also the `ORD()` function.

- `BIN(`N`)`

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

      mysql> SELECT BIN(12);
              -> '1100'

- `BIT_LENGTH(`str`)`

  Returns the length of the string `str` in bits.

      mysql> SELECT BIT_LENGTH('text');
              -> 32

  `BIT_LENGTH()` was added in MySQL 4.0.2.

- `CHAR(`N`,... [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.

      mysql> SELECT CHAR(77,121,83,81,'76');
              -> 'MySQL'
      mysql> SELECT CHAR(77,77.3,'77.3');
              -> 'MMM'

  `CHAR()` returns a string in the connection character set. As of MySQL 4.1.16, the optional `USING` clause may be used to produce a string in a given character set:

      mysql> SELECT CHARSET(CHAR(0x65)), CHARSET(CHAR(0x65 USING utf8));
      +---------------------+--------------------------------+
      | CHARSET(CHAR(0x65)) | CHARSET(CHAR(0x65 USING utf8)) |
      +---------------------+--------------------------------+
      | latin1              | utf8                           |
      +---------------------+--------------------------------+

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

      mysql> SELECT CONCAT('My', 'S', 'QL');
              -> 'MySQL'
      mysql> SELECT CONCAT('My', NULL, 'QL');
              -> NULL
      mysql> SELECT CONCAT(14.3);
              -> '14.3'

- `CONCAT_WS(`separator`,`str1`,`str2`,...)`

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

      mysql> SELECT CONCAT_WS(',','First name','Second name','Last Name');
              -> 'First name,Second name,Last Name'
      mysql> SELECT CONCAT_WS(',','First name',NULL,'Last Name');
              -> 'First name,Last Name'

  `CONCAT_WS()` skips any `NULL` values after the separator argument. Before MySQL 4.0.14, `CONCAT_WS()` skips empty strings as well as `NULL` values.

- `ELT(`N`,`str1`,`str2`,`str3`,...)`

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

      mysql> SELECT ELT(1, 'ej', 'Heja', 'hej', 'foo');
              -> 'ej'
      mysql> SELECT ELT(4, 'ej', 'Heja', 'hej', 'foo');
              -> 'foo'

- `EXPORT_SET(`bits`,`on`,`off`[,`separator`[,`number_of_bits`]])`

  Returns a string 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).

      mysql> SELECT EXPORT_SET(5,'Y','N',',',4);
              -> 'Y,N,Y,N'
      mysql> SELECT EXPORT_SET(6,'1','0',',',10);
              -> '0,1,1,0,0,0,0,0,0,0'

- `FIELD(`str`,`str1`,`str2`,`str3`,...)`

  Returns the index (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()`.

      mysql> SELECT FIELD('ej', 'Hej', 'ej', 'Heja', 'hej', 'foo');
              -> 2
      mysql> SELECT FIELD('fo', 'Hej', 'ej', 'Heja', 'hej', 'foo');
              -> 0

- `FIND_IN_SET(`str`,`strlist`)`

  Returns a value 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.

      mysql> SELECT FIND_IN_SET('b','a,b,c,d');
              -> 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.

      mysql> SELECT FORMAT(12332.123456, 4);
              -> '12,332.1235'
      mysql> SELECT FORMAT(12332.1,4);
              -> '12,332.1000'
      mysql> SELECT FORMAT(12332.2,0);
              -> '12,332'

- `HEX(`N_or_S`)`

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

  From MySQL 4.0.1 and up, if `N_or_S` is a string, returns a hexadecimal string 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.

      mysql> SELECT HEX(255);
              -> 'FF'
      mysql> SELECT 0x616263;
              -> 'abc'
      mysql> SELECT HEX('abc');
              -> 616263

- `INSERT(`str`,`pos`,`len`,`newstr`)`

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

      mysql> SELECT INSERT('Quadratic', 3, 4, 'What');
              -> 'QuWhattic'
      mysql> SELECT INSERT('Quadratic', -1, 4, 'What');
              -> 'Quadratic'
      mysql> SELECT INSERT('Quadratic', 3, 100, 'What');
              -> 'QuWhat'

  This function is multi-byte safe.

- `INSTR(`str`,`substr`)`

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

      mysql> SELECT INSTR('foobarbar', 'bar');
              -> 4
      mysql> SELECT INSTR('xbar', 'foobar');
              -> 0

  This function is multi-byte safe. In MySQL 3.23, this function is case sensitive. For 4.0 on, it is case sensitive only if either argument is a binary string.

- `LCASE(`str`)`

  `LCASE()` is a synonym for `LOWER()`.

- `LEFT(`str`,`len`)`

  Returns the leftmost `len` characters from the string `str`.

      mysql> SELECT LEFT('foobarbar', 5);
              -> 'fooba'

- `LENGTH(`str`)`

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

      mysql> SELECT LENGTH('text');
              -> 4

- `LOAD_FILE(`file_name`)`

  Reads the file and returns the file contents as a string. 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`.

      mysql> UPDATE t
                  SET blob_col=LOAD_FILE('/tmp/picture')
                  WHERE id=1;

  Before MySQL 3.23, you must read the file inside your application and create an `INSERT` statement to update the database with the file contents. If you are using the MySQL++ library, one way to do this can be found in the MySQL++ manual, available at http://tangentsoft.net/mysql++/doc/.

- `LOCATE(`substr`,`str`)`, `LOCATE(`substr`,`str`,`pos`)`

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

      mysql> SELECT LOCATE('bar', 'foobarbar');
              -> 4
      mysql> SELECT LOCATE('xbar', 'foobar');
              -> 0
      mysql> SELECT LOCATE('bar', 'foobarbar', 5);
              -> 7

  This function is multi-byte safe. In MySQL 3.23, this function is case sensitive. For 4.0 on, it is case sensitive only if either argument is a binary string.

- `LOWER(`str`)`

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

      mysql> SELECT LOWER('QUADRATICALLY');
              -> 'quadratically'

  This function is multi-byte safe.

- `LPAD(`str`,`len`,`padstr`)`

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

      mysql> SELECT LPAD('hi',4,'??');
              -> '??hi'
      mysql> SELECT LPAD('hi',1,'??');
              -> 'h'

- `LTRIM(`str`)`

  Returns the string `str` with leading space characters removed.

      mysql> SELECT LTRIM('  barbar');
              -> 'barbar'

  This function is multi-byte safe.

- `MAKE_SET(`bits`,`str1`,`str2`,...)`

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

      mysql> SELECT MAKE_SET(1,'a','b','c');
              -> 'a'
      mysql> SELECT MAKE_SET(1 | 4,'hello','nice','world');
              -> 'hello,world'
      mysql> SELECT MAKE_SET(1 | 4,'hello','nice',NULL,'world');
              -> 'hello'
      mysql> SELECT MAKE_SET(0,'a','b','c');
              -> ''

- `MID(`str`,`pos`,`len`)`

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

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

      mysql> SELECT ORD('2');
              -> 50

- `POSITION(`substr` IN `str`)`

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

- `QUOTE(`str`)`

  Quotes a string to produce a result that can be used as a properly escaped data value in an SQL statement. The string is returned 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. The `QUOTE()` function was added in MySQL 4.0.3.

      mysql> SELECT QUOTE('Don\'t!');
              -> 'Don\'t!'
      mysql> SELECT QUOTE(NULL);
              -> NULL

- `REPEAT(`str`,`count`)`

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

      mysql> SELECT REPEAT('MySQL', 3);
              -> 'MySQLMySQLMySQL'

- `REPLACE(`str`,`from_str`,`to_str`)`

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

      mysql> SELECT REPLACE('www.mysql.com', 'w', 'Ww');
              -> 'WwWwWw.mysql.com'

  This function is multi-byte safe.

- `REVERSE(`str`)`

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

      mysql> SELECT REVERSE('abc');
              -> 'cba'

  This function is multi-byte safe.

- `RIGHT(`str`,`len`)`

  Returns the rightmost `len` characters from the string `str`.

      mysql> SELECT RIGHT('foobarbar', 4);
              -> 'rbar'

  This function is multi-byte safe.

- `RPAD(`str`,`len`,`padstr`)`

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

      mysql> SELECT RPAD('hi',5,'?');
              -> 'hi???'
      mysql> SELECT RPAD('hi',1,'?');
              -> 'h'

  This function is multi-byte safe.

- `RTRIM(`str`)`

  Returns the string `str` with trailing space characters removed.

      mysql> SELECT RTRIM('barbar   ');
              -> 'barbar'

  This function is multi-byte safe.

- `SOUNDEX(`str`)`

  Returns a soundex string from `str`. Two strings that sound almost the same should have identical soundex strings. A standard soundex string is four characters long, but the `SOUNDEX()` function returns an arbitrarily long string. You can use `SUBSTRING()` on the result to get a standard soundex string. All non-alphabetic characters 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.

      mysql> SELECT SOUNDEX('Hello');
              -> 'H400'
      mysql> SELECT SOUNDEX('Quadratically');
              -> 'Q36324'

  ### Note

  This function implements the original Soundex algorithm, not the more popular enhanced version (also described by D. Knuth). The difference is that original version discards vowels first and 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`)`. It is available beginning with MySQL 4.1.0.

- `SPACE(`N`)`

  Returns a string consisting of `N` space characters.

      mysql> SELECT SPACE(6);
              -> '      '

  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`:

      mysql> SELECT UNHEX('GG');
      +-------------+
      | 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`.

- `SUBSTR(`str`,`pos`)`, `SUBSTR(`str` FROM `pos`)`, `SUBSTR(`str`,`pos`,`len`)`, `SUBSTR(`str` FROM `pos` FOR `len`)`

  `SUBSTR()` is a synonym for `SUBSTRING()`. It was added in MySQL 4.1.1.

- `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. Beginning with MySQL 4.1.0, it is 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`.

      mysql> SELECT SUBSTRING('Quadratically',5);
              -> 'ratically'
      mysql> SELECT SUBSTRING('foobarbar' FROM 4);
              -> 'barbar'
      mysql> SELECT SUBSTRING('Quadratically',5,6);
              -> 'ratica'
      mysql> SELECT SUBSTRING('Sakila', -3);
              -> 'ila'
      mysql> SELECT SUBSTRING('Sakila', -5, 3);
              -> 'aki'
      mysql> SELECT SUBSTRING('Sakila' FROM -4 FOR 2);
              -> '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`.

      mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', 2);
              -> 'www.mysql'
      mysql> SELECT SUBSTRING_INDEX('www.mysql.com', '.', -2);
              -> 'mysql.com'

  This function is multi-byte safe.

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

  Returns the string `str` with all `remstr` prefixes 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.

      mysql> SELECT TRIM('  bar   ');
              -> 'bar'
      mysql> SELECT TRIM(LEADING 'x' FROM 'xxxbarxxx');
              -> 'barxxx'
      mysql> SELECT TRIM(BOTH 'x' FROM 'xxxbarxxx');
              -> 'bar'
      mysql> SELECT TRIM(TRAILING 'xyz' FROM 'barxxyz');
              -> 'barx'

  This function is multi-byte safe.

- `UCASE(`str`)`

  `UCASE()` is a synonym for `UPPER()`.

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

      mysql> SELECT UNHEX('4D7953514C');
              -> 'MySQL'
      mysql> SELECT 0x4D7953514C;
              -> 'MySQL'
      mysql> SELECT UNHEX(HEX('string'));
              -> 'string'
      mysql> SELECT HEX(UNHEX('1267'));
              -> '1267'

  `UNHEX()` was added in MySQL 4.1.2.

- `UPPER(`str`)`

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

      mysql> SELECT UPPER('Hej');
              -> 'HEJ'

  This function is multi-byte safe.

### 11.4.1. String Comparison Functions

Name | Description
--- | ---
`LIKE` | Simple pattern matching
`NOT LIKE` | Negation of simple pattern matching
`SOUNDS LIKE`(v4.1.0) | Compare sounds

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:

      mysql> SELECT 'ä' LIKE 'ae' COLLATE latin1_german2_ci;
      +-----------------------------------------+
      | 'ä' LIKE 'ae' COLLATE latin1_german2_ci |
      +-----------------------------------------+
      |                                       0 |
      +-----------------------------------------+
      mysql> SELECT 'ä' = 'ae' COLLATE latin1_german2_ci;
      +--------------------------------------+
      | 'ä' = 'ae' COLLATE latin1_german2_ci |
      +--------------------------------------+
      |                                    1 |
      +--------------------------------------+

  With `LIKE` you can use the following two wildcard characters in the pattern:

  Character | Description
  `%` | Matches any number of characters, even zero characters
  `_` | Matches exactly one character

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

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

  String | Description
  `\%` | Matches one “`%`” character
  `\_` | Matches one “`_`” character

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

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

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

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

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

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

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

  ### Note

  Because MySQL uses 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

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

      CREATE TABLE foo (bar VARCHAR(10));

      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:

      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. The syntax for regular expressions is discussed in Section 11.4.2, “Regular Expressions”. 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.

  As of MySQL 3.23.4, `REGEXP` is not case sensitive, except when used with binary strings.

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

  `REGEXP` and `RLIKE` use the current character set 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.

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

  As of MySQL 4.0, `STRCMP()` uses the current character set when performing comparisons. This makes the default comparison behavior case insensitive unless one or both of the operands are binary strings. Before MySQL 4.0, `STRCMP()` is case sensitive.

### 11.4.2. Regular Expressions

Name | Description
--- | ---
`NOT REGEXP` | Negation of REGEXP
`REGEXP` | Pattern matching using regular expressions
`RLIKE` | Synonym for REGEXP

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. See Appendix D, Credits. MySQL uses the extended version to support pattern-matching operations performed with the `REGEXP` operator in SQL statements. See Section 3.3.4.7, “Pattern Matching”, and Section 11.4.1, “String Comparison Functions”.

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. That manual page is included in MySQL source distributions, in the `regex.7` file under the `regex` directory.

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.

      mysql> SELECT 'fo\nfo' REGEXP '^fo$';                   -> 0
      mysql> SELECT 'fofo' REGEXP '^fo';                      -> 1

- `$`

  Match the end of a string.

      mysql> SELECT 'fo\no' REGEXP '^fo\no$';                 -> 1
      mysql> SELECT 'fo\no' REGEXP '^fo$';                    -> 0

- `.`

  Match any character (including carriage return and newline).

      mysql> SELECT 'fofo' REGEXP '^f.*$';                    -> 1
      mysql> SELECT 'fo\r\nfo' REGEXP '^f.*$';                -> 1

- `a*`

  Match any sequence of zero or more `a` characters.

      mysql> SELECT 'Ban' REGEXP '^Ba*n';                     -> 1
      mysql> SELECT 'Baaan' REGEXP '^Ba*n';                   -> 1
      mysql> SELECT 'Bn' REGEXP '^Ba*n';                      -> 1

- `a+`

  Match any sequence of one or more `a` characters.

      mysql> SELECT 'Ban' REGEXP '^Ba+n';                     -> 1
      mysql> SELECT 'Bn' REGEXP '^Ba+n';                      -> 0

- `a?`

  Match either zero or one `a` character.

      mysql> SELECT 'Bn' REGEXP '^Ba?n';                      -> 1
      mysql> SELECT 'Ban' REGEXP '^Ba?n';                     -> 1
      mysql> SELECT 'Baan' REGEXP '^Ba?n';                    -> 0

- `de|abc`

  Match either of the sequences `de` or `abc`.

      mysql> SELECT 'pi' REGEXP 'pi|apa';                     -> 1
      mysql> SELECT 'axe' REGEXP 'pi|apa';                    -> 0
      mysql> SELECT 'apa' REGEXP 'pi|apa';                    -> 1
      mysql> SELECT 'apa' REGEXP '^(pi|apa)$';                -> 1
      mysql> SELECT 'pi' REGEXP '^(pi|apa)$';                 -> 1
      mysql> SELECT 'pix' REGEXP '^(pi|apa)$';                -> 0

- `(abc)*`

  Match zero or more instances of the sequence `abc`.

      mysql> SELECT 'pi' REGEXP '^(pi)*$';                    -> 1
      mysql> SELECT 'pip' REGEXP '^(pi)*$';                   -> 0
      mysql> SELECT 'pipi' REGEXP '^(pi)*$';                  -> 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`.

      mysql> SELECT 'abcde' REGEXP 'a[bcd]{2}e';              -> 0
      mysql> SELECT 'abcde' REGEXP 'a[bcd]{3}e';              -> 1
      mysql> SELECT 'abcde' REGEXP 'a[bcd]{1,10}e';           -> 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.

      mysql> SELECT 'aXbc' REGEXP '[a-dXYZ]';                 -> 1
      mysql> SELECT 'aXbc' REGEXP '^[a-dXYZ]$';               -> 0
      mysql> SELECT 'aXbc' REGEXP '^[a-dXYZ]+$';              -> 1
      mysql> SELECT 'aXbc' REGEXP '^[^a-dXYZ]+$';             -> 0
      mysql> SELECT 'gheis' REGEXP '^[^a-dXYZ]+$';            -> 1
      mysql> SELECT 'gheisa' REGEXP '^[^a-dXYZ]+$';           -> 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` |  |

      mysql> SELECT '~' REGEXP '[[.~.]]';                     -> 1
      mysql> SELECT '~' REGEXP '[[.tilde.]]';                 -> 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

      mysql> SELECT 'justalnums' REGEXP '[[:alnum:]]+';       -> 1
      mysql> SELECT '!!' REGEXP '[[:alnum:]]+';               -> 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 (`_`).

      mysql> SELECT 'a word a' REGEXP '[[:<:]]word[[:>:]]';   -> 1
      mysql> SELECT 'a xword a' REGEXP '[[:<:]]word[[:>:]]';  -> 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:

    mysql> SELECT '1+2' REGEXP '1+2';                       -> 0
    mysql> SELECT '1+2' REGEXP '1\+2';                      -> 0
    mysql> SELECT '1+2' REGEXP '1\\+2';                     -> 1

## 11.5. Numeric Functions

Name | Description
--- | ---
`ABS()` | Return the absolute value
`ACOS()` | Return the arc cosine
`ASIN()` | Return the arc sine
`ATAN2()`, `ATAN()` | Return the arc tangent of the two arguments
`ATAN()` | Return the arc tangent
`CEIL()` | Return the smallest integer value not less than the argument
`CEILING()` | Return the smallest integer value not less than the argument
`CONV()` | Convert numbers between different number bases
`COS()` | Return the cosine
`COT()` | Return the cotangent
`CRC32()`(v4.1.0) | Compute a cyclic redundancy check value
`DEGREES()` | Convert radians to degrees
`DIV`(v4.1.0) | Integer division
`/` | Division operator
`EXP()` | Raise to the power of
`FLOOR()` | Return the largest integer value not greater than the argument
`MOD()` | Return the remainder
`LN()` | Return the natural logarithm of the argument
`LOG10()` | Return the base-10 logarithm of the argument
`LOG2()` | Return the base-2 logarithm of the argument
`LOG()` | Return the natural logarithm of the first argument
`-` | Minus operator
`OCT()` | Return an octal representation of a decimal number
`%` | Modulo operator
`PI()` | Return the value of pi
`+` | Addition operator
`POW()` | Return the argument raised to the specified power
`POWER()` | Return the argument raised to the specified power
`RADIANS()` | Return argument converted to radians
`RAND()` | Return a random floating-point value
`ROUND()` | Round the argument
`SIGN()` | Return the sign of the argument
`SIN()` | Return the sine of the argument
`SQRT()` | Return the square root of the argument
`TAN()` | Return the tangent of the argument
`*` | Times operator
`TRUNCATE()` | Truncate to specified number of decimal places
`-` | Change the sign of the argument

### 11.5.1. Arithmetic Operators

Name | Description
--- | ---
`DIV`(v4.1.0) | Integer division
`/` | Division operator
`-` | Minus operator
`%` | Modulo operator
`+` | Addition operator
`*` | Times operator
`-` | Change the sign of the argument

The usual arithmetic operators are available. The precision of 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.

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.57692308`).

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. See Section 11.9, “Cast Functions and Operators”.

- `+`

  Addition:

      mysql> SELECT 3+5;
              -> 8

- `-`

  Subtraction:

      mysql> SELECT 3-5;
              -> -2

- `-`

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

      mysql> SELECT - 2;
              -> -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:

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

  The result of the last expression is incorrect because the result of the integer multiplication exceeds the 64-bit range of `BIGINT` calculations. (See Section 10.2, “Numeric Types”.)

- `/`

  Division:

      mysql> SELECT 3/5;
              -> 0.60

  Division by zero produces a `NULL` result:

      mysql> SELECT 102/(1-1);
              -> 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.

      mysql> SELECT 5 DIV 2;
              -> 2

  `DIV` was implemented in MySQL 4.1.0.

- ``N` % `M``

  Modulo operation. Returns the remainder of `N` divided by `M`. For more information, see the description for the `MOD()` function in Section 11.5.2, “Mathematical Functions”.

### 11.5.2. Mathematical Functions

Name | Description
--- | ---
`ABS()` | Return the absolute value
`ACOS()` | Return the arc cosine
`ASIN()` | Return the arc sine
`ATAN2()`, `ATAN()` | Return the arc tangent of the two arguments
`ATAN()` | Return the arc tangent
`CEIL()` | Return the smallest integer value not less than the argument
`CEILING()` | Return the smallest integer value not less than the argument
`CONV()` | Convert numbers between different number bases
`COS()` | Return the cosine
`COT()` | Return the cotangent
`CRC32()`(v4.1.0) | Compute a cyclic redundancy check value
`DEGREES()` | Convert radians to degrees
`EXP()` | Raise to the power of
`FLOOR()` | Return the largest integer value not greater than the argument
`MOD()` | Return the remainder
`LN()` | Return the natural logarithm of the argument
`LOG10()` | Return the base-10 logarithm of the argument
`LOG2()` | Return the base-2 logarithm of the argument
`LOG()` | Return the natural logarithm of the first argument
`OCT()` | Return an octal representation of a decimal number
`PI()` | Return the value of pi
`POW()` | Return the argument raised to the specified power
`POWER()` | Return the argument raised to the specified power
`RADIANS()` | Return argument converted to radians
`RAND()` | Return a random floating-point value
`ROUND()` | Round the argument
`SIGN()` | Return the sign of the argument
`SIN()` | Return the sine of the argument
`SQRT()` | Return the square root of the argument
`TAN()` | Return the tangent of the argument
`TRUNCATE()` | Truncate to specified number of decimal places

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

- `ABS(`X`)`

  Returns the absolute value of `X`.

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

  This function is safe to use with `BIGINT` values.

- `ACOS(`X`)`

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

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

- `ASIN(`X`)`

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

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

- `ATAN(`X`)`

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

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

- `ATAN(`Y`,`X`)`, `ATAN2(`Y`,`X`)`

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

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

- `CEIL(`X`)`

  `CEIL()` is a synonym for `CEILING()`. It was added in MySQL 4.0.6.

- `CEILING(`X`)`

  Returns the smallest integer value not less than `X`.

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

  Note that the return value is converted to a `BIGINT`.

- `CONV(`N`,`from_base`,`to_base`)`

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

      mysql> SELECT CONV('a',16,2);
              -> '1010'
      mysql> SELECT CONV('6E',18,8);
              -> '172'
      mysql> SELECT CONV(-17,10,-18);
              -> '-H'
      mysql> SELECT CONV(10+'10'+'10'+0xa,10,10);
              -> '40'

- `COS(`X`)`

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

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

- `COT(`X`)`

  Returns the cotangent of `X`.

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

- `CRC32(`expr`)`

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

      mysql> SELECT CRC32('MySQL');
              -> 3259397556

  `CRC32()` is available as of MySQL 4.1.0.

- `DEGREES(`X`)`

  Returns the argument `X`, converted from radians to degrees.

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

- `EXP(`X`)`

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

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

- `FLOOR(`X`)`

  Returns the largest integer value not greater than `X`.

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

  Note that the return value is converted to a `BIGINT`.

- `FORMAT(`X`,`D`)`

  Formats the number `X` to a format like `'#,###,###.##'`, rounded to `D` decimal places, and returns the result as a string. For details, see Section 11.4, “String Functions”.

- `HEX(N_or_S)`

  This function can be used to obtain a hexadecimal representation of a decimal number or (beginning with MySQL 4.0.1) a string; the manner in which it does so varies according to the argument's type. See this function's description in Section 11.4, “String Functions”, for details.

- `LN(`X`)`

  Returns the natural logarithm of `X`; that is, the base-e logarithm of `X`.

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

  This function was added in MySQL 4.0.3. It is synonymous with `LOG(`X`)`.

- `LOG(`X`)`, `LOG(`B`,`X`)`

  If called with one parameter, this function returns the natural logarithm of `X`.

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

  If called with two parameters, this function returns the logarithm of `X` for an arbitrary base `B`.

      mysql> SELECT LOG(2,65536);
              -> 16.000000
      mysql> SELECT LOG(1,100);
              -> NULL

  The arbitrary base option was added in MySQL 4.0.3. `LOG(`B`,`X`)` is equivalent to `LOG(`X`) / LOG(`B`)`.

- `LOG2(`X`)`

  Returns the base-2 logarithm of ``X``.

      mysql> SELECT LOG2(65536);
              -> 16.000000
      mysql> SELECT LOG2(-100);
              -> NULL

  `LOG2()` is useful for finding out how many bits a number would require for storage. This function was added in MySQL 4.0.3. In earlier versions, you can use `LOG(`X`) / LOG(2)` instead.

- `LOG10(`X`)`

  Returns the base-10 logarithm of `X`.

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

- `MOD(`N`,`M`)`, ``N` % `M``, ``N` MOD `M``

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

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

  This function is safe to use with `BIGINT` values. The ``N` MOD `M`` syntax works only as of MySQL 4.1.0.

  As of MySQL 4.1.7, `MOD()` works on values that have a fractional part and returns the exact remainder after division:

      mysql> SELECT MOD(34.5,3);
              -> 1.5

  Before MySQL 4.1.7, `MOD()` rounds arguments with a fractional value to integers and returns an integer result:

      mysql> SELECT MOD(34.5,3);
              -> 2

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

      mysql> SELECT OCT(12);
              -> '14'

- `PI()`

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

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

- `POW(`X`,`Y`)`

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

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

- `POWER(`X`,`Y`)`

  This is a synonym for `POW()`.

- `RADIANS(`X`)`

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

      mysql> SELECT RADIANS(90);
              -> 1.570796

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

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

  The effect of using a non-constant argument is undefined. As of MySQL 4.1.15, non-constant arguments are disallowed.

  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:

      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, as of MySQL 3.23, you can retrieve rows in random order like this:

      mysql> SELECT * FROM tbl_name ORDER BY RAND();

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

      mysql> SELECT * FROM table1, table2 WHERE a=b AND c<d -> ORDER BY RAND() LIMIT 1000;

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

  `RAND()` is not meant to be a perfect random generator, but instead 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. `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.

      mysql> SELECT ROUND(-1.23);
              -> -1
      mysql> SELECT ROUND(-1.58);
              -> -2
      mysql> SELECT ROUND(1.58);
              -> 2
      mysql> SELECT ROUND(1.298, 1);
              -> 1.3
      mysql> SELECT ROUND(1.298, 0);
              -> 1
      mysql> SELECT ROUND(23.298, -1);
              -> 20

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

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

- `SIGN(`X`)`

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

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

- `SIN(`X`)`

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

      mysql> SELECT SIN(PI());
              -> 1.2246063538224e-16
      mysql> SELECT ROUND(SIN(PI()));
              -> 0

- `SQRT(`X`)`

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

      mysql> SELECT SQRT(4);
              -> 2
      mysql> SELECT SQRT(20);
              -> 4.4721359549996
      mysql> SELECT SQRT(-16);
              -> NULL

- `TAN(`X`)`

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

      mysql> SELECT TAN(PI());
              -> -1.2246063538224e-16
      mysql> SELECT TAN(PI()+1);
              -> 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.

      mysql> SELECT TRUNCATE(1.223,1);
              -> 1.2
      mysql> SELECT TRUNCATE(1.999,1);
              -> 1.9
      mysql> SELECT TRUNCATE(1.999,0);
              -> 1
      mysql> SELECT TRUNCATE(-1.999,1);
              -> -1.9
      mysql> SELECT TRUNCATE(122,-2);
             -> 100
      mysql> SELECT TRUNCATE(10.28*100,0);
             -> 1027

  Starting from MySQL 3.23.51, all numbers are rounded toward zero.

## 11.6. Date and Time Functions

This section describes the functions that can be used to manipulate temporal values. See Section 10.3, “Date and Time Types”, for a description of the range of values each date and time type has and the valid formats in which values may be specified.

Name | Description
--- | ---
`ADDDATE()`(v4.1.1) | Add dates
`ADDTIME()`(v4.1.1) | Add time
`CONVERT_TZ()`(v4.1.3) | Convert from one timezone to another
`CURDATE()` | Return the current date
`CURRENT_DATE()`, `CURRENT_DATE` | Synonyms for CURDATE()
`CURRENT_TIME()`, `CURRENT_TIME` | Synonyms for CURTIME()
`CURRENT_TIMESTAMP()`, `CURRENT_TIMESTAMP` | Synonyms for NOW()
`CURTIME()` | Return the current time
`DATE_ADD()` | Add two dates
`DATE_FORMAT()` | Format date as specified
`DATE_SUB()` | Subtract two dates
`DATE()`(v4.1.1) | Extract the date part of a date or datetime expression
`DATEDIFF()`(v4.1.1) | Subtract two dates
`DAY()`(v4.1.1) | Synonym for DAYOFMONTH()
`DAYNAME()`(v4.1.21) | Return the name of the weekday
`DAYOFMONTH()` | Return the day of the month (1-31)
`DAYOFWEEK()` | Return the weekday index of the argument
`DAYOFYEAR()` | Return the day of the year (1-366)
`EXTRACT` | Extract part of a date
`FROM_DAYS()` | Convert a day number to a date
`FROM_UNIXTIME()` | Format date as a UNIX timestamp
`GET_FORMAT()`(v4.1.1) | Return a date format string
`HOUR()` | Extract the hour
`LAST_DAY`(v4.1.1) | Return the last day of the month for the argument
`LOCALTIME()`, `LOCALTIME` | Synonym for NOW()
`LOCALTIMESTAMP`, `LOCALTIMESTAMP()`(v4.0.6) | Synonym for NOW()
`MAKEDATE()`(v4.1.1) | Create a date from the year and day of year
`MAKETIME`(v4.1.1) | MAKETIME()
`MICROSECOND()`(v4.1.1) | Return the microseconds from argument
`MINUTE()` | Return the minute from the argument
`MONTH()` | Return the month from the date passed
`MONTHNAME()`(v4.1.21) | Return the name of the month
`NOW()` | Return the current date and time
`PERIOD_ADD()` | Add a period to a year-month
`PERIOD_DIFF()` | Return the number of months between periods
`QUARTER()` | Return the quarter from a date argument
`SEC_TO_TIME()` | Converts seconds to 'HH:MM:SS' format
`SECOND()` | Return the second (0-59)
`STR_TO_DATE()`(v4.1.1) | Convert a string to a date
`SUBDATE()` | When invoked with three arguments a synonym for DATE_SUB()
`SUBTIME()`(v4.1.1) | Subtract times
`SYSDATE()` | Return the time at which the function executes
`TIME_FORMAT()` | Format as time
`TIME_TO_SEC()` | Return the argument converted to seconds
`TIME()`(v4.1.1) | Extract the time portion of the expression passed
`TIMEDIFF()`(v4.1.1) | Subtract time
`TIMESTAMP()`(v4.1.1) | With a single argument, this function returns the date or datetime expression. With two arguments, the sum of the arguments
`TO_DAYS()` | Return the date argument converted to days
`UNIX_TIMESTAMP()` | Return a UNIX timestamp
`UTC_DATE()`(v4.1.1) | Return the current UTC date
`UTC_TIME()`(v4.1.1) | Return the current UTC time
`UTC_TIMESTAMP()`(v4.1.1) | Return the current UTC date and time
`WEEK()` | Return the week number
`WEEKDAY()` | Return the weekday index
`WEEKOFYEAR()`(v4.1.1) | Return the calendar week of the date (1-53)
`YEAR()` | Return the year
`YEARWEEK()` | Return the year and week

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:

    mysql> SELECT something FROM tbl_name
        -> WHERE DATE_SUB(CURDATE(),INTERVAL 30 DAY) <= date_col;

Note that 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. This principle also applies to `CURDATE()`, `CURTIME()`, `UTC_DATE()`, `UTC_TIME()`, `UTC_TIMESTAMP()`, and to any of their synonyms.

Beginning with MySQL 4.1.3, the `CURRENT_TIMESTAMP()`, `CURRENT_TIME()`, `CURRENT_DATE()`, and `FROM_UNIXTIME()` functions return values in the connection's current time zone, which is available as the value of the `time_zone` system variable. In addition, `UNIX_TIMESTAMP()` assumes that its argument is a datetime value in the current time zone. See Section 9.9, “MySQL Server Time Zone Support”.

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. For example:

    mysql> SELECT DAYOFMONTH('2001-11-00'), MONTH('2005-00-00');
            -> 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:

    mysql> SELECT DATE_ADD('2006-05-00',INTERVAL 1 DAY);
            -> NULL
    mysql> SELECT DAYNAME('2006-05-00');
            -> 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()`.

      mysql> SELECT DATE_ADD('1998-01-02', INTERVAL 31 DAY);
              -> '1998-02-02'
      mysql> SELECT ADDDATE('1998-01-02', INTERVAL 31 DAY);
              -> '1998-02-02'

  As of MySQL 4.1.1, the second syntax is allowed. When invoked with the `days` form of the second argument, MySQL treats it as an integer number of days to be added to `expr`.

      mysql> SELECT ADDDATE('1998-01-02', 31);
              -> '1998-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.

      mysql> SELECT ADDTIME('1997-12-31 23:59:59.999999',
          ->                '1 1:1:1.000002');
              -> '1998-01-02 01:01:01.000001'
      mysql> SELECT ADDTIME('01:00:00.999999', '02:00:00.999998');
              -> '03:00:01.999997'

  `ADDTIME()` was added in MySQL 4.1.1.

- `CONVERT_TZ(`dt`,`from_tz`,`to_tz`)`

  `CONVERT_TZ()` converts a datetime value `dt` from the time zone given by `from_tz` to the time zone given by `to_tz` and returns the resulting value. Time zones are specified as described in Section 9.9, “MySQL Server Time Zone Support”. This function returns `NULL` if the arguments are invalid.

  If the value falls out of the supported range of the `TIMESTAMP` type when converted from `from_tz` to UTC, no conversion occurs. The `TIMESTAMP` range is described in Section 10.1.2, “Overview of Date and Time Types”.

      mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','GMT','MET');
              -> '2004-01-01 13:00:00'
      mysql> SELECT CONVERT_TZ('2004-01-01 12:00:00','+00:00','+10:00');
              -> '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. See Section 9.9, “MySQL Server Time Zone Support”, for instructions.

  `CONVERT_TZ()` was added in MySQL 4.1.3.

  If you intend to use `CONVERT_TZ()` while other tables are locked with `LOCK TABLES`, you must also lock the `mysql.time_zone_name` table.

- `CURDATE()`

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

      mysql> SELECT CURDATE();
              -> '1997-12-15'
      mysql> SELECT CURDATE() + 0;
              -> 19971215

- `CURRENT_DATE`, `CURRENT_DATE()`

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

- `CURTIME()`

  Returns the current time as a value in `'HH:MM:SS'` or `HHMMSS.uuuuuu` format, depending on whether the function is used in a string or numeric context. (There is no `.uuuuuu` part before MySQL 4.1.13.) The value is expressed in the current time zone.

      mysql> SELECT CURTIME();
              -> '23:50:26'
      mysql> SELECT CURTIME() + 0;
              -> 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`.

      mysql> SELECT DATE('2003-12-31 01:02:03');
              -> '2003-12-31'

  `DATE()` is available as of MySQL 4.1.1.

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

      mysql> SELECT DATEDIFF('1997-12-31 23:59:59','1997-12-30');
              -> 1
      mysql> SELECT DATEDIFF('1997-11-30 23:59:59','1997-12-31');
              -> -31

  `DATEDIFF()` was added in MySQL 4.1.1.

- `DATE_ADD(`date`,INTERVAL `expr` `unit`)`, `DATE_SUB(`date`,INTERVAL `expr` `unit`)`

  These functions perform date arithmetic. `date` is a `DATETIME` or `DATE` value specifying the starting date. `expr` is an expression specifying the interval value to be added or subtracted from the starting date. `expr` is a string; it may start with a “`-`” for negative intervals. `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 | Version
  `MICROSECOND` | `MICROSECONDS` | 4.1.1
  `SECOND` | `SECONDS` | Pre-4.1
  `MINUTE` | `MINUTES` | Pre-4.1
  `HOUR` | `HOURS` | Pre-4.1
  `DAY` | `DAYS` | Pre-4.1
  `WEEK` | `WEEKS` | 5.0.0
  `MONTH` | `MONTHS` | Pre-4.1
  `QUARTER` | `QUARTERS` | 5.0.0
  `YEAR` | `YEARS` | Pre-4.1
  `SECOND_MICROSECOND` | `'SECONDS.MICROSECONDS'` | 4.1.1
  `MINUTE_MICROSECOND` | `'MINUTES.MICROSECONDS'` | 4.1.1
  `MINUTE_SECOND` | `'MINUTES:SECONDS'` | 4.1.1
  `HOUR_MICROSECOND` | `'HOURS.MICROSECONDS'` | 4.1.1
  `HOUR_SECOND` | `'HOURS:MINUTES:SECONDS'` | 4.1.1
  `HOUR_MINUTE` | `'HOURS:MINUTES'` | Pre-4.1
  `DAY_MICROSECOND` | `'DAYS.MICROSECONDS'` | 4.1.1
  `DAY_SECOND` | `'DAYS HOURS:MINUTES:SECONDS'` | Pre-4.1
  `DAY_MINUTE` | `'DAYS HOURS:MINUTES'` | Pre-4.1
  `DAY_HOUR` | `'DAYS HOURS'` | Pre-4.1
  `YEAR_MONTH` | `'YEARS-MONTHS'` | Pre-4.1

  The `type` values `DAY_MICROSECOND`, `HOUR_MICROSECOND`, `MINUTE_MICROSECOND`, `SECOND_MICROSECOND`, and `MICROSECOND` are allowed as of MySQL 4.1.1.

  MySQL allows any punctuation delimiter in the `expr` format. Those shown in the table are the suggested delimiters. If the `date` argument is a `DATE` value and your calculations involve only `YEAR`, `MONTH`, and `DAY` parts (that is, no time parts), the result is a `DATE` value. Otherwise, the result is a `DATETIME` value.

  As of MySQL 3.23, 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.

      mysql> SELECT '1997-12-31 23:59:59' + INTERVAL 1 SECOND;
              -> '1998-01-01 00:00:00'
      mysql> SELECT INTERVAL 1 DAY + '1997-12-31';
              -> '1998-01-01'
      mysql> SELECT '1998-01-01' - INTERVAL 1 SECOND;
              -> '1997-12-31 23:59:59'
      mysql> SELECT DATE_ADD('1997-12-31 23:59:59',
          ->                 INTERVAL 1 SECOND);
              -> '1998-01-01 00:00:00'
      mysql> SELECT DATE_ADD('1997-12-31 23:59:59',
          ->                 INTERVAL 1 DAY);
              -> '1998-01-01 23:59:59'
      mysql> SELECT DATE_ADD('1997-12-31 23:59:59',
          ->                 INTERVAL '1:1' MINUTE_SECOND);
              -> '1998-01-01 00:01:00'
      mysql> SELECT DATE_SUB('1998-01-01 00:00:00',
          ->                 INTERVAL '1 1:1:1' DAY_SECOND);
              -> '1997-12-30 22:58:59'
      mysql> SELECT DATE_ADD('1998-01-01 00:00:00',
          ->                 INTERVAL '-1 10' DAY_HOUR);
              -> '1997-12-30 14:00:00'
      mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY);
              -> '1997-12-02'
      mysql> SELECT DATE_ADD('1992-12-31 23:59:59.000002',
          ->            INTERVAL '1.999999' SECOND_MICROSECOND);
              -> '1993-01-01 00:00:01.000001'

  If you specify an interval value that is too short (does not include all the interval parts that would be expected from the `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.50` and is treated as 1 hour, 50 minutes:

      mysql> SELECT 6/4;
              -> 1.50
      mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 6/4 HOUR_MINUTE);
              -> '1999-01-01 01:50: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:

      mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 1 DAY);
              -> '1999-01-02'
      mysql> SELECT DATE_ADD('1999-01-01', INTERVAL 1 HOUR);
              -> '1999-01-01 01:00:00'

  If you add `MONTH`, `YEAR_MONTH`, or `YEAR` and the resulting date has a day that is larger than the maximum day for the new month, the day is adjusted to the maximum days in the new month:

      mysql> SELECT DATE_ADD('1998-01-30', INTERVAL 1 MONTH);
              -> '1998-02-28'

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

      mysql> SELECT DATE_ADD('2006-07-00', INTERVAL 1 DAY);
              -> NULL
      mysql> SELECT '2005-03-32' + INTERVAL 1 MONTH;
              -> NULL

- `DATE_FORMAT(`date`,`format`)`

  Formats the `date` value according to the `format` string.

  The following specifiers may be used in the `format` string. As of MySQL 3.23, the “`%`” character is required before format specifier characters. In earlier versions of MySQL, “`%`” was optional.

  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

  The `%v`, `%V`, `%x`, and `%X` format specifiers are available as of MySQL 3.23.8. `%f` is available as of MySQL 4.1.1.

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

  As of MySQL 4.1.21, the language used for day and month names and abbreviations is controlled by the value of the `lc_time_names` system variable (Section 9.10, “MySQL Server Locale Support”).

  As of MySQL 4.1.23, `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. Before 4.1.23, the return value is a binary string.

      mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%W %M %Y');
              -> 'Saturday October 1997'
      mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00', '%H:%i:%s');
              -> '22:23:00'
      mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00',
                                '%D %y %a %d %m %b %j');
              -> '4th 97 Sat 04 10 Oct 277'
      mysql> SELECT DATE_FORMAT('1997-10-04 22:23:00',
                                '%H %k %I %r %T %S %w');
              -> '22 22 10 10:23:00 PM 22:23:00 00 6'
      mysql> SELECT DATE_FORMAT('1999-01-01', '%X %V');
              -> '1998 52'
      mysql> SELECT DATE_FORMAT('2006-06-00', '%d');
              -> '00'

- `DATE_SUB(`date`,INTERVAL `expr` `unit`)`

  See the description for `DATE_ADD()`.

- `DAY(`date`)`

  `DAY()` is a synonym for `DAYOFMONTH()`. It is available as of MySQL 4.1.1.

- `DAYNAME(`date`)`

  Returns the name of the weekday for `date`. As of MySQL 4.1.21, the language used for the name is controlled by the value of the `lc_time_names` system variable (Section 9.10, “MySQL Server Locale Support”).

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

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

      mysql> SELECT DAYOFMONTH('1998-02-03');
              -> 3

- `DAYOFWEEK(`date`)`

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

      mysql> SELECT DAYOFWEEK('1998-02-03');
              -> 3

- `DAYOFYEAR(`date`)`

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

      mysql> SELECT DAYOFYEAR('1998-02-03');
              -> 34

- `EXTRACT(`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.

      mysql> SELECT EXTRACT(YEAR FROM '1999-07-02');
             -> 1999
      mysql> SELECT EXTRACT(YEAR_MONTH FROM '1999-07-02 01:02:03');
             -> 199907
      mysql> SELECT EXTRACT(DAY_MINUTE FROM '1999-07-02 01:02:03');
             -> 20102
      mysql> SELECT EXTRACT(MICROSECOND
          ->                FROM '2003-01-02 10:30:00.000123');
              -> 123

  `EXTRACT()` was added in MySQL 3.23.0.

- `FROM_DAYS(`N`)`

  Given a day number `N`, returns a `DATE` value.

      mysql> SELECT FROM_DAYS(729669);
              -> '1997-10-07'

  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). See Section 11.7, “What Calendar Is Used By MySQL?”.

- `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. (There is no `.uuuuuu` part before MySQL 4.1.13.) 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.

      mysql> SELECT FROM_UNIXTIME(1196440219);
              -> '2007-11-30 10:30:19'
      mysql> SELECT FROM_UNIXTIME(1196440219) + 0;
              -> 20071130103019.000000
      mysql> SELECT FROM_UNIXTIME(UNIX_TIMESTAMP(),
          ->                      '%Y %D %M %h:%i:%s %x');
              -> '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'`

  As of MySQL 4.1.4, `TIMESTAMP` can also be used as the first argument to `GET_FORMAT()`, in which case the function returns the same values as for `DATETIME`.

      mysql> SELECT DATE_FORMAT('2003-10-03',GET_FORMAT(DATE,'EUR'));
              -> '03.10.2003'
      mysql> SELECT STR_TO_DATE('10.31.2003',GET_FORMAT(DATE,'USA'));
              -> '2003-10-31'

  `GET_FORMAT()` is available as of MySQL 4.1.1.

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

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

- `LAST_DAY(`date`)`

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

      mysql> SELECT LAST_DAY('2003-02-05');
              -> '2003-02-28'
      mysql> SELECT LAST_DAY('2004-02-05');
              -> '2004-02-29'
      mysql> SELECT LAST_DAY('2004-01-01 01:01:01');
              -> '2004-01-31'
      mysql> SELECT LAST_DAY('2003-03-32');
              -> NULL

  `LAST_DAY()` is available as of MySQL 4.1.1.

- `LOCALTIME`, `LOCALTIME()`

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

- `LOCALTIMESTAMP`, `LOCALTIMESTAMP()`

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

  They were added in MySQL 4.0.6.

- `MAKEDATE(`year`,`dayofyear`)`

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

      mysql> SELECT MAKEDATE(2001,31), MAKEDATE(2001,32);
              -> '2001-01-31', '2001-02-01'
      mysql> SELECT MAKEDATE(2001,365), MAKEDATE(2004,365);
              -> '2001-12-31', '2004-12-30'
      mysql> SELECT MAKEDATE(2001,0);
              -> NULL

  `MAKEDATE()` is available as of MySQL 4.1.1.

- `MAKETIME(`hour`,`minute`,`second`)`

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

      mysql> SELECT MAKETIME(12,15,30);
              -> '12:15:30'

  `MAKETIME()` is available as of MySQL 4.1.1.

- `MICROSECOND(`expr`)`

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

      mysql> SELECT MICROSECOND('12:00:00.123456');
              -> 123456
      mysql> SELECT MICROSECOND('1997-12-31 23:59:59.000010');
              -> 10

  `MICROSECOND()` is available as of MySQL 4.1.1.

- `MINUTE(`time`)`

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

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

- `MONTH(`date`)`

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

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

- `MONTHNAME(`date`)`

  Returns the full name of the month for `date`. As of MySQL 4.1.21, the language used for the name is controlled by the value of the `lc_time_names` system variable (Section 9.10, “MySQL Server Locale Support”).

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

- `NOW()`

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

      mysql> SELECT NOW();
              -> '2007-12-15 23:50:26'
      mysql> SELECT NOW() + 0;
              -> 20071215235026.000000

- `PERIOD_ADD(`P`,`N`)`

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

      mysql> SELECT PERIOD_ADD(9801,2);
              -> 199803

- `PERIOD_DIFF(`P1`,`P2`)`

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

      mysql> SELECT PERIOD_DIFF(9802,199703);
              -> 11

- `QUARTER(`date`)`

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

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

- `SECOND(`time`)`

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

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

- `SEC_TO_TIME(`seconds`)`

  Returns the `seconds` argument, converted to hours, minutes, and seconds, as a `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.

      mysql> SELECT SEC_TO_TIME(2378);
              -> '00:39:38'
      mysql> SELECT SEC_TO_TIME(2378) + 0;
              -> 3938

  ### 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:

      mysql> SELECT STR_TO_DATE('200442 Monday', '%X%V %W');
              -> '2004-10-18'

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

  Range checking on the parts of date values is as described in Section 10.3.1, “The `DATETIME`, `DATE`, and `TIMESTAMP` Types”. This means, for example, that a date with a day part larger than the number of days in a month is allowable as long as the day part is in the range from 1 to 31. Also, “zero” dates or dates with part values of 0 are allowed.

      mysql> SELECT STR_TO_DATE('00/00/0000', '%m/%d/%Y');
              -> '0000-00-00'
      mysql> SELECT STR_TO_DATE('04/31/2004', '%m/%d/%Y');
              -> '2004-04-31'

  `STR_TO_DATE()` is available as of MySQL 4.1.1.

- `SUBDATE(`date`,INTERVAL `expr` `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()`.

      mysql> SELECT DATE_SUB('1998-01-02', INTERVAL 31 DAY);
              -> '1997-12-02'
      mysql> SELECT SUBDATE('1998-01-02', INTERVAL 31 DAY);
              -> '1997-12-02'

  As of MySQL 4.1.1, the second syntax is allowed, where `expr` is a date or datetime expression and `days` is the number of days to be subtracted from `expr`.

      mysql> SELECT SUBDATE('1998-01-02 12:00:00', 31);
              -> '1997-12-02 12:00:00'

- `SUBTIME(`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.

      mysql> SELECT SUBTIME('1997-12-31 23:59:59.999999','1 1:1:1.000002');
              -> '1997-12-30 22:58:58.999997'
      mysql> SELECT SUBTIME('01:00:00.999999', '02:00:00.999998');
              -> '-00:59:59.999999'

  `SUBTIME()` was added in MySQL 4.1.1.

- `SYSDATE()`

  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. (There is no `.uuuuuu` part before MySQL 4.1.13.)

- `TIME(`expr`)`

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

      mysql> SELECT TIME('2003-12-31 01:02:03');
              -> '01:02:03'
      mysql> SELECT TIME('2003-12-31 01:02:03.000123');
              -> '01:02:03.000123'

  `TIME()` is available as of MySQL 4.1.1.

- `TIMEDIFF(`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.

      mysql> SELECT TIMEDIFF('2000:01:01 00:00:00',
          ->                 '2000:01:01 00:00:00.000001');
              -> '-00:00:00.000001'
      mysql> SELECT TIMEDIFF('1997-12-31 23:59:59.000001',
          ->                 '1997-12-30 01:01:01.000002');
              -> '46:58:57.999999'

  `TIMEDIFF()` was added in MySQL 4.1.1.

- `TIMESTAMP(`expr`)`, `TIMESTAMP(`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.

      mysql> SELECT TIMESTAMP('2003-12-31');
              -> '2003-12-31 00:00:00'
      mysql> SELECT TIMESTAMP('2003-12-31 12:00:00','12:00:00');
              -> '2004-01-01 00:00:00'

  `TIMESTAMP()` is available as of MySQL 4.1.1.

- `TIME_FORMAT(`time`,`format`)`

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

      mysql> SELECT TIME_FORMAT('100:00:00', '%H %k %h %I %l');
              -> '100 100 04 04 4'

- `TIME_TO_SEC(`time`)`

  Returns the `time` argument, converted to seconds.

      mysql> SELECT TIME_TO_SEC('22:23:00');
              -> 80580
      mysql> SELECT TIME_TO_SEC('00:39:38');
              -> 2378

- `TO_DAYS(`date`)`

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

      mysql> SELECT TO_DAYS(950501);
              -> 728779
      mysql> SELECT TO_DAYS('1997-10-07');
              -> 729669

  `TO_DAYS()` is not intended for use with values that precede the advent of the Gregorian calendar (1582), because it does not take into account the days that were lost when the calendar was changed. For dates before 1582 (and possibly a later year in other locales), results from this function are not reliable. See Section 11.7, “What Calendar Is Used By MySQL?”, for details.

  Remember that MySQL converts two-digit year values in dates to four-digit form using the rules in Section 10.3, “Date and Time Types”. For example, `'1997-10-07'` and `'97-10-07'` are seen as identical dates:

      mysql> SELECT TO_DAYS('1997-10-07'), TO_DAYS('97-10-07');
              -> 729669, 729669

- `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 as described in Section 9.9, “MySQL Server Time Zone Support”.

      mysql> SELECT UNIX_TIMESTAMP();
              -> 1196440210
      mysql> SELECT UNIX_TIMESTAMP('2007-11-30 10:30:19');
              -> 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`, but please note that only basic range checking is performed (year from `1970` to `2038`, month from `01` to `12`, day from `01` from `31`).

  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:

      mysql> SELECT UNIX_TIMESTAMP('2005-03-27 03:00:00');
      +---------------------------------------+
      | UNIX_TIMESTAMP('2005-03-27 03:00:00') |
      +---------------------------------------+
      |                            1111885200 |
      +---------------------------------------+
      mysql> SELECT UNIX_TIMESTAMP('2005-03-27 02:00:00');
      +---------------------------------------+
      | UNIX_TIMESTAMP('2005-03-27 02:00:00') |
      +---------------------------------------+
      |                            1111885200 |
      +---------------------------------------+
      mysql> SELECT FROM_UNIXTIME(1111885200);
      +---------------------------+
      | 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. See Section 11.9, “Cast Functions and Operators”.

- `UTC_DATE`, `UTC_DATE()`

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

      mysql> SELECT UTC_DATE(), UTC_DATE() + 0;
              -> '2003-08-14', 20030814

  `UTC_DATE()` is available as of MySQL 4.1.1.

- `UTC_TIME`, `UTC_TIME()`

  Returns the current UTC time as a value in `'HH:MM:SS'` or `HHMMSS.uuuuuu` format, depending on whether the function is used in a string or numeric context. (There is no `.uuuuuu` part before MySQL 4.1.13.)

      mysql> SELECT UTC_TIME(), UTC_TIME() + 0;
              -> '18:07:53', 180753.000000

  `UTC_TIME()` is available as of MySQL 4.1.1.

- `UTC_TIMESTAMP`, `UTC_TIMESTAMP()`

  Returns the current UTC date and time as a value in `'YYYY-MM-DD HH:MM:SS'` or `YYYYMMDDHHMMSS.uuuuuu` format, depending on whether the function is used in a string or numeric context. (There is no `.uuuuuu` part before MySQL 4.1.13.)

      mysql> SELECT UTC_TIMESTAMP(), UTC_TIMESTAMP() + 0;
              -> '2003-08-14 18:08:04', 20030814180804.000000

  `UTC_TIMESTAMP()` is available as of MySQL 4.1.1.

- `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 (or `0` before MySQL 4.0.14). See Section 5.1.3, “System Variables”.

  The following table describes how the `mode` argument works.

  | First day |  |
  Mode | 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

  A `mode` value of `3` can be used as of MySQL 4.0.5. Values of `4` and above can be used as of MySQL 4.0.17.

      mysql> SELECT WEEK('1998-02-20');
              -> 7
      mysql> SELECT WEEK('1998-02-20',0);
              -> 7
      mysql> SELECT WEEK('1998-02-20',1);
              -> 8
      mysql> SELECT WEEK('1998-12-31',1);
              -> 53

  Note: In MySQL 4.0, `WEEK(`date`,0)` was changed to match the calendar in the USA. Before that, `WEEK()` was calculated incorrectly for dates in the USA. (In effect, `WEEK(`date`)` and `WEEK(`date`,0)` were incorrect for all cases.)

  Note that if a date falls in the last week of the previous year, MySQL returns `0` if you do not use `2`, `3`, `6`, or `7` as the optional `mode` argument:

      mysql> SELECT YEAR('2000-01-01'), WEEK('2000-01-01',0);
              -> 2000, 0

  One might argue that MySQL should return `52` for the `WEEK()` function, because the given date actually occurs in the 52nd week of 1999. We decided to return `0` instead because we want the function to return “the week number in the given year.” This makes use of the `WEEK()` function reliable when combined with other functions that extract a date part from a date.

  If you would prefer the result to be evaluated with respect to the year that contains the first day of the week for the given date, use `0`, `2`, `5`, or `7` as the optional `mode` argument.

      mysql> SELECT WEEK('2000-01-01',2);
              -> 52

  Alternatively, use the `YEARWEEK()` function:

      mysql> SELECT YEARWEEK('2000-01-01');
              -> 199952
      mysql> SELECT MID(YEARWEEK('2000-01-01'),5,2);
              -> '52'

- `WEEKDAY(`date`)`

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

      mysql> SELECT WEEKDAY('1998-02-03 22:23:00');
              -> 1
      mysql> SELECT WEEKDAY('1997-11-05');
              -> 2

- `WEEKOFYEAR(`date`)`

  Returns the calendar week of the date as a number in the range from `1` to `53`. `WEEKOFYEAR()` is a compatibility function that is equivalent to `WEEK(`date`,3)`.

      mysql> SELECT WEEKOFYEAR('1998-02-20');
              -> 8

  `WEEKOFYEAR()` is available as of MySQL 4.1.1.

- `YEAR(`date`)`

  Returns the year for `date`, in the range `1000` to `9999`, or `0` for the “zero” date.

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

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

      mysql> SELECT YEARWEEK('1987-01-01');
              -> 198653

  Note that the week number is different from what the `WEEK()` function would return (`0`) for optional arguments `0` or `1`, as `WEEK()` then returns the week in the context of the given year.

  `YEARWEEK()` was added in MySQL 3.23.8.

## 11.7. What Calendar Is Used By MySQL?

MySQL uses what is known as a proleptic Gregorian calendar.

Every country that has switched from the Julian to the Gregorian calendar has had to discard at least ten days during the switch. To see how this works, consider the month of October 1582, when the first Julian-to-Gregorian switch occurred:

Monday | Tuesday | Wednesday | Thursday | Friday | Saturday | Sunday
1 | 2 | 3 | 4 | 15 | 16 | 17
18 | 19 | 20 | 21 | 22 | 23 | 24
25 | 26 | 27 | 28 | 29 | 30 | 31

There are no dates between October 4 and October 15. This discontinuity is called the cutover. Any dates before the cutover are Julian, and any dates following the cutover are Gregorian. Dates during a cutover are non-existent.

A calendar applied to dates when it wasn't actually in use is called proleptic. Thus, if we assume there was never a cutover and Gregorian rules always rule, we have a proleptic Gregorian calendar. This is what is used by MySQL, as is required by standard SQL. For this reason, dates prior to the cutover stored as MySQL `DATE` or `DATETIME` values must be adjusted to compensate for the difference. It is important to realize that the cutover did not occur at the same time in all countries, and that the later it happened, the more days were lost. For example, in Great Britain, it took place in 1752, when Wednesday September 2 was followed by Thursday September 14. Russia remained on the Julian calendar until 1918, losing 13 days in the process, and what is popularly referred to as its “October Revolution” occurred in November according to the Gregorian calendar.

## 11.8. Full-Text Search Functions

`MATCH (`col1`,`col2`,...) AGAINST (`expr` [`search_modifier`])`

    search_modifier: { IN BOOLEAN MODE | WITH QUERY EXPANSION }

As of MySQL 3.23.23, MySQL has support for full-text indexing and searching:

- A full-text index in MySQL is an index of type `FULLTEXT`.

- Full-text indexes can be used only with `MyISAM` tables, and can be created only for `CHAR`, `VARCHAR`, or `TEXT` columns.

- A `FULLTEXT` index definition can be given in the `CREATE TABLE` statement when a table is created, or added later using `ALTER TABLE` or `CREATE INDEX`.

- For large data sets, it is much faster to load your data into a table that has no `FULLTEXT` index and then create the index after that, than to load data into a table that has an existing `FULLTEXT` index.

Full-text searching is performed using `MATCH() ... AGAINST` syntax. `MATCH()` takes a comma-separated list that names the columns to be searched. `AGAINST` takes a string to search for, and an optional modifier that indicates what type of search to perform. The search string must be a literal string, not a variable or a column name. There are three types of full-text searches:

- A boolean search interprets the search string using the rules of a special query language. The string contains the words to search for. It can also contain operators that specify requirements such that a word must be present or absent in matching rows, or that it should be weighted higher or lower than usual. Common words such as “some” or “then” are stopwords and do not match if present in the search string. The `IN BOOLEAN MODE` modifier specifies a boolean search. For more information, see Section 11.8.2, “Boolean Full-Text Searches”.

- A natural language search interprets the search string as a phrase in natural human language (a phrase in free text). There are no special operators. The stopword list applies. In addition, words that are present in 50% or more of the rows are considered common and do not match. Full-text searches are natural language searches if no modifier is given.

- A query expansion search is a modification of a natural language search. The search string is used to perform a natural language search. Then words from the most relevant rows returned by the search are added to the search string and the search is done again. The query returns the rows from the second search. The `WITH QUERY EXPANSION` modifier specifies a query expansion search. For more information, see Section 11.8.3, “Full-Text Searches with Query Expansion”.

Constraints on full-text searching are listed in Section 11.8.5, “Full-Text Restrictions”.

### 11.8.1. Natural Language Full-Text Searches

By default, the `MATCH()` function performs a natural language search for a string against a text collection. A collection is a set of one or more columns included in a `FULLTEXT` index. The search string is given as the argument to `AGAINST()`. For each row in the table, `MATCH()` returns a relevance value; that is, a similarity measure between the search string and the text in that row in the columns named in the `MATCH()` list.

    mysql> CREATE TABLE articles (
        ->   id INT UNSIGNED AUTO_INCREMENT NOT NULL PRIMARY KEY,
        ->   title VARCHAR(200),
        ->   body TEXT,
        ->   FULLTEXT (title,body)
        -> );
    Query OK, 0 rows affected (0.00 sec)

    mysql> INSERT INTO articles (title,body) VALUES
        -> ('MySQL Tutorial','DBMS stands for DataBase ...'),
        -> ('How To Use MySQL Well','After you went through a ...'),
        -> ('Optimizing MySQL','In this tutorial we will show ...'),
        -> ('1001 MySQL Tricks','1. Never run mysqld as root. 2. ...'),
        -> ('MySQL vs. YourSQL','In the following database comparison ...'),
        -> ('MySQL Security','When configured properly, MySQL ...');
    Query OK, 6 rows affected (0.00 sec)
    Records: 6  Duplicates: 0  Warnings: 0

    mysql> SELECT * FROM articles
        -> WHERE MATCH (title,body) AGAINST ('database');
    +----+-------------------+------------------------------------------+
    | id | title             | body                                     |
    +----+-------------------+------------------------------------------+
    |  5 | MySQL vs. YourSQL | In the following database comparison ... |
    |  1 | MySQL Tutorial    | DBMS stands for DataBase ...             |
    +----+-------------------+------------------------------------------+
    2 rows in set (0.00 sec)

By default, the search is performed in case-insensitive fashion. In MySQL 4.1 and up, you can make a full-text search by using a binary collation for the indexed columns. For example, a column that has a character set of `latin1` character set of can be assigned a collation of `latin1_bin` to make it case sensitive for full-text searches.

When `MATCH()` is used in a `WHERE` clause, as in the example shown earlier, the rows returned are automatically sorted with the highest relevance first. Relevance values are non-negative floating-point numbers. Zero relevance means no similarity. Relevance is computed based on the number of words in the row, the number of unique words in that row, the total number of words in the collection, and the number of documents (rows) that contain a particular word.

To simply count matches, you could use a query like this:

    mysql> SELECT COUNT(*) FROM articles
        -> WHERE MATCH (title,body)
        -> AGAINST ('database');
    +----------+
    | COUNT(*) |
    +----------+
    |        2 |
    +----------+
    1 row in set (0.00 sec)

However, you might find it quicker to rewrite the query as follows:

    mysql> SELECT
        -> COUNT(IF(MATCH (title,body) AGAINST ('database'), 1, NULL))
        -> AS count
        -> FROM articles;
    +-------+
    | count |
    +-------+
    |     2 |
    +-------+
    1 row in set (0.00 sec)

The first query sorts the results by relevance whereas the second does not. However, the second query performs a full table scan and the first does not. The first may be faster if the search matches few rows; otherwise, the second may be faster because it would read many rows anyway.

For natural-language full-text searches, it is a requirement that the columns named in the `MATCH()` function be the same columns included in some `FULLTEXT` index in your table. For the preceding query, note that the columns named in the `MATCH()` function (`title` and `body`) are the same as those named in the definition of the `article` table's `FULLTEXT` index. If you wanted to search the `title` or `body` separately, you would need to create separate `FULLTEXT` indexes for each column.

It is also possible to perform a boolean search or a search with query expansion. These search types are described in Section 11.8.2, “Boolean Full-Text Searches”, and Section 11.8.3, “Full-Text Searches with Query Expansion”.

A full-text search that uses an index can name columns only from a single table in the `MATCH()` clause because an index cannot span multiple tables. A boolean search can be done in the absence of an index (albeit more slowly), in which case it is possible to name columns from multiple tables.

The preceding example is a basic illustration that shows how to use the `MATCH()` function where rows are returned in order of decreasing relevance. The next example shows how to retrieve the relevance values explicitly. Returned rows are not ordered because the `SELECT` statement includes neither `WHERE` nor `ORDER BY` clauses:

    mysql> SELECT id, MATCH (title,body) AGAINST ('Tutorial')
        -> FROM articles;
    +----+-----------------------------------------+
    | id | MATCH (title,body) AGAINST ('Tutorial') |
    +----+-----------------------------------------+
    |  1 |                        0.65545833110809 |
    |  2 |                                       0 |
    |  3 |                        0.66266459226608 |
    |  4 |                                       0 |
    |  5 |                                       0 |
    |  6 |                                       0 |
    +----+-----------------------------------------+
    6 rows in set (0.00 sec)

The following example is more complex. The query returns the relevance values and it also sorts the rows in order of decreasing relevance. To achieve this result, you should specify `MATCH()` twice: once in the `SELECT` list and once in the `WHERE` clause. This causes no additional overhead, because the MySQL optimizer notices that the two `MATCH()` calls are identical and invokes the full-text search code only once.

    mysql> SELECT id, body, MATCH (title,body) AGAINST
        -> ('Security implications of running MySQL as root') AS score
        -> FROM articles WHERE MATCH (title,body) AGAINST
        -> ('Security implications of running MySQL as root');
    +----+-------------------------------------+-----------------+
    | id | body                                | score           |
    +----+-------------------------------------+-----------------+
    |  4 | 1. Never run mysqld as root. 2. ... | 1.5219271183014 |
    |  6 | When configured properly, MySQL ... | 1.3114095926285 |
    +----+-------------------------------------+-----------------+
    2 rows in set (0.00 sec)

The MySQL `FULLTEXT` implementation regards any sequence of true word characters (letters, digits, and underscores) as a word. That sequence may also contain apostrophes (“`'`”), but not more than one in a row. This means that `aaa'bbb` is regarded as one word, but `aaa''bbb` is regarded as two words. Apostrophes at the beginning or the end of a word are stripped by the `FULLTEXT` parser; `'aaa'bbb'` would be parsed as `aaa'bbb`.

The `FULLTEXT` parser determines where words start and end by looking for certain delimiter characters; for example, “`` ” (space), “`,`” (comma), and “`.`” (period). If words are not separated by delimiters (as in, for example, Chinese), the `FULLTEXT` parser cannot determine where a word begins or ends. To be able to add words or other indexed terms in such languages to a `FULLTEXT` index, you must preprocess them so that they are separated by some arbitrary delimiter such as “`"`”.

Some words are ignored in full-text searches:

- Any word that is too short is ignored. The default minimum length of words that are found by full-text searches is four characters.

- Words in the stopword list are ignored. A stopword is a word such as “the” or “some” that is so common that it is considered to have zero semantic value. There is a built-in stopword list, but it can be overwritten by a user-defined list.

The default stopword list is given in Section 11.8.4, “Full-Text Stopwords”. The default minimum word length and stopword list can be changed as described in Section 11.8.6, “Fine-Tuning MySQL Full-Text Search”.

Every correct word in the collection and in the query is weighted according to its significance in the collection or query. Consequently, a word that is present in many documents has a lower weight (and may even have a zero weight), because it has lower semantic value in this particular collection. Conversely, if the word is rare, it receives a higher weight. The weights of the words are combined to compute the relevance of the row.

Such a technique works best with large collections (in fact, it was carefully tuned this way). For very small tables, word distribution does not adequately reflect their semantic value, and this model may sometimes produce bizarre results. For example, although the word “MySQL” is present in every row of the `articles` table shown earlier, a search for the word produces no results:

    mysql> SELECT * FROM articles
        -> WHERE MATCH (title,body) AGAINST ('MySQL');
    Empty set (0.00 sec)

The search result is empty because the word “MySQL” is present in at least 50% of the rows. As such, it is effectively treated as a stopword. For large data sets, this is the most desirable behavior: A natural language query should not return every second row from a 1GB table. For small data sets, it may be less desirable.

A word that matches half of the rows in a table is less likely to locate relevant documents. In fact, it most likely finds plenty of irrelevant documents. We all know this happens far too often when we are trying to find something on the Internet with a search engine. It is with this reasoning that rows containing the word are assigned a low semantic value for the particular data set in which they occur. A given word may reach the 50% threshold in one data set but not another.

The 50% threshold has a significant implication when you first try full-text searching to see how it works: If you create a table and insert only one or two rows of text into it, every word in the text occurs in at least 50% of the rows. As a result, no search returns any results. Be sure to insert at least three rows, and preferably many more. Users who need to bypass the 50% limitation can use the boolean search mode; see Section 11.8.2, “Boolean Full-Text Searches”.

### 11.8.2. Boolean Full-Text Searches

As of version 4.0.1, MySQL can perform boolean full-text searches using the `IN BOOLEAN MODE` modifier:

    mysql> SELECT * FROM articles WHERE MATCH (title,body)
        -> AGAINST ('+MySQL -YourSQL' IN BOOLEAN MODE);
    +----+-----------------------+-------------------------------------+
    | id | title                 | body                                |
    +----+-----------------------+-------------------------------------+
    |  1 | MySQL Tutorial        | DBMS stands for DataBase ...        |
    |  2 | How To Use MySQL Well | After you went through a ...        |
    |  3 | Optimizing MySQL      | In this tutorial we will show ...   |
    |  4 | 1001 MySQL Tricks     | 1. Never run mysqld as root. 2. ... |
    |  6 | MySQL Security        | When configured properly, MySQL ... |
    +----+-----------------------+-------------------------------------+

The `+` and `-` operators indicate that a word is required to be present or absent, respectively, for a match to occur. Thus, this query retrieves all the rows that contain the word “MySQL” but that do not contain the word “YourSQL”.

Boolean full-text searches have these characteristics:

- They do not use the 50% threshold.

- They do not automatically sort rows in order of decreasing relevance. You can see this from the preceding query result: The row with the highest relevance is the one that contains “MySQL” twice, but it is listed last, not first.

- They can work even without a `FULLTEXT` index, although a search executed in this fashion would be quite slow.

- The minimum and maximum word length full-text parameters apply.

- The stopword list applies.

The boolean full-text search capability supports the following operators:

- `+`

  A leading plus sign indicates that this word must be present in each row that is returned.

- `-`

  A leading minus sign indicates that this word must not be present in any of the rows that are returned.

  Note: The `-` operator acts only to exclude rows that are otherwise matched by other search terms. Thus, a boolean-mode search that contains only terms preceded by `-` returns an empty result. It does not return “all rows except those containing any of the excluded terms.”

- (no operator)

  By default (when neither `+` nor `-` is specified) the word is optional, but the rows that contain it are rated higher. This mimics the behavior of `MATCH() ... AGAINST()` without the `IN BOOLEAN MODE` modifier.

- `> <`

  These two operators are used to change a word's contribution to the relevance value that is assigned to a row. The `>` operator increases the contribution and the `<` operator decreases it. See the example following this list.

- `( )`

  Parentheses group words into subexpressions. Parenthesized groups can be nested.

- `~`

  A leading tilde acts as a negation operator, causing the word's contribution to the row's relevance to be negative. This is useful for marking “noise” words. A row containing such a word is rated lower than others, but is not excluded altogether, as it would be with the `-` operator.

- `*`

  The asterisk serves as the truncation (or wildcard) operator. Unlike the other operators, it should be appended to the word to be affected. Words match if they begin with the word preceding the `*` operator.

  If a stopword or too-short word is specified with the truncation operator, it will not be stripped from a boolean query. For example, a search for `'+word +stopword*'` will likely return fewer rows than a search for `'+word +stopword'` because the former query remains as is and requires `stopword*` to be present in a document. The latter query is transformed to `+word`.

- `"`

  A phrase that is enclosed within double quote (“`"`”) characters matches only rows that contain the phrase literally, as it was typed. The full-text engine splits the phrase into words, performs a search in the `FULLTEXT` index for the words. The engine then performs a substring search for the phrase in the records that are found, so the match must include non-word characters in the phrase. For example, `"test phrase"` does not match `"test, phrase"`.

  If the phrase contains no words that are in the index, the result is empty. For example, if all words are either stopwords or shorter than the minimum length of indexed words, the result is empty.

The following examples demonstrate some search strings that use boolean full-text operators:

- `'apple banana'`

  Find rows that contain at least one of the two words.

- `'+apple +juice'`

  Find rows that contain both words.

- `'+apple macintosh'`

  Find rows that contain the word “apple”, but rank rows higher if they also contain “macintosh”.

- `'+apple -macintosh'`

  Find rows that contain the word “apple” but not “macintosh”.

- `'+apple ~macintosh'`

  Find rows that contain the word “apple”, but if the row also contains the word “macintosh”, rate it lower than if row does not. This is “softer” than a search for `'+apple -macintosh'`, for which the presence of “macintosh” causes the row not to be returned at all.

- `'+apple +(>turnover <strudel)'`

  Find rows that contain the words “apple” and “turnover”, or “apple” and “strudel” (in any order), but rank “apple turnover” higher than “apple strudel”.

- `'apple*'`

  Find rows that contain words such as “apple”, “apples”, “applesauce”, or “applet”.

- `'"some words"'`

  Find rows that contain the exact phrase “some words” (for example, rows that contain “some words of wisdom” but not “some noise words”). Note that the “`"`” characters that enclose the phrase are operator characters that delimit the phrase. They are not the quotes that enclose the search string itself.

### 11.8.3. Full-Text Searches with Query Expansion

As of MySQL 4.1.1, full-text search supports query expansion (in particular, its variant “blind query expansion”). This is generally useful when a search phrase is too short, which often means that the user is relying on implied knowledge that the full-text search engine lacks. For example, a user searching for “database” may really mean that “MySQL”, “Oracle”, “DB2”, and “RDBMS” all are phrases that should match “databases” and should be returned, too. This is implied knowledge.

Blind query expansion (also known as automatic relevance feedback) is enabled by adding `WITH QUERY EXPANSION` following the search phrase. It works by performing the search twice, where the search phrase for the second search is the original search phrase concatenated with the few most highly relevant documents from the first search. Thus, if one of these documents contains the word “databases” and the word “MySQL”, the second search finds the documents that contain the word “MySQL” even if they do not contain the word “database”. The following example shows this difference:

    mysql> SELECT * FROM articles
        -> WHERE MATCH (title,body) AGAINST ('database');
    +----+-------------------+------------------------------------------+
    | id | title             | body                                     |
    +----+-------------------+------------------------------------------+
    |  5 | MySQL vs. YourSQL | In the following database comparison ... |
    |  1 | MySQL Tutorial    | DBMS stands for DataBase ...             |
    +----+-------------------+------------------------------------------+
    2 rows in set (0.00 sec)

    mysql> SELECT * FROM articles
        -> WHERE MATCH (title,body)
        -> AGAINST ('database' WITH QUERY EXPANSION);
    +----+-------------------+------------------------------------------+
    | id | title             | body                                     |
    +----+-------------------+------------------------------------------+
    |  1 | MySQL Tutorial    | DBMS stands for DataBase ...             |
    |  5 | MySQL vs. YourSQL | In the following database comparison ... |
    |  3 | Optimizing MySQL  | In this tutorial we will show ...        |
    +----+-------------------+------------------------------------------+
    3 rows in set (0.00 sec)

Another example could be searching for books by Georges Simenon about Maigret, when a user is not sure how to spell “Maigret”. A search for “Megre and the reluctant witnesses” finds only “Maigret and the Reluctant Witnesses” without query expansion. A search with query expansion finds all books with the word “Maigret” on the second pass.

### Note

Because blind query expansion tends to increase noise significantly by returning non-relevant documents, it is meaningful to use only when a search phrase is rather short.

### 11.8.4. Full-Text Stopwords

The following table shows the default list of full-text stopwords.

a's | able | about | above | according
accordingly | across | actually | after | afterwards
again | against | ain't | all | allow
allows | almost | alone | along | already
also | although | always | am | among
amongst | an | and | another | any
anybody | anyhow | anyone | anything | anyway
anyways | anywhere | apart | appear | appreciate
appropriate | are | aren't | around | as
aside | ask | asking | associated | at
available | away | awfully | be | became
because | become | becomes | becoming | been
before | beforehand | behind | being | believe
below | beside | besides | best | better
between | beyond | both | brief | but
by | c'mon | c's | came | can
can't | cannot | cant | cause | causes
certain | certainly | changes | clearly | co
com | come | comes | concerning | consequently
consider | considering | contain | containing | contains
corresponding | could | couldn't | course | currently
definitely | described | despite | did | didn't
different | do | does | doesn't | doing
don't | done | down | downwards | during
each | edu | eg | eight | either
else | elsewhere | enough | entirely | especially
et | etc | even | ever | every
everybody | everyone | everything | everywhere | ex
exactly | example | except | far | few
fifth | first | five | followed | following
follows | for | former | formerly | forth
four | from | further | furthermore | get
gets | getting | given | gives | go
goes | going | gone | got | gotten
greetings | had | hadn't | happens | hardly
has | hasn't | have | haven't | having
he | he's | hello | help | hence
her | here | here's | hereafter | hereby
herein | hereupon | hers | herself | hi
him | himself | his | hither | hopefully
how | howbeit | however | i'd | i'll
i'm | i've | ie | if | ignored
immediate | in | inasmuch | inc | indeed
indicate | indicated | indicates | inner | insofar
instead | into | inward | is | isn't
it | it'd | it'll | it's | its
itself | just | keep | keeps | kept
know | knows | known | last | lately
later | latter | latterly | least | less
lest | let | let's | like | liked
likely | little | look | looking | looks
ltd | mainly | many | may | maybe
me | mean | meanwhile | merely | might
more | moreover | most | mostly | much
must | my | myself | name | namely
nd | near | nearly | necessary | need
needs | neither | never | nevertheless | new
next | nine | no | nobody | non
none | noone | nor | normally | not
nothing | novel | now | nowhere | obviously
of | off | often | oh | ok
okay | old | on | once | one
ones | only | onto | or | other
others | otherwise | ought | our | ours
ourselves | out | outside | over | overall
own | particular | particularly | per | perhaps
placed | please | plus | possible | presumably
probably | provides | que | quite | qv
rather | rd | re | really | reasonably
regarding | regardless | regards | relatively | respectively
right | said | same | saw | say
saying | says | second | secondly | see
seeing | seem | seemed | seeming | seems
seen | self | selves | sensible | sent
serious | seriously | seven | several | shall
she | should | shouldn't | since | six
so | some | somebody | somehow | someone
something | sometime | sometimes | somewhat | somewhere
soon | sorry | specified | specify | specifying
still | sub | such | sup | sure
t's | take | taken | tell | tends
th | than | thank | thanks | thanx
that | that's | thats | the | their
theirs | them | themselves | then | thence
there | there's | thereafter | thereby | therefore
therein | theres | thereupon | these | they
they'd | they'll | they're | they've | think
third | this | thorough | thoroughly | those
though | three | through | throughout | thru
thus | to | together | too | took
toward | towards | tried | tries | truly
try | trying | twice | two | un
under | unfortunately | unless | unlikely | until
unto | up | upon | us | use
used | useful | uses | using | usually
value | various | very | via | viz
vs | want | wants | was | wasn't
way | we | we'd | we'll | we're
we've | welcome | well | went | were
weren't | what | what's | whatever | when
whence | whenever | where | where's | whereafter
whereas | whereby | wherein | whereupon | wherever
whether | which | while | whither | who
who's | whoever | whole | whom | whose
why | will | willing | wish | with
within | without | won't | wonder | would
would | wouldn't | yes | yet | you
you'd | you'll | you're | you've | your
yours | yourself | yourselves | zero |

### 11.8.5. Full-Text Restrictions

- Full-text searches are supported for `MyISAM` tables only.

- As of MySQL 4.1.1, full-text searches can be used with most multi-byte character sets. The exception is that for Unicode, the `utf8` character set can be used, but not the `ucs2` character set. However, although `FULLTEXT` indexes on `ucs2` columns cannot be used, you can perform `IN BOOLEAN MODE` searches on a `ucs2` column that has no such index.

- Ideographic languages such as Chinese and Japanese do not have word delimiters. Therefore, the `FULLTEXT` parser cannot determine where words begin and end in these and other such languages. The implications of this and some workarounds for the problem are described in Section 11.8, “Full-Text Search Functions”.

- As of MySQL 4.1, the use of multiple character sets within a single table is supported. However, all columns in a `FULLTEXT` index must use the same character set and collation.

- The `MATCH()` column list must match exactly the column list in some `FULLTEXT` index definition for the table, unless this `MATCH()` is `IN BOOLEAN MODE`. Boolean-mode searches can be done on non-indexed columns, although they are likely to be slow.

- The argument to `AGAINST()` must be a constant string.

### 11.8.6. Fine-Tuning MySQL Full-Text Search

MySQL's full-text search capability has few user-tunable parameters. You can exert more control over full-text searching behavior if you have a MySQL source distribution because some changes require source code modifications. See Section 2.9, “MySQL Installation Using a Source Distribution”.

Note that full-text search is carefully tuned for the most effectiveness. Modifying the default behavior in most cases can actually decrease effectiveness. Do not alter the MySQL sources unless you know what you are doing.

Most full-text variables described in this section must be set at server startup time. A server restart is required to change them; they cannot be modified while the server is running.

Some variable changes require that you rebuild the `FULLTEXT` indexes in your tables. Instructions for doing this are given at the end of this section.

- The minimum and maximum lengths of words to be indexed are defined by the `ft_min_word_len` and `ft_max_word_len` system variables (available as of MySQL 4.0.0). See Section 5.1.3, “System Variables”.) The default minimum value is four characters; the default maximum is version dependent. If you change either value, you must rebuild your `FULLTEXT` indexes. For example, if you want three-character words to be searchable, you can set the `ft_min_word_len` variable by putting the following lines in an option file:

      [mysqld]
      ft_min_word_len=3

  Then you must restart the server and rebuild your `FULLTEXT` indexes. Note particularly the remarks regarding myisamchk in the instructions following this list.

- To override the default stopword list, set the `ft_stopword_file` system variable (available as of MySQL 4.0.10). See Section 5.1.3, “System Variables”.) The variable value should be the pathname of the file containing the stopword list, or the empty string to disable stopword filtering. After changing the value of this variable or the contents of the stopword file, restart the server and rebuild your `FULLTEXT` indexes.

  The stopword list is free-form. That is, you may use any non-alphanumeric character such as newline, space, or comma to separate stopwords. Exceptions are the underscore character (“`_`”) and a single apostrophe (“`'`”) which are treated as part of a word. The character set of the stopword list is the server's default character set; see Section 9.1.3.1, “Server Character Set and Collation”.

- The 50% threshold for natural language searches is determined by the particular weighting scheme chosen. To disable it, look for the following line in `myisam/ftdefs.h`:

      #define GWS_IN_USE GWS_PROB

  Change that line to this:

      #define GWS_IN_USE GWS_FREQ

  Then recompile MySQL. There is no need to rebuild the indexes in this case.

  ### Note

  By making this change, you severely decrease MySQL's ability to provide adequate relevance values for the `MATCH()` function. If you really need to search for such common words, it would be better to search using `IN BOOLEAN MODE` instead, which does not observe the 50% threshold.

- To change the operators used for boolean full-text searches, set the `ft_boolean_syntax` system variable (available as of MySQL 4.0.1). The variable can be changed while the server is running, but you must have the `SUPER` privilege to do so. No rebuilding of indexes is necessary in this case. See Section 5.1.3, “System Variables”, which describes the rules governing how to set this variable.

- If you want to change the set of characters that are considered word characters, you can do so in two ways. Suppose that you want to treat the hyphen character ('-') as a word character. Use either of these methods:

  - Modify the MySQL source: In `myisam/ftdefs.h`, see the `true_word_char()` and `misc_word_char()` macros. Add `'-'` to one of those macros and recompile MySQL.

  - Modify a character set file: This requires no recompilation. The `true_word_char()` macro uses a “character type” table to distinguish letters and numbers from other characters. . You can edit the `<ctype><map>` contents in one of the character set XML files to specify that `'-'` is a “letter.” Then use the given character set for your `FULLTEXT` indexes.

  After making the modification, you must rebuild the indexes for each table that contains any `FULLTEXT` indexes.

If you modify full-text variables that affect indexing (`ft_min_word_len`, `ft_max_word_len`, or `ft_stopword_file`), or if you change the stopword file itself, you must rebuild your `FULLTEXT` indexes after making the changes and restarting the server. To rebuild the indexes in this case, it is sufficient to do a `QUICK` repair operation:

    mysql> REPAIR TABLE tbl_name QUICK;

Each table that contains any `FULLTEXT` index must be repaired as just shown. Otherwise, queries for the table may yield incorrect results, and modifications to the table will cause the server to see the table as corrupt and in need of repair.

With regard specifically to using the `IN BOOLEAN MODE` capability, if you upgrade from MySQL 3.23 to 4.0 or later, it is necessary to replace the index header as well. To do this, perform a `USE_FRM` repair operation:

    mysql> REPAIR TABLE tbl_name USE_FRM;

This is necessary because boolean full-text searches require a flag in the index header that was not present in MySQL 3.23, and that is not added if you do only a `QUICK` repair. If you attempt a boolean full-text search without rebuilding the indexes this way, the search returns incorrect results.

Note that if you use myisamchk to perform an operation that modifies table indexes (such as repair or analyze), the `FULLTEXT` indexes are rebuilt using the default full-text parameter values for minimum word length, maximum word length, and stopword file unless you specify otherwise. This can result in queries failing.

The problem occurs because these parameters are known only by the server. They are not stored in `MyISAM` index files. To avoid the problem if you have modified the minimum or maximum word length or stopword file values used by the server, specify the same `ft_min_word_len`, `ft_max_word_len`, and `ft_stopword_file` values to myisamchk that you use for mysqld. For example, if you have set the minimum word length to 3, you can repair a table with myisamchk like this:

    shell> myisamchk --recover --ft_min_word_len=3 tbl_name.MYI

To ensure that myisamchk and the server use the same values for full-text parameters, place each one in both the `[mysqld]` and `[myisamchk]` sections of an option file:

    [mysqld]
    ft_min_word_len=3

    [myisamchk]
    ft_min_word_len=3

An alternative to using myisamchk is to use the `REPAIR TABLE`, `ANALYZE TABLE`, `OPTIMIZE TABLE`, or `ALTER TABLE` statements. These statements are performed by the server, which knows the proper full-text parameter values to use.

## 11.9. Cast Functions and Operators

Name | Description
--- | ---
`BINARY` | Cast a string to a binary string
`CAST()` | Cast a value as a certain type
`Convert()` | Cast a value as a certain type

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

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

  In a comparison, `BINARY` affects the entire operation; it can be given before either operand with the same result.

  `BINARY` was added in MySQL 3.23.0. As of MySQL 4.0.2, `BINARY `str`` is a shorthand for `CAST(`str` AS BINARY)`.

  Note that in some contexts, if you cast an indexed column to `BINARY`, MySQL 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` (and `BINARY[`N`]` as of MySQL 4.1.1)

  - `CHAR` (and `CHAR[`N`]` as of MySQL 4.1.1)

  - `DATE`

  - `DATETIME`

  - `SIGNED [INTEGER]`

  - `TIME`

  - `UNSIGNED [INTEGER]`

  `BINARY` produces a string with the `BINARY` data type. See Section 10.4.2, “The `BINARY` and `VARBINARY` Types” for a description of how this affects comparisons. If the optional length `N` is given, `BINARY(`N`)` causes the cast to use no more than `N` bytes of the argument. Similarly, `CHAR[`N`]` causes the cast to use no more than `N` characters of the argument.

  `CAST()` and `CONVERT()` are available as of MySQL 4.0.2. The `CHAR` conversion type is available as of 4.0.6. The `USING` form of `CONVERT()` is available as of 4.1.0.

  `CAST()` and `CONVERT(... USING ...)` are standard SQL syntax. The non-`USING` form of `CONVERT()` is ODBC syntax.

  `CONVERT()` with `USING` is used to convert data between different character sets. In MySQL, transcoding names are the same as the corresponding character set names. For example, this statement converts the string `'abc'` in the default character set to the corresponding string in the `utf8` character set:

      SELECT CONVERT('abc' USING utf8);

If you want to compare a `BLOB` value or other binary string in case-insensitive fashion, you can do so as follows:

- Before MySQL 4.1.1, use the `UPPER()` function to convert the binary string to uppercase before performing the comparison:

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

  If the comparison value is lowercase, convert the string value using `LOWER()` instead.

- For MySQL 4.1.1 and up, 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:

      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:

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

The functions also can be useful for sorting `ENUM` columns in lexical order. Normally, sorting of `ENUM` columns occurs using the internal numeric values. Casting the values to `CHAR` results in a lexical sort:

    SELECT enum_col FROM tbl_name ORDER BY CAST(enum_col AS CHAR);

`CAST(`str` AS BINARY)` is the same thing as `BINARY `str``. `CAST(`expr` AS CHAR)` treats the expression as a string with the default character set.

### Note

In MySQL 4.0, a `CAST()` to `DATE`, `DATETIME`, or `TIME` only marks the column to be a specific type but does not change the value of the column.

As of MySQL 4.1.0, the value is converted to the correct column type when it is sent to the user (this is a feature of how the new protocol in 4.1 sends date information to the client):

    mysql> SELECT CAST(NOW() AS DATE);
           -> 2003-05-26

As of MySQL 4.1.1, `CAST()` also changes the result if you use it as part of a more complex expression such as `CONCAT('Date: ',CAST(NOW() AS DATE))`.

You should not use `CAST()` to extract data in different formats but instead use string functions like `LEFT()` or `EXTRACT()`. See Section 11.6, “Date and Time Functions”.

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:

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

If you use a number in string context, the number automatically is converted to a `BINARY` string.

    mysql> SELECT CONCAT('hello you ',2);
            -> 'hello you 2'

MySQL supports arithmetic with both signed and unsigned 64-bit values. If you are using numeric operators (such as `+` 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.

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

Note that if either operand is a floating-point value, the result is a floating-point value and is not affected by the preceding rule. (In this context, `DECIMAL` column values are regarded as floating-point values.)

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

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

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

    mysql> SELECT (ucol1+0.0)-(ucol2+0.0) FROM ...;

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

If you have a problem with `UNSIGNED` columns in old MySQL applications when porting them to MySQL 4.0, you can use the `--sql-mode=NO_UNSIGNED_SUBTRACTION` option when starting mysqld. However, as long as you use this option, you are not able to make efficient use of the `BIGINT UNSIGNED` data type.

## 11.10. Other Functions

Name | Description
--- | ---
`AES_DECRYPT()` | Decrypt using AES
`AES_ENCRYPT()` | Encrypt using AES
`BENCHMARK()` | Repeatedly execute an expression
`BIT_COUNT()` | Return the number of bits that are set
`&` | Bitwise AND
`~` | Invert bits
`|` | Bitwise OR
`^` | Bitwise XOR
`CHARSET()`(v4.1.0) | Return the character set of the argument
`COERCIBILITY()`(v4.1.1) | Return the collation coercibility value of the string argument
`COLLATION()`(v4.1.0) | Return the collation of the string argument
`COMPRESS()`(v4.1.1) | Return result as a binary string
`CONNECTION_ID()` | Return the connection ID (thread ID) for the connection
`CURRENT_USER()`, `CURRENT_USER` | Return the username and hostname combination
`DATABASE()` | Return the default (current) database name
`DECODE()` | Decodes a string encrypted using ENCODE()
`DEFAULT()` | Return the default value for a table column
`DES_DECRYPT()` | Decrypt a string
`DES_ENCRYPT()` | Decrypt a string
`ENCODE()` | Encode a string
`ENCRYPT()` | Encrypt a string
`FOUND_ROWS()` | For a SELECT with a LIMIT clause, the number of rows that would be returned were there no LIMIT clause
`GET_LOCK()` | Get a named lock
`INET_ATON()` | Return the numeric value of an IP address
`INET_NTOA()` | Return the IP address from a numeric value
`IS_FREE_LOCK()` | Checks whether the named lock is free
`IS_USED_LOCK()`(v4.1.0) | Checks whether the named lock is in use. Return connection identifier if true.
`LAST_INSERT_ID()` | Value of the AUTOINCREMENT column for the last INSERT
`<<` | Left shift
`MASTER_POS_WAIT()` | Block until the slave has read and applied all updates up to the specified position
`MD5()` | Calculate MD5 checksum
`OLD_PASSWORD()`(v4.1) | Return the value of the old (pre-4.1) implementation of PASSWORD
`PASSWORD()` | Calculate and return a password string
`RELEASE_LOCK()` | Releases the named lock
`>>` | Right shift
`SESSION_USER()` | Synonym for USER()
`SHA1()`, `SHA()` | Calculate an SHA-1 160-bit checksum
`SYSTEM_USER()` | Synonym for USER()
`UNCOMPRESS()`(v4.1.1) | Uncompress a string compressed
`UNCOMPRESSED_LENGTH()`(v4.1.1) | Return the length of a string before compression
`USER()` | Return the current username and hostname
`UUID()`(v4.1.2) | Return a Universal Unique Identifier (UUID)
`VALUES()`(v4.1.1) | Defines the values to be used during an INSERT
`VERSION()` | Returns a string that indicates the MySQL server version

### 11.10.1. Bit Functions

Name | Description
--- | ---
`BIT_COUNT()` | Return the number of bits that are set
`&` | Bitwise AND
`~` | Invert bits
`|` | Bitwise OR
`^` | Bitwise XOR
`<<` | Left shift
`>>` | Right shift

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

- `|`

  Bitwise OR:

      mysql> SELECT 29 | 15;
              -> 31

  The result is an unsigned 64-bit integer.

- `&`

  Bitwise AND:

      mysql> SELECT 29 & 15;
              -> 13

  The result is an unsigned 64-bit integer.

- `^`

  Bitwise XOR:

      mysql> SELECT 1 ^ 1;
              -> 0
      mysql> SELECT 1 ^ 0;
              -> 1
      mysql> SELECT 11 ^ 3;
              -> 8

  The result is an unsigned 64-bit integer.

  Bitwise XOR was added in MySQL 4.0.2.

- `<<`

  Shifts a longlong (`BIGINT`) number to the left.

      mysql> SELECT 1 << 2;
              -> 4

  The result is an unsigned 64-bit integer.

- `>>`

  Shifts a longlong (`BIGINT`) number to the right.

      mysql> SELECT 4 >> 2;
              -> 1

  The result is an unsigned 64-bit integer.

- `~`

  Invert all bits.

      mysql> SELECT 5 & ~1;
              -> 4

  The result is an unsigned 64-bit integer.

- `BIT_COUNT(`N`)`

  Returns the number of bits that are set in the argument `N`.

      mysql> SELECT BIT_COUNT(29);
              -> 4

### 11.10.2. Encryption and Compression Functions

Name | Description
--- | ---
`AES_DECRYPT()` | Decrypt using AES
`AES_ENCRYPT()` | Encrypt using AES
`COMPRESS()`(v4.1.1) | Return result as a binary string
`DECODE()` | Decodes a string encrypted using ENCODE()
`DES_DECRYPT()` | Decrypt a string
`DES_ENCRYPT()` | Decrypt a string
`ENCODE()` | Encode a string
`ENCRYPT()` | Encrypt a string
`MD5()` | Calculate MD5 checksum
`OLD_PASSWORD()`(v4.1) | Return the value of the old (pre-4.1) implementation of PASSWORD
`PASSWORD()` | Calculate and return a password string
`SHA1()`, `SHA()` | Calculate an SHA-1 160-bit checksum
`UNCOMPRESS()`(v4.1.1) | Uncompress a string compressed
`UNCOMPRESSED_LENGTH()`(v4.1.1) | Return the length of a string before compression

### 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 `BLOB` column rather than a `CHAR` or `VARCHAR` column to avoid potential problems with trailing space removal that would change data values.

### 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()` were added in MySQL 4.0.2, and can be considered the most cryptographically secure encryption functions 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()`.

      mysql> SELECT LENGTH(COMPRESS(REPEAT('a',1000)));
              -> 21
      mysql> SELECT LENGTH(COMPRESS(''));
              -> 0
      mysql> SELECT LENGTH(COMPRESS('a'));
              -> 13
      mysql> SELECT LENGTH(COMPRESS(REPEAT('a',16)));
              -> 15

  The compressed string contents are stored the following way:

  - Empty strings are stored as empty strings.

  - Non-empty strings are stored as a four-byte length of the uncompressed string (low byte first), followed by the compressed string. If the string ends with space, an extra “`.`” character is added to avoid problems with endspace trimming should the result be stored in a `CHAR` or `VARCHAR` column. (Use of `CHAR` or `VARCHAR` to store compressed strings is not recommended. It is better to use a `BLOB` column instead.)

  `COMPRESS()` was added in MySQL 4.1.1.

- `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. See Section 5.6.7, “Using Secure Connections”.

  If no `key_str` argument is given, `DES_DECRYPT()` examines the first byte of the encrypted string to determine the DES key number that was used to encrypt the original string, and then reads the key from the DES key file to decrypt the message. For this to work, the user must have the `SUPER` privilege. The key file can be specified with the `--des-key-file` server option.

  If you pass this function a `key_str` argument, that string is used as the key for decrypting the message.

  If the `crypt_str` argument does not appear to be an encrypted string, MySQL returns the given `crypt_str`.

  `DES_DECRYPT()` was added in MySQL 4.0.1.

- `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. See Section 5.6.7, “Using Secure Connections”.

  The encryption key to use is chosen based on the second argument to `DES_ENCRYPT()`, if one was given:

  Argument | Description
  No argument | The first key from the DES key file is used.
  `key_num` | The given key number (0-9) from the DES key file is used.
  `key_str` | The given key string is used to encrypt `str`.

  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.

      mysql> SELECT customer_address FROM customer_table
           > WHERE crypted_credit_card = DES_ENCRYPT('credit_card_number');

  `DES_ENCRYPT()` was added in MySQL 4.0.1.

- `ENCRYPT(`str`[,`salt`])`

  Encrypts `str` using the Unix `crypt()` system call and returns a binary string. The `salt` argument should be a string with two characters. (As of MySQL 3.22.16, `salt` may be longer than two characters.) If no `salt` argument is given, a random value is used.

      mysql> SELECT ENCRYPT('hello');
              -> 'VxuFAJXVARROc'

  `ENCRYPT()` ignores all but the first eight characters of `str`, at least on some systems. This behavior is determined by the implementation of the underlying `crypt()` system call.

  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.

      mysql> SELECT MD5('testing');
              -> 'ae2b1fca515949e5d54fb22b8ed95575'

  This is the “RSA Data Security, Inc. MD5 Message-Digest Algorithm.”

  If you want to convert the value to uppercase, see the description of binary string conversion given in the entry for the `BINARY` operator in Section 11.9, “Cast Functions and Operators”.

  See the note regarding the MD5 algorithm at the beginning this section.

  `MD5()` was added in MySQL 3.23.2.

- `OLD_PASSWORD(`str`)`

  `OLD_PASSWORD()` is available as of MySQL 4.1, when the implementation of `PASSWORD()` was changed to improve security. `OLD_PASSWORD()` returns the value of the pre-4.1 implementation of `PASSWORD()` 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 4.1 MySQL server without locking them out. See Section 5.5.9, “Password Hashing as of MySQL 4.1”.

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

      mysql> SELECT PASSWORD('badpwd');
              -> '7f84554057dd964b'

  `PASSWORD()` encryption is one-way (not reversible).

  `PASSWORD()` does not perform password encryption in the same way that Unix passwords are encrypted. See `ENCRYPT()`.

  ### Note

  The `PASSWORD()` function is used by the authentication system in MySQL Server; you should not use it in your own applications. For that purpose, 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()`.

      mysql> SELECT SHA1('abc');
              -> 'a9993e364706816aba3e25717850c26c9cd0d89d'

  `SHA1()` was added in MySQL 4.0.2, and 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`.

      mysql> SELECT UNCOMPRESS(COMPRESS('any string'));
              -> 'any string'
      mysql> SELECT UNCOMPRESS('any string');
              -> NULL

  `UNCOMPRESS()` was added in MySQL 4.1.1.

- `UNCOMPRESSED_LENGTH(`compressed_string`)`

  Returns the length that the compressed string had before being compressed.

      mysql> SELECT UNCOMPRESSED_LENGTH(COMPRESS(REPEAT('a',30)));
              -> 30

  `UNCOMPRESSED_LENGTH()` was added in MySQL 4.1.1.

### 11.10.3. Information Functions

Name | Description
--- | ---
`BENCHMARK()` | Repeatedly execute an expression
`CHARSET()`(v4.1.0) | Return the character set of the argument
`COERCIBILITY()`(v4.1.1) | Return the collation coercibility value of the string argument
`COLLATION()`(v4.1.0) | Return the collation of the string argument
`CONNECTION_ID()` | Return the connection ID (thread ID) for the connection
`CURRENT_USER()`, `CURRENT_USER` | Return the username and hostname combination
`DATABASE()` | Return the default (current) database name
`FOUND_ROWS()` | For a SELECT with a LIMIT clause, the number of rows that would be returned were there no LIMIT clause
`LAST_INSERT_ID()` | Value of the AUTOINCREMENT column for the last INSERT
`SESSION_USER()` | Synonym for USER()
`SYSTEM_USER()` | Synonym for USER()
`USER()` | Return the current username and hostname
`VERSION()` | Returns a string that indicates the MySQL server version

- `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:

      mysql> SELECT BENCHMARK(1000000,ENCODE('hello','goodbye'));
      +----------------------------------------------+
      | BENCHMARK(1000000,ENCODE('hello','goodbye')) |
      +----------------------------------------------+
      |                                            0 |
      +----------------------------------------------+
      1 row in set (4.74 sec)

  The time reported is elapsed time on the client end, not CPU time on the server end. It is advisable to execute `BENCHMARK()` several times, and to interpret the result with regard to how heavily loaded the server machine is.

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

      mysql> SELECT CHARSET('abc');
              -> 'latin1'
      mysql> SELECT CHARSET(CONVERT('abc' USING utf8));
              -> 'utf8'
      mysql> SELECT CHARSET(USER());
              -> 'utf8'

  `CHARSET()` was added in MySQL 4.1.0.

- `COERCIBILITY(`str`)`

  Returns the collation coercibility value of the string argument.

      mysql> SELECT COERCIBILITY('abc' COLLATE latin1_swedish_ci);
              -> 0
      mysql> SELECT COERCIBILITY(USER());
              -> 3
      mysql> SELECT COERCIBILITY('abc');
              -> 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
  `3` | System constant | `USER()` return value
  `4` | Coercible | Literal string
  `5` | Ignorable | `NULL` or an expression derived from `NULL`

  Before MySQL 4.1.11, the return values are shown in following table, and functions such as `USER()` have a coercibility of 2.

  Coercibility | Meaning | Example
  `0` | Explicit collation | Value with `COLLATE` clause
  `1` | No collation | Concatenation of strings with different collations
  `2` | Implicit collation | Column value
  `3` | Coercible | Literal string

  `COERCIBILITY()` was added in MySQL 4.1.1.

- `COLLATION(`str`)`

  Returns the collation of the string argument.

      mysql> SELECT COLLATION('abc');
              -> 'latin1_swedish_ci'
      mysql> SELECT COLLATION(_utf8'abc');
              -> 'utf8_general_ci'

  `COLLATION()` was added in MySQL 4.1.0.

- `CONNECTION_ID()`

  Returns the connection ID (thread ID) for the connection. Every connection has an ID that is unique among the set of currently connected clients.

      mysql> SELECT CONNECTION_ID();
              -> 23786

  `CONNECTION_ID()` was added in MySQL 3.23.14.

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

  The value of `CURRENT_USER()` can differ from the value of `USER()`.

      mysql> SELECT USER();
              -> 'davida@localhost'
      mysql> SELECT * FROM mysql.user;
      ERROR 1044: Access denied for user ''@'localhost' to
      database 'mysql'
      mysql> SELECT CURRENT_USER();
              -> '@localhost'

  The example illustrates that although the client specified a username of `davida` (as indicated by the value of the `USER()` function), the server authenticated the client using an anonymous user account (as seen by the empty username part of the `CURRENT_USER()` value). One way this might occur is that there is no account listed in the grant tables for `davida`.

  `CURRENT_USER()` was added in MySQL 4.0.6. As of MySQL 4.1.0, the string uses the `utf8` character set.

- `DATABASE()`

  Returns the default (current) database name. As of MySQL 4.1, the string uses the `utf8` character set. If there is no default database, `DATABASE()` returns `NULL` as of MySQL 4.1.1, and the empty string before that.

      mysql> SELECT DATABASE();
              -> 'test'

- `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:

      mysql> SELECT SQL_CALC_FOUND_ROWS * FROM tbl_name
          -> WHERE id > 100 LIMIT 10;
      mysql> 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 `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:

      mysql> SELECT SQL_CALC_FOUND_ROWS * FROM ... ;
      mysql> 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`.

  `SQL_CALC_FOUND_ROWS` and `FOUND_ROWS()` are available starting at MySQL 4.0.0.

  ### Important

  `FOUND_ROWS()` is not replicated reliably, and should not be used with databases that are to be replicated.

- `LAST_INSERT_ID()`, `LAST_INSERT_ID(`expr`)`

  `LAST_INSERT_ID()` (with no argument) returns the first automatically generated value that was set for an `AUTO_INCREMENT` column by the most recently executed `INSERT` or `UPDATE` statement to affect such a column. For example, after inserting a row that generates an `AUTO_INCREMENT` value, you can get the value like this:

      mysql> SELECT LAST_INSERT_ID();
              -> 195

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

  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:

      mysql> USE test;
      Database changed
      mysql> CREATE TABLE t (
          ->   id INT AUTO_INCREMENT NOT NULL PRIMARY KEY,
          ->   name VARCHAR(10) NOT NULL
          -> );
      Query OK, 0 rows affected (0.09 sec)

      mysql> INSERT INTO t VALUES (NULL, 'Bob');
      Query OK, 1 row affected (0.01 sec)

      mysql> SELECT * FROM t;
      +----+------+
      | id | name |
      +----+------+
      |  1 | Bob  |
      +----+------+
      1 row in set (0.01 sec)

      mysql> SELECT LAST_INSERT_ID();
      +------------------+
      | LAST_INSERT_ID() |
      +------------------+
      |                1 |
      +------------------+
      1 row in set (0.00 sec)

      mysql> INSERT INTO t VALUES
          -> (NULL, 'Mary'), (NULL, 'Jane'), (NULL, 'Lisa');
      Query OK, 3 rows affected (0.00 sec)
      Records: 3  Duplicates: 0  Warnings: 0

      mysql> SELECT * FROM t;
      +----+------+
      | id | name |
      +----+------+
      |  1 | Bob  |
      |  2 | Mary |
      |  3 | Jane |
      |  4 | Lisa |
      +----+------+
      4 rows in set (0.01 sec)

      mysql> SELECT LAST_INSERT_ID();
      +------------------+
      | LAST_INSERT_ID() |
      +------------------+
      |                2 |
      +------------------+
      1 row in set (0.00 sec)

  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. (Before MySQL 4.1, the `AUTO_INCREMENT` counter is still incremented and `LAST_INSERT_ID()` returns the new value.)

  If `expr` is given as an argument to `LAST_INSERT_ID()`, the value of the argument is returned by the function and is remembered as the next value to be returned by `LAST_INSERT_ID()`. This can be used to simulate sequences:

  1. Create a table to hold the sequence counter and initialize it:

         mysql> CREATE TABLE sequence (id INT NOT NULL);
         mysql> INSERT INTO sequence VALUES (0);

  2. Use the table to generate sequence numbers like this:

         mysql> UPDATE sequence SET id=LAST_INSERT_ID(id+1);
         mysql> SELECT LAST_INSERT_ID();

     The `UPDATE` statement increments the sequence counter and causes the next call to `LAST_INSERT_ID()` to return the updated value. The `SELECT` statement retrieves that value. The `mysql_insert_id()` C API function can also be used to get the value. See Section 16.2.3.35, “`mysql_insert_id()`”.

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

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

      mysql> SELECT USER();
              -> 'davida@localhost'

  The value indicates the username you specified when connecting to the server, and the client host from which you connected. The value can be different from that of `CURRENT_USER()`.

  Prior to MySQL 3.22.11, the function value does not include the client hostname. You can extract only the username part, regardless of whether the value includes a hostname part, like this:

      mysql> SELECT SUBSTRING_INDEX(USER(),'@',1);
              -> 'davida'

  As of MySQL 4.1, `USER()` returns a value in the `utf8` character set, so you should also make sure that the `'@'` string literal is interpreted in that character set:

      mysql> SELECT SUBSTRING_INDEX(USER(),_utf8'@',1);
              -> 'davida'

- `VERSION()`

  Returns a string that indicates the MySQL server version. As of MySQL 4.1, the string has the `utf8` character set.

      mysql> SELECT VERSION();
              -> '4.1.24-standard'

  Note that if your version string ends with `-log` this means that logging is enabled.

### 11.10.4. Miscellaneous Functions

Name | Description
--- | ---
`DEFAULT()` | Return the default value for a table column
`GET_LOCK()` | Get a named lock
`INET_ATON()` | Return the numeric value of an IP address
`INET_NTOA()` | Return the IP address from a numeric value
`IS_FREE_LOCK()` | Checks whether the named lock is free
`IS_USED_LOCK()`(v4.1.0) | Checks whether the named lock is in use. Return connection identifier if true.
`MASTER_POS_WAIT()` | Block until the slave has read and applied all updates up to the specified position
`RELEASE_LOCK()` | Releases the named lock
`UUID()`(v4.1.2) | Return a Universal Unique Identifier (UUID)
`VALUES()`(v4.1.1) | Defines the values to be used during an INSERT

- `DEFAULT(`col_name`)`

  Returns the default value for a table column.

      mysql> UPDATE t SET i = DEFAULT(i)+1 WHERE id < 100;

  `DEFAULT()` was added in MySQL 4.1.0.

- `FORMAT(`X`,`D`)`

  Formats the number `X` to a format like `'#,###,###.##'`, rounded to `D` decimal places, and returns the result as a string. For details, see Section 11.4, “String Functions”.

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

      mysql> SELECT GET_LOCK('lock1',10);
              -> 1
      mysql> SELECT IS_FREE_LOCK('lock2');
              -> 1
      mysql> SELECT GET_LOCK('lock2',10);
              -> 1
      mysql> SELECT RELEASE_LOCK('lock2');
              -> 1
      mysql> SELECT RELEASE_LOCK('lock1');
              -> NULL

  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.

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

      mysql> SELECT INET_ATON('209.207.224.40');
              -> 3520061480

  The generated number is always in network byte order. For the example just shown, the number is calculated as 209×2563 + 207×2562 + 224×256 + 40.

  As of MySQL 4.1.2, `INET_ATON()` also understands short-form IP addresses:

      mysql> SELECT INET_ATON('127.0.0.1'), INET_ATON('127.1');
              -> 2130706433, 2130706433

  ### 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. See Section 10.2, “Numeric Types”.

  `INET_ATON()` was added in MySQL 3.23.15.

- `INET_NTOA(`expr`)`

  Given a numeric network address (4 or 8 byte), returns the dotted-quad representation of the address as a string.

      mysql> SELECT INET_NTOA(3520061480);
              -> '209.207.224.40'

  `INET_NTOA()` was added in MySQL 3.23.15.

- `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_FREE_LOCK()` was added in MySQL 4.0.2.

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

  `IS_USED_LOCK()` was added in MySQL 4.1.0.

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

  `MASTER_POS_WAIT()` was added in MySQL 3.23.32. The `timeout` argument was added in 4.0.10.

- `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()`. See Section 12.2.2, “`DO` Syntax”.

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

      mysql> SELECT UUID();
              -> '6ccd780c-baba-1026-9564-0040f4311e29'

  Note that `UUID()` does not yet work with replication.

  `UUID()` was added in MySQL 4.1.2.

- `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. Section 12.2.4.3, “`INSERT ... ON DUPLICATE KEY UPDATE` Syntax”.

      mysql> INSERT INTO table (a,b,c) VALUES (1,2,3),(4,5,6)
          -> ON DUPLICATE KEY UPDATE c=VALUES(a)+VALUES(b);

  `VALUES()` was added in MySQL 4.1.1.

## 11.11. Functions and Modifiers for Use with `GROUP BY` Clauses

### 11.11.1. `GROUP BY` (Aggregate) Functions

Name | Description
--- | ---
`AVG()` | Return the average value of the argument
`BIT_AND()` | Return bitwise and
`BIT_OR()` | Return bitwise or
`BIT_XOR()`(v4.1.1) | Return bitwise xor
`COUNT(DISTINCT)` | Return the count of a number of different values
`COUNT()` | Return a count of the number of rows returned
`GROUP_CONCAT()`(v4.1) | Return a concatenated string
`MAX()` | Return the maximum value
`MIN()` | Return the minimum value
`STD()` | Return the population standard deviation
`STDDEV()` | Return the population standard deviation
`SUM()` | Return the sum
`VARIANCE()`(v4.1) | Return the population standard variance

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, standard deviation, `SUM()`, and `AVG()` functions return a `DOUBLE` value.

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.

- Returns the average value of ``expr``.

  `AVG()` returns `NULL` if there were no matching rows.

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

  As of MySQL 4.0.17, 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.) Before 4.0.17, the function returns `-1` if there were no matching rows.

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

  This function is available as of MySQL 4.1.1.

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

      mysql> SELECT student.student_name,COUNT(*)
          ->        FROM student,course
          ->        WHERE student.student_id=course.student_id
          ->        GROUP BY student_name;

  `COUNT(*)` is somewhat different in that it returns a count of the number of rows retrieved, whether or not they contain `NULL` values.

  `COUNT(*)` is optimized to return very quickly if the `SELECT` retrieves from one table, no other columns are retrieved, and there is no `WHERE` clause. For example:

      mysql> SELECT COUNT(*) FROM student;

  This optimization applies only to `MyISAM` and `ISAM` tables only, because an exact row count is stored for these storage engines and can be accessed very quickly. For transactional storage engines such as `InnoDB` and `BDB`, storing an exact row count is more problematic because multiple transactions may be occurring, each of which may affect the count.

- `COUNT(DISTINCT `expr`,[`expr`...])`

  Returns a count of the number of different non-`NULL` values.

  `COUNT(DISTINCT)` returns `0` if there were no matching rows.

      mysql> 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 ...)`.

  `COUNT(DISTINCT ...)` was added in MySQL 3.23.2.

- `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])

      mysql> SELECT student_name,
          ->     GROUP_CONCAT(test_score)
          ->     FROM student
          ->     GROUP BY student_name;

  Or:

      mysql> SELECT student_name,
          ->     GROUP_CONCAT(DISTINCT test_score
          ->               ORDER BY test_score DESC SEPARATOR ' ')
          ->     FROM student
          ->     GROUP BY student_name;

  In MySQL, you can get the concatenated values of expression combinations. You can eliminate duplicate values by using `DISTINCT`. If you want to sort values in the result, you should use `ORDER BY` clause. To sort in reverse order, add the `DESC` (descending) keyword to the name of the column you are sorting by in the `ORDER BY` clause. The default is ascending order; this may be specified explicitly using the `ASC` keyword. `SEPARATOR` is followed by the string value that should be inserted between values of result. The default is a comma (“`,`”). You can 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;

  Beginning with MySQL 4.1.19, 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`. (Previously, it returned a `BLOB` with `group_concat_max_len` greater than 512 only if the query included an `ORDER BY` clause.)

  `GROUP_CONCAT()` was added in MySQL 4.1.

  Note: Before MySQL 4.1.6, there are some small limitations with `GROUP_CONCAT()` for `BLOB` and `TEXT` values when it comes to using `DISTINCT` together with `ORDER BY`. To work around this limitation, use `MID(`expr`,1,255)` instead.

  See also `CONCAT()` and `CONCAT_WS()`: Section 11.4, “String Functions”.

- `MAX(`expr`)`

  Returns the maximum value of `expr`. `MAX()` may take a string argument; in such cases, it returns the maximum string value. See Section 7.4.5, “How MySQL Uses Indexes”.

  `MAX()` returns `NULL` if there were no matching rows.

      mysql> 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(`expr`)`

  Returns the minimum value of `expr`. `MIN()` may take a string argument; in such cases, it returns the minimum string value. See Section 7.4.5, “How MySQL Uses Indexes”.

  `MIN()` returns `NULL` if there were no matching rows.

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

  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.

  This function returns `NULL` if there were no matching rows.

- `SUM(`expr`)`

  Returns the sum of `expr`. If the return set has no rows, `SUM()` returns `NULL`.

  `SUM()` returns `NULL` if there were no matching rows.

- `VARIANCE(`expr`)`

  Returns the population standard variance of `expr`. This is an extension to standard SQL, available in MySQL 4.1 or later.

  `VARIANCE()` returns `NULL` if there were no matching rows.

### 11.11.2. `GROUP BY` Modifiers

As of MySQL 4.1.1, the `GROUP BY` clause allows a `WITH ROLLUP` modifier that causes extra rows to be added to the summary output. These rows represent higher-level (or super-aggregate) summary operations. `ROLLUP` thus allows you to answer questions at multiple levels of analysis with a single query. It can be used, for example, to provide support for OLAP (Online Analytical Processing) operations.

Suppose that a table named `sales` has `year`, `country`, `product`, and `profit` columns for recording sales profitability:

    CREATE TABLE sales
    (
        year    INT NOT NULL,
        country VARCHAR(20) NOT NULL,
        product VARCHAR(32) NOT NULL,
        profit  INT
    );

The table's contents can be summarized per year with a simple `GROUP BY` like this:

    mysql> SELECT year, SUM(profit) FROM sales GROUP BY year;
    +------+-------------+
    | year | SUM(profit) |
    +------+-------------+
    | 2000 |        4525 |
    | 2001 |        3010 |
    +------+-------------+

This output shows the total profit for each year, but if you also want to determine the total profit summed over all years, you must add up the individual values yourself or run an additional query.

Or you can use `ROLLUP`, which provides both levels of analysis with a single query. Adding a `WITH ROLLUP` modifier to the `GROUP BY` clause causes the query to produce another row that shows the grand total over all year values:

    mysql> SELECT year, SUM(profit) FROM sales GROUP BY year WITH ROLLUP;
    +------+-------------+
    | year | SUM(profit) |
    +------+-------------+
    | 2000 |        4525 |
    | 2001 |        3010 |
    | NULL |        7535 |
    +------+-------------+

The grand total super-aggregate line is identified by the value `NULL` in the `year` column.

`ROLLUP` has a more complex effect when there are multiple `GROUP BY` columns. In this case, each time there is a “break” (change in value) in any but the last grouping column, the query produces an extra super-aggregate summary row.

For example, without `ROLLUP`, a summary on the `sales` table based on `year`, `country`, and `product` might look like this:

    mysql> SELECT year, country, product, SUM(profit)
        -> FROM sales
        -> GROUP BY year, country, product;
    +------+---------+------------+-------------+
    | year | country | product    | SUM(profit) |
    +------+---------+------------+-------------+
    | 2000 | Finland | Computer   |        1500 |
    | 2000 | Finland | Phone      |         100 |
    | 2000 | India   | Calculator |         150 |
    | 2000 | India   | Computer   |        1200 |
    | 2000 | USA     | Calculator |          75 |
    | 2000 | USA     | Computer   |        1500 |
    | 2001 | Finland | Phone      |          10 |
    | 2001 | USA     | Calculator |          50 |
    | 2001 | USA     | Computer   |        2700 |
    | 2001 | USA     | TV         |         250 |
    +------+---------+------------+-------------+

The output indicates summary values only at the year/country/product level of analysis. When `ROLLUP` is added, the query produces several extra rows:

    mysql> SELECT year, country, product, SUM(profit)
        -> FROM sales
        -> GROUP BY year, country, product WITH ROLLUP;
    +------+---------+------------+-------------+
    | year | country | product    | SUM(profit) |
    +------+---------+------------+-------------+
    | 2000 | Finland | Computer   |        1500 |
    | 2000 | Finland | Phone      |         100 |
    | 2000 | Finland | NULL       |        1600 |
    | 2000 | India   | Calculator |         150 |
    | 2000 | India   | Computer   |        1200 |
    | 2000 | India   | NULL       |        1350 |
    | 2000 | USA     | Calculator |          75 |
    | 2000 | USA     | Computer   |        1500 |
    | 2000 | USA     | NULL       |        1575 |
    | 2000 | NULL    | NULL       |        4525 |
    | 2001 | Finland | Phone      |          10 |
    | 2001 | Finland | NULL       |          10 |
    | 2001 | USA     | Calculator |          50 |
    | 2001 | USA     | Computer   |        2700 |
    | 2001 | USA     | TV         |         250 |
    | 2001 | USA     | NULL       |        3000 |
    | 2001 | NULL    | NULL       |        3010 |
    | NULL | NULL    | NULL       |        7535 |
    +------+---------+------------+-------------+

For this query, adding `ROLLUP` causes the output to include summary information at four levels of analysis, not just one. Here's how to interpret the `ROLLUP` output:

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

    mysql> SELECT year, country, product, SUM(profit)
        -> FROM sales
        -> GROUP BY year, country, product WITH ROLLUP
        -> LIMIT 5;
    +------+---------+------------+-------------+
    | year | country | product    | SUM(profit) |
    +------+---------+------------+-------------+
    | 2000 | Finland | Computer   |        1500 |
    | 2000 | Finland | Phone      |         100 |
    | 2000 | Finland | NULL       |        1600 |
    | 2000 | India   | Calculator |         150 |
    | 2000 | India   | Computer   |        1200 |
    +------+---------+------------+-------------+

Using `LIMIT` with `ROLLUP` may produce results that are more difficult to interpret, because you have less context for understanding the super-aggregate rows.

The `NULL` indicators in each super-aggregate row are produced when the row is sent to the client. The server looks at the columns named in the `GROUP BY` clause following the leftmost one that has changed value. For any column in the result set with a name that is a lexical match to any of those names, its value is set to `NULL`. (If you specify grouping columns by column number, the server identifies which columns to set to `NULL` by number.)

Because the `NULL` values in the super-aggregate rows are placed into the result set at such a late stage in query processing, you cannot test them as `NULL` values within the query itself. For example, you cannot add `HAVING product IS NULL` to the query to eliminate from the output all but the super-aggregate rows.

On the other hand, the `NULL` values do appear as `NULL` on the client side and can be tested as such using any MySQL client programming interface.

### 11.11.3. `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:

    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 to the `SELECT`. That is, columns not named in the `GROUP BY` clause cannot be used in the `SELECT` list 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:

    SUBSTR(MIN(CONCAT(RPAD(sort,6,' '),column)),7)

See Section 3.6.4, “The Rows Holding the Group-wise Maximum of a Certain Field”.

Note that if you are using MySQL 3.22 (or earlier) or if you are trying to follow standard SQL, you cannot use expressions in `GROUP BY` or `ORDER BY` clauses. You can work around this limitation by using an alias for the expression:

    mysql> SELECT id,FLOOR(value/100) AS val
        ->     FROM tbl_name
        ->     GROUP BY id, val ORDER BY val;

In MySQL 3.23 and up, aliases are unnecessary. You can use expressions in `GROUP BY` and `ORDER BY` clauses. For example:

    mysql> SELECT id, FLOOR(value/100) FROM tbl_name ORDER BY RAND();

Note that if you are using MySQL 3.22 (or earlier) or if you are trying to follow standard SQL, you can't use expressions in `GROUP BY` clauses. You can work around this limitation by using an alias for the expression:

    SELECT id,FLOOR(value/100) AS val
      FROM tbl_name
      GROUP BY id, val;

In MySQL 3.23 and up, aliases are unnecessary and MySQL does allow expressions in `GROUP BY` clauses. For example:

    SELECT id,FLOOR(value/100)
      FROM tbl_name
      GROUP BY id, FLOOR(value/100);

Before MySQL 3.23, MySQL also requires use of aliases to refer to expressions in `ORDER BY` clauses.

Prev |  | Next
Chapter 10. Data Types | Home | Chapter 12. SQL Statement Syntax