<!-- doc/src/sgml/rowtypes.sgml -->

<sect1 id="rowtypes">
 <title>Composite Types</title>

 <indexterm>
  <primary>composite type</primary>
 </indexterm>

 <indexterm>
  <primary>row type</primary>
 </indexterm>

 <para>
  A <firstterm>composite type</firstterm> represents the structure of a row or record;
  it is essentially just a list of field names and their data types.
  <productname>PostgreSQL</productname> allows  composite types to be
  used in many of the same ways that simple types can be used.  For example, a
  column of a table can be declared to be of a composite type.
 </para>

 <sect2 id="rowtypes-declaring">
  <title>Declaration of Composite Types</title>

 <para>
  Here are two simple examples of defining composite types:
<programlisting>
CREATE TYPE complex AS (
    r       double precision,
    i       double precision
);

CREATE TYPE inventory_item AS (
    name            text,
    supplier_id     integer,
    price           numeric
);
</programlisting>
  The syntax is comparable to <command>CREATE TABLE</command>, except that only
  field names and types can be specified; no constraints (such as <literal>NOT
  NULL</literal>) can presently be included.  Note that the <literal>AS</literal> keyword
  is essential; without it, the system will think a different kind
  of <command>CREATE TYPE</command> command is meant, and you will get odd syntax
  errors.
 </para>

 <para>
  Having defined the types, we can use them to create tables:

<programlisting>
CREATE TABLE on_hand (
    item      inventory_item,
    count     integer
);

INSERT INTO on_hand VALUES (ROW('fuzzy dice', 42, 1.99), 1000);
</programlisting>

  or functions:

<programlisting>
CREATE FUNCTION price_extension(inventory_item, integer) RETURNS numeric
AS 'SELECT $1.price * $2' LANGUAGE SQL;

SELECT price_extension(item, 10) FROM on_hand;
</programlisting>

 </para>

 <para>
  Whenever you create a table, a composite type is also automatically
  created, with the same name as the table, to represent the table's
  row type.  For example, had we said:
<programlisting>
CREATE TABLE inventory_item (
    name            text,
    supplier_id     integer REFERENCES suppliers,
    price           numeric CHECK (price &gt; 0)
);
</programlisting>
  then the same <literal>inventory_item</literal> composite type shown above would
  come into being as a
  byproduct, and could be used just as above.  Note however an important
  restriction of the current implementation: since no constraints are
  associated with a composite type, the constraints shown in the table
  definition <emphasis>do not apply</emphasis> to values of the composite type
  outside the table.  (To work around this, create a
  <glossterm linkend="glossary-domain">domain</glossterm> over the composite
  type, and apply the desired constraints as <literal>CHECK</literal>
  constraints of the domain.)
 </para>
 </sect2>

 <sect2 id="rowtypes-constructing">
  <title>Constructing Composite Values</title>

  <indexterm>
   <primary>composite type</primary>
   <secondary>constant</secondary>
  </indexterm>

  <para>
   To write a composite value as a literal constant, enclose the field
   values within parentheses and separate them by commas.  You can put double
   quotes around any field value, and must do so if it contains commas or
   parentheses.  (More details appear <link
   linkend="rowtypes-io-syntax">below</link>.)  Thus, the general format of
   a composite constant is the following:
<synopsis>
'( <replaceable>val1</replaceable> , <replaceable>val2</replaceable> , ... )'
</synopsis>
   An example is:
<programlisting>
'("fuzzy dice",42,1.99)'
</programlisting>
   which would be a valid value of the <literal>inventory_item</literal> type
   defined above.  To make a field be NULL, write no characters at all
   in its position in the list.  For example, this constant specifies
   a NULL third field:
<programlisting>
'("fuzzy dice",42,)'
</programlisting>
   If you want an empty string rather