STRING

On this page Carat arrow pointing down
Warning:
As of October 4, 2019, CockroachDB v2.0 is no longer supported. For more details, refer to the Release Support Policy.

The STRING data type stores a string of Unicode characters.

Aliases

In CockroachDB, the following are aliases for STRING:

  • CHARACTER
  • CHAR
  • VARCHAR
  • TEXT

And the following are aliases for STRING(n):

  • CHARACTER(n)
  • CHARACTER VARYING(n)
  • CHAR(n)
  • CHAR VARYING(n)
  • VARCHAR(n)

Length

To limit the length of a string column, use STRING(n), where n is the maximum number of Unicode code points (normally thought of as "characters") allowed.

When inserting a string:

  • If the value exceeds the column's length limit, CockroachDB gives an error.
  • If the value is cast as a string with a length limit (e.g., CAST('hello world' AS STRING(5))), CockroachDB truncates to the limit.
  • If the value is under the column's length limit, CockroachDB does not add padding. This applies to STRING(n) and all its aliases.

Syntax

A value of type STRING can be expressed using a variety of formats. See string literals for more details.

When printing out a STRING value in the SQL shell, the shell uses the simple SQL string literal format if the value doesn't contain special character, or the escaped format otherwise.

Collations

STRING values accept collations, which lets you sort strings according to language- and country-specific rules.

Size

The size of a STRING value is variable, but it's recommended to keep values under 64 kilobytes to ensure performance. Above that threshold, write amplification and other considerations may cause significant performance degradation.

Examples

> CREATE TABLE strings (a STRING PRIMARY KEY, b STRING(4), c TEXT);

> SHOW COLUMNS FROM strings;
+-------+-----------+-------+---------+
| Field |  Type     | Null  | Default |
+-------+-----------+-------+---------+
| a     | STRING    | false | NULL    |
| b     | STRING(4) | true  | NULL    |
| c     | STRING    | true  | NULL    |
+-------+-----------+-------+---------+
> INSERT INTO strings VALUES ('a1b2c3d4', 'e5f6', 'g7h8i9');

> SELECT * FROM strings;
+----------+------+--------+
|    a     |  b   |   c    |
+----------+------+--------+
| a1b2c3d4 | e5f6 | g7h8i9 |
+----------+------+--------+

Supported Casting & Conversion

STRING values can be cast to any of the following data types:

Type Details
BOOL Requires supported BOOL string format, e.g., 'true'.
BYTES For more details, see here.
DATE Requires supported DATE string format, e.g., '2016-01-25'.
DECIMAL Requires supported DECIMAL string format, e.g., '1.1'.
FLOAT Requires supported FLOAT string format, e.g., '1.1'.
INET Requires supported INET string format, e.g, '192.168.0.1'.
INT Requires supported INT string format, e.g., '10'.
INTERVAL Requires supported INTERVAL string format, e.g., '1h2m3s4ms5us6ns'.
TIME New in v2.0: Requires supported TIME string format, e.g., '01:22:12' (microsecond precision).
TIMESTAMP Requires supported TIMESTAMP string format, e.g., '2016-01-25 10:10:10.555555'.

See Also

Data Types


Yes No
On this page

Yes No