<!--
doc/src/sgml/ref/create_statistics.sgml
PostgreSQL documentation
-->

<refentry id="sql-createstatistics">
 <indexterm zone="sql-createstatistics">
  <primary>CREATE STATISTICS</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CREATE STATISTICS</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE STATISTICS</refname>
  <refpurpose>define extended statistics</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
CREATE STATISTICS [ [ IF NOT EXISTS ] <replaceable class="parameter">statistics_name</replaceable> ]
    ON ( <replaceable class="parameter">expression</replaceable> )
    FROM <replaceable class="parameter">table_name</replaceable>

CREATE STATISTICS [ [ IF NOT EXISTS ] <replaceable class="parameter">statistics_name</replaceable> ]
    [ ( <replaceable class="parameter">statistics_kind</replaceable> [, ... ] ) ]
    ON { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) }, { <replaceable class="parameter">column_name</replaceable> | ( <replaceable class="parameter">expression</replaceable> ) } [, ...]
    FROM <replaceable class="parameter">table_name</replaceable>
</synopsis>

 </refsynopsisdiv>

 <refsect1 id="sql-createstatistics-description">
  <title>Description</title>

  <para>
   <command>CREATE STATISTICS</command> will create a new extended statistics
   object tracking data about the specified table, foreign table or
   materialized view.  The statistics object will be created in the current
   database and will be owned by the user issuing the command.
  </para>

  <para>
   The <command>CREATE STATISTICS</command> command has two basic forms. The
   first form allows univariate statistics for a single expression to be
   collected, providing benefits similar to an expression index without the
   overhead of index maintenance.  This form does not allow the statistics
   kind to be specified, since the various statistics kinds refer only to
   multivariate statistics.  The second form of the command allows
   multivariate statistics on multiple columns and/or expressions to be
   collected, optionally specifying which statistics kinds to include.  This
   form will also automatically cause univariate statistics to be collected on
   any expressions included in the list.
  </para>

  <para>
   If a schema name is given (for example, <literal>CREATE STATISTICS
   myschema.mystat ...</literal>) then the statistics object is created in the
   specified schema.  Otherwise it is created in the current schema.
   If given, the name of the statistics object must be distinct from the name
   of any other statistics object in the same schema.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

  <variablelist>

   <varlistentry>
    <term><literal>IF NOT EXISTS</literal></term>
    <listitem>
     <para>
      Do not throw an error if a statistics object with the same name already
      exists.  A notice is issued in this case.  Note that only the name of
      the statistics object is considered here, not the details of its
      definition.
      Statistics name is required when <literal>IF NOT EXISTS</literal> is specified.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">statistics_name</replaceable></term>
    <listitem>
     <para>
      The name (optionally schema-qualified) of the statistics object to be
      created.
      If the name is omitted, <productname>PostgreSQL</productname> chooses a
      suitable name based on the parent table's name and the defined column
      name(s) and/or expression(s).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><replaceable class="parameter">statistics_kind</replaceable></term>
    <listitem>
     <para>
      A multivariate statistics kind to be computed in this statistics object.
      Currently supported