granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_view.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_view.sgml,v 1.29 2005/01/04 00:39:53 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEVIEW">
   7  <refmeta>
   8   <refentrytitle id="SQL-CREATEVIEW-TITLE">CREATE VIEW</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE VIEW</refname>
  14   <refpurpose>define a new view</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createview">
  18   <primary>CREATE VIEW</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE [ OR REPLACE ] VIEW <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable
  24 class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">query</replaceable>
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>CREATE VIEW</command> defines a view of a query.  The view
  33    is not physically materialized. Instead, the query is run every time
  34    the view is referenced in a query.
  35   </para>
  36
  37   <para>
  38    <command>CREATE OR REPLACE VIEW</command> is similar, but if a view
  39    of the same name already exists, it is replaced.  You can only replace
  40    a view with a new query that generates the identical set of columns
  41    (i.e., same column names and data types).
  42   </para>
  43
  44   <para>
  45    If a schema name is given (for example, <literal>CREATE VIEW
  46    myschema.myview ...</>) then the view is created in the
  47    specified schema.  Otherwise it is created in the current schema.
  48    The view name must be distinct from the name of any other view, table,
  49    sequence, or index in the same schema.
  50   </para>
  51  </refsect1>
  52
  53  <refsect1>
  54   <title>Parameters</title>
  55
  56   <variablelist>
  57    <varlistentry>
  58     <term><replaceable class="parameter">name</replaceable></term>
  59     <listitem>
  60      <para>
  61       The name (optionally schema-qualified) of a view to be created.
  62      </para>
  63     </listitem>
  64    </varlistentry>
  65
  66    <varlistentry>
  67     <term><replaceable class="parameter">column_name</replaceable></term>
  68     <listitem>
  69      <para>
  70       An optional list of names to be used for columns of the view.
  71       If not given, the column names are deduced from the query.
  72      </para>
  73     </listitem>
  74    </varlistentry>
  75
  76    <varlistentry>
  77     <term><replaceable class="parameter">query</replaceable></term>
  78     <listitem>
  79      <para>
  80       A query (that is, a <command>SELECT</> statement) which will
  81       provide the columns and rows of the view.
  82      </para>
  83
  84      <para>
  85       Refer to <xref linkend="sql-select" endterm="sql-select-title">
  86       for more information about valid queries.
  87      </para>
  88     </listitem>
  89    </varlistentry>
  90   </variablelist>
  91  </refsect1>
  92
  93  <refsect1>
  94   <title>Notes</title>
  95
  96    <para>
  97     Currently, views are read only: the system will not allow an insert,
  98     update, or delete on a view.  You can get the effect of an updatable
  99     view by creating rules that rewrite inserts, etc. on the view into
 100     appropriate actions on other tables.  For more information see
 101     <xref linkend="sql-createrule" endterm="sql-createrule-title">.
 102    </para>
 103
 104    <para>
 105     Use the <command>DROP VIEW</command> statement to drop views.
 106    </para>
 107
 108    <para>
 109     Be careful that the names and types of the view's columns will be
 110     assigned the way you want.  For example,
 111 <programlisting>
 112 CREATE VIEW vista AS SELECT 'Hello World';
 113 </programlisting>
 114     is bad form in two ways: the column name defaults to <literal>?column?</>,
 115     and the column data type defaults to <type>unknown</>.  If you want a
 116     string literal in a view's result, use something like
 117 <programlisting>
 118 CREATE VIEW vista AS SELECT text 'Hello World' AS hello;
 119 </programlisting>
 120    </para>
 121
 122    <para>
 123     Access to tables referenced in the view is determined by permissions of
 124     the view owner.  However, functions called in the view are treated the
 125     same as if they had been called directly from the query using the view.
 126     Therefore the user of a view must have permissions to call all functions
 127     used by the view.
 128    </para>
 129
 130  </refsect1>
 131
 132  <refsect1>
 133   <title>Examples</title>
 134
 135   <para>
 136    Create a view consisting of all comedy films:
 137
 138 <programlisting>
 139 CREATE VIEW comedies AS
 140     SELECT *
 141     FROM films
 142     WHERE kind = 'Comedy';
 143 </programlisting>
 144   </para>
 145  </refsect1>
 146
 147  <refsect1>
 148   <title>Compatibility</title>
 149
 150   <para>
 151    The SQL standard specifies some additional capabilities for the
 152    <command>CREATE VIEW</command> statement:
 153 <synopsis>
 154 CREATE VIEW <replaceable class="parameter">name</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
 155     AS query
 156     [ WITH [ CASCADE | LOCAL ] CHECK OPTION ]
 157 </synopsis>
 158   </para>
 159
 160   <para>
 161    The optional clauses for the full SQL command are:
 162
 163    <variablelist>
 164      <varlistentry>
 165       <term><literal>CHECK OPTION</literal></term>
 166       <listitem>
 167        <para>
 168         This option has to do with updatable views.  All
 169         <command>INSERT</> and <command>UPDATE</> commands on the view
 170         will be checked to ensure data satisfy the view-defining
 171         condition (that is, the new data would be visible through the
 172         view). If they do not, the update will be rejected.
 173        </para>
 174       </listitem>
 175      </varlistentry>
 176
 177      <varlistentry>
 178       <term><literal>LOCAL</literal></term>
 179       <listitem>
 180        <para>
 181         Check for integrity on this view.
 182        </para>
 183       </listitem>
 184      </varlistentry>
 185
 186      <varlistentry>
 187       <term><literal>CASCADE</literal></term>
 188       <listitem>
 189        <para>
 190         Check for integrity on this view and on any dependent
 191         view. <literal>CASCADE</> is assumed if neither
 192         <literal>CASCADE</> nor <literal>LOCAL</> is specified.
 193        </para>
 194       </listitem>
 195      </varlistentry>
 196    </variablelist>
 197   </para>
 198
 199   <para>
 200    <command>CREATE OR REPLACE VIEW</command> is a
 201    <productname>PostgreSQL</productname> language extension.
 202   </para>
 203  </refsect1>
 204
 205  <refsect1>
 206   <title>See Also</title>
 207
 208   <simplelist type="inline">
 209    <member><xref linkend="sql-dropview" endterm="sql-dropview-title"></member>
 210   </simplelist>
 211  </refsect1>
 212 </refentry>
 213
 214 <!-- Keep this comment at the end of the file
 215 Local variables:
 216 mode: sgml
 217 sgml-omittag:nil
 218 sgml-shorttag:t
 219 sgml-minimize-attributes:nil
 220 sgml-always-quote-attributes:t
 221 sgml-indent-step:1
 222 sgml-indent-data:t
 223 sgml-parent-document:nil
 224 sgml-default-dtd-file:"../reference.ced"
 225 sgml-exposed-tags:nil
 226 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 227 sgml-local-ecat-files:nil
 228 End:
 229 -->