begriffs open source - ai-pg/blob - full-docs/txt/datatype-character.txt

   1
   2 8.3. Character Types #
   3
   4    Table 8.4. Character Types
   5                  Name                             Description
   6    character varying(n), varchar(n) variable-length with limit
   7    character(n), char(n), bpchar(n) fixed-length, blank-padded
   8    bpchar                           variable unlimited length, blank-trimmed
   9    text                             variable unlimited length
  10
  11    Table 8.4 shows the general-purpose character types available in
  12    PostgreSQL.
  13
  14    SQL defines two primary character types: character varying(n) and
  15    character(n), where n is a positive integer. Both of these types can
  16    store strings up to n characters (not bytes) in length. An attempt to
  17    store a longer string into a column of these types will result in an
  18    error, unless the excess characters are all spaces, in which case the
  19    string will be truncated to the maximum length. (This somewhat bizarre
  20    exception is required by the SQL standard.) However, if one explicitly
  21    casts a value to character varying(n) or character(n), then an
  22    over-length value will be truncated to n characters without raising an
  23    error. (This too is required by the SQL standard.) If the string to be
  24    stored is shorter than the declared length, values of type character
  25    will be space-padded; values of type character varying will simply
  26    store the shorter string.
  27
  28    In addition, PostgreSQL provides the text type, which stores strings of
  29    any length. Although the text type is not in the SQL standard, several
  30    other SQL database management systems have it as well. text is
  31    PostgreSQL's native string data type, in that most built-in functions
  32    operating on strings are declared to take or return text not character
  33    varying. For many purposes, character varying acts as though it were a
  34    domain over text.
  35
  36    The type name varchar is an alias for character varying, while bpchar
  37    (with length specifier) and char are aliases for character. The varchar
  38    and char aliases are defined in the SQL standard; bpchar is a
  39    PostgreSQL extension.
  40
  41    If specified, the length n must be greater than zero and cannot exceed
  42    10,485,760. If character varying (or varchar) is used without length
  43    specifier, the type accepts strings of any length. If bpchar lacks a
  44    length specifier, it also accepts strings of any length, but trailing
  45    spaces are semantically insignificant. If character (or char) lacks a
  46    specifier, it is equivalent to character(1).
  47
  48    Values of type character are physically padded with spaces to the
  49    specified width n, and are stored and displayed that way. However,
  50    trailing spaces are treated as semantically insignificant and
  51    disregarded when comparing two values of type character. In collations
  52    where whitespace is significant, this behavior can produce unexpected
  53    results; for example SELECT 'a '::CHAR(2) collate "C" < E'a\n'::CHAR(2)
  54    returns true, even though C locale would consider a space to be greater
  55    than a newline. Trailing spaces are removed when converting a character
  56    value to one of the other string types. Note that trailing spaces are
  57    semantically significant in character varying and text values, and when
  58    using pattern matching, that is LIKE and regular expressions.
  59
  60    The characters that can be stored in any of these data types are
  61    determined by the database character set, which is selected when the
  62    database is created. Regardless of the specific character set, the
  63    character with code zero (sometimes called NUL) cannot be stored. For
  64    more information refer to Section 23.3.
  65
  66    The storage requirement for a short string (up to 126 bytes) is 1 byte
  67    plus the actual string, which includes the space padding in the case of
  68    character. Longer strings have 4 bytes of overhead instead of 1. Long
  69    strings are compressed by the system automatically, so the physical
  70    requirement on disk might be less. Very long values are also stored in
  71    background tables so that they do not interfere with rapid access to
  72    shorter column values. In any case, the longest possible character
  73    string that can be stored is about 1 GB. (The maximum value that will
  74    be allowed for n in the data type declaration is less than that. It
  75    wouldn't be useful to change this because with multibyte character
  76    encodings the number of characters and bytes can be quite different. If
  77    you desire to store long strings with no specific upper limit, use text
  78    or character varying without a length specifier, rather than making up
  79    an arbitrary length limit.)
  80
  81 Tip
  82
  83    There is no performance difference among these three types, apart from
  84    increased storage space when using the blank-padded type, and a few
  85    extra CPU cycles to check the length when storing into a
  86    length-constrained column. While character(n) has performance
  87    advantages in some other database systems, there is no such advantage
  88    in PostgreSQL; in fact character(n) is usually the slowest of the three
  89    because of its additional storage costs. In most situations text or
  90    character varying should be used instead.
  91
  92    Refer to Section 4.1.2.1 for information about the syntax of string
  93    literals, and to Chapter 9 for information about available operators
  94    and functions.
  95
  96    Example 8.1. Using the Character Types
  97 CREATE TABLE test1 (a character(4));
  98 INSERT INTO test1 VALUES ('ok');
  99 SELECT a, char_length(a) FROM test1; -- (1)
 100
 101   a   | char_length
 102 ------+-------------
 103  ok   |           2
 104
 105
 106 CREATE TABLE test2 (b varchar(5));
 107 INSERT INTO test2 VALUES ('ok');
 108 INSERT INTO test2 VALUES ('good      ');
 109 INSERT INTO test2 VALUES ('too long');
 110 ERROR:  value too long for type character varying(5)
 111 INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation
 112 SELECT b, char_length(b) FROM test2;
 113
 114    b   | char_length
 115 -------+-------------
 116  ok    |           2
 117  good  |           5
 118  too l |           5
 119
 120
 121    (1)
 122
 123    The char_length function is discussed in Section 9.4.
 124
 125    There are two other fixed-length character types in PostgreSQL, shown
 126    in Table 8.5. These are not intended for general-purpose use, only for
 127    use in the internal system catalogs. The name type is used to store
 128    identifiers. Its length is currently defined as 64 bytes (63 usable
 129    characters plus terminator) but should be referenced using the constant
 130    NAMEDATALEN in C source code. The length is set at compile time (and is
 131    therefore adjustable for special uses); the default maximum length
 132    might change in a future release. The type "char" (note the quotes) is
 133    different from char(1) in that it only uses one byte of storage, and
 134    therefore can store only a single ASCII character. It is used in the
 135    system catalogs as a simplistic enumeration type.
 136
 137    Table 8.5. Special Character Types
 138     Name  Storage Size          Description
 139    "char" 1 byte       single-byte internal type
 140    name   64 bytes     internal type for object names