begriffs open source - ai-pg/blob - full-docs/txt/extend-type-system.txt

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