From 41a7e94e1b89155eae513867330772545df699c0 Mon Sep 17 00:00:00 2001 From: SIGSEGV Date: Fri, 3 Jul 2020 11:31:32 +0800 Subject: [PATCH] cherry pick #3078 to release-3.1 Signed-off-by: ti-srebot --- literal-values.md | 160 ++++++++++++++++++++++++---------------------- 1 file changed, 83 insertions(+), 77 deletions(-) diff --git a/literal-values.md b/literal-values.md index 27cb31d2396ee..3a8dc85354b5a 100644 --- a/literal-values.md +++ b/literal-values.md @@ -1,12 +1,14 @@ --- title: Literal Values -summary: Learn how to use various literal values. +summary: This article introduces the literal values ​​of TiDB SQL statements. category: reference aliases: ['/docs/v3.1/literal-values/','/docs/v3.1/reference/sql/language-structure/literal-values/'] --- # Literal Values +TiDB literal values include character literals, numeric literals, time and date literals, hexadecimal, binary literals, and NULL literals. This document introduces each of these literal values. + This document describes String literals, Numeric literals, NULL values, Hexadecimal literals, Date and time literals, Boolean literals, and Bit-value literals. ## String literals @@ -28,11 +30,12 @@ Quoted strings placed next to each other are concatenated to a single string. Th If the `ANSI_QUOTES` SQL MODE is enabled, string literals can be quoted only within single quotation marks because a string quoted within double quotation marks is interpreted as an identifier. -A binary string is a string of bytes. Each binary string has a character set and collation named `binary`. A non-binary string is a string of characters. It has a character set other than `binary` and a collation that is compatible with the character set. +The string is divided into the following two types: -For both types of strings, comparisons are based on the numeric values of the string unit. For binary strings, the unit is the byte. For non-binary strings, the unit is the character and some character sets support multibyte characters. ++ Binary string: It consists of a sequence of bytes, whose charset and collation are both `binary`, and uses **byte** as the unit when compared with each other. ++ Non-binary string: It consists of a sequence of characters and has various charsets and collations other than `binary`. When compared with each other, non-binary strings use **characters** as the unit. A charater might contian multiple bytes, depending on the charset. -A string literal may have an optional `character set introducer` and `COLLATE clause`, to designate it as a string that uses a specific character set and collation. TiDB only supports this in syntax, but does not process it. +A string literal may have an optional `character set introducer` and `COLLATE clause`, to designate it as a string that uses a specific character set and collation. ``` [_charset_name]'string' [COLLATE collation_name] @@ -54,26 +57,23 @@ SELECT n'some text'; SELECT _utf8'some text'; ``` -Escape characters: - -- `\0`: An ASCII NUL (X'00') character -- `\'`: A single quote (') character -- `\"`: A double quote (")character -- `\b`: A backspace character -- `\n`: A newline (linefeed) character -- `\r`: A carriage return character -- `\t`: A tab character -- `\z`: ASCII 26 (Ctrl + Z) -- `\\`: A backslash `\` character -- `\%`: A `%` character -- `\_`: A `_` character +To represent some special characters in a string, you can use escape characters to escape: -You can use the following ways to include quote characters within a string: +| Escape Characters | Meaning | +| :---------------- | :------ | +| \\0 | An ASCII NUL (X'00') character | +| \\' | A single quote `'` character | +| \\" | A double quote `"` character | +| \\b | A backspace character | +| \\n | A line break (newline) character | +| \\r | A carriage return character | +| \\t | A tab character | +| \\z | ASCII 26 (Ctrl + Z) | +| \\\\ | A backslash `\` character | +| \\% | A `%` character | +| \\_ | A `_` character | -- A `'` inside a string quoted with `'` may be written as `''`. -- A `"` inside a string quoted with `"` may be written as `""`. -- Precede the quote character by an escape character `\`. -- A `'` inside a string quoted with `"` needs no special treatment, and a `"` inside a string quoted with `'` needs no special treatment either. +If you want to represent `"` in the string surrounded by `'`, or `'` in the string surrounded by `"`, you do not need to use escape characters. For more information, see [String Literals in MySQL](https://dev.mysql.com/doc/refman/5.7/en/string-literals.html). @@ -89,11 +89,60 @@ Numeric literals can also be represented in scientific notation, such as `1.2E3, For more information, see [Numeric Literals in MySQL](https://dev.mysql.com/doc/refman/5.7/en/number-literals.html). -## NULL values +## Date and time literals + +Date and time literal values can be represented in several formats, such as quoted strings or as numbers. When TiDB expects a date, it interprets any of `'2017-08-24'`, `'20170824'` and `20170824` as a date. + +TiDB supports the following date formats: + +* `'YYYY-MM-DD'` or `'YY-MM-DD'`: The `-` delimiter here is not strict. It can be any punctuation. For example, `'2017-08-24'`, `'2017&08&24'`, `'2012@12^31'` are all valid date formats. The only special punctuation is '.', which is is treated as a decimal point to separate the integer and fractional parts. Date and time can be separated by `T` or a white space. For example, `2017-8-24 10:42:00` and `2017-8-24T10:42:00` represents the same date and time. +* `'YYYYMMDDHHMMSS'` or `'YYMMDDHHMMSS'`: For example, `'20170824104520'` and `'170824104520'` are regarded as `'2017-08-24 10:45:20'`. However, if you provide a value out of range, such as `'170824304520'`, it is not treated as a valid date. +* `YYYYMMDDHHMMSS` or `YYMMDDHHMMSS`: Note that these formats have no single or double quotes, but a number. For example, `20170824104520` is interpreted as `'2017-08-24 10:45:20'`. + +DATETIME or TIMESTAMP values can be followed by a fractional part, used to represent microseconds precision (6 digits). The fractional part should always be separated from the rest of the time by a decimal point `.`. + +The year value containing only two digits is ambiguous. It is recommended to use the four-digit year format. TiDB interpretes the two-digit year value according to the following rules: + +* If the year value is in the range of `70-99`, it is converted to `1970-1999`. +* If the year value is in the range of `00-69`, it is converted to `2000-2069`. + +For month or day values ​​less than 10, `'2017-8-4'` is the same as `'2017-08-04'`. The same is true for Time. For example, `'2017-08-24 1:2:3'` is the same as `'2017-08-24 01:02:03'`. + +When the date or time value is required, TiDB selects the specified format according to the length of the value: + +* 6 digits: `YYMMDD`. +* 12 digits: `YYMMDDHHMMSS`. +* 8 digits: `YYYYMMDD`. +* 14 digits: `YYYYMMDDHHMMSS`. + +TiDB supports the following formats for time values: + +* `'D HH:MM:SS'`, or `'HH:MM:SS'`, `'HH:MM'`, `'D HH:MM'`, `'D HH'`, `'SS'`: `D` means days and the valid value range is `0-34`. +* A number in `HHMMSS` format: For example, `231010` is interpreted as `'23:10:10'`. +* A number in any of `SS`, `MMSS`, and `HHMMSS`formats can be regarded as time. -The `NULL` value means “no data”. NULL can be written in any letter case. A synonym is `\N` (case sensitive). +The decimal point of the Time type is also `.`, with a precision of up to 6 digits after the decimal point. -Be aware that the `NULL` value is different from values such as `0` for numeric types or the empty string `''` for string types. +See [MySQL date and time literals](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-literals.html) for more details. + +## Boolean Literals + +The constants `TRUE` and `FALSE` are equal to 1 and 0 respectively, which are not case sensitive. + +{{< copyable "sql" >}} + +```sql +SELECT TRUE, true, tRuE, FALSE, FaLsE, false; +``` + +``` ++------+------+------+-------+-------+-------+ +| TRUE | true | tRuE | FALSE | FaLsE | false | ++------+------+------+-------+-------+-------+ +| 1 | 1 | 1 | 0 | 0 | 0 | ++------+------+------+-------+-------+-------+ +1 row in set (0.00 sec) +``` ## Hexadecimal literals @@ -126,8 +175,7 @@ mysql> select X'0aff'; +---------+ | X'0aff' | +---------+ -| - | +| 0x0aff | +---------+ 1 row in set (0.00 sec) ``` @@ -154,56 +202,6 @@ mysql> SELECT X'54694442'; 1 row in set (0.00 sec) ``` -## Date and time literals - -Date and time values can be represented in several formats, such as quoted strings or as numbers. When TiDB expects a date, it interprets any of `'2015-07-21'`, `'20150721'` and `20150721` as a date. - -TiDB supports the following formats for date values: - -- As a string in either `'YYYY-MM-DD'` or `'YY-MM-DD'` format. The `-` delimiter is "relaxed" in syntax. Any punctuation character may be used as the delimiter between date parts. For example, `'2017-08-24'`, `'2017&08&24'` and `'2012@12^31'` are equivalent. The only delimiter recognized is the `.` character, which is treated as a decimal point to separate the integer and fractional parts. The date and time parts can be separated by `T` other than a space. For example, `2017-8-24 10:42:00` and `2017-8-24T10:42:00` are equivalent. -- As a string with no delimiters in either `'YYYYMMDDHHMMSS'` or `'YYMMDDHHMMSS'` format. For example, `'20170824104520'` and `'170824104520'` are interpreted as `'2017-08-24 10:45:20'`. But `'170824304520'` is illegal because the hour part exceeds the legal range. -- As a number in either `YYYYMMDDHHMMSS` or `YYMMDDHHMMSS` format, without single quotation marks or double quotation marks. For example, `20170824104520` is interpreted as `'2017-08-24 10:45:20'`. - -A DATETIME or TIMESTAMP value can include a trailing fractional seconds part in up to microseconds (6 digits) precision. The fractional part should always be separated from the rest of the time by a decimal point. - -Dates containing two-digit year values are ambiguous. It is recommended to use the four-digit format. TiDB interprets two-digit year values using the following rules: - -- Year values in the range of `70-99` are converted to `1970-1999`. -- Year values in the range of `00-69` are converted to `2000-2069`. - -For values specified as strings that include date part delimiters, it is unnecessary to specify two digits for month or day values that are less than 10. `'2017-8-4'` is the same as `'2017-08-04'`. Similarly, for values specified as strings that include time part delimiters, it is unnecessary to specify two digits for hour, minute, or second values that are less than 10. `'2017-08-24 1:2:3'` is the same as `'2017-08-24 01:02:03'`. - -In TiDB, the date or time values specified as numbers are interpreted according their length: - -- 6 digits: `YYMMDD` -- 12 digits: `YYMMDDHHMMSS` -- 8 digits: `YYYYMMDD` -- 14 digits: `YYYYMMDDHHMMSS` - -TiDB supports the following formats for time values: - -- As a string in `'D HH:MM:SS'` format. You can also use one of the following “relaxed” syntaxes: `'HH:MM:SS'`, `'HH:MM'`, `'D HH:MM'`, `'D HH'`, or `'SS'`. Here D represents days and the legal value range is `0-34`. -- As a number in `'HHMMSS'` format. For example, `231010` is interpreted as `'23:10:10'`. -- A number in any of the `SS`, `MMSS` or `HHMMSS` format can be treated as time. - -The time value can also include a trailing fractional part in up to 6 digits precision. The `.` character represents the decimal point. - -For more information, see [Date and Time Literals in MySQL](https://dev.mysql.com/doc/refman/5.7/en/date-and-time-literals.html). - -## Boolean literals - -The constants `TRUE` and `FALSE` evaluate to 1 and 0 respectively, which are not case sensitive. - -```sql -mysql> SELECT TRUE, true, tRuE, FALSE, FaLsE, false; -+------+------+------+-------+-------+-------+ -| TRUE | true | tRuE | FALSE | FaLsE | false | -+------+------+------+-------+-------+-------+ -| 1 | 1 | 1 | 0 | 0 | 0 | -+------+------+------+-------+-------+-------+ -1 row in set (0.00 sec) -``` - ## Bit-value literals Bit-value literals are written using `b'val'` or `0bval` notation. The `val` is a binary value written using zeros and ones. A leading `0b` is case sensitive and cannot be written as `0B`. @@ -243,3 +241,11 @@ mysql> SELECT b+0, BIN(b), HEX(b) FROM t; +------+--------+--------+ 3 rows in set (0.00 sec) ``` + +## NULL Values + +`NULL` means the data is empty, which is case-insensitive, and is synonymous with `\N` (case-sensitive). + +> **Note:** +> +> `NULL` is not the same as `0`, nor the empty string `''`.