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

<sect1 id="tablefunc" xreflabel="tablefunc">
 <title>tablefunc &mdash; functions that return tables (<function>crosstab</function> and others)</title>

 <indexterm zone="tablefunc">
  <primary>tablefunc</primary>
 </indexterm>

 <para>
  The <filename>tablefunc</filename> module includes various functions that return
  tables (that is, multiple rows).  These functions are useful both in their
  own right and as examples of how to write C functions that return
  multiple rows.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="tablefunc-functions-sect">
  <title>Functions Provided</title>

  <para>
   <xref linkend="tablefunc-functions"/> summarizes the functions provided
   by the <filename>tablefunc</filename> module.
  </para>

  <table id="tablefunc-functions">
   <title><filename>tablefunc</filename> Functions</title>
    <tgroup cols="1">
     <thead>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        Function
       </para>
       <para>
        Description
       </para></entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>normal_rand</function> ( <parameter>numvals</parameter> <type>integer</type>, <parameter>mean</parameter> <type>float8</type>, <parameter>stddev</parameter> <type>float8</type> )
        <returnvalue>setof float8</returnvalue>
       </para>
       <para>
        Produces a set of normally distributed random values.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>crosstab</function> ( <parameter>sql</parameter> <type>text</type> )
        <returnvalue>setof record</returnvalue>
       </para>
       <para>
        Produces a <quote>pivot table</quote> containing
        row names plus <replaceable>N</replaceable> value columns, where
        <replaceable>N</replaceable> is determined by the row type specified
        in the calling query.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>crosstab<replaceable>N</replaceable></function> ( <parameter>sql</parameter> <type>text</type> )
        <returnvalue>setof table_crosstab_<replaceable>N</replaceable></returnvalue>
       </para>
       <para>
        Produces a <quote>pivot table</quote> containing
        row names plus <replaceable>N</replaceable> value columns.
        <function>crosstab2</function>, <function>crosstab3</function>, and
        <function>crosstab4</function> are predefined, but you can create additional
        <function>crosstab<replaceable>N</replaceable></function> functions as described below.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>crosstab</function> ( <parameter>source_sql</parameter> <type>text</type>, <parameter>category_sql</parameter> <type>text</type> )
        <returnvalue>setof record</returnvalue>
       </para>
       <para>
        Produces a <quote>pivot table</quote>
        with the value columns specified by a second query.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <function>crosstab</function> ( <parameter>sql</parameter> <type>text</type>, <parameter>N</parameter> <type>integer</type> )
        <returnvalue>setof record</returnvalue>
       </para>
       <para>
        Obsolete version of <function>crosstab(text)</function>.
        The parameter <parameter>N</parameter> is now ignored, since the
        number of value columns is always determined by the calling query.
       </para></entry>
      </row>

      <row>
       <entry role="func_table_entry"><para