array.sgml

<!-- $PostgreSQL: pgsql/doc/src/sgml/array.sgml,v 1.68 2008/11/12 13:09:27 petere Exp $ -->

<sect1 id="arrays">
 <title>Arrays</title>

 <indexterm>
  <primary>array</primary>
 </indexterm>

 <para>
  <productname>PostgreSQL</productname> allows columns of a table to be
  defined as variable-length multidimensional arrays. Arrays of any
  built-in or user-defined base type, enum type, or composite type
  can be created.
  Arrays of domains are not yet supported.
 </para>

 <sect2 id="arrays-declaration">
  <title>Declaration of Array Types</title>

  <indexterm>
   <primary>array</primary>
   <secondary>declaration</secondary>
  </indexterm>

 <para>
  To illustrate the use of array types, we create this table:
<programlisting>
CREATE TABLE sal_emp (
    name            text,
    pay_by_quarter  integer[],
    schedule        text[][]
);
</programlisting>
  As shown, an array data type is named by appending square brackets
  (<literal>[]</>) to the data type name of the array elements.  The
  above command will create a table named
  <structname>sal_emp</structname> with a column of type
  <type>text</type> (<structfield>name</structfield>), a
  one-dimensional array of type <type>integer</type>
  (<structfield>pay_by_quarter</structfield>), which represents the
  employee's salary by quarter, and a two-dimensional array of
  <type>text</type> (<structfield>schedule</structfield>), which
  represents the employee's weekly schedule.
 </para>

 <para>
  The syntax for <command>CREATE TABLE</command> allows the exact size of
  arrays to be specified, for example:

<programlisting>
CREATE TABLE tictactoe (
    squares   integer[3][3]
);
</programlisting>

  However, the current implementation does not enforce the array size
  limits &mdash; the behavior is the same as for arrays of unspecified
  length.
 </para>

 <para>
  Actually, the current implementation does not enforce the declared
  number of dimensions either.  Arrays of a particular element type are
  all considered to be of the same type, regardless of size or number
  of dimensions.  So, declaring number of dimensions or sizes in
  <command>CREATE TABLE</command> is simply documentation, it does not
  affect run-time behavior.
 </para>