begriffs open source - ai-pg/blob - full-docs/src/sgml/html/extend-type-system.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>36.2. The PostgreSQL Type System</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="extend-how.html" title="36.1. How Extensibility Works" /><link rel="next" href="xfunc.html" title="36.3. User-Defined Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">36.2. The <span class="productname">PostgreSQL</span> Type System</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="extend-how.html" title="36.1. How Extensibility Works">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="extend.html" title="Chapter 36. Extending SQL">Up</a></td><th width="60%" align="center">Chapter 36. Extending <acronym class="acronym">SQL</acronym></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="xfunc.html" title="36.3. User-Defined Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="EXTEND-TYPE-SYSTEM"><div class="titlepage"><div><div><h2 class="title" style="clear: both">36.2. The <span class="productname">PostgreSQL</span> Type System <a href="#EXTEND-TYPE-SYSTEM" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPE-SYSTEM-BASE">36.2.1. Base Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPE-SYSTEM-CONTAINER">36.2.2. Container Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPE-SYSTEM-DOMAINS">36.2.3. Domains</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPE-SYSTEM-PSEUDO">36.2.4. Pseudo-Types</a></span></dt><dt><span class="sect2"><a href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC">36.2.5. Polymorphic Types</a></span></dt></dl></div><a id="id-1.8.3.5.2" class="indexterm"></a><a id="id-1.8.3.5.3" class="indexterm"></a><a id="id-1.8.3.5.4" class="indexterm"></a><a id="id-1.8.3.5.5" class="indexterm"></a><a id="id-1.8.3.5.6" class="indexterm"></a><a id="id-1.8.3.5.7" class="indexterm"></a><p>
   3     <span class="productname">PostgreSQL</span> data types can be divided into base
   4     types, container types, domains, and pseudo-types.
   5    </p><div class="sect2" id="EXTEND-TYPE-SYSTEM-BASE"><div class="titlepage"><div><div><h3 class="title">36.2.1. Base Types <a href="#EXTEND-TYPE-SYSTEM-BASE" class="id_link">#</a></h3></div></div></div><p>
   6      Base types are those, like <code class="type">integer</code>, that are
   7      implemented below the level of the <acronym class="acronym">SQL</acronym> language
   8      (typically in a low-level language such as C).  They generally
   9      correspond to what are often known as abstract data types.
  10      <span class="productname">PostgreSQL</span> can only operate on such
  11      types through functions provided by the user and only understands
  12      the behavior of such types to the extent that the user describes
  13      them.
  14      The built-in base types are described in <a class="xref" href="datatype.html" title="Chapter 8. Data Types">Chapter 8</a>.
  15     </p><p>
  16      Enumerated (enum) types can be considered as a subcategory of base
  17      types.  The main difference is that they can be created using
  18      just <acronym class="acronym">SQL</acronym> commands, without any low-level programming.
  19      Refer to <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a> for more information.
  20     </p></div><div class="sect2" id="EXTEND-TYPE-SYSTEM-CONTAINER"><div class="titlepage"><div><div><h3 class="title">36.2.2. Container Types <a href="#EXTEND-TYPE-SYSTEM-CONTAINER" class="id_link">#</a></h3></div></div></div><p>
  21      <span class="productname">PostgreSQL</span> has three kinds
  22      of <span class="quote">“<span class="quote">container</span>”</span> types, which are types that contain multiple
  23      values of other types.  These are arrays, composites, and ranges.
  24     </p><p>
  25      Arrays can hold multiple values that are all of the same type.  An array
  26      type is automatically created for each base type, composite type, range
  27      type, and domain type.  But there are no arrays of arrays.  So far as
  28      the type system is concerned, multi-dimensional arrays are the same as
  29      one-dimensional arrays.  Refer to <a class="xref" href="arrays.html" title="8.15. Arrays">Section 8.15</a> for more
  30      information.
  31     </p><p>
  32      Composite types, or row types, are created whenever the user
  33      creates a table. It is also possible to use <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a> to
  34      define a <span class="quote">“<span class="quote">stand-alone</span>”</span> composite type with no associated
  35      table.  A composite type is simply a list of types with
  36      associated field names.  A value of a composite type is a row or
  37      record of field values.  Refer to <a class="xref" href="rowtypes.html" title="8.16. Composite Types">Section 8.16</a>
  38      for more information.
  39     </p><p>
  40      A range type can hold two values of the same type, which are the lower
  41      and upper bounds of the range.  Range types are user-created, although
  42      a few built-in ones exist.  Refer to <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>
  43      for more information.
  44     </p></div><div class="sect2" id="EXTEND-TYPE-SYSTEM-DOMAINS"><div class="titlepage"><div><div><h3 class="title">36.2.3. Domains <a href="#EXTEND-TYPE-SYSTEM-DOMAINS" class="id_link">#</a></h3></div></div></div><p>
  45      A domain is based on a particular underlying type and for many purposes
  46      is interchangeable with its underlying type.  However, a domain can have
  47      constraints that restrict its valid values to a subset of what the
  48      underlying type would allow.  Domains are created using
  49      the <acronym class="acronym">SQL</acronym> command <a class="xref" href="sql-createdomain.html" title="CREATE DOMAIN"><span class="refentrytitle">CREATE DOMAIN</span></a>.
  50      Refer to <a class="xref" href="domains.html" title="8.18. Domain Types">Section 8.18</a> for more information.
  51     </p></div><div class="sect2" id="EXTEND-TYPE-SYSTEM-PSEUDO"><div class="titlepage"><div><div><h3 class="title">36.2.4. Pseudo-Types <a href="#EXTEND-TYPE-SYSTEM-PSEUDO" class="id_link">#</a></h3></div></div></div><p>
  52      There are a few <span class="quote">“<span class="quote">pseudo-types</span>”</span> for special purposes.
  53      Pseudo-types cannot appear as columns of tables or components of
  54      container types, but they can be used to declare the argument and
  55      result types of functions.  This provides a mechanism within the
  56      type system to identify special classes of functions.  <a class="xref" href="datatype-pseudo.html#DATATYPE-PSEUDOTYPES-TABLE" title="Table 8.27. Pseudo-Types">Table 8.27</a> lists the existing
  57      pseudo-types.
  58     </p></div><div class="sect2" id="EXTEND-TYPES-POLYMORPHIC"><div class="titlepage"><div><div><h3 class="title">36.2.5. Polymorphic Types <a href="#EXTEND-TYPES-POLYMORPHIC" class="id_link">#</a></h3></div></div></div><a id="id-1.8.3.5.13.2" class="indexterm"></a><a id="id-1.8.3.5.13.3" class="indexterm"></a><a id="id-1.8.3.5.13.4" class="indexterm"></a><a id="id-1.8.3.5.13.5" class="indexterm"></a><p>
  59      Some pseudo-types of special interest are the <em class="firstterm">polymorphic
  60      types</em>, which are used to declare <em class="firstterm">polymorphic
  61      functions</em>.  This powerful feature allows a single function
  62      definition to operate on many different data types, with the specific
  63      data type(s) being determined by the data types actually passed to it
  64      in a particular call.  The polymorphic types are shown in
  65      <a class="xref" href="extend-type-system.html#EXTEND-TYPES-POLYMORPHIC-TABLE" title="Table 36.1. Polymorphic Types">Table 36.1</a>.  Some examples of
  66      their use appear in <a class="xref" href="xfunc-sql.html#XFUNC-SQL-POLYMORPHIC-FUNCTIONS" title="36.5.11. Polymorphic SQL Functions">Section 36.5.11</a>.
  67     </p><div class="table" id="EXTEND-TYPES-POLYMORPHIC-TABLE"><p class="title"><strong>Table 36.1. Polymorphic Types</strong></p><div class="table-contents"><table class="table" summary="Polymorphic Types" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Family</th><th>Description</th></tr></thead><tbody><tr><td><code class="type">anyelement</code></td><td>Simple</td><td>Indicates that a function accepts any data type</td></tr><tr><td><code class="type">anyarray</code></td><td>Simple</td><td>Indicates that a function accepts any array data type</td></tr><tr><td><code class="type">anynonarray</code></td><td>Simple</td><td>Indicates that a function accepts any non-array data type</td></tr><tr><td><code class="type">anyenum</code></td><td>Simple</td><td>Indicates that a function accepts any enum data type
  68         (see <a class="xref" href="datatype-enum.html" title="8.7. Enumerated Types">Section 8.7</a>)
  69         </td></tr><tr><td><code class="type">anyrange</code></td><td>Simple</td><td>Indicates that a function accepts any range data type
  70         (see <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>)
  71         </td></tr><tr><td><code class="type">anymultirange</code></td><td>Simple</td><td>Indicates that a function accepts any multirange data type
  72         (see <a class="xref" href="rangetypes.html" title="8.17. Range Types">Section 8.17</a>)
  73         </td></tr><tr><td><code class="type">anycompatible</code></td><td>Common</td><td>Indicates that a function accepts any data type,
  74         with automatic promotion of multiple arguments to a common data type
  75         </td></tr><tr><td><code class="type">anycompatiblearray</code></td><td>Common</td><td>Indicates that a function accepts any array data type,
  76         with automatic promotion of multiple arguments to a common data type
  77         </td></tr><tr><td><code class="type">anycompatiblenonarray</code></td><td>Common</td><td>Indicates that a function accepts any non-array data type,
  78         with automatic promotion of multiple arguments to a common data type
  79         </td></tr><tr><td><code class="type">anycompatiblerange</code></td><td>Common</td><td>Indicates that a function accepts any range data type,
  80         with automatic promotion of multiple arguments to a common data type
  81         </td></tr><tr><td><code class="type">anycompatiblemultirange</code></td><td>Common</td><td>Indicates that a function accepts any multirange data type,
  82         with automatic promotion of multiple arguments to a common data type
  83         </td></tr></tbody></table></div></div><br class="table-break" /><p>
  84      Polymorphic arguments and results are tied to each other and are resolved
  85      to specific data types when a query calling a polymorphic function is
  86      parsed.  When there is more than one polymorphic argument, the actual
  87      data types of the input values must match up as described below.  If the
  88      function's result type is polymorphic, or it has output parameters of
  89      polymorphic types, the types of those results are deduced from the
  90      actual types of the polymorphic inputs as described below.
  91     </p><p>
  92      For the <span class="quote">“<span class="quote">simple</span>”</span> family of polymorphic types, the
  93      matching and deduction rules work like this:
  94     </p><p>
  95      Each position (either argument or return value) declared as
  96      <code class="type">anyelement</code> is allowed to have any specific actual
  97      data type, but in any given call they must all be the
  98      <span class="emphasis"><em>same</em></span> actual type. Each
  99      position declared as <code class="type">anyarray</code> can have any array data type,
 100      but similarly they must all be the same type.  And similarly,
 101      positions declared as <code class="type">anyrange</code> must all be the same range
 102      type.  Likewise for <code class="type">anymultirange</code>.
 103     </p><p>
 104      Furthermore, if there are
 105      positions declared <code class="type">anyarray</code> and others declared
 106      <code class="type">anyelement</code>, the actual array type in the
 107      <code class="type">anyarray</code> positions must be an array whose elements are
 108      the same type appearing in the <code class="type">anyelement</code> positions.
 109      <code class="type">anynonarray</code> is treated exactly the same as <code class="type">anyelement</code>,
 110      but adds the additional constraint that the actual type must not be
 111      an array type.
 112      <code class="type">anyenum</code> is treated exactly the same as <code class="type">anyelement</code>,
 113      but adds the additional constraint that the actual type must
 114      be an enum type.
 115     </p><p>
 116      Similarly, if there are positions declared <code class="type">anyrange</code>
 117      and others declared <code class="type">anyelement</code> or <code class="type">anyarray</code>,
 118      the actual range type in the <code class="type">anyrange</code> positions must be a
 119      range whose subtype is the same type appearing in
 120      the <code class="type">anyelement</code> positions and the same as the element type
 121      of the <code class="type">anyarray</code> positions.
 122      If there are positions declared <code class="type">anymultirange</code>,
 123      their actual multirange type must contain ranges matching parameters declared
 124      <code class="type">anyrange</code> and base elements matching parameters declared
 125      <code class="type">anyelement</code> and <code class="type">anyarray</code>.
 126     </p><p>
 127      Thus, when more than one argument position is declared with a polymorphic
 128      type, the net effect is that only certain combinations of actual argument
 129      types are allowed.  For example, a function declared as
 130      <code class="literal">equal(anyelement, anyelement)</code> will take any two input values,
 131      so long as they are of the same data type.
 132     </p><p>
 133      When the return value of a function is declared as a polymorphic type,
 134      there must be at least one argument position that is also polymorphic,
 135      and the actual data type(s) supplied for the polymorphic arguments
 136      determine the actual
 137      result type for that call.  For example, if there were not already
 138      an array subscripting mechanism, one could define a function that
 139      implements subscripting as <code class="literal">subscript(anyarray, integer)
 140      returns anyelement</code>.  This declaration constrains the actual first
 141      argument to be an array type, and allows the parser to infer the correct
 142      result type from the actual first argument's type.  Another example
 143      is that a function declared as <code class="literal">f(anyarray) returns anyenum</code>
 144      will only accept arrays of enum types.
 145     </p><p>
 146      In most cases, the parser can infer the actual data type for a
 147      polymorphic result type from arguments that are of a different
 148      polymorphic type in the same family; for example <code class="type">anyarray</code>
 149      can be deduced from <code class="type">anyelement</code> or vice versa.
 150      An exception is that a
 151      polymorphic result of type <code class="type">anyrange</code> requires an argument
 152      of type <code class="type">anyrange</code>; it cannot be deduced
 153      from <code class="type">anyarray</code> or <code class="type">anyelement</code> arguments.  This
 154      is because there could be multiple range types with the same subtype.
 155     </p><p>
 156      Note that <code class="type">anynonarray</code> and <code class="type">anyenum</code> do not represent
 157      separate type variables; they are the same type as
 158      <code class="type">anyelement</code>, just with an additional constraint.  For
 159      example, declaring a function as <code class="literal">f(anyelement, anyenum)</code>
 160      is equivalent to declaring it as <code class="literal">f(anyenum, anyenum)</code>:
 161      both actual arguments have to be the same enum type.
 162     </p><p>
 163      For the <span class="quote">“<span class="quote">common</span>”</span> family of polymorphic types, the
 164      matching and deduction rules work approximately the same as for
 165      the <span class="quote">“<span class="quote">simple</span>”</span> family, with one major difference: the
 166      actual types of the arguments need not be identical, so long as they
 167      can be implicitly cast to a single common type.  The common type is
 168      selected following the same rules as for <code class="literal">UNION</code> and
 169      related constructs (see <a class="xref" href="typeconv-union-case.html" title="10.5. UNION, CASE, and Related Constructs">Section 10.5</a>).
 170      Selection of the common type considers the actual types
 171      of <code class="type">anycompatible</code> and <code class="type">anycompatiblenonarray</code>
 172      inputs, the array element types of <code class="type">anycompatiblearray</code>
 173      inputs, the range subtypes of <code class="type">anycompatiblerange</code> inputs,
 174      and the multirange subtypes of <code class="type">anycompatiblemultirange</code>
 175      inputs.  If <code class="type">anycompatiblenonarray</code> is present then the
 176      common type is required to be a non-array type.  Once a common type is
 177      identified, arguments in <code class="type">anycompatible</code>
 178      and <code class="type">anycompatiblenonarray</code> positions are automatically
 179      cast to that type, and arguments in <code class="type">anycompatiblearray</code>
 180      positions are automatically cast to the array type for that type.
 181     </p><p>
 182      Since there is no way to select a range type knowing only its subtype,
 183      use of <code class="type">anycompatiblerange</code> and/or
 184      <code class="type">anycompatiblemultirange</code> requires that all arguments declared
 185      with that type have the same actual range and/or multirange type, and that
 186      that type's subtype agree with the selected common type, so that no casting
 187      of the range values is required.  As with <code class="type">anyrange</code> and
 188      <code class="type">anymultirange</code>, use of <code class="type">anycompatiblerange</code> and
 189      <code class="type">anymultirange</code> as a function result type requires that there be
 190      an <code class="type">anycompatiblerange</code> or <code class="type">anycompatiblemultirange</code>
 191      argument.
 192     </p><p>
 193      Notice that there is no <code class="type">anycompatibleenum</code> type.  Such a
 194      type would not be very useful, since there normally are not any
 195      implicit casts to enum types, meaning that there would be no way to
 196      resolve a common type for dissimilar enum inputs.
 197     </p><p>
 198      The <span class="quote">“<span class="quote">simple</span>”</span> and <span class="quote">“<span class="quote">common</span>”</span> polymorphic
 199      families represent two independent sets of type variables.  Consider
 200      for example
 201 </p><pre class="programlisting">
 202 CREATE FUNCTION myfunc(a anyelement, b anyelement,
 203                        c anycompatible, d anycompatible)
 204 RETURNS anycompatible AS ...
 205 </pre><p>
 206      In an actual call of this function, the first two inputs must have
 207      exactly the same type.  The last two inputs must be promotable to a
 208      common type, but this type need not have anything to do with the type
 209      of the first two inputs.  The result will have the common type of the
 210      last two inputs.
 211     </p><p>
 212      A variadic function (one taking a variable number of arguments, as in
 213      <a class="xref" href="xfunc-sql.html#XFUNC-SQL-VARIADIC-FUNCTIONS" title="36.5.6. SQL Functions with Variable Numbers of Arguments">Section 36.5.6</a>) can be
 214      polymorphic: this is accomplished by declaring its last parameter as
 215      <code class="literal">VARIADIC</code> <code class="type">anyarray</code> or
 216      <code class="literal">VARIADIC</code> <code class="type">anycompatiblearray</code>.
 217      For purposes of argument
 218      matching and determining the actual result type, such a function behaves
 219      the same as if you had written the appropriate number of
 220      <code class="type">anynonarray</code> or <code class="type">anycompatiblenonarray</code>
 221      parameters.
 222     </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="extend-how.html" title="36.1. How Extensibility Works">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="extend.html" title="Chapter 36. Extending SQL">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="xfunc.html" title="36.3. User-Defined Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">36.1. How Extensibility Works </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"> 36.3. User-Defined Functions</td></tr></table></div></body></html>