begriffs open source - ai-pg/blob - full-docs/src/sgml/html/datatype-character.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>8.3. Character Types</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datatype-money.html" title="8.2. Monetary Types" /><link rel="next" href="datatype-binary.html" title="8.4. Binary Data Types" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">8.3. Character Types</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datatype-money.html" title="8.2. Monetary Types">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><th width="60%" align="center">Chapter 8. Data Types</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datatype-binary.html" title="8.4. Binary Data Types">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATATYPE-CHARACTER"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8.3. Character Types <a href="#DATATYPE-CHARACTER" class="id_link">#</a></h2></div></div></div><a id="id-1.5.7.11.2" class="indexterm"></a><a id="id-1.5.7.11.3" class="indexterm"></a><a id="id-1.5.7.11.4" class="indexterm"></a><a id="id-1.5.7.11.5" class="indexterm"></a><a id="id-1.5.7.11.6" class="indexterm"></a><a id="id-1.5.7.11.7" class="indexterm"></a><a id="id-1.5.7.11.8" class="indexterm"></a><a id="id-1.5.7.11.9" class="indexterm"></a><div class="table" id="DATATYPE-CHARACTER-TABLE"><p class="title"><strong>Table 8.4. Character Types</strong></p><div class="table-contents"><table class="table" summary="Character Types" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">character varying(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">varchar(<em class="replaceable"><code>n</code></em>)</code></td><td>variable-length with limit</td></tr><tr><td><code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">char(<em class="replaceable"><code>n</code></em>)</code>, <code class="type">bpchar(<em class="replaceable"><code>n</code></em>)</code></td><td>fixed-length, blank-padded</td></tr><tr><td><code class="type">bpchar</code></td><td>variable unlimited length, blank-trimmed</td></tr><tr><td><code class="type">text</code></td><td>variable unlimited length</td></tr></tbody></table></div></div><br class="table-break" /><p>
   3     <a class="xref" href="datatype-character.html#DATATYPE-CHARACTER-TABLE" title="Table 8.4. Character Types">Table 8.4</a> shows the
   4     general-purpose character types available in
   5     <span class="productname">PostgreSQL</span>.
   6    </p><p>
   7     <acronym class="acronym">SQL</acronym> defines two primary character types:
   8     <code class="type">character varying(<em class="replaceable"><code>n</code></em>)</code> and
   9     <code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, where <em class="replaceable"><code>n</code></em>
  10     is a positive integer.  Both of these types can store strings up to
  11     <em class="replaceable"><code>n</code></em> characters (not bytes) in length.  An attempt to store a
  12     longer string into a column of these types will result in an
  13     error, unless the excess characters are all spaces, in which case
  14     the string will be truncated to the maximum length. (This somewhat
  15     bizarre exception is required by the <acronym class="acronym">SQL</acronym>
  16     standard.)
  17     However, if one explicitly casts a value to <code class="type">character
  18     varying(<em class="replaceable"><code>n</code></em>)</code> or
  19     <code class="type">character(<em class="replaceable"><code>n</code></em>)</code>, then an over-length
  20     value will be truncated to <em class="replaceable"><code>n</code></em> characters without
  21     raising an error. (This too is required by the
  22     <acronym class="acronym">SQL</acronym> standard.)
  23     If the string to be stored is shorter than the declared
  24     length, values of type <code class="type">character</code> will be space-padded;
  25     values of type <code class="type">character varying</code> will simply store the
  26     shorter
  27     string.
  28    </p><p>
  29     In addition, <span class="productname">PostgreSQL</span> provides the
  30     <code class="type">text</code> type, which stores strings of any length.
  31     Although the <code class="type">text</code> type is not in the
  32     <acronym class="acronym">SQL</acronym> standard, several other SQL database
  33     management systems have it as well.
  34     <code class="type">text</code> is <span class="productname">PostgreSQL</span>'s native
  35     string data type, in that most built-in functions operating on strings
  36     are declared to take or return <code class="type">text</code> not <code class="type">character
  37     varying</code>.  For many purposes, <code class="type">character varying</code>
  38     acts as though it were a <a class="link" href="domains.html" title="8.18. Domain Types">domain</a>
  39     over <code class="type">text</code>.
  40    </p><p>
  41     The type name <code class="type">varchar</code> is an alias for <code class="type">character
  42     varying</code>, while <code class="type">bpchar</code> (with length specifier) and
  43     <code class="type">char</code> are aliases for <code class="type">character</code>.  The
  44     <code class="type">varchar</code> and <code class="type">char</code> aliases are defined in the
  45     <acronym class="acronym">SQL</acronym> standard;  <code class="type">bpchar</code> is a
  46     <span class="productname">PostgreSQL</span> extension.
  47    </p><p>
  48     If specified, the length <em class="replaceable"><code>n</code></em> must be greater
  49     than zero and cannot exceed 10,485,760.  If <code class="type">character
  50     varying</code> (or <code class="type">varchar</code>) is used without
  51     length specifier, the type accepts strings of any length. If
  52     <code class="type">bpchar</code> lacks a length specifier, it also accepts strings
  53     of any length, but trailing spaces are semantically insignificant.
  54     If <code class="type">character</code> (or <code class="type">char</code>) lacks a specifier,
  55     it is equivalent to <code class="type">character(1)</code>.
  56    </p><p>
  57     Values of type <code class="type">character</code> are physically padded
  58     with spaces to the specified width <em class="replaceable"><code>n</code></em>, and are
  59     stored and displayed that way.  However, trailing spaces are treated as
  60     semantically insignificant and disregarded when comparing two values
  61     of type <code class="type">character</code>.  In collations where whitespace
  62     is significant, this behavior can produce unexpected results;
  63     for example <code class="command">SELECT 'a '::CHAR(2) collate "C" &lt;
  64     E'a\n'::CHAR(2)</code> returns true, even though <code class="literal">C</code>
  65     locale would consider a space to be greater than a newline.
  66     Trailing spaces are removed when converting a <code class="type">character</code> value
  67     to one of the other string types.  Note that trailing spaces
  68     <span class="emphasis"><em>are</em></span> semantically significant in
  69     <code class="type">character varying</code> and <code class="type">text</code> values, and
  70     when using pattern matching, that is <code class="literal">LIKE</code> and
  71     regular expressions.
  72    </p><p>
  73     The characters that can be stored in any of these data types are
  74     determined by the database character set, which is selected when
  75     the database is created.  Regardless of the specific character set,
  76     the character with code zero (sometimes called NUL) cannot be stored.
  77     For more information refer to <a class="xref" href="multibyte.html" title="23.3. Character Set Support">Section 23.3</a>.
  78    </p><p>
  79     The storage requirement for a short string (up to 126 bytes) is 1 byte
  80     plus the actual string, which includes the space padding in the case of
  81     <code class="type">character</code>.  Longer strings have 4 bytes of overhead instead
  82     of 1.  Long strings are compressed by the system automatically, so
  83     the physical requirement on disk might be less. Very long values are also
  84     stored in background tables so that they do not interfere with rapid
  85     access to shorter column values. In any case, the longest
  86     possible character string that can be stored is about 1 GB. (The
  87     maximum value that will be allowed for <em class="replaceable"><code>n</code></em> in the data
  88     type declaration is less than that. It wouldn't be useful to
  89     change this because with multibyte character encodings the number of
  90     characters and bytes can be quite different. If you desire to
  91     store long strings with no specific upper limit, use
  92     <code class="type">text</code> or <code class="type">character varying</code> without a length
  93     specifier, rather than making up an arbitrary length limit.)
  94    </p><div class="tip"><h3 class="title">Tip</h3><p>
  95      There is no performance difference among these three types,
  96      apart from increased storage space when using the blank-padded
  97      type, and a few extra CPU cycles to check the length when storing into
  98      a length-constrained column.  While
  99      <code class="type">character(<em class="replaceable"><code>n</code></em>)</code> has performance
 100      advantages in some other database systems, there is no such advantage in
 101      <span class="productname">PostgreSQL</span>; in fact
 102      <code class="type">character(<em class="replaceable"><code>n</code></em>)</code> is usually the slowest of
 103      the three because of its additional storage costs.  In most situations
 104      <code class="type">text</code> or <code class="type">character varying</code> should be used
 105      instead.
 106     </p></div><p>
 107     Refer to <a class="xref" href="sql-syntax-lexical.html#SQL-SYNTAX-STRINGS" title="4.1.2.1. String Constants">Section 4.1.2.1</a> for information about
 108     the syntax of string literals, and to <a class="xref" href="functions.html" title="Chapter 9. Functions and Operators">Chapter 9</a>
 109     for information about available operators and functions.
 110    </p><div class="example" id="id-1.5.7.11.21"><p class="title"><strong>Example 8.1. Using the Character Types</strong></p><div class="example-contents"><pre class="programlisting">
 111 CREATE TABLE test1 (a character(4));
 112 INSERT INTO test1 VALUES ('ok');
 113 SELECT a, char_length(a) FROM test1; -- <span id="co.datatype-char"></span>(1)
 114 <code class="computeroutput">
 115   a   | char_length
 116 ------+-------------
 117  ok   |           2
 118 </code>
 119
 120 CREATE TABLE test2 (b varchar(5));
 121 INSERT INTO test2 VALUES ('ok');
 122 INSERT INTO test2 VALUES ('good      ');
 123 INSERT INTO test2 VALUES ('too long');
 124 <code class="computeroutput">ERROR:  value too long for type character varying(5)</code>
 125 INSERT INTO test2 VALUES ('too long'::varchar(5)); -- explicit truncation
 126 SELECT b, char_length(b) FROM test2;
 127 <code class="computeroutput">
 128    b   | char_length
 129 -------+-------------
 130  ok    |           2
 131  good  |           5
 132  too l |           5
 133 </code>
 134 </pre><div class="calloutlist"><table border="0" summary="Callout list"><tr><td width="5%" valign="top" align="left"><p><a href="#co.datatype-char">(1)</a> </p></td><td valign="top" align="left"><p>
 135        The <code class="function">char_length</code> function is discussed in
 136        <a class="xref" href="functions-string.html" title="9.4. String Functions and Operators">Section 9.4</a>.
 137       </p></td></tr></table></div></div></div><br class="example-break" /><p>
 138     There are two other fixed-length character types in
 139     <span class="productname">PostgreSQL</span>, shown in <a class="xref" href="datatype-character.html#DATATYPE-CHARACTER-SPECIAL-TABLE" title="Table 8.5. Special Character Types">Table 8.5</a>.
 140     These are not intended for general-purpose use, only for use
 141     in the internal system catalogs.
 142     The <code class="type">name</code> type is used to store identifiers. Its
 143     length is currently defined as 64 bytes (63 usable characters plus
 144     terminator) but should be referenced using the constant
 145     <code class="symbol">NAMEDATALEN</code> in <code class="literal">C</code> source code.
 146     The length is set at compile time (and
 147     is therefore adjustable for special uses); the default maximum
 148     length might change in a future release. The type <code class="type">"char"</code>
 149     (note the quotes) is different from <code class="type">char(1)</code> in that it
 150     only uses one byte of storage, and therefore can store only a single
 151     ASCII character. It is used in the system
 152     catalogs as a simplistic enumeration type.
 153    </p><div class="table" id="DATATYPE-CHARACTER-SPECIAL-TABLE"><p class="title"><strong>Table 8.5. Special Character Types</strong></p><div class="table-contents"><table class="table" summary="Special Character Types" border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Name</th><th>Storage Size</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">"char"</code></td><td>1 byte</td><td>single-byte internal type</td></tr><tr><td><code class="type">name</code></td><td>64 bytes</td><td>internal type for object names</td></tr></tbody></table></div></div><br class="table-break" /></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datatype-money.html" title="8.2. Monetary Types">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datatype.html" title="Chapter 8. Data Types">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datatype-binary.html" title="8.4. Binary Data Types">Next</a></td></tr><tr><td width="40%" align="left" valign="top">8.2. Monetary Types </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 8.4. Binary Data Types</td></tr></table></div></body></html>