String Functions

TiDB supports most of the string functions available in MySQL 5.7, some of the string functions available in MySQL 8.0, and some of the functions available in Oracle 21.

For comparisons between functions and syntax of Oracle and TiDB, see Comparisons between Functions and Syntax of Oracle and TiDB.

Supported functions

`ASCII()`

The ASCII(str) function is used to get the ASCII value of the leftmost character in the given argument. The argument can be either a string or a number.

If the argument is not empty, the function returns the ASCII value of the leftmost character.
If the argument is an empty string, the function returns 0.
If the argument is NULL, the function returns NULL.

Note

ASCII(str) only works for characters represented using 8 bits of binary digits (one byte).

Examples:

SELECT ASCII('A');

+------------+
| ASCII('A') |
+------------+
|         65 |
+------------+

SELECT ASCII('TiDB');

+---------------+
| ASCII('TiDB') |
+---------------+
|            84 |
+---------------+

SELECT ASCII(23);

+-----------+
| ASCII(23) |
+-----------+
|        50 |
+-----------+

`BIN()`

The BIN() function is used to convert the given argument into a string representation of its binary value. The argument can be either a string or a number.

If the argument is a positive number, the function returns a string representation of its binary value.
If the argument is a negative number, the function converts the absolute value of the argument to its binary representation, inverts each bit of the binary value (changing 0 to 1 and 1 to 0), and then adds 1 to the inverted value.
If the argument is a string containing only digits, the function returns the result according to those digits. For example, the results for "123" and 123 are the same.
If the argument is a string and its first character is not a digit (such as "q123"), the function returns 0.
If the argument is a string that consists of digits and non-digits, the function returns the result according to the consecutive digits at the beginning of the argument. For example, the results for "123q123" and 123 are the same.
If the argument is NULL, the function returns NULL.

Examples:

SELECT BIN(123);

+----------+
| BIN(123) |
+----------+
| 1111011  |
+----------+

SELECT BIN(-7);

+------------------------------------------------------------------+
| BIN(-7)                                                          |
+------------------------------------------------------------------+
| 1111111111111111111111111111111111111111111111111111111111111001 |
+------------------------------------------------------------------+

SELECT BIN("123q123");

+----------------+
| BIN("123q123") |
+----------------+
| 1111011        |
+----------------+

Return a string containing binary representation of a number.

`CHAR()`

Return the character for each integer passed.

`CHAR_LENGTH()`

Return number of characters in argument.

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

`FROM_BASE64()`

Decode to a base-64 string and return result.

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

`LEFT()`

Return the leftmost number of characters as specified.

`LOCATE()`

Return the position of the first occurrence of substring.

`LPAD()`

Return the string argument, left-padded with the specified string.

`MAKE_SET()`

Return a set of comma-separated strings that have the corresponding bit in bits set.

`MID()`

Return a substring starting from the specified position.

`OCT()`

Return a string containing octal representation of a number.

`ORD()`

Return character code for leftmost character of the argument.

`QUOTE()`

Escape the argument for use in an SQL statement.

`REGEXP`

Pattern matching using regular expressions.

`REGEXP_INSTR()`

Return the starting index of the substring that matches the regular expression (Partly compatible with MySQL. For more details, see Regular expression compatibility with MySQL).

`REGEXP_LIKE()`

Whether the string matches the regular expression (Partly compatible with MySQL. For more details, see Regular expression compatibility with MySQL).

`REGEXP_REPLACE()`

Replace substrings that match the regular expression (Partly compatible with MySQL. For more details, see Regular expression compatibility with MySQL).

`REGEXP_SUBSTR()`

Return the substring that matches the regular expression (Partly compatible with MySQL. For more details, see Regular expression compatibility with MySQL).

`REPEAT()`

Repeat a string the specified number of times.

`REPLACE()`

Replace occurrences of a specified string.

`RIGHT()`

Return the specified rightmost number of characters.

`RPAD()`

Append string the specified number of times.

`SPACE()`

Return a string of the specified number of spaces.

`SUBSTRING_INDEX()`

Return a substring from a string before the specified number of occurrences of the delimiter.

`TO_BASE64()`

Return the argument converted to a base-64 string.

`TRANSLATE()`

Replace all occurrences of characters by other characters in a string. It does not treat empty strings as NULL as Oracle does.

`UNHEX()`

Return a string containing hex representation of a number.

`WEIGHT_STRING()`

Return the weight string for the input string.

Unsupported functions

LOAD_FILE()
MATCH()
SOUNDEX()

Regular expression compatibility with MySQL

The following sections describe the regular expression compatibility with MySQL.

Syntax compatibility

MySQL implements regular expression using International Components for Unicode (ICU), and TiDB uses RE2. To learn the syntax differences between the two libraries, you can refer to the ICU documentation and RE2 Syntax.

`match_type` compatibility

The value options of match_type between TiDB and MySQL are:

Value options in TiDB are "c", "i", "m", and "s", and value options in MySQL are "c", "i", "m", "n", and "u".
The "s" in TiDB corresponds to "n" in MySQL. When "s" is set in TiDB, the . character also matches line terminators (\n).
For example, the SELECT REGEXP_LIKE(a, b, "n") FROM t1 in MySQL is the same as the SELECT REGEXP_LIKE(a, b, "s") FROM t1 in TiDB.
TiDB does not support "u", which means Unix-only line endings in MySQL.

Data type compatibility

The difference between TiDB and MySQL support for the binary string type:

MySQL does not support binary strings in regular expression functions since 8.0.22. For more details, refer to MySQL documentation. But in practice, regular functions can work in MySQL when all parameters or return types are binary strings. Otherwise, an error will be reported.
Currently, TiDB prohibits using binary strings and an error will be reported under any circumstances.

Other compatibility

The difference between TiDB and MySQL support in replacing empty strings:

The following takes REGEXP_REPLACE("", "^$", "123") as an example:

MySQL does not replace the empty string and returns "" as the result.
TiDB replaces the empty string and returns "123" as the result.