1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2006-04-06 00:11:58 +02:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/create_type.sgml,v 1.63 2006/04/05 22:11:54 tgl Exp $
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refentry id="SQL-CREATETYPE">
|
|
|
|
<refmeta>
|
2002-04-21 21:02:39 +02:00
|
|
|
<refentrytitle id="sql-createtype-title">CREATE TYPE</refentrytitle>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<refname>CREATE TYPE</refname>
|
|
|
|
<refpurpose>define a new data type</refpurpose>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="sql-createtype">
|
|
|
|
<primary>CREATE TYPE</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<synopsis>
|
2003-09-22 02:16:58 +02:00
|
|
|
CREATE TYPE <replaceable class="parameter">name</replaceable> AS
|
2003-05-09 00:19:58 +02:00
|
|
|
( <replaceable class="PARAMETER">attribute_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] )
|
|
|
|
|
2003-09-22 02:16:58 +02:00
|
|
|
CREATE TYPE <replaceable class="parameter">name</replaceable> (
|
2003-05-09 00:19:58 +02:00
|
|
|
INPUT = <replaceable class="parameter">input_function</replaceable>,
|
|
|
|
OUTPUT = <replaceable class="parameter">output_function</replaceable>
|
|
|
|
[ , RECEIVE = <replaceable class="parameter">receive_function</replaceable> ]
|
|
|
|
[ , SEND = <replaceable class="parameter">send_function</replaceable> ]
|
2004-02-13 00:41:04 +01:00
|
|
|
[ , ANALYZE = <replaceable class="parameter">analyze_function</replaceable> ]
|
2003-05-09 00:19:58 +02:00
|
|
|
[ , INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE } ]
|
2000-08-25 01:36:29 +02:00
|
|
|
[ , PASSEDBYVALUE ]
|
|
|
|
[ , ALIGNMENT = <replaceable class="parameter">alignment</replaceable> ]
|
|
|
|
[ , STORAGE = <replaceable class="parameter">storage</replaceable> ]
|
2003-05-09 00:19:58 +02:00
|
|
|
[ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
|
|
|
|
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ]
|
|
|
|
[ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
|
2000-08-25 01:36:29 +02:00
|
|
|
)
|
2006-02-28 23:37:27 +01:00
|
|
|
|
|
|
|
CREATE TYPE <replaceable class="parameter">name</replaceable>
|
2003-04-22 12:08:08 +02:00
|
|
|
</synopsis>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsynopsisdiv>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
<command>CREATE TYPE</command> registers a new data type for use in
|
2005-01-04 01:39:53 +01:00
|
|
|
the current database. The user who defines a type becomes its
|
2003-04-22 12:08:08 +02:00
|
|
|
owner.
|
2002-04-23 04:07:16 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
If a schema name is given then the type is created in the specified
|
|
|
|
schema. Otherwise it is created in the current schema. The type
|
|
|
|
name must be distinct from the name of any existing type or domain
|
|
|
|
in the same schema. (Because tables have associated data types,
|
|
|
|
the type name must also be distinct from the name of any existing
|
|
|
|
table in the same schema.)
|
1998-07-29 08:23:26 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2003-05-09 00:19:58 +02:00
|
|
|
<refsect2>
|
|
|
|
<title>Composite Types</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The first form of <command>CREATE TYPE</command>
|
|
|
|
creates a composite type.
|
|
|
|
The composite type is specified by a list of attribute names and data types.
|
|
|
|
This is essentially the same as the row type
|
|
|
|
of a table, but using <command>CREATE TYPE</command> avoids the need to
|
|
|
|
create an actual table when all that is wanted is to define a type.
|
2005-01-04 01:39:53 +01:00
|
|
|
A stand-alone composite type is useful as the argument or return type of a
|
|
|
|
function.
|
2003-05-09 00:19:58 +02:00
|
|
|
</para>
|
|
|
|
</refsect2>
|
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
<refsect2>
|
|
|
|
<title>Base Types</title>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The second form of <command>CREATE TYPE</command> creates a new base type
|
|
|
|
(scalar type). The parameters may appear in any order, not only that
|
|
|
|
illustrated above, and most are optional. You must register
|
|
|
|
two or more functions (using <command>CREATE FUNCTION</command>) before
|
|
|
|
defining the type. The support functions
|
|
|
|
<replaceable class="parameter">input_function</replaceable> and
|
|
|
|
<replaceable class="parameter">output_function</replaceable>
|
|
|
|
are required, while the functions
|
2004-02-13 00:41:04 +01:00
|
|
|
<replaceable class="parameter">receive_function</replaceable>,
|
|
|
|
<replaceable class="parameter">send_function</replaceable> and
|
|
|
|
<replaceable class="parameter">analyze_function</replaceable>
|
2003-05-09 00:19:58 +02:00
|
|
|
are optional. Generally these functions have to be coded in C
|
|
|
|
or another low-level language.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <replaceable class="parameter">input_function</replaceable>
|
|
|
|
converts the type's external textual representation to the internal
|
2006-04-04 21:35:37 +02:00
|
|
|
representation used by the operators and functions defined for the type.
|
1998-07-29 08:23:26 +02:00
|
|
|
<replaceable class="parameter">output_function</replaceable>
|
2001-11-03 22:42:47 +01:00
|
|
|
performs the reverse transformation. The input function may be
|
2002-08-22 02:01:51 +02:00
|
|
|
declared as taking one argument of type <type>cstring</type>,
|
2001-11-03 22:42:47 +01:00
|
|
|
or as taking three arguments of types
|
2003-04-22 12:08:08 +02:00
|
|
|
<type>cstring</type>, <type>oid</type>, <type>integer</type>.
|
|
|
|
The first argument is the input text as a C string, the second
|
2005-08-12 23:49:47 +02:00
|
|
|
argument is the type's own OID (except for array types, which instead
|
|
|
|
receive their element type's OID),
|
2005-01-04 01:39:53 +01:00
|
|
|
and the third is the <literal>typmod</> of the destination column, if known
|
|
|
|
(-1 will be passed if not).
|
2005-05-01 20:56:19 +02:00
|
|
|
The input function must return a value of the data type itself.
|
2006-04-04 21:35:37 +02:00
|
|
|
Usually, an input function should be declared STRICT; if it is not,
|
|
|
|
it will be called with a NULL first parameter when reading a NULL
|
|
|
|
input value. The function must still return NULL in this case, unless
|
|
|
|
it raises an error.
|
|
|
|
(This case is mainly meant to support domain input functions, which
|
|
|
|
may need to reject NULL inputs.)
|
2005-05-01 20:56:19 +02:00
|
|
|
The output function must be
|
|
|
|
declared as taking one argument of the new data type.
|
|
|
|
The output function must return type <type>cstring</type>.
|
2006-04-04 21:35:37 +02:00
|
|
|
Output functions are not invoked for NULL values.
|
1998-07-29 08:23:26 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2003-05-09 00:19:58 +02:00
|
|
|
<para>
|
|
|
|
The optional <replaceable class="parameter">receive_function</replaceable>
|
|
|
|
converts the type's external binary representation to the internal
|
|
|
|
representation. If this function is not supplied, the type cannot
|
|
|
|
participate in binary input. The binary representation should be
|
|
|
|
chosen to be cheap to convert to internal form, while being reasonably
|
2003-11-01 02:56:29 +01:00
|
|
|
portable. (For example, the standard integer data types use network
|
2003-05-09 00:19:58 +02:00
|
|
|
byte order as the external binary representation, while the internal
|
|
|
|
representation is in the machine's native byte order.) The receive
|
|
|
|
function should perform adequate checking to ensure that the value is
|
|
|
|
valid.
|
2003-05-10 01:01:45 +02:00
|
|
|
The receive function may be declared as taking one argument of type
|
2005-07-10 23:14:00 +02:00
|
|
|
<type>internal</type>, or as taking three arguments of types
|
|
|
|
<type>internal</type>, <type>oid</type>, <type>integer</type>.
|
|
|
|
The first argument is a pointer to a <type>StringInfo</type> buffer
|
|
|
|
holding the received byte string; the optional arguments are the
|
|
|
|
same as for the text input function.
|
|
|
|
The receive function must return a value of the data type itself.
|
2006-04-04 21:35:37 +02:00
|
|
|
Usually, a receive function should be declared STRICT; if it is not,
|
|
|
|
it will be called with a NULL first parameter when reading a NULL
|
|
|
|
input value. The function must still return NULL in this case, unless
|
|
|
|
it raises an error.
|
|
|
|
(This case is mainly meant to support domain receive functions, which
|
|
|
|
may need to reject NULL inputs.)
|
2005-07-10 23:14:00 +02:00
|
|
|
Similarly, the optional
|
2003-05-09 00:19:58 +02:00
|
|
|
<replaceable class="parameter">send_function</replaceable> converts
|
|
|
|
from the internal representation to the external binary representation.
|
|
|
|
If this function is not supplied, the type cannot participate in binary
|
2005-05-01 20:56:19 +02:00
|
|
|
output. The send function must be
|
|
|
|
declared as taking one argument of the new data type.
|
2003-05-10 01:01:45 +02:00
|
|
|
The send function must return type <type>bytea</type>.
|
2006-04-04 21:35:37 +02:00
|
|
|
Send functions are not invoked for NULL values.
|
2003-05-09 00:19:58 +02:00
|
|
|
</para>
|
|
|
|
|
2002-08-22 02:01:51 +02:00
|
|
|
<para>
|
|
|
|
You should at this point be wondering how the input and output functions
|
2006-02-28 23:37:27 +01:00
|
|
|
can be declared to have results or arguments of the new type, when they
|
|
|
|
have to be created before the new type can be created. The answer is that
|
|
|
|
the type should first be defined as a <firstterm>shell type</>, which is a
|
|
|
|
placeholder type that has no properties except a name and an owner. This
|
|
|
|
is done by issuing the command <literal>CREATE TYPE
|
|
|
|
<replaceable>name</></literal>, with no additional parameters. Then the
|
|
|
|
I/O functions can be defined referencing the shell type. Finally,
|
|
|
|
<command>CREATE TYPE</> with a full definition replaces the shell entry
|
|
|
|
with a complete, valid type definition, after which the new type can be
|
|
|
|
used normally.
|
2002-08-22 02:01:51 +02:00
|
|
|
</para>
|
|
|
|
|
2004-02-13 00:41:04 +01:00
|
|
|
<para>
|
|
|
|
The optional <replaceable class="parameter">analyze_function</replaceable>
|
|
|
|
performs type-specific statistics collection for columns of the data type.
|
|
|
|
By default, <command>ANALYZE</> will attempt to gather statistics using
|
|
|
|
the type's <quote>equals</> and <quote>less-than</> operators, if there
|
|
|
|
is a default b-tree operator class for the type. For non-scalar types
|
|
|
|
this behavior is likely to be unsuitable, so it can be overridden by
|
|
|
|
specifying a custom analysis function. The analysis function must be
|
|
|
|
declared to take a single argument of type <type>internal</>, and return
|
|
|
|
a <type>boolean</> result. The detailed API for analysis functions appears
|
|
|
|
in <filename>src/include/commands/vacuum.h</>.
|
|
|
|
</para>
|
|
|
|
|
2002-08-22 02:01:51 +02:00
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
While the details of the new type's internal representation are only
|
|
|
|
known to the I/O functions and other functions you create to work with
|
|
|
|
the type, there are several properties of the internal representation
|
|
|
|
that must be declared to <productname>PostgreSQL</productname>.
|
|
|
|
Foremost of these is
|
|
|
|
<replaceable class="parameter">internallength</replaceable>.
|
2003-04-22 12:08:08 +02:00
|
|
|
Base data types can be fixed-length, in which case
|
1998-07-29 08:23:26 +02:00
|
|
|
<replaceable class="parameter">internallength</replaceable> is a
|
2001-11-03 22:42:47 +01:00
|
|
|
positive integer, or variable length, indicated by setting
|
1998-07-29 08:23:26 +02:00
|
|
|
<replaceable class="parameter">internallength</replaceable>
|
2003-04-22 12:08:08 +02:00
|
|
|
to <literal>VARIABLE</literal>. (Internally, this is represented
|
2002-09-21 20:32:54 +02:00
|
|
|
by setting <literal>typlen</> to -1.) The internal representation of all
|
2003-04-22 12:08:08 +02:00
|
|
|
variable-length types must start with a 4-byte integer giving the total
|
2001-11-03 22:42:47 +01:00
|
|
|
length of this value of the type.
|
|
|
|
</para>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The optional flag <literal>PASSEDBYVALUE</literal> indicates that
|
2003-05-09 00:19:58 +02:00
|
|
|
values of this data type are passed by value, rather than by
|
2003-04-22 12:08:08 +02:00
|
|
|
reference. You may not pass by value types whose internal
|
|
|
|
representation is larger than the size of the <type>Datum</> type
|
|
|
|
(4 bytes on most machines, 8 bytes on a few).
|
2001-11-03 22:42:47 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The <replaceable class="parameter">alignment</replaceable> parameter
|
2002-01-20 23:19:57 +01:00
|
|
|
specifies the storage alignment required for the data type. The
|
2001-11-03 22:42:47 +01:00
|
|
|
allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
|
|
|
|
Note that variable-length types must have an alignment of at least
|
|
|
|
4, since they necessarily contain an <type>int4</> as their first component.
|
1998-07-29 08:23:26 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
2000-08-25 01:36:29 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
The <replaceable class="parameter">storage</replaceable> parameter
|
|
|
|
allows selection of storage strategies for variable-length data
|
|
|
|
types. (Only <literal>plain</literal> is allowed for fixed-length
|
|
|
|
types.) <literal>plain</literal> specifies that data of the type
|
|
|
|
will always be stored in-line and not compressed.
|
|
|
|
<literal>extended</literal> specifies that the system will first
|
|
|
|
try to compress a long data value, and will move the value out of
|
2000-08-25 01:36:29 +02:00
|
|
|
the main table row if it's still too long.
|
2003-04-22 12:08:08 +02:00
|
|
|
<literal>external</literal> allows the value to be moved out of the
|
|
|
|
main table, but the system will not try to compress it.
|
|
|
|
<literal>main</literal> allows compression, but discourages moving
|
|
|
|
the value out of the main table. (Data items with this storage
|
|
|
|
strategy may still be moved out of the main table if there is no
|
|
|
|
other way to make a row fit, but they will be kept in the main
|
|
|
|
table preferentially over <literal>extended</literal> and
|
|
|
|
<literal>external</literal> items.)
|
2000-08-25 01:36:29 +02:00
|
|
|
</para>
|
2002-08-29 02:17:06 +02:00
|
|
|
|
2003-05-09 00:19:58 +02:00
|
|
|
<para>
|
|
|
|
A default value may be specified, in case a user wants columns of the
|
|
|
|
data type to default to something other than the null value.
|
|
|
|
Specify the default with the <literal>DEFAULT</literal> key word.
|
|
|
|
(Such a default may be overridden by an explicit <literal>DEFAULT</literal>
|
|
|
|
clause attached to a particular column.)
|
|
|
|
</para>
|
2000-08-25 01:36:29 +02:00
|
|
|
|
2002-08-15 18:36:08 +02:00
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
To indicate that a type is an array, specify the type of the array
|
|
|
|
elements using the <literal>ELEMENT</> key word. For example, to
|
|
|
|
define an array of 4-byte integers (<type>int4</type>), specify
|
|
|
|
<literal>ELEMENT = int4</literal>. More details about array types
|
|
|
|
appear below.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To indicate the delimiter to be used between values in the external
|
|
|
|
representation of arrays of this type, <replaceable
|
|
|
|
class="parameter">delimiter</replaceable> can be
|
|
|
|
set to a specific character. The default delimiter is the comma
|
|
|
|
(<literal>,</literal>). Note that the delimiter is associated
|
|
|
|
with the array element type, not the array type itself.
|
2002-08-15 18:36:08 +02:00
|
|
|
</para>
|
2003-05-09 00:19:58 +02:00
|
|
|
|
2002-08-29 02:17:06 +02:00
|
|
|
</refsect2>
|
2002-08-15 18:36:08 +02:00
|
|
|
|
1998-07-29 08:23:26 +02:00
|
|
|
<refsect2>
|
|
|
|
<title>Array Types</title>
|
2001-11-03 22:42:47 +01:00
|
|
|
|
1998-07-29 08:23:26 +02:00
|
|
|
<para>
|
2002-08-29 02:17:06 +02:00
|
|
|
Whenever a user-defined base data type is created,
|
2001-11-03 22:42:47 +01:00
|
|
|
<productname>PostgreSQL</productname> automatically creates an
|
|
|
|
associated array type, whose name consists of the base type's
|
|
|
|
name prepended with an underscore. The parser understands this
|
|
|
|
naming convention, and translates requests for columns of type
|
|
|
|
<literal>foo[]</> into requests for type <literal>_foo</>.
|
|
|
|
The implicitly-created array type is variable length and uses the
|
|
|
|
built-in input and output functions <literal>array_in</> and
|
|
|
|
<literal>array_out</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
You might reasonably ask why there is an <option>ELEMENT</>
|
|
|
|
option, if the system makes the correct array type automatically.
|
2001-11-03 22:42:47 +01:00
|
|
|
The only case where it's useful to use <option>ELEMENT</> is when you are
|
2003-04-22 12:08:08 +02:00
|
|
|
making a fixed-length type that happens to be internally an array of a number of
|
|
|
|
identical things, and you want to allow these things to be accessed
|
2001-11-03 22:42:47 +01:00
|
|
|
directly by subscripting, in addition to whatever operations you plan
|
|
|
|
to provide for the type as a whole. For example, type <type>name</>
|
2003-04-22 12:08:08 +02:00
|
|
|
allows its constituent <type>char</> elements to be accessed this way.
|
|
|
|
A 2-D <type>point</> type could allow its two component numbers to be
|
2001-11-03 22:42:47 +01:00
|
|
|
accessed like <literal>point[0]</> and <literal>point[1]</>.
|
|
|
|
Note that
|
|
|
|
this facility only works for fixed-length types whose internal form
|
2003-04-22 12:08:08 +02:00
|
|
|
is exactly a sequence of identical fixed-length fields. A subscriptable
|
2001-11-03 22:42:47 +01:00
|
|
|
variable-length type must have the generalized internal representation
|
|
|
|
used by <literal>array_in</> and <literal>array_out</>.
|
|
|
|
For historical reasons (i.e., this is clearly wrong but it's far too
|
|
|
|
late to change it), subscripting of fixed-length array types starts from
|
|
|
|
zero, rather than from one as for variable-length arrays.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
1998-07-29 08:23:26 +02:00
|
|
|
</refsect2>
|
|
|
|
</refsect1>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
|
|
|
<refsect1>
|
2003-05-09 00:19:58 +02:00
|
|
|
<title>Parameters</title>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2003-09-22 02:16:58 +02:00
|
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name (optionally schema-qualified) of a type to be created.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-05-09 00:19:58 +02:00
|
|
|
<term><replaceable class="parameter">attribute_name</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The name of an attribute (column) for the composite type.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">data_type</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of an existing data type to become a column of the
|
|
|
|
composite type.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">input_function</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of a function that converts data from the type's
|
2003-05-09 00:19:58 +02:00
|
|
|
external textual form to its internal form.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">output_function</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of a function that converts data from the type's
|
2003-05-09 00:19:58 +02:00
|
|
|
internal form to its external textual form.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-05-09 00:19:58 +02:00
|
|
|
<term><replaceable class="parameter">receive_function</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The name of a function that converts data from the type's
|
|
|
|
external binary form to its internal form.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-05-09 00:19:58 +02:00
|
|
|
<term><replaceable class="parameter">send_function</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The name of a function that converts data from the type's
|
|
|
|
internal form to its external binary form.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2004-02-13 00:41:04 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">analyze_function</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of a function that performs statistical analysis for the
|
|
|
|
data type.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<varlistentry>
|
2003-05-09 00:19:58 +02:00
|
|
|
<term><replaceable class="parameter">internallength</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
A numeric constant that specifies the length in bytes of the new
|
|
|
|
type's internal representation. The default assumption is that
|
|
|
|
it is variable-length.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">alignment</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The storage alignment requirement of the data type. If specified,
|
|
|
|
it must be <literal>char</literal>, <literal>int2</literal>,
|
|
|
|
<literal>int4</literal>, or <literal>double</literal>; the
|
|
|
|
default is <literal>int4</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">storage</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The storage strategy for the data type. If specified, must be
|
2003-04-22 12:08:08 +02:00
|
|
|
<literal>plain</literal>, <literal>external</literal>,
|
|
|
|
<literal>extended</literal>, or <literal>main</literal>; the
|
|
|
|
default is <literal>plain</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-05-09 00:19:58 +02:00
|
|
|
<term><replaceable class="parameter">default</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The default value for the data type. If this is omitted, the
|
|
|
|
default is null.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2003-05-09 00:19:58 +02:00
|
|
|
<term><replaceable class="parameter">element</replaceable></term>
|
2003-04-22 12:08:08 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
The type being created is an array; this specifies the type of
|
|
|
|
the array elements.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">delimiter</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The delimiter character to be used between values in arrays made
|
|
|
|
of this type.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
2001-09-13 21:05:29 +02:00
|
|
|
<refsect1 id="SQL-CREATETYPE-notes">
|
|
|
|
<title>Notes</title>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
User-defined type names cannot begin with the underscore character
|
|
|
|
(<literal>_</literal>) and can only be 62 characters
|
|
|
|
long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than
|
|
|
|
the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other
|
|
|
|
names). Type names beginning with underscore are reserved for
|
|
|
|
internally-created array type names.
|
|
|
|
</para>
|
|
|
|
|
2006-01-13 19:06:45 +01:00
|
|
|
<para>
|
|
|
|
Because there are no restrictions on use of a data type once it's been
|
|
|
|
created, creating a base type is tantamount to granting public execute
|
|
|
|
permission on the functions mentioned in the type definition. (The creator
|
|
|
|
of the type is therefore required to own these functions.) This is usually
|
|
|
|
not an issue for the sorts of functions that are useful in a type
|
|
|
|
definition. But you might want to think twice before designing a type
|
|
|
|
in a way that would require <quote>secret</> information to be used
|
|
|
|
while converting it to or from external form.
|
|
|
|
</para>
|
|
|
|
|
2006-02-28 23:37:27 +01:00
|
|
|
<para>
|
|
|
|
Before <productname>PostgreSQL</productname> version 8.2, the syntax
|
|
|
|
<literal>CREATE TYPE <replaceable>name</></literal> did not exist.
|
|
|
|
The way to create a new base type was to create its input function first.
|
|
|
|
In this approach, <productname>PostgreSQL</productname> will first see
|
|
|
|
the name of the new data type as the return type of the input function.
|
|
|
|
The shell type is implicitly created in this situation, and then it
|
|
|
|
can be referenced in the definitions of the remaining I/O functions.
|
|
|
|
This approach still works, but is deprecated and may be disallowed in
|
|
|
|
some future release. Also, to avoid accidentally cluttering
|
|
|
|
the catalogs with shell types as a result of simple typos in function
|
|
|
|
definitions, a shell type will only be made this way when the input
|
|
|
|
function is written in C.
|
|
|
|
</para>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
In <productname>PostgreSQL</productname> versions before 7.3, it
|
2006-02-28 23:37:27 +01:00
|
|
|
was customary to avoid creating a shell type at all, by replacing the
|
2003-04-22 12:08:08 +02:00
|
|
|
functions' forward references to the type name with the placeholder
|
|
|
|
pseudotype <type>opaque</>. The <type>cstring</> arguments and
|
|
|
|
results also had to be declared as <type>opaque</> before 7.3. To
|
|
|
|
support loading of old dump files, <command>CREATE TYPE</> will
|
2006-02-28 23:37:27 +01:00
|
|
|
accept I/O functions declared using <type>opaque</>, but it will issue
|
|
|
|
a notice and change the function declarations to use the correct
|
2003-04-22 12:08:08 +02:00
|
|
|
types.
|
|
|
|
</para>
|
2006-02-28 23:37:27 +01:00
|
|
|
|
2001-09-13 21:05:29 +02:00
|
|
|
</refsect1>
|
|
|
|
|
1998-07-29 08:23:26 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1998-07-29 08:23:26 +02:00
|
|
|
<para>
|
2003-05-09 00:19:58 +02:00
|
|
|
This example creates a composite type and uses it in
|
|
|
|
a function definition:
|
|
|
|
<programlisting>
|
|
|
|
CREATE TYPE compfoo AS (f1 int, f2 text);
|
2005-01-04 01:39:53 +01:00
|
|
|
|
2004-05-17 01:22:08 +02:00
|
|
|
CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$
|
|
|
|
SELECT fooid, fooname FROM foo
|
|
|
|
$$ LANGUAGE SQL;
|
2003-05-09 00:19:58 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This example creates the base data type <type>box</type> and then uses the
|
2001-01-14 00:58:55 +01:00
|
|
|
type in a table definition:
|
2001-09-13 21:05:29 +02:00
|
|
|
<programlisting>
|
2006-02-28 23:37:27 +01:00
|
|
|
CREATE TYPE box;
|
|
|
|
|
|
|
|
CREATE FUNCTION my_box_in_function(cstring) RETURNS box AS ... ;
|
|
|
|
CREATE FUNCTION my_box_out_function(box) RETURNS cstring AS ... ;
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
CREATE TYPE box (
|
|
|
|
INTERNALLENGTH = 16,
|
|
|
|
INPUT = my_box_in_function,
|
|
|
|
OUTPUT = my_box_out_function
|
|
|
|
);
|
|
|
|
|
|
|
|
CREATE TABLE myboxes (
|
|
|
|
id integer,
|
|
|
|
description box
|
|
|
|
);
|
2001-09-13 21:05:29 +02:00
|
|
|
</programlisting>
|
1999-07-22 17:09:15 +02:00
|
|
|
</para>
|
|
|
|
|
1998-07-29 08:23:26 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
If the internal structure of <type>box</type> were an array of four
|
|
|
|
<type>float4</> elements, we might instead use
|
2001-09-13 21:05:29 +02:00
|
|
|
<programlisting>
|
2003-04-22 12:08:08 +02:00
|
|
|
CREATE TYPE box (
|
|
|
|
INTERNALLENGTH = 16,
|
|
|
|
INPUT = my_box_in_function,
|
|
|
|
OUTPUT = my_box_out_function,
|
|
|
|
ELEMENT = float4
|
|
|
|
);
|
2001-09-13 21:05:29 +02:00
|
|
|
</programlisting>
|
2003-04-22 12:08:08 +02:00
|
|
|
which would allow a box value's component numbers to be accessed
|
2001-11-03 22:42:47 +01:00
|
|
|
by subscripting. Otherwise the type behaves the same as before.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
1999-07-22 17:09:15 +02:00
|
|
|
|
1998-07-29 08:23:26 +02:00
|
|
|
<para>
|
2001-11-03 22:42:47 +01:00
|
|
|
This example creates a large object type and uses it in
|
2001-01-14 00:58:55 +01:00
|
|
|
a table definition:
|
2001-09-13 21:05:29 +02:00
|
|
|
<programlisting>
|
2003-04-22 12:08:08 +02:00
|
|
|
CREATE TYPE bigobj (
|
|
|
|
INPUT = lo_filein, OUTPUT = lo_fileout,
|
|
|
|
INTERNALLENGTH = VARIABLE
|
|
|
|
);
|
|
|
|
CREATE TABLE big_objs (
|
|
|
|
id integer,
|
|
|
|
obj bigobj
|
|
|
|
);
|
2002-08-15 18:36:08 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
More examples, including suitable input and output functions, are
|
2005-01-04 01:39:53 +01:00
|
|
|
in <xref linkend="xtypes">.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
2001-09-13 21:05:29 +02:00
|
|
|
</refsect1>
|
1998-07-29 08:23:26 +02:00
|
|
|
|
2001-09-13 21:05:29 +02:00
|
|
|
<refsect1 id="SQL-CREATETYPE-compatibility">
|
|
|
|
<title>Compatibility</title>
|
1998-12-29 03:24:47 +01:00
|
|
|
|
2001-09-13 21:05:29 +02:00
|
|
|
<para>
|
|
|
|
This <command>CREATE TYPE</command> command is a
|
|
|
|
<productname>PostgreSQL</productname> extension. There is a
|
2005-11-01 22:09:51 +01:00
|
|
|
<command>CREATE TYPE</command> statement in the <acronym>SQL</> standard
|
|
|
|
that is rather different in detail.
|
2001-09-13 21:05:29 +02:00
|
|
|
</para>
|
1998-07-29 08:23:26 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2001-09-13 21:05:29 +02:00
|
|
|
<refsect1 id="SQL-CREATETYPE-see-also">
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2002-11-22 00:34:43 +01:00
|
|
|
<member><xref linkend="sql-createfunction" endterm="sql-createfunction-title"></member>
|
|
|
|
<member><xref linkend="sql-droptype" endterm="sql-droptype-title"></member>
|
2004-06-25 23:55:59 +02:00
|
|
|
<member><xref linkend="sql-altertype" endterm="sql-altertype-title"></member>
|
2006-04-06 00:11:58 +02:00
|
|
|
<member><xref linkend="sql-createdomain" endterm="sql-createdomain-title"></member>
|
2001-09-13 21:05:29 +02:00
|
|
|
</simplelist>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refsect1>
|
2001-09-13 21:05:29 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|
1998-07-29 08:23:26 +02:00
|
|
|
|
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
|
|
|
mode: sgml
|
1999-06-14 18:33:46 +02:00
|
|
|
sgml-omittag:nil
|
1998-07-29 08:23:26 +02:00
|
|
|
sgml-shorttag:t
|
|
|
|
sgml-minimize-attributes:nil
|
|
|
|
sgml-always-quote-attributes:t
|
|
|
|
sgml-indent-step:1
|
|
|
|
sgml-indent-data:t
|
|
|
|
sgml-parent-document:nil
|
|
|
|
sgml-default-dtd-file:"../reference.ced"
|
|
|
|
sgml-exposed-tags:nil
|
|
|
|
sgml-local-catalogs:"/usr/lib/sgml/catalog"
|
|
|
|
sgml-local-ecat-files:nil
|
|
|
|
End:
|
1998-08-15 09:00:37 +02:00
|
|
|
-->
|