More editing of reference pages.
This commit is contained in:
parent
8a703496a2
commit
3450fd08a9
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.24 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_aggregate.sgml,v 1.25 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -10,39 +10,129 @@ PostgreSQL documentation
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE AGGREGATE</refname>
|
||||||
CREATE AGGREGATE
|
<refpurpose>define a new aggregate function</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new aggregate function
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
<refsynopsisdiv>
|
|
||||||
<refsynopsisdivinfo>
|
|
||||||
<date>2000-07-16</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
|
|
||||||
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>, STYPE = <replaceable class="PARAMETER">state_type</replaceable>
|
|
||||||
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
|
|
||||||
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ] )
|
|
||||||
</synopsis>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEAGGREGATE-1">
|
<refsynopsisdiv>
|
||||||
<refsect2info>
|
<synopsis>
|
||||||
<date>2000-07-16</date>
|
CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> (
|
||||||
</refsect2info>
|
BASETYPE = <replaceable class="PARAMETER">input_data_type</replaceable>,
|
||||||
<title>
|
SFUNC = <replaceable class="PARAMETER">sfunc</replaceable>,
|
||||||
Inputs
|
STYPE = <replaceable class="PARAMETER">state_data_type</replaceable>
|
||||||
</title>
|
[ , FINALFUNC = <replaceable class="PARAMETER">ffunc</replaceable> ]
|
||||||
|
[ , INITCOND = <replaceable class="PARAMETER">initial_condition</replaceable> ]
|
||||||
|
)
|
||||||
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE AGGREGATE</command> defines a new aggregate function. Some aggregate functions
|
||||||
|
for base types such as <function>min(integer)</function>
|
||||||
|
and <function>avg(double precision)</function> are already provided in the standard
|
||||||
|
distribution. If one defines new types or needs an aggregate function not
|
||||||
|
already provided, then <command>CREATE AGGREGATE</command>
|
||||||
|
can be used to provide the desired features.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If a schema name is given (for example, <literal>CREATE AGGREGATE
|
||||||
|
myschema.myagg ...</>) then the aggregate function is created in the
|
||||||
|
specified schema. Otherwise it is created in the current schema.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
An aggregate function is identified by its name and input data type.
|
||||||
|
Two aggregates in the same schema can have the same name if they operate on
|
||||||
|
different input types. The
|
||||||
|
name and input data type of an aggregate must also be distinct from
|
||||||
|
the name and input data type(s) of every ordinary function in the same
|
||||||
|
schema.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
An aggregate function is made from one or two ordinary
|
||||||
|
functions:
|
||||||
|
a state transition function
|
||||||
|
<replaceable class="PARAMETER">sfunc</replaceable>,
|
||||||
|
and an optional final calculation function
|
||||||
|
<replaceable class="PARAMETER">ffunc</replaceable>.
|
||||||
|
These are used as follows:
|
||||||
|
<programlisting>
|
||||||
|
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
|
||||||
|
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<productname>PostgreSQL</productname> creates a temporary variable
|
||||||
|
of data type <replaceable class="PARAMETER">stype</replaceable>
|
||||||
|
to hold the current internal state of the aggregate. At each input
|
||||||
|
data item,
|
||||||
|
the state transition function is invoked to calculate a new
|
||||||
|
internal state value. After all the data has been processed,
|
||||||
|
the final function is invoked once to calculate the aggregate's return
|
||||||
|
value. If there is no final function then the ending state value
|
||||||
|
is returned as-is.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
An aggregate function may provide an initial condition,
|
||||||
|
that is, an initial value for the internal state value.
|
||||||
|
This is specified and stored in the database as a column of type
|
||||||
|
<type>text</type>, but it must be a valid external representation
|
||||||
|
of a constant of the state value data type. If it is not supplied
|
||||||
|
then the state value starts out null.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If the state transition function is declared <quote>strict</quote>,
|
||||||
|
then it cannot be called with null inputs. With such a transition
|
||||||
|
function, aggregate execution behaves as follows. Null input values
|
||||||
|
are ignored (the function is not called and the previous state value
|
||||||
|
is retained). If the initial state value is null, then the first
|
||||||
|
nonnull input value replaces the state value, and the transition
|
||||||
|
function is invoked beginning with the second nonnull input value.
|
||||||
|
This is handy for implementing aggregates like <function>max</function>.
|
||||||
|
Note that this behavior is only available when
|
||||||
|
<replaceable class="PARAMETER">state_data_type</replaceable>
|
||||||
|
is the same as
|
||||||
|
<replaceable class="PARAMETER">input_data_type</replaceable>.
|
||||||
|
When these types are different, you must supply a nonnull initial
|
||||||
|
condition or use a nonstrict transition function.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If the state transition function is not strict, then it will be called
|
||||||
|
unconditionally at each input value, and must deal with null inputs
|
||||||
|
and null transition values for itself. This allows the aggregate
|
||||||
|
author to have full control over the aggregate's handling of null values.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If the final function is declared <quote>strict</quote>, then it will not
|
||||||
|
be called when the ending state value is null; instead a null result
|
||||||
|
will be returned automatically. (Of course this is just the normal
|
||||||
|
behavior of strict functions.) In any case the final function has
|
||||||
|
the option of returning a null value. For example, the final function for
|
||||||
|
<function>avg</function> returns null when it sees there were zero
|
||||||
|
input rows.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="PARAMETER">name</replaceable></term>
|
<term><replaceable class="PARAMETER">name</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name (optionally schema-qualified) of an aggregate function to
|
The name (optionally schema-qualified) of the aggregate function
|
||||||
create.
|
to create.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -52,9 +142,9 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE =
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The input data type on which this aggregate function operates.
|
The input data type on which this aggregate function operates.
|
||||||
This can be specified as <literal>"ANY"</> for an aggregate that does
|
This can be specified as <literal>"ANY"</> for an aggregate that
|
||||||
not examine its input values
|
does not examine its input values (an example is
|
||||||
(an example is <function>count(*)</function>).
|
<function>count(*)</function>).
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -63,25 +153,25 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE =
|
||||||
<term><replaceable class="PARAMETER">sfunc</replaceable></term>
|
<term><replaceable class="PARAMETER">sfunc</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name of the state transition function
|
The name of the state transition function to be called for each
|
||||||
to be called for each input data value.
|
input data value. This is normally a function of two arguments,
|
||||||
This is normally a function of two arguments, the first being of
|
the first being of type <replaceable
|
||||||
type <replaceable class="PARAMETER">state_type</replaceable>
|
class="PARAMETER">state_data_type</replaceable> and the second
|
||||||
and the second of
|
of type <replaceable
|
||||||
type <replaceable class="PARAMETER">input_data_type</replaceable>.
|
class="PARAMETER">input_data_type</replaceable>. Alternatively,
|
||||||
Alternatively, for an aggregate that does not examine its input
|
for an aggregate that does not examine its input values, the
|
||||||
values, the function takes just one argument of
|
function takes just one argument of type <replaceable
|
||||||
type <replaceable class="PARAMETER">state_type</replaceable>.
|
class="PARAMETER">state_data_type</replaceable>. In either case
|
||||||
In either case the function must return a value of
|
the function must return a value of type <replaceable
|
||||||
type <replaceable class="PARAMETER">state_type</replaceable>.
|
class="PARAMETER">state_data_type</replaceable>. This function
|
||||||
This function takes the current state value and the current
|
takes the current state value and the current input data item,
|
||||||
input data item, and returns the next state value.
|
and returns the next state value.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="PARAMETER">state_type</replaceable></term>
|
<term><replaceable class="PARAMETER">state_data_type</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The data type for the aggregate's state value.
|
The data type for the aggregate's state value.
|
||||||
|
@ -95,14 +185,13 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE =
|
||||||
<para>
|
<para>
|
||||||
The name of the final function called to compute the aggregate's
|
The name of the final function called to compute the aggregate's
|
||||||
result after all input data has been traversed. The function
|
result after all input data has been traversed. The function
|
||||||
must take a single argument of type
|
must take a single argument of type <replaceable
|
||||||
<replaceable class="PARAMETER">state_type</replaceable>.
|
class="PARAMETER">state_data_type</replaceable>. The return
|
||||||
The output data type of the aggregate is defined as the return
|
data type of the aggregate is defined as the return type of this
|
||||||
type of this function.
|
function. If <replaceable class="PARAMETER">ffunc</replaceable>
|
||||||
If <replaceable class="PARAMETER">ffunc</replaceable>
|
|
||||||
is not specified, then the ending state value is used as the
|
is not specified, then the ending state value is used as the
|
||||||
aggregate's result, and the output type is
|
aggregate's result, and the return type is <replaceable
|
||||||
<replaceable class="PARAMETER">state_type</replaceable>.
|
class="PARAMETER">state_data_type</replaceable>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -111,31 +200,27 @@ CREATE AGGREGATE <replaceable class="PARAMETER">name</replaceable> ( BASETYPE =
|
||||||
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
|
<term><replaceable class="PARAMETER">initial_condition</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The initial setting for the state value. This must be a literal
|
The initial setting for the state value. This must be a string
|
||||||
constant in the form accepted for the data type
|
constant in the form accepted for the data type <replaceable
|
||||||
<replaceable class="PARAMETER">state_type</replaceable>.
|
class="PARAMETER">state_data_type</replaceable>. If not
|
||||||
If not specified, the state value starts out NULL.
|
specified, the state value starts out null.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEAGGREGATE-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-09</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
The parameters of <command>CREATE AGGREGATE</command> can be
|
||||||
|
written in any order, not just the order illustrated above.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>CREATE AGGREGATE</computeroutput></term>
|
||||||
CREATE AGGREGATE
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if the command completes successfully.
|
Message returned if the command completes successfully.
|
||||||
|
@ -143,130 +228,17 @@ CREATE AGGREGATE
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEAGGREGATE-1">
|
|
||||||
<refsect1info>
|
|
||||||
<date>2000-07-16</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE AGGREGATE</command>
|
|
||||||
allows a user or programmer to extend <productname>PostgreSQL</productname>
|
|
||||||
functionality by defining new aggregate functions. Some aggregate functions
|
|
||||||
for base types such as <function>min(integer)</function>
|
|
||||||
and <function>avg(double precision)</function> are already provided in the base
|
|
||||||
distribution. If one defines new types or needs an aggregate function not
|
|
||||||
already provided, then <command>CREATE AGGREGATE</command>
|
|
||||||
can be used to provide the desired features.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If a schema name is given (for example, <literal>CREATE AGGREGATE
|
|
||||||
myschema.myagg ...</>) then the aggregate function is created in the
|
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
An aggregate function is identified by its name and input data type.
|
|
||||||
Two aggregates in the same schema can have the same name if they operate on
|
|
||||||
different input types. The
|
|
||||||
name and input data type of an aggregate must also be distinct from
|
|
||||||
the name and input data type(s) of every ordinary function in the same
|
|
||||||
schema.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
An aggregate function is made from one or two ordinary
|
|
||||||
functions:
|
|
||||||
a state transition function
|
|
||||||
<replaceable class="PARAMETER">sfunc</replaceable>,
|
|
||||||
and an optional final calculation function
|
|
||||||
<replaceable class="PARAMETER">ffunc</replaceable>.
|
|
||||||
These are used as follows:
|
|
||||||
<programlisting>
|
|
||||||
<replaceable class="PARAMETER">sfunc</replaceable>( internal-state, next-data-item ) ---> next-internal-state
|
|
||||||
<replaceable class="PARAMETER">ffunc</replaceable>( internal-state ) ---> aggregate-value
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
<productname>PostgreSQL</productname> creates a temporary variable
|
|
||||||
of data type <replaceable class="PARAMETER">stype</replaceable>
|
|
||||||
to hold the current internal state of the aggregate. At each input
|
|
||||||
data item,
|
|
||||||
the state transition function is invoked to calculate a new
|
|
||||||
internal state value. After all the data has been processed,
|
|
||||||
the final function is invoked once to calculate the aggregate's output
|
|
||||||
value. If there is no final function then the ending state value
|
|
||||||
is returned as-is.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
An aggregate function may provide an initial condition,
|
|
||||||
that is, an initial value for the internal state value.
|
|
||||||
This is specified and stored in the database as a field of type
|
|
||||||
<type>text</type>, but it must be a valid external representation
|
|
||||||
of a constant of the state value data type. If it is not supplied
|
|
||||||
then the state value starts out NULL.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If the state transition function is declared <quote>strict</quote>,
|
|
||||||
then it cannot be called with NULL inputs. With such a transition
|
|
||||||
function, aggregate execution behaves as follows. NULL input values
|
|
||||||
are ignored (the function is not called and the previous state value
|
|
||||||
is retained). If the initial state value is NULL, then the first
|
|
||||||
non-NULL input value replaces the state value, and the transition
|
|
||||||
function is invoked beginning with the second non-NULL input value.
|
|
||||||
This is handy for implementing aggregates like <function>max</function>.
|
|
||||||
Note that this behavior is only available when
|
|
||||||
<replaceable class="PARAMETER">state_type</replaceable>
|
|
||||||
is the same as
|
|
||||||
<replaceable class="PARAMETER">input_data_type</replaceable>.
|
|
||||||
When these types are different, you must supply a non-NULL initial
|
|
||||||
condition or use a non-strict transition function.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If the state transition function is not strict, then it will be called
|
|
||||||
unconditionally at each input value, and must deal with NULL inputs
|
|
||||||
and NULL transition values for itself. This allows the aggregate
|
|
||||||
author to have full control over the aggregate's handling of null values.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If the final function is declared <quote>strict</quote>, then it will not
|
|
||||||
be called when the ending state value is NULL; instead a NULL result
|
|
||||||
will be output automatically. (Of course this is just the normal
|
|
||||||
behavior of strict functions.) In any case the final function has
|
|
||||||
the option of returning NULL. For example, the final function for
|
|
||||||
<function>avg</function> returns NULL when it sees there were zero
|
|
||||||
input tuples.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEAGGREGATE-3">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-07-16</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
Use <command>DROP AGGREGATE</command>
|
|
||||||
to drop aggregate functions.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The parameters of <command>CREATE AGGREGATE</command> can be written
|
|
||||||
in any order, not just the order illustrated above.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEAGGREGATE-2">
|
<refsect1>
|
||||||
|
<title>Notes</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Use <command>DROP AGGREGATE</command> to drop aggregate functions.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -274,24 +246,14 @@ CREATE AGGREGATE
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEAGGREGATE-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEAGGREGATE-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-09</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE AGGREGATE</command>
|
<command>CREATE AGGREGATE</command> is a
|
||||||
is a <productname>PostgreSQL</productname> language extension.
|
<productname>PostgreSQL</productname> language extension. The SQL
|
||||||
There is no <command>CREATE AGGREGATE</command> in SQL92.
|
standard does not provide for user-defined aggregate function.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.10 2003/03/25 16:15:39 petere Exp $ -->
|
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.11 2003/04/22 10:08:08 petere Exp $ -->
|
||||||
|
|
||||||
<refentry id="SQL-CREATECAST">
|
<refentry id="SQL-CREATECAST">
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
@ -58,11 +58,11 @@ SELECT CAST(42 AS text);
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked
|
If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked
|
||||||
implicitly when assigning to a column of the target data type.
|
implicitly when assigning a value to a column of the target data type.
|
||||||
For example, supposing that <literal>foo.f1</literal> is a column of
|
For example, supposing that <literal>foo.f1</literal> is a column of
|
||||||
type <type>text</type>, then
|
type <type>text</type>, then
|
||||||
<programlisting>
|
<programlisting>
|
||||||
INSERT INTO foo(f1) VALUES(42);
|
INSERT INTO foo (f1) VALUES (42);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
will be allowed if the cast from type <type>integer</type> to type
|
will be allowed if the cast from type <type>integer</type> to type
|
||||||
<type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise
|
<type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise
|
||||||
|
@ -75,7 +75,7 @@ INSERT INTO foo(f1) VALUES(42);
|
||||||
If the cast is marked <literal>AS IMPLICIT</> then it can be invoked
|
If the cast is marked <literal>AS IMPLICIT</> then it can be invoked
|
||||||
implicitly in any context, whether assignment or internally in an
|
implicitly in any context, whether assignment or internally in an
|
||||||
expression. For example, since <literal>||</> takes <type>text</>
|
expression. For example, since <literal>||</> takes <type>text</>
|
||||||
arguments,
|
operands,
|
||||||
<programlisting>
|
<programlisting>
|
||||||
SELECT 'The time is ' || now();
|
SELECT 'The time is ' || now();
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
@ -106,14 +106,16 @@ SELECT 'The time is ' || CAST(now() AS text);
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To be able to create a cast, you must own the source or the target
|
To be able to create a cast, you must own the source or the target
|
||||||
data type. To create a binary-compatible cast, you must be superuser
|
data type. To create a binary-compatible cast, you must be superuser.
|
||||||
(this restriction is made because an erroneous binary-compatible cast
|
(This restriction is made because an erroneous binary-compatible cast
|
||||||
conversion can easily crash the server).
|
conversion can easily crash the server.)
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<variablelist>
|
<refsect1>
|
||||||
<title>Parameters</title>
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable>sourcetype</replaceable></term>
|
<term><replaceable>sourcetype</replaceable></term>
|
||||||
|
|
||||||
|
@ -183,6 +185,21 @@ SELECT 'The time is ' || CAST(now() AS text);
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE CAST</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the cast was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="sql-createcast-notes">
|
<refsect1 id="sql-createcast-notes">
|
||||||
<title>Notes</title>
|
<title>Notes</title>
|
||||||
|
|
||||||
|
@ -201,8 +218,8 @@ SELECT 'The time is ' || CAST(now() AS text);
|
||||||
argument of a different type was automatically a cast function.
|
argument of a different type was automatically a cast function.
|
||||||
This convention has been abandoned in face of the introduction of
|
This convention has been abandoned in face of the introduction of
|
||||||
schemas and to be able to represent binary compatible casts in the
|
schemas and to be able to represent binary compatible casts in the
|
||||||
catalogs. (The built-in cast functions still follow this naming
|
system catalogs. (The built-in cast functions still follow this naming
|
||||||
scheme, but they have to be shown as casts in <literal>pg_cast</>
|
scheme, but they have to be shown as casts in the system catalog <literal>pg_cast</>
|
||||||
now.)
|
now.)
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
@ -227,7 +244,7 @@ CREATE CAST (text AS int4) WITH FUNCTION int4(text);
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <command>CREATE CAST</command> command conforms to SQL99,
|
The <command>CREATE CAST</command> command conforms to SQL99,
|
||||||
except that SQL99 does not make provisions for binary compatible
|
except that SQL99 does not make provisions for binary-compatible
|
||||||
types. <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>
|
types. <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>
|
||||||
extension, too.
|
extension, too.
|
||||||
</para>
|
</para>
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_constraint.sgml,v 1.8 2002/05/18 15:44:47 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_constraint.sgml,v 1.9 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,30 +8,35 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createconstraint-title">CREATE CONSTRAINT TRIGGER</refentrytitle>
|
<refentrytitle id="sql-createconstraint-title">CREATE CONSTRAINT TRIGGER</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE CONSTRAINT TRIGGER</refname>
|
||||||
CREATE CONSTRAINT TRIGGER
|
<refpurpose>define a new constraint trigger</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new constraint trigger
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2000-04-13</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
|
CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
|
||||||
AFTER <replaceable class="parameter">events</replaceable> ON
|
AFTER <replaceable class="parameter">events</replaceable> ON
|
||||||
<replaceable class="parameter">relation</replaceable> <replaceable class="parameter">constraint</replaceable> <replaceable class="parameter">attributes</replaceable>
|
<replaceable class="parameter">table</replaceable> <replaceable class="parameter">constraint</replaceable> <replaceable class="parameter">attributes</replaceable>
|
||||||
FOR EACH ROW EXECUTE PROCEDURE <replaceable class="parameter">func</replaceable> '(' <replaceable class="parameter">args</replaceable> ')'
|
FOR EACH ROW EXECUTE PROCEDURE <replaceable class="parameter">func</replaceable> ( <replaceable class="parameter">args</replaceable> )
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATECONSTRAINT-1">
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE CONSTRAINT TRIGGER</command> is used within
|
||||||
|
<command>CREATE TABLE</command>/<command>ALTER TABLE</command> and by
|
||||||
|
<application>pg_dump</application> to create the special triggers for
|
||||||
|
referential integrity.
|
||||||
|
It is not intended for general use.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -53,10 +58,10 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="PARAMETER">relation</replaceable></term>
|
<term><replaceable class="PARAMETER">table</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name (possibly schema-qualified) of the relation in which
|
The name (possibly schema-qualified) of the table in which
|
||||||
the triggering events occur.
|
the triggering events occur.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
@ -75,7 +80,7 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
|
||||||
<term><replaceable class="PARAMETER">attributes</replaceable></term>
|
<term><replaceable class="PARAMETER">attributes</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Constraint attributes.
|
The constraint attributes.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -84,25 +89,19 @@ CREATE CONSTRAINT TRIGGER <replaceable class="parameter">name</replaceable>
|
||||||
<term><replaceable class="PARAMETER">func</replaceable>(<replaceable class="PARAMETER">args</replaceable>)</term>
|
<term><replaceable class="PARAMETER">func</replaceable>(<replaceable class="PARAMETER">args</replaceable>)</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Function to call as part of the trigger processing.
|
The function to call as part of the trigger processing.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATECONSTRAINT-2">
|
<refsect1>
|
||||||
<title>
|
<title>Diagnostics</title>
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>CREATE TRIGGER</computeroutput></term>
|
||||||
CREATE TRIGGER
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if successful.
|
Message returned if successful.
|
||||||
|
@ -110,24 +109,6 @@ CREATE TRIGGER
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATECONSTRAINT-1">
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE CONSTRAINT TRIGGER</command> is used within
|
|
||||||
<command>CREATE/ALTER TABLE</command> and by
|
|
||||||
<application>pg_dump</application> to create the special triggers for
|
|
||||||
referential integrity.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
It is not intended for general use.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.7 2003/03/25 16:15:39 petere Exp $ -->
|
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_conversion.sgml,v 1.8 2003/04/22 10:08:08 petere Exp $ -->
|
||||||
|
|
||||||
<refentry id="SQL-CREATECONVERSION">
|
<refentry id="SQL-CREATECONVERSION">
|
||||||
<refmeta>
|
<refmeta>
|
||||||
|
@ -23,21 +23,24 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE CONVERSION</command> defines a new encoding
|
<command>CREATE CONVERSION</command> defines a new encoding
|
||||||
conversion. Conversion names may be used in the CONVERT() function
|
conversion. Conversion names may be used in the <function>convert</function> function
|
||||||
to specify a particular encoding conversion. Also, conversions that
|
to specify a particular encoding conversion. Also, conversions that
|
||||||
are marked DEFAULT can be used for automatic encoding conversion between
|
are marked <literal>DEFAULT</> can be used for automatic encoding conversion between
|
||||||
frontend and backend. For this purpose, two conversions, from encoding A to
|
client and server. For this purpose, two conversions, from encoding A to
|
||||||
B AND from encoding B to A, must be defined.
|
B <emphasis>and</emphasis> from encoding B to A, must be defined.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To be able to create a conversion, you must have the execute right
|
To be able to create a conversion, you must have <literal>EXECUTE</literal> privilege
|
||||||
on the function and the create right on the destination schema.
|
on the function and <literal>CREATE</literal> privilege on the destination schema.
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
|
<refsect1>
|
||||||
<title>Parameters</title>
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><literal>DEFAULT</literal></term>
|
<term><literal>DEFAULT</literal></term>
|
||||||
|
|
||||||
|
@ -75,7 +78,7 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable>source_encoding</replaceable></term>
|
<term><replaceable>dest_encoding</replaceable></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
|
@ -97,20 +100,34 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
|
||||||
<para>
|
<para>
|
||||||
The function must have the following signature:
|
The function must have the following signature:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
conv_proc(
|
conv_proc(
|
||||||
INTEGER, -- source encoding id
|
integer, -- source encoding ID
|
||||||
INTEGER, -- destination encoding id
|
integer, -- destination encoding ID
|
||||||
CSTRING, -- source string (null terminated C string)
|
cstring, -- source string (null terminated C string)
|
||||||
CSTRING, -- destination string (null terminated C string)
|
cstring, -- destination string (null terminated C string)
|
||||||
INTEGER -- source string length
|
integer -- source string length
|
||||||
) returns VOID;
|
) RETURNS void;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE CONVERSION</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the conversion was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="sql-createconversion-notes">
|
<refsect1 id="sql-createconversion-notes">
|
||||||
|
@ -124,15 +141,14 @@ CREATE [DEFAULT] CONVERSION <replaceable>conversion_name</replaceable>
|
||||||
The privileges required to create a conversion may be changed in a future
|
The privileges required to create a conversion may be changed in a future
|
||||||
release.
|
release.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
||||||
<refsect1 id="sql-createconversion-examples">
|
<refsect1 id="sql-createconversion-examples">
|
||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To create a conversion from encoding UNICODE to LATIN1 using <function>myfunc</>:
|
To create a conversion from encoding <literal>UNICODE</literal> to
|
||||||
|
<literal>LATIN1</literal> using <function>myfunc</>:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
|
CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
@ -147,7 +163,7 @@ CREATE CONVERSION myconv FOR 'UNICODE' TO 'LATIN1' FROM myfunc;
|
||||||
<command>CREATE CONVERSION</command>
|
<command>CREATE CONVERSION</command>
|
||||||
is a <productname>PostgreSQL</productname> extension.
|
is a <productname>PostgreSQL</productname> extension.
|
||||||
There is no <command>CREATE CONVERSION</command>
|
There is no <command>CREATE CONVERSION</command>
|
||||||
statement in <acronym>SQL99</acronym>.
|
statement in the SQL standard.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.33 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.34 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,34 +8,81 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
|
<refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE DATABASE</refname>
|
||||||
CREATE DATABASE
|
<refpurpose>create a new database</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
create a new database
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>1999-12-11</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
||||||
[ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
|
[ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
|
||||||
[ LOCATION [=] '<replaceable class="parameter">dbpath</replaceable>' ]
|
[ LOCATION [=] '<replaceable class="parameter">dbpath</replaceable>' ]
|
||||||
[ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
|
[ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
|
||||||
[ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ] ]
|
[ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ] ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEDATABASE-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1999-12-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE DATABASE</command> creates a new
|
||||||
|
<productname>PostgreSQL</productname> database.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Normally, the creator becomes the owner of the new database.
|
||||||
|
Superusers can create databases owned by other users using the
|
||||||
|
<literal>OWNER</> clause. They can even create databases owned by
|
||||||
|
users with no special privileges. Non-superusers with <literal>CREATEDB</>
|
||||||
|
privilege can only create databases owned by themselves.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
An alternative location can be specified in order to,
|
||||||
|
for example, store the database on a different disk.
|
||||||
|
The path must have been prepared with the
|
||||||
|
<xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
|
||||||
|
command.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If the path name does not contain a slash, it is interpreted
|
||||||
|
as an environment variable name, which must be known to the
|
||||||
|
server process. This way the database administrator can
|
||||||
|
exercise control over locations in which databases can be created.
|
||||||
|
(A customary choice is, e.g., <envar>PGDATA2</envar>.)
|
||||||
|
If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
|
||||||
|
(not so by default), absolute path names, as identified by
|
||||||
|
a leading slash
|
||||||
|
(e.g., <filename>/usr/local/pgsql/data</filename>),
|
||||||
|
are allowed as well.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
By default, the new database will be created by cloning the standard
|
||||||
|
system database <literal>template1</>. A different template can be
|
||||||
|
specified by writing <literal>TEMPLATE
|
||||||
|
<replaceable class="parameter">name</replaceable></literal>. In particular,
|
||||||
|
by writing <literal>TEMPLATE template0</>, you can create a virgin
|
||||||
|
database containing only the standard objects predefined by your
|
||||||
|
version of <productname>PostgreSQL</productname>. This is useful
|
||||||
|
if you wish to avoid copying
|
||||||
|
any installation-local objects that may have been added to
|
||||||
|
<literal>template1</>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The optional encoding parameter allows selection of the database
|
||||||
|
encoding. When not specified, it defaults to the encoding used by
|
||||||
|
the selected template database.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameter</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -50,7 +97,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
||||||
<term><replaceable class="parameter">dbowner</replaceable></term>
|
<term><replaceable class="parameter">dbowner</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Name of the database user who will own the new database,
|
The name of the database user who will own the new database,
|
||||||
or <literal>DEFAULT</literal> to use the default (namely, the
|
or <literal>DEFAULT</literal> to use the default (namely, the
|
||||||
user executing the command).
|
user executing the command).
|
||||||
</para>
|
</para>
|
||||||
|
@ -70,7 +117,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
||||||
<term><replaceable class="parameter">template</replaceable></term>
|
<term><replaceable class="parameter">template</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Name of template from which to create the new database,
|
The name of the template from which to create the new database,
|
||||||
or <literal>DEFAULT</literal> to use the default template
|
or <literal>DEFAULT</literal> to use the default template
|
||||||
(<literal>template1</literal>).
|
(<literal>template1</literal>).
|
||||||
</para>
|
</para>
|
||||||
|
@ -80,32 +127,30 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
||||||
<term><replaceable class="parameter">encoding</replaceable></term>
|
<term><replaceable class="parameter">encoding</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Multibyte encoding method to use in the new database. Specify
|
Character set encoding to use in the new database. Specify
|
||||||
a string literal name (e.g., <literal>'SQL_ASCII'</literal>),
|
a string constant (e.g., <literal>'SQL_ASCII'</literal>),
|
||||||
or an integer encoding number, or <literal>DEFAULT</literal>
|
or an integer encoding number, or <literal>DEFAULT</literal>
|
||||||
to use the default encoding.
|
to use the default encoding.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEDATABASE-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1999-12-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
Optional parameters can be written in any order, not only the order
|
||||||
|
illustrated above.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>CREATE DATABASE</computeroutput></term>
|
<term><computeroutput>CREATE DATABASE</computeroutput></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if the command completes successfully.
|
Message returned if the database was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -125,8 +170,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
||||||
<term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
|
<term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This occurs if a database with the <replaceable class="parameter">name</replaceable>
|
This occurs if a database with the specified name already
|
||||||
specified already exists.
|
exists.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -166,186 +211,73 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEDATABASE-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Notes</title>
|
||||||
<date>1999-12-11</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE DATABASE</command> creates a new
|
|
||||||
<productname>PostgreSQL</productname> database.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Normally, the creator becomes the owner of the new database.
|
|
||||||
Superusers can create databases owned by other users using the
|
|
||||||
<option>OWNER</> clause. They can even create databases owned by
|
|
||||||
users with no special privileges. Non-superusers with <literal>CREATEDB</>
|
|
||||||
privilege can only create databases owned by themselves.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
An alternate location can be specified in order to,
|
|
||||||
for example, store the database on a different disk.
|
|
||||||
The path must have been prepared with the
|
|
||||||
<xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
|
|
||||||
command.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If the path name does not contain a slash, it is interpreted
|
|
||||||
as an environment variable name, which must be known to the
|
|
||||||
server process. This way the database administrator can
|
|
||||||
exercise control over locations in which databases can be created.
|
|
||||||
(A customary choice is, e.g., <envar>PGDATA2</envar>.)
|
|
||||||
If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
|
|
||||||
(not so by default), absolute path names, as identified by
|
|
||||||
a leading slash
|
|
||||||
(e.g., <filename>/usr/local/pgsql/data</filename>),
|
|
||||||
are allowed as well.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, the new database will be created by cloning the standard
|
|
||||||
system database <literal>template1</>. A different template can be
|
|
||||||
specified by writing <literal>TEMPLATE =</>
|
|
||||||
<replaceable class="parameter">name</replaceable>. In particular,
|
|
||||||
by writing <literal>TEMPLATE = template0</>, you can create a virgin
|
|
||||||
database containing only the standard objects predefined by your
|
|
||||||
version of <productname>PostgreSQL</productname>. This is useful
|
|
||||||
if you wish to avoid copying
|
|
||||||
any installation-local objects that may have been added to
|
|
||||||
<literal>template1</>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The optional encoding parameter allows selection of the database
|
|
||||||
encoding. When not specified, it defaults to the encoding used by
|
|
||||||
the selected template database.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Optional parameters can be written in any order, not only the order
|
|
||||||
illustrated above.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEDATABASE-3">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1999-12-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE DATABASE</command> is a <productname>PostgreSQL</productname>
|
|
||||||
language extension.
|
|
||||||
</para>
|
|
||||||
<para>
|
<para>
|
||||||
Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
|
Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
|
The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
|
||||||
shell script wrapper around this command, provided for convenience.
|
wrapper program around this command, provided for convenience.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There are security and data integrity issues
|
There are security issues involved with using alternate database
|
||||||
involved with using alternate database locations
|
locations specified with absolute path names. See <xref
|
||||||
specified with absolute path names, and by default
|
linkend="manage-ag-alternate-locs"> for more information.
|
||||||
only an environment variable known to the backend may be
|
|
||||||
specified for an alternate location.
|
|
||||||
See <xref linkend="manage-ag-alternate-locs"> for more information.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<!--
|
|
||||||
comment from Olly; response from Thomas...
|
|
||||||
<comment>
|
|
||||||
initlocation does not create a PG_VERSION file in the specified location.
|
|
||||||
How will PostgreSQL handle the situation if it is upgraded to an
|
|
||||||
incompatible database version?
|
|
||||||
</comment>
|
|
||||||
Hmm. This isn't an issue since the upgrade would do
|
|
||||||
a dump/reload from the main database area also.
|
|
||||||
Not sure if the dump/reload would guarantee that
|
|
||||||
the alternate data area gets refreshed though...
|
|
||||||
-->
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Although it is possible to copy a database other than <literal>template1</>
|
Although it is possible to copy a database other than <literal>template1</>
|
||||||
by specifying its name as the template, this is not (yet) intended as
|
by specifying its name as the template, this is not (yet) intended as
|
||||||
a general-purpose COPY DATABASE facility.
|
a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
|
||||||
We recommend that databases used as templates be treated as read-only.
|
We recommend that databases used as templates be treated as read-only.
|
||||||
See <xref linkend="user-manag"> for more information.
|
See <xref linkend="manage-ag-templatedbs"> for more information.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEDATABASE-2">
|
<refsect1>
|
||||||
<title>
|
<title>Examples</title>
|
||||||
Usage
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
To create a new database:
|
To create a new database:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
|
CREATE DATABASE lusiadas;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To create a new database in an alternate area <filename>~/private_db</filename>:
|
To create a new database in an alternate area
|
||||||
|
<filename>~/private_db</filename>, execute the following from the
|
||||||
|
shell:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
|
mkdir private_db
|
||||||
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
|
initlocation ~/private_db
|
||||||
<computeroutput>
|
</programlisting>
|
||||||
The location will be initialized with username "olly".
|
|
||||||
This user will own all the files and must also own the server process.
|
|
||||||
Creating directory /home/olly/private_db
|
|
||||||
Creating directory /home/olly/private_db/base
|
|
||||||
|
|
||||||
initlocation is complete.
|
Then execute the following from within a
|
||||||
</computeroutput>
|
<application>psql</application> session:
|
||||||
|
|
||||||
<prompt>$</prompt> <userinput>psql olly</userinput>
|
<programlisting>
|
||||||
<computeroutput>
|
CREATE DATABASE elsewhere WITH LOCATION '/home/olly/private_db';
|
||||||
Welcome to psql, the PostgreSQL interactive terminal.
|
</programlisting>
|
||||||
|
|
||||||
Type: \copyright for distribution terms
|
|
||||||
\h for help with SQL commands
|
|
||||||
\? for help on internal slash commands
|
|
||||||
\g or terminate with semicolon to execute query
|
|
||||||
\q to quit
|
|
||||||
|
|
||||||
<prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput>
|
|
||||||
<computeroutput>CREATE DATABASE</computeroutput>
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEDATABASE-4">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEDATABASE-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-04-15</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
There is no <command>CREATE DATABASE</command> statement in SQL92.
|
There is no <command>CREATE DATABASE</command> statement in the SQL
|
||||||
Databases are equivalent to catalogs, whose creation is
|
standard. Databases are equivalent to catalogs, whose creation is
|
||||||
implementation-defined.
|
implementation-defined.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,28 +1,21 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.12 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.13 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<refentry id="SQL-CREATEDOMAIN">
|
<refentry id="SQL-CREATEDOMAIN">
|
||||||
<refmeta>
|
<refmeta>
|
||||||
<refentrytitle id="sql-createdomain-title">
|
<refentrytitle id="sql-createdomain-title">CREATE DOMAIN</refentrytitle>
|
||||||
CREATE DOMAIN
|
|
||||||
</refentrytitle>
|
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE DOMAIN</refname>
|
||||||
CREATE DOMAIN
|
<refpurpose>define a new domain</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new domain
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2002-02-24</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> [AS] <replaceable class="parameter">data_type</replaceable>
|
CREATE DOMAIN <replaceable class="parameter">domainname</replaceable> [AS] <replaceable class="parameter">data_type</replaceable>
|
||||||
[ DEFAULT <replaceable>default_expr</> ]
|
[ DEFAULT <replaceable>default_expr</> ]
|
||||||
[ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ]
|
[ <replaceable class="PARAMETER">constraint</replaceable> [ ... ] ]
|
||||||
|
@ -31,16 +24,35 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
|
||||||
|
|
||||||
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
|
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
|
||||||
{ NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) }
|
{ NOT NULL | NULL | CHECK (<replaceable class="PARAMETER">expression</replaceable>) }
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEDOMAIN-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2002-02-24</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Parameters
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE DOMAIN</command> creates a new data domain. The
|
||||||
|
user who defines a domain becomes its owner.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If a schema name is given (for example, <literal>CREATE DOMAIN
|
||||||
|
myschema.mydomain ...</>) then the domain is created in the
|
||||||
|
specified schema. Otherwise it is created in the current schema.
|
||||||
|
The domain name must be unique among the types and domains existing
|
||||||
|
in its schema.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Domains are useful for abstracting common fields between tables into
|
||||||
|
a single location for maintenance. For example, an email address column may be used
|
||||||
|
in several tables, all with the same properties. Define a domain and
|
||||||
|
use that rather than setting up each table's constraints individually.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -63,32 +75,26 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><literal>DEFAULT
|
<term><literal>DEFAULT <replaceable>default_expr</replaceable></literal></term>
|
||||||
<replaceable>default_expr</replaceable></literal></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <literal>DEFAULT</> clause specifies a default value for
|
The <literal>DEFAULT</> clause specifies a default value for
|
||||||
columns of the domain data type. The value
|
columns of the domain data type. The value is any
|
||||||
is any variable-free expression (but subselects are not allowed).
|
variable-free expression (but subqueries are not allowed).
|
||||||
The
|
The data type of the default expression must match the data
|
||||||
data type of the default expression must match the data type of the
|
type of the domain. If no default value is specified, then
|
||||||
domain.
|
the default value is the null value.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The default expression will be used in any insert operation that
|
The default expression will be used in any insert operation
|
||||||
does not specify a value for the column. If there is no default
|
that does not specify a value for the column. If a default
|
||||||
for a domain, then the default is NULL.
|
value is defined for a particular column, it overrides any
|
||||||
|
default associated with the domain. In turn, the domain
|
||||||
|
default overrides any default value associated with the
|
||||||
|
underlying data type.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
If a default value is specified for a particular column, it
|
|
||||||
overrides any default associated with the domain. In turn,
|
|
||||||
the domain default overrides any default value associated with
|
|
||||||
the underlying data type.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
@ -106,7 +112,7 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
|
||||||
<term><literal>NOT NULL</></term>
|
<term><literal>NOT NULL</></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Values of this domain are not allowed to be NULL.
|
Values of this domain are not allowed to be null.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -115,12 +121,12 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
|
||||||
<term><literal>NULL</></term>
|
<term><literal>NULL</></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Values of this domain are allowed to be NULL. This is the default.
|
Values of this domain are allowed to be null. This is the default.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This clause is only available for compatibility with
|
This clause is only intended for compatibility with
|
||||||
non-standard SQL databases. Its use is discouraged in new
|
nonstandard SQL databases. Its use is discouraged in new
|
||||||
applications.
|
applications.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
@ -139,84 +145,50 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Currently, <literal>CHECK</literal> expressions cannot contain
|
Currently, <literal>CHECK</literal> expressions cannot contain
|
||||||
subselects nor refer to variables other than <literal>VALUE</>.
|
subqueries nor refer to variables other than <literal>VALUE</>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEDOMAIN-2">
|
<refsect1>
|
||||||
<refsect2info>
|
<title>Diagnostics</title>
|
||||||
<date>2002-02-24</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>CREATE DOMAIN</computeroutput></term>
|
||||||
CREATE DOMAIN
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if the domain is successfully created.
|
Message returned if the domain was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEDOMAIN-1">
|
|
||||||
<refsect1info>
|
|
||||||
<date>2002-02-24</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<command>CREATE DOMAIN</command> allows the user to register a new
|
|
||||||
data domain with <productname>PostgreSQL</> for use in the
|
|
||||||
current data base. The user who defines a domain becomes its owner.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If a schema name is given (for example, <literal>CREATE DOMAIN
|
|
||||||
myschema.mydomain ...</>) then the domain is created in the
|
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
The domain name must be unique among the types and domains existing
|
|
||||||
in its schema.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Domains are useful for abstracting common fields between tables into
|
|
||||||
a single location for maintenance. An email address column may be used
|
|
||||||
in several tables, all with the same properties. Define a domain and
|
|
||||||
use that rather than setting up each table's constraints individually.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This example creates the <type>country_code</type> data type and then uses the
|
This example creates the <type>country_code</type> data type and then uses the
|
||||||
type in a table definition:
|
type in a table definition:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE DOMAIN country_code char(2) NOT NULL;
|
CREATE DOMAIN country_code char(2) NOT NULL;
|
||||||
CREATE TABLE countrylist (id INT4, country country_code);
|
CREATE TABLE countrylist (id integer, country country_code);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1 id="SQL-CREATEDOMAIN-compatibility">
|
||||||
|
<title>Compatibility</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The command <command>CREATE DOMAIN</command> conforms to the SQL
|
||||||
|
standard.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="SQL-CREATEDOMAIN-see-also">
|
<refsect1 id="SQL-CREATEDOMAIN-see-also">
|
||||||
<title>See Also</title>
|
<title>See Also</title>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.46 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.47 2003/04/22 10:08:08 petere Exp $
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<refentry id="SQL-CREATEFUNCTION">
|
<refentry id="SQL-CREATEFUNCTION">
|
||||||
|
@ -38,25 +38,48 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The user that creates the function becomes the owner of the function.
|
If a schema name is included, then the function is created in the
|
||||||
|
specified schema. Otherwise it is created in the current schema.
|
||||||
|
The name of the new function must not match any existing function
|
||||||
|
with the same argument types in the same schema. However,
|
||||||
|
functions of different argument types may share a name (this is
|
||||||
|
called <firstterm>overloading</>).
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<variablelist>
|
<para>
|
||||||
|
To update the definition of an existing function, use
|
||||||
|
<command>CREATE OR REPLACE FUNCTION</command>. It is not possible
|
||||||
|
to change the name or argument types of a function this way (if you
|
||||||
|
tried, you'd just be creating a new, distinct function). Also,
|
||||||
|
<command>CREATE OR REPLACE FUNCTION</command> will not let you
|
||||||
|
change the return type of an existing function. To do that, you
|
||||||
|
must drop and recreate the function.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If you drop and then recreate a function, the new function is not
|
||||||
|
the same entity as the old; you will break existing rules, views,
|
||||||
|
triggers, etc. that referred to the old function. Use
|
||||||
|
<command>CREATE OR REPLACE FUNCTION</command> to change a function
|
||||||
|
definition without breaking objects that refer to the function.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The user that creates the function becomes the owner of the function.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
<title>Parameters</title>
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">name</replaceable></term>
|
<term><replaceable class="parameter">name</replaceable></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name of a function to create. If a schema name is included,
|
The name of a function to create.
|
||||||
then the function is created in the
|
|
||||||
specified schema. Otherwise it is created in the current schema (the
|
|
||||||
one at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
The name of the new function must not match any existing function
|
|
||||||
with the same argument types in the same schema. However, functions of
|
|
||||||
different argument types may share a name (this is called
|
|
||||||
<firstterm>overloading</>).
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -67,20 +90,21 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The data type(s) of the function's arguments (optionally
|
The data type(s) of the function's arguments (optionally
|
||||||
schema-qualified), if any. The input types may be base, complex, or
|
schema-qualified), if any. The argument types may be base, complex, or
|
||||||
domain types, or the same as the type of an existing column.
|
domain types, or copy the type of an existing column.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The type of a column is referenced by writing <replaceable
|
The type of a column is referenced by writing
|
||||||
|
<literal><replaceable
|
||||||
class="parameter">tablename</replaceable>.<replaceable
|
class="parameter">tablename</replaceable>.<replaceable
|
||||||
class="parameter">columnname</replaceable><literal>%TYPE</literal>;
|
class="parameter">columnname</replaceable>%TYPE</literal>;
|
||||||
using this can sometimes help make a function independent from
|
using this can sometimes help make a function independent from
|
||||||
changes to the definition of a table.
|
changes to the definition of a table.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Depending on the implementation language it may also be allowed
|
Depending on the implementation language it may also be allowed
|
||||||
to specify <quote>pseudo-types</> such as <type>cstring</>.
|
to specify <quote>pseudotypes</> such as <type>cstring</>.
|
||||||
Pseudo-types indicate that the actual argument type is either
|
Pseudotypes indicate that the actual argument type is either
|
||||||
incompletely specified, or outside the set of ordinary SQL data types.
|
incompletely specified, or outside the set of ordinary SQL data types.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
@ -92,15 +116,15 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The return data type (optionally schema-qualified). The return type
|
The return data type (optionally schema-qualified). The return type
|
||||||
may be specified as a base, complex, domain type
|
may be specified as a base, complex, or domain type,
|
||||||
or the same as the type of an existing column. See the description
|
or may copy the type of an existing column. See the description
|
||||||
under <literal>argtype</literal> above on how to reference the type
|
under <literal>argtype</literal> above on how to reference the type
|
||||||
of an existing column.
|
of an existing column.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Depending on the implementation language it may also be allowed
|
Depending on the implementation language it may also be allowed
|
||||||
to specify <quote>pseudo-types</> such as <type>cstring</>.
|
to specify <quote>pseudotypes</> such as <type>cstring</>.
|
||||||
The <literal>setof</literal>
|
The <literal>SETOF</literal>
|
||||||
modifier indicates that the function will return a set of
|
modifier indicates that the function will return a set of
|
||||||
items, rather than a single item.
|
items, rather than a single item.
|
||||||
</para>
|
</para>
|
||||||
|
@ -123,9 +147,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>IMMUTABLE</term>
|
<term><literal>IMMUTABLE</literal></term>
|
||||||
<term>STABLE</term>
|
<term><literal>STABLE</literal></term>
|
||||||
<term>VOLATILE</term>
|
<term><literal>VOLATILE</literal></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
|
@ -140,7 +164,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
<literal>IMMUTABLE</literal> indicates that the function always
|
<literal>IMMUTABLE</literal> indicates that the function always
|
||||||
returns the same result when given the same argument values; that
|
returns the same result when given the same argument values; that
|
||||||
is, it does not do database lookups or otherwise use information not
|
is, it does not do database lookups or otherwise use information not
|
||||||
directly present in its parameter list. If this option is given,
|
directly present in its argument list. If this option is given,
|
||||||
any call of the function with all-constant arguments can be
|
any call of the function with all-constant arguments can be
|
||||||
immediately replaced with the function value.
|
immediately replaced with the function value.
|
||||||
</para>
|
</para>
|
||||||
|
@ -152,7 +176,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
result could change across SQL statements. This is the appropriate
|
result could change across SQL statements. This is the appropriate
|
||||||
selection for functions whose results depend on database lookups,
|
selection for functions whose results depend on database lookups,
|
||||||
parameter variables (such as the current time zone), etc. Also note
|
parameter variables (such as the current time zone), etc. Also note
|
||||||
that the <literal>CURRENT_TIMESTAMP</> family of functions qualify
|
that the <function>current_timestamp</> family of functions qualify
|
||||||
as stable, since their values do not change within a transaction.
|
as stable, since their values do not change within a transaction.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -170,9 +194,9 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>CALLED ON NULL INPUT</term>
|
<term><literal>CALLED ON NULL INPUT</literal></term>
|
||||||
<term>RETURNS NULL ON NULL INPUT</term>
|
<term><literal>RETURNS NULL ON NULL INPUT</literal></term>
|
||||||
<term>STRICT</term>
|
<term><literal>STRICT</literal></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
|
@ -186,17 +210,17 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
<para>
|
<para>
|
||||||
<literal>RETURNS NULL ON NULL INPUT</literal> or
|
<literal>RETURNS NULL ON NULL INPUT</literal> or
|
||||||
<literal>STRICT</literal> indicates that the function always
|
<literal>STRICT</literal> indicates that the function always
|
||||||
returns NULL whenever any of its arguments are NULL. If this
|
returns null whenever any of its arguments are null. If this
|
||||||
parameter is specified, the function is not executed when there
|
parameter is specified, the function is not executed when there
|
||||||
are NULL arguments; instead a NULL result is assumed
|
are null arguments; instead a null result is assumed
|
||||||
automatically.
|
automatically.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><optional>EXTERNAL</optional> SECURITY INVOKER</term>
|
<term><literal><optional>EXTERNAL</optional> SECURITY INVOKER</literal></term>
|
||||||
<term><optional>EXTERNAL</optional> SECURITY DEFINER</term>
|
<term><literal><optional>EXTERNAL</optional> SECURITY DEFINER</literal></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
|
@ -209,7 +233,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The key word <literal>EXTERNAL</literal> is present for SQL
|
The key word <literal>EXTERNAL</literal> is present for SQL
|
||||||
compatibility but is optional since, unlike in SQL, this feature
|
conformance but is optional since, unlike in SQL, this feature
|
||||||
does not only apply to external functions.
|
does not only apply to external functions.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
@ -222,25 +246,26 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
<para>
|
<para>
|
||||||
A string defining the function; the meaning depends on the
|
A string defining the function; the meaning depends on the
|
||||||
language. It may be an internal function name, the path to an
|
language. It may be an internal function name, the path to an
|
||||||
object file, an SQL query, or text in a procedural language.
|
object file, an SQL command, or text in a procedural language.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></term>
|
<term><literal><replaceable class="parameter">obj_file</replaceable>, <replaceable class="parameter">link_symbol</replaceable></literal></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This form of the <literal>AS</literal> clause is used for
|
This form of the <literal>AS</literal> clause is used for
|
||||||
dynamically linked C language functions when the function name
|
dynamically loadable C language functions when the function name
|
||||||
in the C language source code is not the same as the name of
|
in the C language source code is not the same as the name of
|
||||||
the SQL function. The string <replaceable
|
the SQL function. The string <replaceable
|
||||||
class="parameter">obj_file</replaceable> is the name of the
|
class="parameter">obj_file</replaceable> is the name of the
|
||||||
file containing the dynamically loadable object, and
|
file containing the dynamically loadable object, and
|
||||||
<replaceable class="parameter">link_symbol</replaceable> is the
|
<replaceable class="parameter">link_symbol</replaceable> is the
|
||||||
object's link symbol, that is, the name of the function in the C
|
function's link symbol, that is, the name of the function in the C
|
||||||
language source code.
|
language source code. If the link symbol is omitted, it is assumed
|
||||||
|
to be the same as the name of the SQL function being defined.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -285,48 +310,47 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE FUNCTION</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the function was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="sql-createfunction-notes">
|
<refsect1 id="sql-createfunction-notes">
|
||||||
<title>Notes</title>
|
<title>Notes</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Refer to <xref linkend="xfunc"> for further information on writing
|
Refer to <xref linkend="xfunc"> for further information on writing
|
||||||
external functions.
|
functions.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The full <acronym>SQL</acronym> type syntax is allowed for
|
The full <acronym>SQL</acronym> type syntax is allowed for
|
||||||
input arguments and return value. However, some details of the
|
input arguments and return value. However, some details of the
|
||||||
type specification (e.g., the precision field for
|
type specification (e.g., the precision field for
|
||||||
<type>numeric</type> types) are the responsibility of the
|
type <type>numeric</type>) are the responsibility of the
|
||||||
underlying function implementation and are silently swallowed
|
underlying function implementation and are silently swallowed
|
||||||
(i.e., not recognized or
|
(i.e., not recognized or
|
||||||
enforced) by the <command>CREATE FUNCTION</command> command.
|
enforced) by the <command>CREATE FUNCTION</command> command.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<productname>PostgreSQL</productname> allows function <firstterm>overloading</firstterm>;
|
<productname>PostgreSQL</productname> allows function
|
||||||
that is, the same name can be used for several different functions
|
<firstterm>overloading</firstterm>; that is, the same name can be
|
||||||
so long as they have distinct argument types. This facility must
|
used for several different functions so long as they have distinct
|
||||||
be used with caution for internal and C-language functions, however.
|
argument types. However, the C names of all functions must be
|
||||||
</para>
|
different, so you must give overloaded C functions different C
|
||||||
|
names (for example, use the argument types as part of the C
|
||||||
<para>
|
names).
|
||||||
Two <literal>internal</literal>
|
|
||||||
functions cannot have the same C name without causing
|
|
||||||
errors at link time. To get around that, give them different C names
|
|
||||||
(for example, use the argument types as part of the C names), then
|
|
||||||
specify those names in the AS clause of <command>CREATE FUNCTION</command>.
|
|
||||||
If the AS clause is left empty, then <command>CREATE FUNCTION</command>
|
|
||||||
assumes the C name of the function is the same as the SQL name.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Similarly, when overloading SQL function names with multiple C-language
|
|
||||||
functions, give
|
|
||||||
each C-language instance of the function a distinct name, then use
|
|
||||||
the alternative form of the <command>AS</command> clause in the
|
|
||||||
<command>CREATE FUNCTION</command> syntax to select the appropriate
|
|
||||||
C-language implementation of each overloaded SQL function.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -341,116 +365,26 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||||
to remove user-defined functions.
|
to remove user-defined functions.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
|
||||||
To update the definition of an existing function, use
|
|
||||||
<command>CREATE OR REPLACE FUNCTION</command>. Note that it is
|
|
||||||
not possible to change the name or argument types of a function
|
|
||||||
this way (if you tried, you'd just be creating a new, distinct
|
|
||||||
function). Also, <command>CREATE OR REPLACE FUNCTION</command>
|
|
||||||
will not let you change the return type of an existing function.
|
|
||||||
To do that, you must drop and re-create the function.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If you drop and then re-create a function, the new function is not
|
|
||||||
the same entity as the old; you will break existing rules, views,
|
|
||||||
triggers, etc that referred to the old function. Use
|
|
||||||
<command>CREATE OR REPLACE FUNCTION</command> to change a function
|
|
||||||
definition without breaking objects that refer to the function.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To be able to define a function, the user must have the
|
To be able to define a function, the user must have the
|
||||||
<literal>USAGE</literal> privilege on the language.
|
<literal>USAGE</literal> privilege on the language.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
|
||||||
By default, only the owner (creator) of the function has the right
|
|
||||||
to execute it. Other users must be granted the
|
|
||||||
<literal>EXECUTE</literal> privilege on the function to be able to
|
|
||||||
use it.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="sql-createfunction-examples">
|
<refsect1 id="sql-createfunction-examples">
|
||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To create a simple SQL function:
|
Here is a trivial example to help you get startet. For more
|
||||||
|
information and examples, see <xref linkend="xfunc">.
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE FUNCTION one() RETURNS integer
|
CREATE FUNCTION add(integer, integer) RETURNS integer
|
||||||
AS 'SELECT 1 AS RESULT;'
|
AS 'select $1 + $2;'
|
||||||
LANGUAGE SQL;
|
LANGUAGE SQL
|
||||||
|
IMMUTABLE
|
||||||
SELECT one() AS answer;
|
RETURNS NULL ON NULL INPUT;
|
||||||
<computeroutput>
|
|
||||||
answer
|
|
||||||
--------
|
|
||||||
1
|
|
||||||
</computeroutput>
|
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
|
||||||
The next example creates a C function by calling a routine from a
|
|
||||||
user-created shared library named <filename>funcs.so</> (the extension
|
|
||||||
may vary across platforms). The shared library file is sought in the
|
|
||||||
server's dynamic library search path. This particular routine calculates
|
|
||||||
a check digit and returns true if the check digit in the function
|
|
||||||
parameters is correct. It is intended for use in a CHECK
|
|
||||||
constraint.
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
CREATE FUNCTION ean_checkdigit(char, char) RETURNS boolean
|
|
||||||
AS 'funcs' LANGUAGE C;
|
|
||||||
|
|
||||||
CREATE TABLE product (
|
|
||||||
id char(8) PRIMARY KEY,
|
|
||||||
eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
|
|
||||||
REFERENCES brandname(ean_prefix),
|
|
||||||
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
|
|
||||||
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
|
|
||||||
);
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The next example creates a function that does type conversion from the
|
|
||||||
user-defined type complex to the built-in type point. The
|
|
||||||
function is implemented by a dynamically loaded object that was
|
|
||||||
compiled from C source (we illustrate the now-deprecated alternative
|
|
||||||
of specifying the absolute file name to the shared object file).
|
|
||||||
For <productname>PostgreSQL</productname> to
|
|
||||||
find a type conversion function automatically, the SQL function has
|
|
||||||
to have the same name as the return type, and so overloading is
|
|
||||||
unavoidable. The function name is overloaded by using the second
|
|
||||||
form of the <command>AS</command> clause in the SQL definition:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
CREATE FUNCTION point(complex) RETURNS point
|
|
||||||
AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
|
|
||||||
LANGUAGE C STRICT;
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
The C declaration of the function could be:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
Point * complex_to_point (Complex *z)
|
|
||||||
{
|
|
||||||
Point *p;
|
|
||||||
|
|
||||||
p = (Point *) palloc(sizeof(Point));
|
|
||||||
p->x = z->x;
|
|
||||||
p->y = z->y;
|
|
||||||
|
|
||||||
return p;
|
|
||||||
}
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
Note that the function is marked <quote>strict</>; this allows us
|
|
||||||
to skip checking for NULL input in the function body.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_group.sgml,v 1.10 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_group.sgml,v 1.11 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,35 +8,41 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-creategroup-title">CREATE GROUP</refentrytitle>
|
<refentrytitle id="sql-creategroup-title">CREATE GROUP</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE GROUP</refname>
|
||||||
CREATE GROUP
|
<refpurpose>define a new user group</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new user group
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2000-01-14</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
|
CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
|
||||||
|
|
||||||
where <replaceable class="PARAMETER">option</replaceable> can be:
|
where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
|
|
||||||
SYSID <replaceable class="PARAMETER">gid</replaceable>
|
SYSID <replaceable class="PARAMETER">gid</replaceable>
|
||||||
| USER <replaceable class="PARAMETER">username</replaceable> [, ...]
|
| USER <replaceable class="PARAMETER">username</replaceable> [, ...]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEGROUP-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-01-14</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE GROUP</command> will create a new group in the
|
||||||
|
database cluster. You must be a database
|
||||||
|
superuser to use this command.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
|
||||||
|
to change a group's membership, and <xref linkend="SQL-DROPGROUP"
|
||||||
|
endterm="SQL-DROPGROUP-title"> to remove a group.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -53,11 +59,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <literal>SYSID</literal> clause can be used to choose
|
The <literal>SYSID</literal> clause can be used to choose
|
||||||
the <productname>PostgreSQL</productname> group id of the new
|
the <productname>PostgreSQL</productname> group ID of the new
|
||||||
group. It is not necessary to do so, however.
|
group. It is not necessary to do so, however.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
If this is not specified, the highest assigned group id plus one,
|
If this is not specified, the highest assigned group ID plus one,
|
||||||
starting at 1, will be used as default.
|
starting at 1, will be used as default.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
@ -73,54 +79,26 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEGROUP-2">
|
<refsect1>
|
||||||
<refsect2info>
|
<title>Diagnostics</title>
|
||||||
<date>2000-01-14</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>CREATE GROUP</computeroutput></term>
|
<term><computeroutput>CREATE GROUP</computeroutput></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if the command completes successfully.
|
Message returned if the group was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEGROUP-1">
|
|
||||||
<refsect1info>
|
|
||||||
<date>2000-01-14</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE GROUP</command> will create a new group in the
|
|
||||||
database installation. You must be a database
|
|
||||||
superuser to use this command.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
|
|
||||||
to change a group's membership, and <xref linkend="SQL-DROPGROUP"
|
|
||||||
endterm="SQL-DROPGROUP-title"> to remove a group.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
<refsect1 id="R1-SQL-CREATEGROUP-2">
|
|
||||||
<title>
|
<refsect1>
|
||||||
Usage
|
<title>Examples</title>
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
Create an empty group:
|
Create an empty group:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
|
@ -136,24 +114,13 @@ CREATE GROUP marketing WITH USER jonathan, david;
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEGROUP-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEGROUP-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-01-14</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
There is no <command>CREATE GROUP</command> statement in SQL92.
|
There is no <command>CREATE GROUP</command> statement in the SQL
|
||||||
Roles are similar in concept to groups.
|
standard. Roles are similar in concept to groups.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.37 2002/09/21 18:32:54 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_index.sgml,v 1.38 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,39 +8,101 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
|
<refentrytitle id="sql-createindex-title">CREATE INDEX</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
<refnamediv>
|
|
||||||
<refname>
|
|
||||||
CREATE INDEX
|
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new index
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
|
||||||
<refsynopsisdiv>
|
|
||||||
<refsynopsisdivinfo>
|
|
||||||
<date>2001-07-15</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
|
|
||||||
[ USING <replaceable class="parameter">acc_method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
|
|
||||||
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
|
|
||||||
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
|
|
||||||
[ USING <replaceable class="parameter">acc_method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
|
|
||||||
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
|
|
||||||
</synopsis>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEINDEX-1">
|
<refnamediv>
|
||||||
<refsect2info>
|
<refname>CREATE INDEX</refname>
|
||||||
<date>1998-09-09</date>
|
<refpurpose>define a new index</refpurpose>
|
||||||
</refsect2info>
|
</refnamediv>
|
||||||
<title>
|
|
||||||
Inputs
|
<refsynopsisdiv>
|
||||||
</title>
|
<synopsis>
|
||||||
|
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
|
||||||
|
[ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">column</replaceable> [ <replaceable class="parameter">ops_name</replaceable> ] [, ...] )
|
||||||
|
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
|
||||||
|
|
||||||
|
CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table</replaceable>
|
||||||
|
[ USING <replaceable class="parameter">method</replaceable> ] ( <replaceable class="parameter">func_name</replaceable>( <replaceable class="parameter">column</replaceable> [, ... ]) [ <replaceable class="parameter">ops_name</replaceable> ] )
|
||||||
|
[ WHERE <replaceable class="parameter">predicate</replaceable> ]
|
||||||
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE INDEX</command> constructs an index <replaceable
|
||||||
|
class="parameter">index_name</replaceable> on the specified table.
|
||||||
|
Indexes are primarily used to enhance database performance. But
|
||||||
|
inappropriate use will result in slower performance.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In the first syntax shown above, the key field(s) for the
|
||||||
|
index are specified as column names.
|
||||||
|
Multiple fields can be specified if the index method supports
|
||||||
|
multicolumn indexes.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In the second syntax shown above, an index is defined on the result
|
||||||
|
of a user-specified function <replaceable
|
||||||
|
class="parameter">func_name</replaceable> applied to one or more
|
||||||
|
columns of a single table. These <firstterm>functional
|
||||||
|
indexes</firstterm> can be used to obtain fast access to data based
|
||||||
|
on operators that would normally require some transformation to apply
|
||||||
|
them to the base data. For example, a functional index on
|
||||||
|
<literal>upper(col)</> would allow the clause
|
||||||
|
<literal>WHERE upper(col) = 'JIM'</> to use an index.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<application>PostgreSQL</application> provides the index methods
|
||||||
|
B-tree, R-tree, hash, and GiST. The B-tree index method is an
|
||||||
|
implementation of Lehman-Yao high-concurrency B-trees. The R-tree
|
||||||
|
index method implements standard R-trees using Guttman's quadratic
|
||||||
|
split algorithm. The hash index method is an implementation of
|
||||||
|
Litwin's linear hashing. Users can also define their own index
|
||||||
|
methods, but that is fairly complicated.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
When the <literal>WHERE</literal> clause is present, a
|
||||||
|
<firstterm>partial index</firstterm> is created.
|
||||||
|
A partial index is an index that contains entries for only a portion of
|
||||||
|
a table, usually a portion that is somehow more interesting than the
|
||||||
|
rest of the table. For example, if you have a table that contains both
|
||||||
|
billed and unbilled orders where the unbilled orders take up a small
|
||||||
|
fraction of the total table and yet that is an often used section, you
|
||||||
|
can improve performance by creating an index on just that portion.
|
||||||
|
Another possible application is to use <literal>WHERE</literal> with
|
||||||
|
<literal>UNIQUE</literal> to enforce uniqueness over a subset of a
|
||||||
|
table.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The expression used in the <literal>WHERE</literal> clause may refer
|
||||||
|
only to columns of the underlying table (but it can use all columns,
|
||||||
|
not only the one(s) being indexed). Presently, subqueries and
|
||||||
|
aggregate expressions are also forbidden in <literal>WHERE</literal>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
All functions and operators used in an index definition must be
|
||||||
|
<quote>immutable</>, that is, their results must depend only on
|
||||||
|
their arguments and never on any outside influence (such as
|
||||||
|
the contents of another table or the current time). This restriction
|
||||||
|
ensures that the behavior of the index is well-defined. To use a
|
||||||
|
user-defined function in an index, remember to mark the function immutable
|
||||||
|
when you create it.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>UNIQUE</term>
|
<term><literal>UNIQUE</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Causes the system to check for
|
Causes the system to check for
|
||||||
|
@ -73,52 +135,13 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">acc_method</replaceable></term>
|
<term><replaceable class="parameter">method</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name of the access method to be used for the index. The
|
The name of the method to be used for the index. Choices are
|
||||||
default access method is <literal>BTREE</literal>.
|
<literal>btree</literal>, <literal>hash</literal>,
|
||||||
<application>PostgreSQL</application> provides four access
|
<literal>rtree</literal>, and <literal>gist</literal>. The
|
||||||
methods for indexes:
|
default method is <literal>btree</literal>.
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><literal>BTREE</></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
an implementation of Lehman-Yao
|
|
||||||
high-concurrency B-trees.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><literal>RTREE</></term>
|
|
||||||
<listitem>
|
|
||||||
<para>implements standard R-trees using Guttman's
|
|
||||||
quadratic split algorithm.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><literal>HASH</></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
an implementation of Litwin's linear hashing.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><literal>GIST</></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Generalized Index Search Trees.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -159,190 +182,38 @@ CREATE [ UNIQUE ] INDEX <replaceable class="parameter">index_name</replaceable>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEINDEX-2">
|
<refsect1>
|
||||||
<refsect2info>
|
<title>Diagnostics</title>
|
||||||
<date>1998-09-09</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>CREATE INDEX</computeroutput></term>
|
||||||
CREATE INDEX
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The message returned if the index is successfully created.
|
Message returned if the index was successfully created.
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
ERROR: Cannot create index: 'index_name' already exists.
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This error occurs if it is impossible to create the index.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEINDEX-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Notes</title>
|
||||||
<date>1998-09-09</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE INDEX</command> constructs an index
|
|
||||||
<replaceable class="parameter">index_name</replaceable>
|
|
||||||
on the specified <replaceable class="parameter">table</replaceable>.
|
|
||||||
|
|
||||||
<tip>
|
|
||||||
<para>
|
<para>
|
||||||
Indexes are primarily used to enhance database performance.
|
See <xref linkend="indexes"> for information about when indexes can
|
||||||
But inappropriate use will result in slower performance.
|
be used, when they are not used, and in which particular situations
|
||||||
</para>
|
can be useful.
|
||||||
</tip>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In the first syntax shown above, the key field(s) for the
|
Currently, only the B-tree and GiST index methods support
|
||||||
index are specified as column names.
|
multicolumn indexes. Up to 32 fields may be specified by default.
|
||||||
Multiple fields can be specified if the index access method supports
|
(This limit can be altered when building
|
||||||
multicolumn indexes.
|
<application>PostgreSQL</application>.) Only B-tree currently
|
||||||
</para>
|
supports unique indexes.
|
||||||
|
|
||||||
<para>
|
|
||||||
In the second syntax shown above, an index is defined on the result
|
|
||||||
of a user-specified function <replaceable
|
|
||||||
class="parameter">func_name</replaceable> applied to one or more
|
|
||||||
columns of a single table. These <firstterm>functional
|
|
||||||
indexes</firstterm> can be used to obtain fast access to data based
|
|
||||||
on operators that would normally require some transformation to apply
|
|
||||||
them to the base data. For example, a functional index on
|
|
||||||
<literal>upper(col)</> would allow the clause
|
|
||||||
<literal>WHERE upper(col) = 'JIM'</> to use an index.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<application>PostgreSQL</application> provides B-tree, R-tree, hash,
|
|
||||||
and GiST access methods for indexes. The B-tree access method is an
|
|
||||||
implementation of Lehman-Yao high-concurrency B-trees. The R-tree
|
|
||||||
access method implements standard R-trees using Guttman's quadratic
|
|
||||||
split algorithm. The hash access method is an implementation of
|
|
||||||
Litwin's linear hashing. We mention the algorithms used solely to
|
|
||||||
indicate that all of these access methods are fully dynamic and do
|
|
||||||
not have to be optimized periodically (as is the case with, for
|
|
||||||
example, static hash access methods).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
When the <command>WHERE</command> clause is present, a
|
|
||||||
<firstterm>partial index</firstterm> is created.
|
|
||||||
A partial index is an index that contains entries for only a portion of
|
|
||||||
a table, usually a portion that is somehow more interesting than the
|
|
||||||
rest of the table. For example, if you have a table that contains both
|
|
||||||
billed and unbilled orders where the unbilled orders take up a small
|
|
||||||
fraction of the total table and yet that is an often used section, you
|
|
||||||
can improve performance by creating an index on just that portion.
|
|
||||||
Another possible application is to use <command>WHERE</command> with
|
|
||||||
<command>UNIQUE</command> to enforce uniqueness over a subset of a
|
|
||||||
table.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The expression used in the <command>WHERE</command> clause may refer
|
|
||||||
only to columns of the underlying table (but it can use all columns,
|
|
||||||
not only the one(s) being indexed). Presently, subqueries and
|
|
||||||
aggregate expressions are also forbidden in <command>WHERE</command>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
All functions and operators used in an index definition must be
|
|
||||||
<firstterm>immutable</>, that is, their results must depend only on
|
|
||||||
their input arguments and never on any outside influence (such as
|
|
||||||
the contents of another table or the current time). This restriction
|
|
||||||
ensures that the behavior of the index is well-defined. To use a
|
|
||||||
user-defined function in an index, remember to mark the function immutable
|
|
||||||
when you create it.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
|
|
||||||
to remove an index.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEINDEX-3">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-09</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <productname>PostgreSQL</productname>
|
|
||||||
query optimizer will consider using a B-tree index whenever
|
|
||||||
an indexed attribute is involved in a comparison using one of:
|
|
||||||
|
|
||||||
<simplelist type="inline">
|
|
||||||
<member><</member>
|
|
||||||
<member><=</member>
|
|
||||||
<member>=</member>
|
|
||||||
<member>>=</member>
|
|
||||||
<member>></member>
|
|
||||||
</simplelist>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <productname>PostgreSQL</productname>
|
|
||||||
query optimizer will consider using an R-tree index whenever
|
|
||||||
an indexed attribute is involved in a comparison using one of:
|
|
||||||
|
|
||||||
<simplelist type="inline">
|
|
||||||
<member><<</member>
|
|
||||||
<member>&<</member>
|
|
||||||
<member>&></member>
|
|
||||||
<member>>></member>
|
|
||||||
<member>@</member>
|
|
||||||
<member>~=</member>
|
|
||||||
<member>&&</member>
|
|
||||||
</simplelist>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <productname>PostgreSQL</productname>
|
|
||||||
query optimizer will consider using a hash index whenever
|
|
||||||
an indexed attribute is involved in a comparison using
|
|
||||||
the <literal>=</literal> operator.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Testing has shown PostgreSQL's hash indexes to be similar or slower
|
|
||||||
than B-tree indexes, and the index size and build time for hash
|
|
||||||
indexes is much worse. Hash indexes also suffer poor performance
|
|
||||||
under high concurrency. For these reasons, hash index use is
|
|
||||||
discouraged.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Currently, only the B-tree and gist access methods support multicolumn
|
|
||||||
indexes. Up to 32 keys may be specified by default (this limit
|
|
||||||
can be altered when building
|
|
||||||
<application>PostgreSQL</application>). Only B-tree currently supports
|
|
||||||
unique indexes.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -351,57 +222,33 @@ ERROR: Cannot create index: 'index_name' already exists.
|
||||||
used by the index for that column. For example, a B-tree index on
|
used by the index for that column. For example, a B-tree index on
|
||||||
four-byte integers would use the <literal>int4_ops</literal> class;
|
four-byte integers would use the <literal>int4_ops</literal> class;
|
||||||
this operator class includes comparison functions for four-byte
|
this operator class includes comparison functions for four-byte
|
||||||
integers. In practice the default operator class for the field's data
|
integers. In practice the default operator class for the column's data
|
||||||
type is usually sufficient. The main point of having operator classes
|
type is usually sufficient. The main point of having operator classes
|
||||||
is that for some data types, there could be more than one meaningful
|
is that for some data types, there could be more than one meaningful
|
||||||
ordering. For example, we might want to sort a complex-number data
|
ordering. For example, we might want to sort a complex-number data
|
||||||
type either by absolute value or by real part. We could do this by
|
type either by absolute value or by real part. We could do this by
|
||||||
defining two operator classes for the data type and then selecting
|
defining two operator classes for the data type and then selecting
|
||||||
the proper class when making an index. There are also some operator
|
the proper class when making an index. More information about
|
||||||
classes with special purposes:
|
operator classes is in <xref linkend="indexes-opclass"> and in <xref
|
||||||
|
linkend="xindex">.
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The operator classes <literal>box_ops</literal> and
|
|
||||||
<literal>bigbox_ops</literal> both support R-tree indexes on the
|
|
||||||
<literal>box</literal> data type.
|
|
||||||
The difference between them is that <literal>bigbox_ops</literal>
|
|
||||||
scales box coordinates down, to avoid floating-point exceptions from
|
|
||||||
doing multiplication, addition, and subtraction on very large
|
|
||||||
floating-point coordinates. (Note: this was true some time ago,
|
|
||||||
but currently the two operator classes both use floating point
|
|
||||||
and are effectively identical.)
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The following query shows all defined operator classes:
|
Use <xref linkend="sql-dropindex" endterm="sql-dropindex-title">
|
||||||
|
to remove an index.
|
||||||
<programlisting>
|
|
||||||
SELECT am.amname AS acc_method,
|
|
||||||
opc.opcname AS ops_name
|
|
||||||
FROM pg_am am, pg_opclass opc
|
|
||||||
WHERE opc.opcamid = am.oid
|
|
||||||
ORDER BY acc_method, ops_name;
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEINDEX-2">
|
<refsect1>
|
||||||
<title>
|
<title>Examples</title>
|
||||||
Usage
|
|
||||||
</title>
|
<para>
|
||||||
<para>To create a B-tree index on the field <literal>title</literal>
|
To create a B-tree index on the column <literal>title</literal> in
|
||||||
in the table <literal>films</literal>:
|
the table <literal>films</literal>:
|
||||||
|
<programlisting>
|
||||||
|
CREATE UNIQUE INDEX title_idx ON films (title);
|
||||||
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
<programlisting>
|
|
||||||
CREATE UNIQUE INDEX title_idx
|
|
||||||
ON films (title);
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
<comment>
|
<comment>
|
||||||
|
@ -422,25 +269,14 @@ SELECT * FROM points
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEINDEX-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEINDEX-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-09</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
CREATE INDEX is a <productname>PostgreSQL</productname> language extension.
|
<command>CREATE INDEX</command> is a
|
||||||
|
<productname>PostgreSQL</productname> language extension. There
|
||||||
|
are no provisions for indexes in the SQL standard.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
|
||||||
There is no <command>CREATE INDEX</command> command in SQL92.
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.31 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_language.sgml,v 1.32 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -60,7 +60,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
|
||||||
<literal>TRUSTED</literal> specifies that the call handler for
|
<literal>TRUSTED</literal> specifies that the call handler for
|
||||||
the language is safe, that is, it does not offer an
|
the language is safe, that is, it does not offer an
|
||||||
unprivileged user any functionality to bypass access
|
unprivileged user any functionality to bypass access
|
||||||
restrictions. If this keyword is omitted when registering the
|
restrictions. If this key word is omitted when registering the
|
||||||
language, only users with the
|
language, only users with the
|
||||||
<productname>PostgreSQL</productname> superuser privilege can
|
<productname>PostgreSQL</productname> superuser privilege can
|
||||||
use this language to create new functions.
|
use this language to create new functions.
|
||||||
|
@ -84,8 +84,8 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name of the new procedural language. The language name is
|
The name of the new procedural language. The language name is
|
||||||
case insensitive. A procedural language cannot override one of
|
case insensitive. The name must be unique among the languages
|
||||||
the built-in languages of <productname>PostgreSQL</productname>.
|
in the database.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -146,45 +146,16 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">langna
|
||||||
<refsect1 id="sql-createlanguage-diagnostics">
|
<refsect1 id="sql-createlanguage-diagnostics">
|
||||||
<title>Diagnostics</title>
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
<msgset>
|
<variablelist>
|
||||||
<msgentry>
|
<varlistentry>
|
||||||
<msg>
|
<term><computeroutput>CREATE LANGUAGE</computeroutput></term>
|
||||||
<msgmain>
|
<listitem>
|
||||||
<msgtext>
|
|
||||||
<screen>
|
|
||||||
CREATE LANGUAGE
|
|
||||||
</screen>
|
|
||||||
</msgtext>
|
|
||||||
</msgmain>
|
|
||||||
</msg>
|
|
||||||
|
|
||||||
<msgexplan>
|
|
||||||
<para>
|
<para>
|
||||||
This message is returned if the language is successfully
|
Message returned if the language was successfully created.
|
||||||
created.
|
|
||||||
</para>
|
</para>
|
||||||
</msgexplan>
|
</listitem>
|
||||||
</msgentry>
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
<msgentry>
|
|
||||||
<msg>
|
|
||||||
<msgmain>
|
|
||||||
<msgtext>
|
|
||||||
<screen>
|
|
||||||
ERROR: PL handler function <replaceable class="parameter">funcname</replaceable>() doesn't exist
|
|
||||||
</screen>
|
|
||||||
</msgtext>
|
|
||||||
</msgmain>
|
|
||||||
</msg>
|
|
||||||
|
|
||||||
<msgexplan>
|
|
||||||
<para>
|
|
||||||
This error is returned if the function <replaceable
|
|
||||||
class="parameter">funcname</replaceable>() is not found.
|
|
||||||
</para>
|
|
||||||
</msgexplan>
|
|
||||||
</msgentry>
|
|
||||||
</msgset>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="sql-createlanguage-notes">
|
<refsect1 id="sql-createlanguage-notes">
|
||||||
|
@ -194,7 +165,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
|
||||||
This command normally should not be executed directly by users.
|
This command normally should not be executed directly by users.
|
||||||
For the procedural languages supplied in the
|
For the procedural languages supplied in the
|
||||||
<productname>PostgreSQL</productname> distribution, the <xref
|
<productname>PostgreSQL</productname> distribution, the <xref
|
||||||
linkend="app-createlang"> script should be used, which will also
|
linkend="app-createlang"> program should be used, which will also
|
||||||
install the correct call handler. (<command>createlang</command>
|
install the correct call handler. (<command>createlang</command>
|
||||||
will call <command>CREATE LANGUAGE</command> internally.)
|
will call <command>CREATE LANGUAGE</command> internally.)
|
||||||
</para>
|
</para>
|
||||||
|
@ -205,7 +176,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
|
||||||
type <type>opaque</>, rather than <type>language_handler</>.
|
type <type>opaque</>, rather than <type>language_handler</>.
|
||||||
To support loading
|
To support loading
|
||||||
of old dump files, <command>CREATE LANGUAGE</> will accept a function
|
of old dump files, <command>CREATE LANGUAGE</> will accept a function
|
||||||
declared as returning <type>opaque</>, but it will issue a NOTICE and
|
declared as returning <type>opaque</>, but it will issue a notice and
|
||||||
change the function's declared return type to <type>language_handler</>.
|
change the function's declared return type to <type>language_handler</>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -216,35 +187,19 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
|
Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
|
||||||
linkend="app-droplang"> script, to drop procedural languages.
|
linkend="app-droplang"> program, to drop procedural languages.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The system catalog <classname>pg_language</classname> records
|
The system catalog <classname>pg_language</classname> (see <xref
|
||||||
information about the currently installed procedural languages.
|
linkend="catalog-pg-language">) records information about the
|
||||||
|
currently installed languages. Also <command>createlang</command>
|
||||||
<screen>
|
has an option to list the installed languages.
|
||||||
Table "pg_language"
|
|
||||||
Attribute | Type | Modifier
|
|
||||||
---------------+-----------+----------
|
|
||||||
lanname | name |
|
|
||||||
lanispl | boolean |
|
|
||||||
lanpltrusted | boolean |
|
|
||||||
lanplcallfoid | oid |
|
|
||||||
lanvalidator | oid |
|
|
||||||
lanacl | aclitem[] |
|
|
||||||
|
|
||||||
lanname | lanispl | lanpltrusted | lanplcallfoid | lanvalidator | lanacl
|
|
||||||
-------------+---------+--------------+---------------+--------------+--------
|
|
||||||
internal | f | f | 0 | 2246 |
|
|
||||||
c | f | f | 0 | 2247 |
|
|
||||||
sql | f | t | 0 | 2248 | {=U}
|
|
||||||
</screen>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
At present, with the exception of the permissions, the definition
|
The definition of a procedural language cannot be changed once it
|
||||||
of a procedural language cannot be changed once it has been created.
|
has been created, with the exception of the privileges.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -262,7 +217,7 @@ ERROR: PL handler function <replaceable class="parameter">funcname</replaceable
|
||||||
The following two commands executed in sequence will register a new
|
The following two commands executed in sequence will register a new
|
||||||
procedural language and the associated call handler.
|
procedural language and the associated call handler.
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE FUNCTION plsample_call_handler () RETURNS language_handler
|
CREATE FUNCTION plsample_call_handler() RETURNS language_handler
|
||||||
AS '$libdir/plsample'
|
AS '$libdir/plsample'
|
||||||
LANGUAGE C;
|
LANGUAGE C;
|
||||||
CREATE LANGUAGE plsample
|
CREATE LANGUAGE plsample
|
||||||
|
@ -280,15 +235,6 @@ CREATE LANGUAGE plsample
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
|
||||||
<title>History</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <command>CREATE LANGUAGE</command> command first appeared in
|
|
||||||
<productname>PostgreSQL</productname> 6.3.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>See Also</title>
|
<title>See Also</title>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.6 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.7 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,206 +8,44 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createopclass-title">CREATE OPERATOR CLASS</refentrytitle>
|
<refentrytitle id="sql-createopclass-title">CREATE OPERATOR CLASS</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE OPERATOR CLASS</refname>
|
||||||
CREATE OPERATOR CLASS
|
<refpurpose>define a new operator class for indexes</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new operator class for indexes
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2002-07-28</date>
|
CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAULT ] FOR TYPE <replaceable class="parameter">data_type</replaceable> USING <replaceable class="parameter">index_method</replaceable> AS
|
||||||
</refsynopsisdivinfo>
|
{ OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_name</replaceable> [ ( <replaceable class="parameter">op_type</replaceable>, <replaceable class="parameter">op_type</replaceable> ) ] [ RECHECK ]
|
||||||
<synopsis>
|
| FUNCTION <replaceable class="parameter">support_number</replaceable> <replaceable class="parameter">func_name</replaceable> ( <replaceable class="parameter">argument_types</replaceable> )
|
||||||
CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAULT ] FOR TYPE <replaceable class="parameter">data_type</replaceable> USING <replaceable class="parameter">access_method</replaceable> AS
|
|
||||||
{ OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_id</replaceable> [ ( <replaceable class="parameter">type</replaceable>, <replaceable class="parameter">type</replaceable> ) ] [ RECHECK ]
|
|
||||||
| FUNCTION <replaceable class="parameter">support_number</replaceable> <replaceable class="parameter">func_name</replaceable> ( <replaceable class="parameter">parameter_types</replaceable> )
|
|
||||||
| STORAGE <replaceable class="parameter">storage_type</replaceable>
|
| STORAGE <replaceable class="parameter">storage_type</replaceable>
|
||||||
} [, ... ]
|
} [, ... ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPCLASS-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2002-07-28</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">name</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of the operator class to be created.
|
|
||||||
The name may be schema-qualified.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><literal>DEFAULT</></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If present, the operator class will become the default index
|
|
||||||
operator class for its data type. At most one operator class
|
|
||||||
can be the default for a specific data type and access method.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">data_type</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The column data type that this operator class is for.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">access_method</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of the index access method this operator class is for.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">strategy_number</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The index access method's strategy number for an operator associated
|
|
||||||
with the operator class.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">operator_id</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The identifier (optionally schema-qualified) of an operator associated
|
|
||||||
with the operator class.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">type</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The input data type(s) of an operator, or <literal>NONE</> to
|
|
||||||
signify a left-unary or right-unary operator. The input data types
|
|
||||||
may be omitted in the normal case where they are the same as the
|
|
||||||
operator class's data type.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><literal>RECHECK</></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If present, the index is <quote>lossy</> for this operator,
|
|
||||||
and so the tuples retrieved using the index must be rechecked
|
|
||||||
to verify that they actually satisfy the qualification clause
|
|
||||||
involving this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">support_number</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The index access method's support procedure number for a function
|
|
||||||
associated with the operator class.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">func_name</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name (optionally schema-qualified) of a function that is
|
|
||||||
an index access method support procedure for the operator class.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">parameter_types</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The parameter data type(s) of the function.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">storage_type</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The data type actually stored in the index. Normally this is the
|
|
||||||
same as the column data type, but some index access methods (only
|
|
||||||
GIST at this writing) allow it to be different. The
|
|
||||||
<literal>STORAGE</> clause must be omitted unless the index access
|
|
||||||
method allows a different type to be used.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPCLASS-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2002-07-28</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
CREATE OPERATOR CLASS
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Message returned if the operator class is successfully created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEOPCLASS-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>2002-07-28</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE OPERATOR CLASS</command> defines a new operator class,
|
|
||||||
<replaceable class="parameter">name</replaceable>.
|
|
||||||
</para>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE OPERATOR CLASS</command> creates a new operator class.
|
||||||
An operator class defines how a particular data type can be used with
|
An operator class defines how a particular data type can be used with
|
||||||
an index. The operator class specifies that certain operators will fill
|
an index. The operator class specifies that certain operators will fill
|
||||||
particular roles or <quote>strategies</> for this data type and this
|
particular roles or <quote>strategies</> for this data type and this
|
||||||
access method. The operator class also specifies the support procedures to
|
index method. The operator class also specifies the support procedures to
|
||||||
be used by
|
be used by
|
||||||
the index access method when the operator class is selected for an
|
the index method when the operator class is selected for an
|
||||||
index column. All the operators and functions used by an operator
|
index column. All the operators and functions used by an operator
|
||||||
class must be defined before the operator class is created.
|
class must be defined before the operator class is created.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If a schema name is given then the operator class is created in the
|
If a schema name is given then the operator class is created in the
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
specified schema. Otherwise it is created in the current schema.
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
Two operator classes in the same schema can have the same name only if they
|
Two operator classes in the same schema can have the same name only if they
|
||||||
are for different index access methods.
|
are for different index methods.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The user who defines an operator class becomes its owner. Presently,
|
The user who defines an operator class becomes its owner. Presently,
|
||||||
the creating user must be a superuser. (This restriction is made because
|
the creating user must be a superuser. (This restriction is made because
|
||||||
|
@ -217,41 +55,187 @@ CREATE OPERATOR CLASS
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE OPERATOR CLASS</command> does not presently check
|
<command>CREATE OPERATOR CLASS</command> does not presently check
|
||||||
whether the class definition includes all the operators and functions
|
whether the operator class definition includes all the operators and functions
|
||||||
required by the index access method. It is the user's
|
required by the index method. It is the user's
|
||||||
responsibility to define a valid operator class.
|
responsibility to define a valid operator class.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Refer to <xref linkend="xindex"> for further information.
|
Refer to <xref linkend="xindex"> for further information.
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of the operator class to be created. The name may be
|
||||||
|
schema-qualified.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>DEFAULT</></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If present, the operator class will become the default
|
||||||
|
operator class for its data type. At most one operator class
|
||||||
|
can be the default for a specific data type and index method.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">data_type</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The column data type that this operator class is for.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">index_method</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of the index method this operator class is for.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">strategy_number</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The index method's strategy number for an operator
|
||||||
|
associated with the operator class.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">operator_name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name (optionally schema-qualified) of an operator associated
|
||||||
|
with the operator class.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">op_type</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The operand data type(s) of an operator, or <literal>NONE</> to
|
||||||
|
signify a left-unary or right-unary operator. The operand data
|
||||||
|
types may be omitted in the normal case where they are the same
|
||||||
|
as the operator class's data type.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>RECHECK</></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If present, the index is <quote>lossy</> for this operator, and
|
||||||
|
so the rows retrieved using the index must be rechecked to
|
||||||
|
verify that they actually satisfy the qualification clause
|
||||||
|
involving this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">support_number</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The index method's support procedure number for a
|
||||||
|
function associated with the operator class.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">func_name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name (optionally schema-qualified) of a function that is an
|
||||||
|
index method support procedure for the operator class.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">argument_types</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The parameter data type(s) of the function.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">storage_type</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The data type actually stored in the index. Normally this is
|
||||||
|
the same as the column data type, but some index methods
|
||||||
|
(only GiST at this writing) allow it to be different. The
|
||||||
|
<literal>STORAGE</> clause must be omitted unless the index
|
||||||
|
method allows a different type to be used.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</>
|
||||||
|
clauses may appear in any order.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE OPERATOR CLASS</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the operator class was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Notes</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPCLASS-3">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2002-07-28</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
Refer to
|
Refer to
|
||||||
<xref linkend="sql-dropopclass" endterm="sql-dropopclass-title">
|
<xref linkend="sql-dropopclass" endterm="sql-dropopclass-title">
|
||||||
to delete user-defined operator classes from a database.
|
to delete user-defined operator classes from a database.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEOPCLASS-2">
|
<refsect1>
|
||||||
<title>
|
<title>Examples</title>
|
||||||
Usage
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
The following example command defines a GiST index operator class
|
The following example command defines a GiST index operator class
|
||||||
for data type <literal>_int4</> (array of int4). See
|
for the data type <literal>_int4</> (array of <type>int4</type>). See
|
||||||
<filename>contrib/intarray/</> for the complete example.
|
<filename>contrib/intarray/</> for the complete example.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE OPERATOR CLASS gist__int_ops
|
CREATE OPERATOR CLASS gist__int_ops
|
||||||
DEFAULT FOR TYPE _int4 USING gist AS
|
DEFAULT FOR TYPE _int4 USING gist AS
|
||||||
OPERATOR 3 &&,
|
OPERATOR 3 &&,
|
||||||
|
@ -266,34 +250,18 @@ CREATE OPERATOR CLASS gist__int_ops
|
||||||
FUNCTION 5 g_int_penalty (internal, internal, internal),
|
FUNCTION 5 g_int_penalty (internal, internal, internal),
|
||||||
FUNCTION 6 g_int_picksplit (internal, internal),
|
FUNCTION 6 g_int_picksplit (internal, internal),
|
||||||
FUNCTION 7 g_int_same (_int4, _int4, internal);
|
FUNCTION 7 g_int_same (_int4, _int4, internal);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<para>
|
|
||||||
The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</>
|
|
||||||
clauses may appear in any order.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEOPCLASS-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPCLASS-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2002-07-28</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE OPERATOR CLASS</command>
|
<command>CREATE OPERATOR CLASS</command> is a
|
||||||
is a <productname>PostgreSQL</productname> extension.
|
<productname>PostgreSQL</productname> extension. There is no
|
||||||
There is no <command>CREATE OPERATOR CLASS</command>
|
<command>CREATE OPERATOR CLASS</command> statement in the SQL
|
||||||
statement in <acronym>SQL92</acronym>.
|
standard.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.34 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.35 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,218 +8,43 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle>
|
<refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE OPERATOR</refname>
|
||||||
CREATE OPERATOR
|
<refpurpose>define a new operator</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new operator
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2000-03-25</date>
|
CREATE OPERATOR <replaceable>name</replaceable> (
|
||||||
</refsynopsisdivinfo>
|
PROCEDURE = <replaceable class="parameter">func_name</replaceable>
|
||||||
<synopsis>
|
[, LEFTARG = <replaceable class="parameter">lefttype</replaceable> ] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
|
||||||
CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class="parameter">func_name</replaceable>
|
|
||||||
[, LEFTARG = <replaceable class="parameter">lefttype</replaceable>
|
|
||||||
] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
|
|
||||||
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
|
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
|
||||||
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
|
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
|
||||||
[, HASHES ] [, MERGES ]
|
[, HASHES ] [, MERGES ]
|
||||||
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
|
[, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
|
||||||
[, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ] )
|
[, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ]
|
||||||
</synopsis>
|
)
|
||||||
|
</synopsis>
|
||||||
<refsect2 id="R2-SQL-CREATEOPERATOR-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">name</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The operator to be defined. See below for allowable characters.
|
|
||||||
The name may be schema-qualified, for example
|
|
||||||
<literal>CREATE OPERATOR myschema.+ (...)</>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">func_name</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The function used to implement this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">lefttype</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The type of the left-hand argument of the operator, if any.
|
|
||||||
This option would be omitted for a left-unary operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">righttype</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The type of the right-hand argument of the operator, if any.
|
|
||||||
This option would be omitted for a right-unary operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">com_op</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The commutator of this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">neg_op</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The negator of this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">res_proc</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The restriction selectivity estimator function for this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">join_proc</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The join selectivity estimator function for this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>HASHES</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Indicates this operator can support a hash join.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>MERGES</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Indicates this operator can support a merge join.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">left_sort_op</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If this operator can support a merge join, the less-than
|
|
||||||
operator that sorts the left-hand data type of this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">right_sort_op</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If this operator can support a merge join, the less-than
|
|
||||||
operator that sorts the right-hand data type of this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">less_than_op</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If this operator can support a merge join, the less-than
|
|
||||||
operator that compares the input data types of this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">greater_than_op</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If this operator can support a merge join, the greater-than
|
|
||||||
operator that compares the input data types of this operator.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPERATOR-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
CREATE OPERATOR
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Message returned if the operator is successfully created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEOPERATOR-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE OPERATOR</command> defines a new operator,
|
<command>CREATE OPERATOR</command> defines a new operator,
|
||||||
<replaceable class="parameter">name</replaceable>.
|
<replaceable class="parameter">name</replaceable>. The user who
|
||||||
The user who defines an operator becomes its owner.
|
defines an operator becomes its owner. If a schema name is given
|
||||||
</para>
|
then the operator is created in the specified schema. Otherwise it
|
||||||
<para>
|
is created in the current schema.
|
||||||
If a schema name is given then the operator is created in the
|
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Two operators in the same schema can have the same name if they operate on
|
|
||||||
different data types. This is called <firstterm>overloading</>. The
|
|
||||||
system will attempt to pick the intended operator based on the actual
|
|
||||||
input data types when there is ambiguity.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The operator <replaceable class="parameter">name</replaceable>
|
The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
|
||||||
is a sequence of up to <symbol>NAMEDATALEN</>-1 (63 by default) characters
|
(63 by default) characters from the following list:
|
||||||
from the following list:
|
<literallayout>
|
||||||
<literallayout>
|
|
||||||
+ - * / < > = ~ ! @ # % ^ & | ` ? $
|
+ - * / < > = ~ ! @ # % ^ & | ` ? $
|
||||||
</literallayout>
|
</literallayout>
|
||||||
|
|
||||||
There are a few restrictions on your choice of name:
|
There are a few restrictions on your choice of name:
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
@ -240,226 +65,232 @@ CREATE OPERATOR
|
||||||
A multicharacter operator name cannot end in <literal>+</literal> or
|
A multicharacter operator name cannot end in <literal>+</literal> or
|
||||||
<literal>-</literal>,
|
<literal>-</literal>,
|
||||||
unless the name also contains at least one of these characters:
|
unless the name also contains at least one of these characters:
|
||||||
<literallayout>
|
<literallayout>
|
||||||
~ ! @ # % ^ & | ` ? $
|
~ ! @ # % ^ & | ` ? $
|
||||||
</literallayout>
|
</literallayout>
|
||||||
For example, <literal>@-</literal> is an allowed operator name,
|
For example, <literal>@-</literal> is an allowed operator name,
|
||||||
but <literal>*-</literal> is not.
|
but <literal>*-</literal> is not.
|
||||||
This restriction allows <productname>PostgreSQL</productname> to
|
This restriction allows <productname>PostgreSQL</productname> to
|
||||||
parse SQL-compliant queries without requiring spaces between tokens.
|
parse SQL-compliant commands without requiring spaces between tokens.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
</para>
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
<para>
|
||||||
When working with non-SQL-standard operator names, you will usually
|
The operator <literal>!=</literal> is mapped to
|
||||||
need to separate adjacent operators with spaces to avoid ambiguity.
|
<literal><></literal> on input, so these two names are always
|
||||||
For example, if you have defined a left-unary operator named <literal>@</literal>,
|
equivalent.
|
||||||
you cannot write <literal>X*@Y</literal>; you must write
|
|
||||||
<literal>X* @Y</literal> to ensure that
|
|
||||||
<productname>PostgreSQL</productname> reads it as two operator names
|
|
||||||
not one.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The operator <literal>!=</literal> is mapped to <literal><></literal> on input, so these two names
|
|
||||||
are always equivalent.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For
|
At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For
|
||||||
binary operators, both should be defined. For right unary
|
binary operators, both must be defined. For right unary
|
||||||
operators, only <literal>LEFTARG</> should be defined, while for left
|
operators, only <literal>LEFTARG</> should be defined, while for left
|
||||||
unary operators only <literal>RIGHTARG</> should be defined.
|
unary operators only <literal>RIGHTARG</> should be defined.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
|
||||||
The
|
|
||||||
<replaceable class="parameter">func_name</replaceable> procedure must have
|
|
||||||
been previously defined using <command>CREATE FUNCTION</command> and must
|
|
||||||
be defined to accept the correct number of arguments
|
|
||||||
(either one or two) of the indicated types.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The commutator operator should be identified if one exists,
|
|
||||||
so that <productname>PostgreSQL</productname> can
|
|
||||||
reverse the order of the operands if it wishes.
|
|
||||||
For example, the operator area-less-than, <<<,
|
|
||||||
would probably have a commutator
|
|
||||||
operator, area-greater-than, >>>.
|
|
||||||
Hence, the query optimizer could freely convert:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
box '((0,0), (1,1))' >>> MYBOXES.description
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
to
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
MYBOXES.description <<< box '((0,0), (1,1))'
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
<para>
|
||||||
This allows the execution code to always use the latter
|
The <replaceable class="parameter">func_name</replaceable>
|
||||||
representation and simplifies the query optimizer somewhat.
|
procedure must have been previously defined using <command>CREATE
|
||||||
</para>
|
FUNCTION</command> and must be defined to accept the correct number
|
||||||
<para>
|
of arguments (either one or two) of the indicated types.
|
||||||
Similarly, if there is a negator operator then it should be
|
|
||||||
identified.
|
|
||||||
Suppose that an
|
|
||||||
operator, area-equal, ===, exists, as well as an area not
|
|
||||||
equal, !==.
|
|
||||||
The negator link allows the query optimizer to simplify
|
|
||||||
<programlisting>
|
|
||||||
NOT MYBOXES.description === box '((0,0), (1,1))'
|
|
||||||
</programlisting>
|
|
||||||
to
|
|
||||||
<programlisting>
|
|
||||||
MYBOXES.description !== box '((0,0), (1,1))'
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If a commutator operator name is supplied,
|
|
||||||
<productname>PostgreSQL</productname>
|
|
||||||
searches for it in the catalog. If it is found and it
|
|
||||||
does not yet have a commutator itself, then the commutator's
|
|
||||||
entry is updated to have the newly created operator as its
|
|
||||||
commutator. This applies to the negator, as well.
|
|
||||||
This is to allow the definition of two operators that are
|
|
||||||
the commutators or the negators of each other. The first
|
|
||||||
operator should be defined without a commutator or negator
|
|
||||||
(as appropriate). When the second operator is defined,
|
|
||||||
name the first as the commutator or negator. The first
|
|
||||||
will be updated as a side effect. (As of
|
|
||||||
<application>PostgreSQL</application> <literal>6.5</literal>,
|
|
||||||
it also works to just have both operators refer to each other.)
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The <literal>HASHES</>, <literal>MERGES</>, <literal>SORT1</>,
|
|
||||||
<literal>SORT2</>, <literal>LTCMP</>, and <literal>GTCMP</> options
|
|
||||||
are present to support the query optimizer in performing joins.
|
|
||||||
<productname>PostgreSQL</productname> can always evaluate a join
|
|
||||||
(i.e., processing a clause with two tuple variables separated by an
|
|
||||||
operator that returns a <type>boolean</type>) by iterative
|
|
||||||
substitution <!--[WONG76]-->. In addition,
|
|
||||||
<productname>PostgreSQL</productname> can use a hash-join algorithm
|
|
||||||
<!--along the lines of [SHAP86]-->; however, it must know whether this
|
|
||||||
strategy is applicable. The current hash-join algorithm is only
|
|
||||||
correct for operators that represent equality tests; furthermore,
|
|
||||||
equality of the data type must mean bitwise equality of the
|
|
||||||
representation of the type. (For example, a data type that
|
|
||||||
contains unused bits that don't matter for equality tests could not
|
|
||||||
be hash-joined.) The <literal>HASHES</> flag indicates to the query optimizer
|
|
||||||
that a hash join may safely be used with this operator.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Similarly, the <literal>MERGES</> flag indicates whether merge-sort
|
|
||||||
is a usable join strategy for this operator. A merge join requires
|
|
||||||
that the two input data types have consistent orderings, and that
|
|
||||||
the merge-join operator behave like equality with respect to that
|
|
||||||
ordering. For example, it is possible to merge-join equality
|
|
||||||
between an integer and a float variable by sorting both inputs in
|
|
||||||
ordinary numeric order. Execution of a merge join requires that
|
|
||||||
the system be able to identify four operators related to the
|
|
||||||
merge-join equality operator: less-than comparison for the left
|
|
||||||
input data type, less-than comparison for the right input data
|
|
||||||
type, less-than comparison between the two data types, and
|
|
||||||
greater-than comparison between the two data types. It is possible
|
|
||||||
to specify these by name, as the <literal>SORT1</>,
|
|
||||||
<literal>SORT2</>, <literal>LTCMP</>, and <literal>GTCMP</> options
|
|
||||||
respectively. The system will fill in the default names
|
|
||||||
<literal><</>, <literal><</>, <literal><</>,
|
|
||||||
<literal>></> respectively if any of these are omitted when
|
|
||||||
<literal>MERGES</> is specified. Also, <literal>MERGES</> will be
|
|
||||||
assumed to be implied if any of these four operator options appear.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
If other join strategies are found to be practical,
|
|
||||||
<productname>PostgreSQL</productname>
|
|
||||||
will change the optimizer and run-time system to use
|
|
||||||
them and will require additional specification when an
|
|
||||||
operator is defined. Fortunately, the research community
|
|
||||||
invents new join strategies infrequently, and the added
|
|
||||||
generality of user-defined join strategies was not felt to
|
|
||||||
be worth the complexity involved.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The <literal>RESTRICT</> and <literal>JOIN</> options assist the
|
|
||||||
query optimizer in estimating result sizes. If a clause of the
|
|
||||||
form:
|
|
||||||
<programlisting>
|
|
||||||
myboxes.description <<< box '((0,0), (1,1))'
|
|
||||||
</programlisting>
|
|
||||||
is present in the qualification,
|
|
||||||
then <productname>PostgreSQL</productname> may have to
|
|
||||||
estimate the fraction of the instances in <literal>myboxes</> that
|
|
||||||
satisfy the clause. The function
|
|
||||||
<replaceable class="parameter">res_proc</replaceable>
|
|
||||||
must be a registered function (meaning it is already defined using
|
|
||||||
<command>CREATE FUNCTION</command>) which accepts arguments of the correct
|
|
||||||
data types and returns a floating-point number. The
|
|
||||||
query optimizer simply calls this function, passing the
|
|
||||||
parameter <literal>((0,0), (1,1))</literal> and multiplies the result by the relation
|
|
||||||
size to get the expected number of instances.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Similarly, when the operands of the operator both contain
|
|
||||||
instance variables, the query optimizer must estimate the
|
|
||||||
size of the resulting join. The function <function>join_proc</> will
|
|
||||||
return another floating-point number which will be multiplied
|
|
||||||
by the cardinalities of the two tables involved to
|
|
||||||
compute the expected result size.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The difference between the function
|
|
||||||
<programlisting>
|
|
||||||
my_procedure_1 (MYBOXES.description, box '((0,0), (1,1))')
|
|
||||||
</programlisting>
|
|
||||||
and the operator
|
|
||||||
<programlisting>
|
|
||||||
MYBOXES.description === box '((0,0), (1,1))'
|
|
||||||
</programlisting>
|
|
||||||
is that <productname>PostgreSQL</productname>
|
|
||||||
attempts to optimize operators and can
|
|
||||||
decide to use an index to restrict the search space when
|
|
||||||
operators are involved. However, there is no attempt to
|
|
||||||
optimize functions, and they are performed by brute force.
|
|
||||||
Moreover, functions can have any number of arguments while
|
|
||||||
operators are restricted to one or two.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPERATOR-3">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
Refer to <xref linkend="xoper"> for further information.
|
The other clauses specify optional operator optimization clauses.
|
||||||
Use <command>DROP OPERATOR</command> to delete
|
Their meaning is detailed in <xref linkend="xoper">.
|
||||||
user-defined operators from a database.
|
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of the operator to be defined. See above for allowable
|
||||||
|
characters. The name may be schema-qualified, for example
|
||||||
|
<literal>CREATE OPERATOR myschema.+ (...)</>. If not, then
|
||||||
|
the operator is created in the current schema. Two operators
|
||||||
|
in the same schema can have the same name if they operate on
|
||||||
|
different data types. This is called
|
||||||
|
<firstterm>overloading</>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">func_name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The function used to implement this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">lefttype</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The type of the left-hand argument of the operator, if any.
|
||||||
|
This option would be omitted for a left-unary operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">righttype</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The type of the right-hand argument of the operator, if any.
|
||||||
|
This option would be omitted for a right-unary operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">com_op</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The commutator of this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">neg_op</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The negator of this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">res_proc</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The restriction selectivity estimator function for this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">join_proc</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The join selectivity estimator function for this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>HASHES</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Indicates this operator can support a hash join.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>MERGES</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Indicates this operator can support a merge join.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">left_sort_op</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If this operator can support a merge join, the less-than
|
||||||
|
operator that sorts the left-hand data type of this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">right_sort_op</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If this operator can support a merge join, the less-than
|
||||||
|
operator that sorts the right-hand data type of this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">less_than_op</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If this operator can support a merge join, the less-than
|
||||||
|
operator that compares the input data types of this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">greater_than_op</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
If this operator can support a merge join, the greater-than
|
||||||
|
operator that compares the input data types of this operator.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To give a schema-qualified operator name in <replaceable
|
To give a schema-qualified operator name in <replaceable
|
||||||
class="parameter">com_op</replaceable> or the other optional
|
class="parameter">com_op</replaceable> or the other optional
|
||||||
arguments, use the <literal>OPERATOR()</> syntax, for example
|
arguments, use the <literal>OPERATOR()</> syntax, for example
|
||||||
<programlisting>
|
<programlisting>
|
||||||
COMMUTATOR = OPERATOR(myschema.===) ,
|
COMMUTATOR = OPERATOR(myschema.===) ,
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEOPERATOR-2">
|
<refsect1>
|
||||||
<title>
|
<title>Diagnostics</title>
|
||||||
Usage
|
|
||||||
</title>
|
<variablelist>
|
||||||
<para>The following command defines a new operator,
|
<varlistentry>
|
||||||
area-equality, for the BOX data type:
|
<term><computeroutput>CREATE OPERATOR</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the operator was successfully created.
|
||||||
</para>
|
</para>
|
||||||
<programlisting>
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Notes</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Refer to <xref linkend="xoper"> for further information.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Use <command>DROP OPERATOR</command> to delete user-defined
|
||||||
|
operators from a database.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Examples</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The following command defines a new operator, area-equality, for
|
||||||
|
the data type <type>box</type>:
|
||||||
|
<programlisting>
|
||||||
CREATE OPERATOR === (
|
CREATE OPERATOR === (
|
||||||
LEFTARG = box,
|
LEFTARG = box,
|
||||||
RIGHTARG = box,
|
RIGHTARG = box,
|
||||||
|
@ -474,29 +305,18 @@ CREATE OPERATOR === (
|
||||||
-- Since sort operators were given, MERGES is implied.
|
-- Since sort operators were given, MERGES is implied.
|
||||||
-- LTCMP and GTCMP are assumed to be < and > respectively
|
-- LTCMP and GTCMP are assumed to be < and > respectively
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEOPERATOR-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEOPERATOR-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE OPERATOR</command>
|
<command>CREATE OPERATOR</command> is a
|
||||||
is a <productname>PostgreSQL</productname> extension.
|
<productname>PostgreSQL</productname> extension. There are no
|
||||||
There is no <command>CREATE OPERATOR</command>
|
provisions for user-defined operators in the SQL standard.
|
||||||
statement in <acronym>SQL92</acronym>.
|
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.38 2002/11/21 23:34:43 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_rule.sgml,v 1.39 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,138 +8,22 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle>
|
<refentrytitle id="sql-createrule-title">CREATE RULE</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE RULE</refname>
|
||||||
CREATE RULE
|
<refpurpose>define a new rewrite rule</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new rewrite rule
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2001-01-05</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable>
|
CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS ON <replaceable class="parameter">event</replaceable>
|
||||||
TO <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
|
TO <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
|
||||||
DO [ INSTEAD ] <replaceable class="parameter">action</replaceable>
|
DO [ INSTEAD ] { NOTHING | <replaceable class="parameter">command</replaceable> | ( <replaceable class="parameter">command</replaceable> ; <replaceable class="parameter">command</replaceable> ... ) }
|
||||||
|
</synopsis>
|
||||||
where <replaceable class="PARAMETER">action</replaceable> can be:
|
|
||||||
|
|
||||||
NOTHING
|
|
||||||
| <replaceable class="parameter">query</replaceable>
|
|
||||||
| ( <replaceable class="parameter">query</replaceable> ; <replaceable class="parameter">query</replaceable> ... )
|
|
||||||
</synopsis>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATERULE-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2001-01-05</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">name</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of a rule to create. This must be distinct from the name
|
|
||||||
of any other rule for the same table.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">event</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Event is one of <literal>SELECT</literal>,
|
|
||||||
<literal>UPDATE</literal>, <literal>DELETE</literal>
|
|
||||||
or <literal>INSERT</literal>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">table</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name (optionally schema-qualified) of the table or view the rule
|
|
||||||
applies to.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">condition</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Any SQL conditional expression (returning <type>boolean</type>).
|
|
||||||
The condition expression may not
|
|
||||||
refer to any tables except <literal>new</literal> and
|
|
||||||
<literal>old</literal>, and may not contain aggregate functions.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">query</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The query or queries making up the
|
|
||||||
<replaceable class="PARAMETER">action</replaceable>
|
|
||||||
can be any SQL <literal>SELECT</literal>, <literal>INSERT</literal>,
|
|
||||||
<literal>UPDATE</literal>, <literal>DELETE</literal>, or
|
|
||||||
<literal>NOTIFY</literal> statement.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Within the <replaceable class="parameter">condition</replaceable>
|
|
||||||
and <replaceable class="PARAMETER">action</replaceable>, the special
|
|
||||||
table names <literal>new</literal> and <literal>old</literal> may be
|
|
||||||
used to refer to values in the referenced table.
|
|
||||||
<literal>new</literal> is valid in ON INSERT and ON UPDATE rules
|
|
||||||
to refer to the new row being inserted or updated.
|
|
||||||
<literal>old</literal> is valid in ON UPDATE and ON DELETE
|
|
||||||
rules to refer to the existing row being updated or deleted.
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATERULE-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
CREATE RULE
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Message returned if the rule is successfully created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATERULE-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE RULE</command> defines a new rule applying to a specified
|
<command>CREATE RULE</command> defines a new rule applying to a specified
|
||||||
|
@ -150,186 +34,206 @@ CREATE RULE
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <productname>PostgreSQL</productname>
|
The <productname>PostgreSQL</productname> rule system allows one to
|
||||||
<firstterm>rule system</firstterm> allows one to define an
|
define an alternate action to be performed on insertions, updates,
|
||||||
alternate action to be performed on inserts, updates, or deletions
|
or deletions in database tables. Roughly speaking, a rule causes
|
||||||
from database tables. Rules are used to
|
additional commands to be executed when a given command on a given
|
||||||
implement table views as well.
|
table is executed. Alternatively, a rule can replace a given
|
||||||
|
command by another, or cause a command not to be executed at all.
|
||||||
|
Rules are used to implement table views as well. It is important
|
||||||
|
to realize that a rule is really a command transformation
|
||||||
|
mechanism, or command macro. The transformation happens before the
|
||||||
|
execution of the commands starts. If you actually want an
|
||||||
|
operation that fires independently for each physical row, you
|
||||||
|
probably want to use a trigger, not a rule. More information about
|
||||||
|
the rules system is in <xref linkend="rules">.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The semantics of a rule is that at the time an individual instance (row)
|
Presently, <literal>ON SELECT</literal> rules must be unconditional
|
||||||
is
|
<literal>INSTEAD</literal> rules and must have actions that consist
|
||||||
accessed, inserted, updated, or deleted, there is an old instance (for
|
of a single <command>SELECT</command> command. Thus, an
|
||||||
selects, updates and deletes) and a new instance (for inserts and
|
<literal>ON SELECT</literal> rule effectively turns the table into
|
||||||
updates). All the rules for the given event type and the given target
|
a view, whose visible contents are the rows returned by the rule's
|
||||||
table are examined successively (in order by name). If the
|
<command>SELECT</command> command rather than whatever had been
|
||||||
<replaceable class="parameter">condition</replaceable> specified in the
|
stored in the table (if anything). It is considered better style
|
||||||
WHERE clause (if any) is true, the
|
to write a <command>CREATE VIEW</command> command than to create a
|
||||||
<replaceable class="parameter">action</replaceable> part of the rule is
|
real table and define an <literal>ON SELECT</literal> rule for it.
|
||||||
executed. The <replaceable class="parameter">action</replaceable> is
|
|
||||||
done instead of the original query if INSTEAD is specified; otherwise
|
|
||||||
it is done after the original query in the case of ON INSERT, or before
|
|
||||||
the original query in the case of ON UPDATE or ON DELETE.
|
|
||||||
Within both the <replaceable class="parameter">condition</replaceable>
|
|
||||||
and <replaceable class="parameter">action</replaceable>, values from
|
|
||||||
fields in the old instance and/or the new instance are substituted for
|
|
||||||
<literal>old.</literal><replaceable class="parameter">attribute-name</replaceable>
|
|
||||||
and <literal>new.</literal><replaceable class="parameter">attribute-name</replaceable>.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <replaceable class="parameter">action</replaceable> part of the
|
You can create the illusion of an updatable view by defining
|
||||||
rule can consist of one or more queries. To write multiple queries,
|
<literal>ON INSERT</literal>, <literal>ON UPDATE</literal>, and
|
||||||
surround them with parentheses. Such queries will be performed in the
|
<literal>ON DELETE</literal> rules (or any subset of those that's
|
||||||
specified order. The <replaceable
|
sufficient for your purposes) to replace update actions on the view
|
||||||
class="parameter">action</replaceable> can also be NOTHING indicating
|
with appropriate updates on other tables.
|
||||||
no action. Thus, a DO INSTEAD NOTHING rule suppresses the original
|
|
||||||
query from executing (when its condition is true); a DO NOTHING rule
|
|
||||||
is useless.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <replaceable class="parameter">action</replaceable> part of the rule
|
There is a catch if you try to use conditional rules for view
|
||||||
executes with the same command and transaction identifier as the user
|
updates: there <emphasis>must</> be an unconditional
|
||||||
command that caused activation.
|
<literal>INSTEAD</literal> rule for each action you wish to allow
|
||||||
|
on the view. If the rule is conditional, or is not
|
||||||
|
<literal>INSTEAD</literal>, then the system will still reject
|
||||||
|
attempts to perform the update action, because it thinks it might
|
||||||
|
end up trying to perform the action on the dummy table of the view
|
||||||
|
in some cases. If you want to handle all the useful cases in
|
||||||
|
conditional rules, you can; just add an unconditional <literal>DO
|
||||||
|
INSTEAD NOTHING</literal> rule to ensure that the system
|
||||||
|
understands it will never be called on to update the dummy table.
|
||||||
|
Then make the conditional rules not <literal>INSTEAD</literal>; in
|
||||||
|
the cases where they are applied, they add to the default
|
||||||
|
<literal>INSTEAD NOTHING</literal> action.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of a rule to create. This must be distinct from the
|
||||||
|
name of any other rule for the same table. Multiple rules on
|
||||||
|
the same table and same event type are applied in alphabetical
|
||||||
|
name order.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">event</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The even is one of <literal>SELECT</literal>,
|
||||||
|
<literal>INSERT</literal>, <literal>UPDATE</literal>, or
|
||||||
|
<literal>DELETE</literal>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">table</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name (optionally schema-qualified) of the table or view the
|
||||||
|
rule applies to.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">condition</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Any SQL conditional expression (returning <type>boolean</type>).
|
||||||
|
The condition expression may not refer to any tables except
|
||||||
|
<literal>NEW</literal> and <literal>OLD</literal>, and may not
|
||||||
|
contain aggregate functions.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">command</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The command or commands that make up the rule action. Valid
|
||||||
|
commands are <literal>SELECT</literal>,
|
||||||
|
<literal>INSERT</literal>, <literal>UPDATE</literal>,
|
||||||
|
<literal>DELETE</literal>, or <literal>NOTIFY</literal>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Within <replaceable class="parameter">condition</replaceable> and
|
||||||
|
<replaceable class="parameter">command</replaceable>, the special
|
||||||
|
table names <literal>NEW</literal> and <literal>OLD</literal> may
|
||||||
|
be used to refer to values in the referenced table.
|
||||||
|
<literal>NEW</literal> is valid in <literal>ON INSERT</literal> and
|
||||||
|
<literal>ON UPDATE</literal> rules to refer to the new row being
|
||||||
|
inserted or updated. <literal>OLD</literal> is valid in
|
||||||
|
<literal>ON UPDATE</literal> and <literal>ON DELETE</literal> rules
|
||||||
|
to refer to the existing row being updated or deleted.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE RULE</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the rule was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Notes</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
You must have the privilege <literal>RULE</literal> on a table to
|
||||||
|
be allowed to define a rule on it.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
It is important to realize that a rule is really a query transformation
|
It is very important to take care to avoid circular rules. For
|
||||||
mechanism, or query macro. The entire query is processed to convert it
|
example, though each of the following two rule definitions are
|
||||||
into a series of queries that include the rule actions. This occurs
|
accepted by <productname>PostgreSQL</productname>, the
|
||||||
before evaluation of the query starts. So, conditional rules are
|
<command>SELECT</command> command would cause
|
||||||
handled by adding the rule condition to the WHERE clause of the action(s)
|
<productname>PostgreSQL</productname> to report an error because
|
||||||
derived from the rule. The above description of a rule as an operation
|
the query cycled too many times:
|
||||||
that executes for each row is thus somewhat misleading. If you actually
|
|
||||||
want an operation that fires independently for each physical row, you
|
|
||||||
probably want to use a trigger not a rule. Rules are most useful for
|
|
||||||
situations that call for transforming entire queries independently of
|
|
||||||
the specific data being handled.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATERULE-3">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2001-11-06</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Rules and Views
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
Presently, ON SELECT rules must be unconditional INSTEAD rules and must
|
|
||||||
have actions that consist of a single SELECT query. Thus, an ON SELECT
|
|
||||||
rule effectively turns the table into a view, whose visible
|
|
||||||
contents are the rows returned by the rule's SELECT query rather than
|
|
||||||
whatever had been stored in the table (if anything). It is considered
|
|
||||||
better style to write a CREATE VIEW command than to create a real table
|
|
||||||
and define an ON SELECT rule for it.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<xref linkend="sql-createview" endterm="sql-createview-title"> creates a dummy table (with no underlying
|
|
||||||
storage) and associates an ON SELECT rule with it. The system will not
|
|
||||||
allow updates to the view, since it knows there is no real table there.
|
|
||||||
You can create the
|
|
||||||
illusion of an updatable view by defining ON INSERT, ON UPDATE, and
|
|
||||||
ON DELETE rules (or any subset of those that's sufficient
|
|
||||||
for your purposes) to replace update actions on the view with
|
|
||||||
appropriate updates on other tables.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
There is a catch if you try to use conditional
|
|
||||||
rules for view updates: there <emphasis>must</> be an unconditional
|
|
||||||
INSTEAD rule for each action you wish to allow on the view. If the
|
|
||||||
rule is conditional, or is not INSTEAD, then the system will still reject
|
|
||||||
attempts to perform the update action, because it thinks it might end up
|
|
||||||
trying to perform the action on the dummy table in some cases.
|
|
||||||
If you want to
|
|
||||||
handle all the useful cases in conditional rules, you can; just add an
|
|
||||||
unconditional DO INSTEAD NOTHING rule to ensure that the system
|
|
||||||
understands it will never be called on to update the dummy table. Then
|
|
||||||
make the conditional rules non-INSTEAD; in the cases where they fire,
|
|
||||||
they add to the default INSTEAD NOTHING action.
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATERULE-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2001-01-05</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
You must have rule definition access to a table in order
|
|
||||||
to define a rule on it. Use <command>GRANT</command>
|
|
||||||
and <command>REVOKE</command> to change permissions.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
It is very important to take care to avoid circular rules.
|
|
||||||
For example, though each
|
|
||||||
of the following two rule definitions are accepted by
|
|
||||||
<productname>PostgreSQL</productname>, the
|
|
||||||
select command will cause <productname>PostgreSQL</productname> to
|
|
||||||
report an error because the query cycled too many times:
|
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE RULE "_RETURN" AS
|
CREATE RULE "_RETURN" AS
|
||||||
ON SELECT TO emp
|
ON SELECT TO t1
|
||||||
DO INSTEAD
|
DO INSTEAD
|
||||||
SELECT * FROM toyemp;
|
SELECT * FROM t2;
|
||||||
|
|
||||||
CREATE RULE "_RETURN" AS
|
CREATE RULE "_RETURN" AS
|
||||||
ON SELECT TO toyemp
|
ON SELECT TO t2
|
||||||
DO INSTEAD
|
DO INSTEAD
|
||||||
SELECT * FROM emp;
|
SELECT * FROM t1;
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
This attempt to select from <literal>EMP</literal> will cause
|
SELECT * FROM t1;
|
||||||
<productname>PostgreSQL</productname> to issue an error
|
|
||||||
because the queries cycled too many times:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
SELECT * FROM emp;
|
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Presently, if a rule contains a NOTIFY query, the NOTIFY will be executed
|
Presently, if a rule action contains a <command>NOTIFY</command>
|
||||||
unconditionally --- that is, the NOTIFY will be issued even if there are
|
command, the <command>NOTIFY</command> command will be executed
|
||||||
not any rows that the rule should apply to. For example, in
|
unconditionally, that is, the <command>NOTIFY</command> will be
|
||||||
<programlisting>
|
issued even if there are not any rows that the rule should apply
|
||||||
|
to. For example, in
|
||||||
|
<programlisting>
|
||||||
CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
|
CREATE RULE notify_me AS ON UPDATE TO mytable DO NOTIFY mytable;
|
||||||
|
|
||||||
UPDATE mytable SET name = 'foo' WHERE id = 42;
|
UPDATE mytable SET name = 'foo' WHERE id = 42;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
one NOTIFY event will be sent during the UPDATE, whether or not there
|
one <command>NOTIFY</command> event will be sent during the
|
||||||
are any rows with id = 42. This is an implementation restriction that
|
<command>UPDATE</command>, whether or not there are any rows with
|
||||||
may be fixed in future releases.
|
<literal>id = 42</literal>. This is an implementation restriction
|
||||||
|
that may be fixed in future releases.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATERULE-4">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATERULE-5">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE RULE</command> is a <productname>PostgreSQL</productname>
|
<command>CREATE RULE</command> is a
|
||||||
language extension.
|
<productname>PostgreSQL</productname> language extension, as is the
|
||||||
There is no <command>CREATE RULE</command> statement in <acronym>SQL92</acronym>.
|
entire rules system.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.4 2003/02/03 15:56:50 momjian Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.5 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,25 +8,51 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle>
|
<refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE SCHEMA</refname>
|
||||||
CREATE SCHEMA
|
<refpurpose>define a new schema</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new schema
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<synopsis>
|
<synopsis>
|
||||||
CREATE SCHEMA <replaceable class="parameter">schemaname</replaceable> [ AUTHORIZATION <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
|
CREATE SCHEMA <replaceable class="parameter">schemaname</replaceable> [ AUTHORIZATION <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
|
||||||
CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable> [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
|
CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable> [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESCHEMA-1">
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE SCHEMA</command> will enter a new schema
|
||||||
|
into the current database.
|
||||||
|
The schema name must be distinct from the name of any existing schema
|
||||||
|
in the current database.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
A schema is essentially a namespace:
|
||||||
|
it contains named objects (tables, data types, functions, and operators)
|
||||||
|
whose names may duplicate those of other objects existing in other
|
||||||
|
schemas. Named objects are accessed either by <quote>qualifying</>
|
||||||
|
their names with the schema name as a prefix, or by setting a search
|
||||||
|
path that includes the desired schema(s). Unqualified objects are
|
||||||
|
created in the current schema (the one at the front of the search path,
|
||||||
|
which can be determined with the function <function>current_schema</function>).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Optionally, <command>CREATE SCHEMA</command> can include subcommands
|
||||||
|
to create objects within the new schema. The subcommands are treated
|
||||||
|
essentially the same as separate commands issued after creating the
|
||||||
|
schema, except that if the <literal>AUTHORIZATION</> clause is used,
|
||||||
|
all the created objects will be owned by that user.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -63,75 +89,34 @@ CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESCHEMA-2">
|
<refsect1>
|
||||||
<title>
|
<title>Diagnostics</title>
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>CREATE SCHEMA</computeroutput></term>
|
||||||
CREATE SCHEMA
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if the command is successful.
|
Message returned if the schema was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>ERROR: namespace "<replaceable class="parameter">schemaname</replaceable>" already exists</computeroutput></term>
|
||||||
ERROR: namespace "<replaceable class="parameter">schemaname</replaceable>" already exists
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
If the schema specified already exists.
|
Message returned if the schema specified already exists.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATESCHEMA-1">
|
<refsect1>
|
||||||
<title>
|
<title>Notes</title>
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<command>CREATE SCHEMA</command> will enter a new schema
|
|
||||||
into the current database.
|
|
||||||
The schema name must be distinct from the name of any existing schema
|
|
||||||
in the current database.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
A schema is essentially a namespace:
|
|
||||||
it contains named objects (tables, data types, functions, and operators)
|
|
||||||
whose names may duplicate those of other objects existing in other
|
|
||||||
schemas. Named objects are accessed either by <quote>qualifying</>
|
|
||||||
their names with the schema name as a prefix, or by setting a search
|
|
||||||
path that includes the desired schema(s). Unqualified objects are
|
|
||||||
created in the current schema (the one at the front of the search path;
|
|
||||||
see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Optionally, <command>CREATE SCHEMA</command> can include subcommands
|
|
||||||
to create objects within the new schema. The subcommands are treated
|
|
||||||
essentially the same as separate commands issued after creating the
|
|
||||||
schema, except that if the <literal>AUTHORIZATION</> clause is used,
|
|
||||||
all the created objects will be owned by that user.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESCHEMA-3">
|
|
||||||
<title>
|
|
||||||
Notes
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To create a schema, the invoking user must have <literal>CREATE</>
|
To create a schema, the invoking user must have <literal>CREATE</>
|
||||||
|
@ -142,85 +127,74 @@ ERROR: namespace "<replaceable class="parameter">schemaname</replaceable>" alre
|
||||||
<para>
|
<para>
|
||||||
Use <command>DROP SCHEMA</command> to remove a schema.
|
Use <command>DROP SCHEMA</command> to remove a schema.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATESCHEMA-2">
|
<refsect1>
|
||||||
<title>
|
<title>Examples</title>
|
||||||
Examples
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
Create a schema:
|
Create a schema:
|
||||||
|
<programlisting>
|
||||||
<programlisting>
|
|
||||||
CREATE SCHEMA myschema;
|
CREATE SCHEMA myschema;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Create a schema for user <literal>joe</> --- the schema will also
|
Create a schema for user <literal>joe</>; the schema will also be
|
||||||
be named <literal>joe</>:
|
named <literal>joe</>:
|
||||||
|
<programlisting>
|
||||||
<programlisting>
|
|
||||||
CREATE SCHEMA AUTHORIZATION joe;
|
CREATE SCHEMA AUTHORIZATION joe;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Create a schema and create a table and view within it:
|
Create a schema and create a table and view within it:
|
||||||
|
<programlisting>
|
||||||
<programlisting>
|
|
||||||
CREATE SCHEMA hollywood
|
CREATE SCHEMA hollywood
|
||||||
CREATE TABLE films (title text, release date, awards text[])
|
CREATE TABLE films (title text, release date, awards text[])
|
||||||
CREATE VIEW winners AS
|
CREATE VIEW winners AS
|
||||||
SELECT title, release FROM films WHERE awards IS NOT NULL;
|
SELECT title, release FROM films WHERE awards IS NOT NULL;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
Notice that the individual subcommands do not end with semicolons.
|
Notice that the individual subcommands do not end with semicolons.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The following is an equivalent way of accomplishing the same result:
|
The following is an equivalent way of accomplishing the same result:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE SCHEMA hollywood;
|
CREATE SCHEMA hollywood;
|
||||||
CREATE TABLE hollywood.films (title text, release date, awards text[]);
|
CREATE TABLE hollywood.films (title text, release date, awards text[]);
|
||||||
CREATE VIEW hollywood.winners AS
|
CREATE VIEW hollywood.winners AS
|
||||||
SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
|
SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATESCHEMA-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESCHEMA-4">
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
SQL92 allows a <literal>DEFAULT CHARACTER SET</> clause in
|
The SQL standard allows a <literal>DEFAULT CHARACTER SET</> clause
|
||||||
<command>CREATE SCHEMA</command>, as well as more subcommand types
|
in <command>CREATE SCHEMA</command>, as well as more subcommand
|
||||||
than are presently accepted by <productname>PostgreSQL</productname>.
|
types than are presently accepted by
|
||||||
|
<productname>PostgreSQL</productname>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
SQL92 specifies that the subcommands in <command>CREATE SCHEMA</command>
|
The SQL standard specifies that the subcommands in <command>CREATE
|
||||||
may appear in any order. The present
|
SCHEMA</command> may appear in any order. The present
|
||||||
<productname>PostgreSQL</productname> implementation does not handle all
|
<productname>PostgreSQL</productname> implementation does not
|
||||||
cases of forward references in subcommands; it may sometimes be necessary
|
handle all cases of forward references in subcommands; it may
|
||||||
to reorder the subcommands to avoid forward references.
|
sometimes be necessary to reorder the subcommands to avoid forward
|
||||||
|
references.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In SQL92, the owner of a schema always owns all objects within it.
|
According to the SQL standard, the owner of a schema always owns
|
||||||
<productname>PostgreSQL</productname> allows schemas to contain objects
|
all objects within it. <productname>PostgreSQL</productname>
|
||||||
owned by users other than the schema owner. This can happen only if the
|
allows schemas to contain objects owned by users other than the
|
||||||
schema owner grants <literal>CREATE</> rights on his schema to someone
|
schema owner. This can happen only if the schema owner grants the
|
||||||
else.
|
<literal>CREATE</> privilege on his schema to someone else.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.32 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.33 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,248 +8,36 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createsequence-title">CREATE SEQUENCE</refentrytitle>
|
<refentrytitle id="sql-createsequence-title">CREATE SEQUENCE</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE SEQUENCE</refname>
|
||||||
CREATE SEQUENCE
|
<refpurpose>define a new sequence generator</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new sequence generator
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>1999-07-20</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE [ TEMPORARY | TEMP ] SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
|
CREATE [ TEMPORARY | TEMP ] SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
|
||||||
[ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
|
[ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
|
||||||
[ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
|
[ START [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESEQUENCE-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term>TEMPORARY or TEMP</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If specified, the sequence object is created only for this session,
|
|
||||||
and is automatically dropped on session exit.
|
|
||||||
Existing permanent sequences with the same name are not visible
|
|
||||||
(in this session) while the temporary sequence exists, unless
|
|
||||||
they are referenced with schema-qualified names.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">seqname</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name (optionally schema-qualified) of a sequence to be created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">increment</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The
|
|
||||||
<option>INCREMENT BY <replaceable class="parameter">increment</replaceable></option>
|
|
||||||
clause is optional. A positive value will make an
|
|
||||||
ascending sequence, a negative one a descending sequence.
|
|
||||||
The default value is one (1).
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">minvalue</replaceable></term>
|
|
||||||
<term>NO MINVALUE</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional clause <option>MINVALUE
|
|
||||||
<replaceable class="parameter">minvalue</replaceable></option>
|
|
||||||
determines the minimum value
|
|
||||||
a sequence can generate. If this clause is not supplied or <option>NO MINVALUE</option>
|
|
||||||
is specified, then defaults will be used. The defaults are 1 and -2^63-1 for
|
|
||||||
ascending and descending sequences, respectively.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">maxvalue</replaceable></term>
|
|
||||||
<term>NO MAXVALUE</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional clause <option>MAXVALUE
|
|
||||||
<replaceable class="parameter">maxvalue</replaceable></option>
|
|
||||||
determines the maximum
|
|
||||||
value for the sequence. If this clause is not supplied or
|
|
||||||
<option>NO MAXVALUE</option> is specified, then default values will be used.
|
|
||||||
The defaults are 2^63-1 and -1 for ascending and descending sequences, respectively.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">start</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional <option>START WITH
|
|
||||||
<replaceable class="parameter">start</replaceable>
|
|
||||||
clause</option> enables the sequence to begin anywhere.
|
|
||||||
The default starting value is
|
|
||||||
<replaceable class="parameter">minvalue</replaceable>
|
|
||||||
for ascending sequences and
|
|
||||||
<replaceable class="parameter">maxvalue</replaceable>
|
|
||||||
for descending ones.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">cache</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The <option>CACHE <replaceable class="parameter">cache</replaceable></option> option
|
|
||||||
enables sequence numbers to be preallocated
|
|
||||||
and stored in memory for faster access. The minimum
|
|
||||||
value is 1 (only one value can be generated at a time, i.e., no cache)
|
|
||||||
and this is also the default.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term>CYCLE</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The optional <option>CYCLE</option> keyword may be used to enable
|
|
||||||
the sequence to wrap around when the
|
|
||||||
<replaceable class="parameter">maxvalue</replaceable> or
|
|
||||||
<replaceable class="parameter">minvalue</replaceable> has been
|
|
||||||
reached by
|
|
||||||
an ascending or descending sequence respectively. If the limit is
|
|
||||||
reached, the next number generated will be the
|
|
||||||
<replaceable class="parameter">minvalue</replaceable> or
|
|
||||||
<replaceable class="parameter">maxvalue</replaceable>,
|
|
||||||
respectively.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term>NO CYCLE</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If the optional <option>NO CYCLE</option> keyword is specified, any
|
|
||||||
calls to <function>nextval</function> after the sequence has reached
|
|
||||||
its maximum value will return an error. If neither
|
|
||||||
<option>CYCLE</option> or <option>NO CYCLE</option> are specified,
|
|
||||||
<option>NO CYCLE</option> is the default.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESEQUENCE-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
CREATE SEQUENCE
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Message returned if the command is successful.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
ERROR: Relation '<replaceable class="parameter">seqname</replaceable>' already exists
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If the sequence specified already exists.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If the specified starting value is out of range.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If the specified starting value is out of range.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
If the minimum and maximum values are inconsistent.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATESEQUENCE-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE SEQUENCE</command> will enter a new sequence number generator
|
<command>CREATE SEQUENCE</command> creates a new sequence number
|
||||||
into the current database. This involves creating and initializing a
|
generator. This involves creating and initializing a new special
|
||||||
new single-row
|
single-row table with the name <replaceable
|
||||||
table with the name <replaceable class="parameter">seqname</replaceable>.
|
class="parameter">seqname</replaceable>. The generator will be
|
||||||
The generator will be owned by the user issuing the command.
|
owned by the user issuing the command.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If a schema name is given then the sequence is created in the
|
If a schema name is given then the sequence is created in the
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
specified schema. Otherwise it is created in the current schema.
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
Temporary sequences exist in a special schema, so a schema name may not be
|
||||||
TEMP sequences exist in a special schema, so a schema name may not be
|
given when creating a temporary sequence.
|
||||||
given when creating a TEMP sequence.
|
|
||||||
The sequence name must be distinct from the name of any other sequence,
|
The sequence name must be distinct from the name of any other sequence,
|
||||||
table, index, or view in the same schema.
|
table, index, or view in the same schema.
|
||||||
</para>
|
</para>
|
||||||
|
@ -257,7 +45,7 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
|
||||||
<para>
|
<para>
|
||||||
After a sequence is created, you use the functions
|
After a sequence is created, you use the functions
|
||||||
<function>nextval</function>,
|
<function>nextval</function>,
|
||||||
<function>currval</function> and
|
<function>currval</function>, and
|
||||||
<function>setval</function>
|
<function>setval</function>
|
||||||
to operate on the sequence. These functions are documented in
|
to operate on the sequence. These functions are documented in
|
||||||
<xref linkend="functions-sequence">.
|
<xref linkend="functions-sequence">.
|
||||||
|
@ -266,132 +54,293 @@ ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceabl
|
||||||
<para>
|
<para>
|
||||||
Although you cannot update a sequence directly, you can use a query like
|
Although you cannot update a sequence directly, you can use a query like
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
SELECT * FROM <replaceable>seqname</replaceable>;
|
SELECT * FROM <replaceable>seqname</replaceable>;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
to examine the parameters and current state of a sequence. In particular,
|
to examine the parameters and current state of a sequence. In particular,
|
||||||
the <literal>last_value</> field of the sequence shows the last value
|
the <literal>last_value</> field of the sequence shows the last value
|
||||||
allocated by any backend process. (Of course, this value may be obsolete
|
allocated by any session. (Of course, this value may be obsolete
|
||||||
by the time it's printed, if other processes are actively doing
|
by the time it's printed, if other sessions are actively doing
|
||||||
<function>nextval</> calls.)
|
<function>nextval</> calls.)
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<caution>
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term>
|
||||||
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Unexpected results may be obtained if a <replaceable class="parameter">cache</replaceable> setting greater than one
|
If specified, the sequence object is created only for this
|
||||||
is used for a sequence object that will be used concurrently by multiple
|
session, and is automatically dropped on session exit. Existing
|
||||||
backends. Each backend will allocate and cache successive sequence values
|
permanent sequences with the same name are not visible (in this
|
||||||
during one access to the sequence object and increase the sequence
|
session) while the temporary sequence exists, unless they are
|
||||||
object's <literal>last_value</> accordingly. Then, the next <replaceable class="parameter">cache</replaceable>-1 uses of <function>nextval</>
|
referenced with schema-qualified names.
|
||||||
within that backend simply return the preallocated values without touching
|
|
||||||
the shared object. So, any numbers allocated but not used within a session
|
|
||||||
will be lost when that session ends. Furthermore, although multiple backends are guaranteed to
|
|
||||||
allocate distinct sequence values, the values may be generated out of
|
|
||||||
sequence when all the backends are considered. (For example, with a <replaceable class="parameter">cache</replaceable>
|
|
||||||
setting of 10, backend A might reserve values 1..10 and return <function>nextval</function>=1,
|
|
||||||
then
|
|
||||||
backend B might reserve values 11..20 and return <function>nextval</function>=11 before backend
|
|
||||||
A has generated <literal>nextval</literal>=2.) Thus, with a <replaceable class="parameter">cache</replaceable> setting of one it is safe
|
|
||||||
to assume that <function>nextval</> values are generated sequentially; with a <replaceable class="parameter">cache</replaceable>
|
|
||||||
setting greater than one you should only assume that the <function>nextval</> values
|
|
||||||
are all distinct, not that they are generated purely sequentially.
|
|
||||||
Also, <literal>last_value</> will reflect the latest value reserved by any backend,
|
|
||||||
whether or not it has yet been returned by <function>nextval</>.
|
|
||||||
Another consideration is that a <function>setval</> executed on such a sequence
|
|
||||||
will not be noticed by other backends until they have used up any
|
|
||||||
preallocated values they have cached.
|
|
||||||
</para>
|
</para>
|
||||||
</caution>
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESEQUENCE-3">
|
<varlistentry>
|
||||||
<refsect2info>
|
<term><replaceable class="parameter">seqname</replaceable></term>
|
||||||
<date>1998-09-11</date>
|
<listitem>
|
||||||
</refsect2info>
|
<para>
|
||||||
<title>
|
The name (optionally schema-qualified) of the sequence to be created.
|
||||||
Notes
|
</para>
|
||||||
</title>
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">increment</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The optional clause <literal>INCREMENT BY <replaceable
|
||||||
|
class="parameter">increment</replaceable></literal> specified,
|
||||||
|
which value is added to the current sequence value to create a
|
||||||
|
new value. A positive value will make an ascending sequence, a
|
||||||
|
negative one a descending sequence. The default value is 1.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">minvalue</replaceable></term>
|
||||||
|
<term><literal>NO MINVALUE</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The optional clause <literal>MINVALUE <replaceable
|
||||||
|
class="parameter">minvalue</replaceable></literal> determines
|
||||||
|
the minimum value a sequence can generate. If this clause is not
|
||||||
|
supplied or <option>NO MINVALUE</option> is specified, then
|
||||||
|
defaults will be used. The defaults are 1 and
|
||||||
|
-2<superscript>63</>-1 for ascending and descending sequences,
|
||||||
|
respectively.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">maxvalue</replaceable></term>
|
||||||
|
<term><literal>NO MAXVALUE</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The optional clause <literal>MAXVALUE <replaceable
|
||||||
|
class="parameter">maxvalue</replaceable></literal> determines
|
||||||
|
the maximum value for the sequence. If this clause is not
|
||||||
|
supplied or <option>NO MAXVALUE</option> is specified, then
|
||||||
|
default values will be used. The defaults are
|
||||||
|
2<superscript>63</>-1 and -1 for ascending and descending
|
||||||
|
sequences, respectively.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">start</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The optional clause <literal>START WITH <replaceable
|
||||||
|
class="parameter">start</replaceable> </literal> allows the
|
||||||
|
sequence to begin anywhere. The default starting value is
|
||||||
|
<replaceable class="parameter">minvalue</replaceable> for
|
||||||
|
ascending sequences and <replaceable
|
||||||
|
class="parameter">maxvalue</replaceable> for descending ones.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">cache</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The optional clause <literal>CACHE <replaceable
|
||||||
|
class="parameter">cache</replaceable></literal> specifies how
|
||||||
|
many sequence numbers are to be preallocated and stored in
|
||||||
|
memory for faster access. The minimum value is 1 (only one value
|
||||||
|
can be generated at a time, i.e., no cache), and this is also the
|
||||||
|
default.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><literal>CYCLE</literal></term>
|
||||||
|
<term><literal>NO CYCLE</literal></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The <literal>CYCLE</literal> option allows the sequence to wrap
|
||||||
|
around when the <replaceable
|
||||||
|
class="parameter">maxvalue</replaceable> or <replaceable
|
||||||
|
class="parameter">minvalue</replaceable> has been reached by an
|
||||||
|
ascending or descending sequence respectively. If the limit is
|
||||||
|
reached, the next number generated will be the <replaceable
|
||||||
|
class="parameter">minvalue</replaceable> or <replaceable
|
||||||
|
class="parameter">maxvalue</replaceable>, respectively.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If <literal>NO CYCLE</literal> is specified, any calls to
|
||||||
|
<function>nextval</function> after the sequence has reached its
|
||||||
|
maximum value will return an error. If neither
|
||||||
|
<literal>CYCLE</literal> or <literal>NO CYCLE</literal> are
|
||||||
|
specified, <literal>NO CYCLE</literal> is the default.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE SEQUENCE</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the sequence was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>ERROR: Relation '<replaceable class="parameter">seqname</replaceable>' already exists</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
A sequence, table, view, or index of the specified name already exists.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
|
||||||
|
<term><computeroutput>ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The specified starting value is out of range.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The minimum and maximum values are inconsistent.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Notes</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Use <command>DROP SEQUENCE</command> to remove a sequence.
|
Use <command>DROP SEQUENCE</command> to remove a sequence.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Sequences are based on <type>bigint</> arithmetic, so the range cannot
|
Sequences are based on <type>bigint</> arithmetic, so the range
|
||||||
exceed the range of an eight-byte integer
|
cannot exceed the range of an eight-byte integer
|
||||||
(-9223372036854775808 to 9223372036854775807). On some older platforms,
|
(-9223372036854775808 to 9223372036854775807). On some older
|
||||||
there may be no compiler support for eight-byte integers, in which case
|
platforms, there may be no compiler support for eight-byte
|
||||||
sequences use regular <type>integer</> arithmetic (range
|
integers, in which case sequences use regular <type>integer</>
|
||||||
-2147483648 to +2147483647).
|
arithmetic (range -2147483648 to +2147483647).
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
When <replaceable class="parameter">cache</replaceable> is greater than
|
Unexpected results may be obtained if a <replaceable
|
||||||
one, each backend uses its own cache to store preallocated numbers.
|
class="parameter">cache</replaceable> setting greater than one is
|
||||||
Numbers that are cached but not used in the current session will be
|
used for a sequence object that will be used concurrently by
|
||||||
lost, resulting in <quote>holes</quote> in the sequence.
|
multiple sessions. Each session will allocate and cache successive
|
||||||
|
sequence values during one access to the sequence object and
|
||||||
|
increase the sequence object's <literal>last_value</> accordingly.
|
||||||
|
Then, the next <replaceable class="parameter">cache</replaceable>-1
|
||||||
|
uses of <function>nextval</> within that session simply return the
|
||||||
|
preallocated values without touching the sequence object. So, any
|
||||||
|
numbers allocated but not used within a session will be lost when
|
||||||
|
that session ends, resulting in <quote>holes</quote> in the
|
||||||
|
sequence.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Furthermore, although multiple sessions are guaranteed to allocate
|
||||||
|
distinct sequence values, the values may be generated out of
|
||||||
|
sequence when all the sessions are considered. FFor example, with
|
||||||
|
a <replaceable class="parameter">cache</replaceable> setting of 10,
|
||||||
|
session A might reserve values 1..10 and return
|
||||||
|
<function>nextval</function>=1, then session B might reserve values
|
||||||
|
11..20 and return <function>nextval</function>=11 before session A
|
||||||
|
has generated <literal>nextval</literal>=2. Thus, with a
|
||||||
|
<replaceable class="parameter">cache</replaceable> setting of one
|
||||||
|
it is safe to assume that <function>nextval</> values are generated
|
||||||
|
sequentially; with a <replaceable
|
||||||
|
class="parameter">cache</replaceable> setting greater than one you
|
||||||
|
should only assume that the <function>nextval</> values are all
|
||||||
|
distinct, not that they are generated purely sequentially. Also,
|
||||||
|
<literal>last_value</> will reflect the latest value reserved by
|
||||||
|
any session, whether or not it has yet been returned by
|
||||||
|
<function>nextval</>.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Another consideration is that a <function>setval</> executed on
|
||||||
|
such a sequence will not be noticed by other sessions until they
|
||||||
|
have used up any preallocated values they have cached.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATESEQUENCE-2">
|
<refsect1>
|
||||||
<title>
|
<title>Examples</title>
|
||||||
Usage
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
Create an ascending sequence called <literal>serial</literal>, starting at 101:
|
Create an ascending sequence called <literal>serial</literal>, starting at 101:
|
||||||
</para>
|
<programlisting>
|
||||||
<programlisting>
|
|
||||||
CREATE SEQUENCE serial START 101;
|
CREATE SEQUENCE serial START 101;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Select the next number from this sequence:
|
Select the next number from this sequence:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
SELECT nextval('serial');
|
SELECT nextval('serial');
|
||||||
|
|
||||||
nextval
|
nextval
|
||||||
-------
|
---------
|
||||||
114
|
114
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Use this sequence in an INSERT:
|
|
||||||
<programlisting>
|
|
||||||
INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Update the sequence value after a COPY FROM:
|
Use this sequence in an <command>INSERT</command> command:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
|
INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Update the sequence value after a <command>COPY FROM</command>:
|
||||||
|
<programlisting>
|
||||||
BEGIN;
|
BEGIN;
|
||||||
COPY distributors FROM 'input_file';
|
COPY distributors FROM 'input_file';
|
||||||
SELECT setval('serial', max(id)) FROM distributors;
|
SELECT setval('serial', max(id)) FROM distributors;
|
||||||
END;
|
END;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATESEQUENCE-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATESEQUENCE-4">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-11</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE SEQUENCE</command> is a <productname>PostgreSQL</productname>
|
<command>CREATE SEQUENCE</command> is a
|
||||||
language extension.
|
<productname>PostgreSQL</productname> language extension. There is
|
||||||
There is no <command>CREATE SEQUENCE</command> statement
|
no <command>CREATE SEQUENCE</command> statement in the SQL
|
||||||
in <acronym>SQL92</acronym>.
|
standard.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.66 2003/04/14 18:08:58 tgl Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table.sgml,v 1.67 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -29,7 +29,7 @@ where <replaceable class="PARAMETER">column_constraint</replaceable> is:
|
||||||
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
|
[ CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> ]
|
||||||
{ NOT NULL | NULL | UNIQUE | PRIMARY KEY |
|
{ NOT NULL | NULL | UNIQUE | PRIMARY KEY |
|
||||||
CHECK (<replaceable class="PARAMETER">expression</replaceable>) |
|
CHECK (<replaceable class="PARAMETER">expression</replaceable>) |
|
||||||
REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL ]
|
REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ]
|
||||||
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
|
[ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
|
||||||
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
|
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
|
||||||
|
|
||||||
|
@ -40,7 +40,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
PRIMARY KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) |
|
PRIMARY KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) |
|
||||||
CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) |
|
CHECK ( <replaceable class="PARAMETER">expression</replaceable> ) |
|
||||||
FOREIGN KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> [, ... ] ) ]
|
FOREIGN KEY ( <replaceable class="PARAMETER">column_name</replaceable> [, ... ] ) REFERENCES <replaceable class="PARAMETER">reftable</replaceable> [ ( <replaceable class="PARAMETER">refcolumn</replaceable> [, ... ] ) ]
|
||||||
[ MATCH FULL | MATCH PARTIAL ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
|
[ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE <replaceable class="parameter">action</replaceable> ] [ ON UPDATE <replaceable class="parameter">action</replaceable> ] }
|
||||||
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
|
[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
|
||||||
|
@ -58,17 +58,16 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<para>
|
<para>
|
||||||
If a schema name is given (for example, <literal>CREATE TABLE
|
If a schema name is given (for example, <literal>CREATE TABLE
|
||||||
myschema.mytable ...</>) then the table is created in the
|
myschema.mytable ...</>) then the table is created in the
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
specified schema. Otherwise it is created in the current schema.
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
Temporary tables exist in a special schema, so a schema name may not be
|
||||||
TEMP tables exist in a special schema, so a schema name may not be
|
given when creating a temporary table.
|
||||||
given when creating a TEMP table.
|
|
||||||
The table name must be distinct from the name of any other table,
|
The table name must be distinct from the name of any other table,
|
||||||
sequence, index, or view in the same schema.
|
sequence, index, or view in the same schema.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE TABLE</command> also automatically creates a data
|
<command>CREATE TABLE</command> also automatically creates a data
|
||||||
type that represents the tuple type (structure type) corresponding
|
type that represents the composite type corresponding
|
||||||
to one row of the table. Therefore, tables cannot have the same
|
to one row of the table. Therefore, tables cannot have the same
|
||||||
name as any existing data type in the same schema.
|
name as any existing data type in the same schema.
|
||||||
</para>
|
</para>
|
||||||
|
@ -81,9 +80,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<para>
|
<para>
|
||||||
The optional constraint clauses specify constraints (or tests) that
|
The optional constraint clauses specify constraints (or tests) that
|
||||||
new or updated rows must satisfy for an insert or update operation
|
new or updated rows must satisfy for an insert or update operation
|
||||||
to succeed. A constraint is a named rule: an SQL object which
|
to succeed. A constraint is an SQL object that helps define the
|
||||||
helps define valid sets of values by putting limits on the results
|
set of valid values in the table in various ways.
|
||||||
of insert, update, or delete operations performed on a table.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -158,7 +156,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<para>
|
<para>
|
||||||
The <literal>DEFAULT</> clause assigns a default data value for
|
The <literal>DEFAULT</> clause assigns a default data value for
|
||||||
the column whose column definition it appears within. The value
|
the column whose column definition it appears within. The value
|
||||||
is any variable-free expression (subselects and cross-references
|
is any variable-free expression (subqueries and cross-references
|
||||||
to other columns in the current table are not allowed). The
|
to other columns in the current table are not allowed). The
|
||||||
data type of the default expression must match the data type of the
|
data type of the default expression must match the data type of the
|
||||||
column.
|
column.
|
||||||
|
@ -167,7 +165,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<para>
|
<para>
|
||||||
The default expression will be used in any insert operation that
|
The default expression will be used in any insert operation that
|
||||||
does not specify a value for the column. If there is no default
|
does not specify a value for the column. If there is no default
|
||||||
for a column, then the default is NULL.
|
for a column, then the default is null.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -212,7 +210,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><literal>WITH OIDS</> or <literal>WITHOUT OIDS</></term>
|
<term><literal>WITH OIDS</></term>
|
||||||
|
<term><literal>WITHOUT OIDS</></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This optional clause specifies whether rows of the new table
|
This optional clause specifies whether rows of the new table
|
||||||
|
@ -250,7 +249,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<term><literal>NOT NULL</></term>
|
<term><literal>NOT NULL</></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The column is not allowed to contain NULL values.
|
The column is not allowed to contain null values.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -259,7 +258,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<term><literal>NULL</></term>
|
<term><literal>NULL</></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The column is allowed to contain NULL values. This is the default.
|
The column is allowed to contain null values. This is the default.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -276,7 +275,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <literal>UNIQUE</literal> constraint specifies a rule that a
|
The <literal>UNIQUE</literal> constraint specifies that a
|
||||||
group of one or more distinct columns of a table may contain
|
group of one or more distinct columns of a table may contain
|
||||||
only unique values. The behavior of the unique table constraint
|
only unique values. The behavior of the unique table constraint
|
||||||
is the same as that for column constraints, with the additional
|
is the same as that for column constraints, with the additional
|
||||||
|
@ -284,7 +283,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
For the purpose of a unique constraint, NULL values are not
|
For the purpose of a unique constraint, null values are not
|
||||||
considered equal.
|
considered equal.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -303,11 +302,11 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The primary key constraint specifies that a column or columns of a table
|
The primary key constraint specifies that a column or columns of a table
|
||||||
may contain only unique (non-duplicate), non-NULL values.
|
may contain only unique (non-duplicate), nonnull values.
|
||||||
Technically, <literal>PRIMARY KEY</literal> is merely a
|
Technically, <literal>PRIMARY KEY</literal> is merely a
|
||||||
combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but
|
combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but
|
||||||
identifying a set of columns as primary key also provides
|
identifying a set of columns as primary key also provides
|
||||||
meta-data about the design of the schema, as a primary key
|
metadata about the design of the schema, as a primary key
|
||||||
implies that other tables
|
implies that other tables
|
||||||
may rely on this set of columns as a unique identifier for rows.
|
may rely on this set of columns as a unique identifier for rows.
|
||||||
</para>
|
</para>
|
||||||
|
@ -329,21 +328,19 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term>
|
<term><literal>CHECK (<replaceable class="PARAMETER">expression</replaceable>)</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<literal>CHECK</> clauses specify integrity constraints or tests
|
The <literal>CHECK</> clause specifies an expression producing a
|
||||||
which new or updated rows must satisfy for an insert or update
|
Boolean result which new or updated rows must satisfy for an
|
||||||
operation to succeed. Each constraint must be an expression
|
insert or update operation to succeed. A check constraint
|
||||||
producing a Boolean result. A condition appearing within a
|
specified as a column constraint should reference that column's
|
||||||
column definition should reference that column's value only,
|
value only, while an expression appearing in a table constraint
|
||||||
while a condition appearing as a table constraint may reference
|
may reference multiple columns.
|
||||||
multiple columns.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Currently, <literal>CHECK</literal> expressions cannot contain
|
Currently, <literal>CHECK</literal> expressions cannot contain
|
||||||
subselects nor refer to variables other than columns of the
|
subqueries nor refer to variables other than columns of the
|
||||||
current row.
|
current row.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
@ -360,7 +357,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <literal>REFERENCES</literal> column constraint specifies
|
Theses clauses specify a foreign key constraint, which specifies
|
||||||
that a group of one or more columns of the new table must only
|
that a group of one or more columns of the new table must only
|
||||||
contain values which match against values in the referenced
|
contain values which match against values in the referenced
|
||||||
column(s) <replaceable class="parameter">refcolumn</replaceable>
|
column(s) <replaceable class="parameter">refcolumn</replaceable>
|
||||||
|
@ -374,23 +371,23 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
A value added to these columns is matched against the values of
|
A value inserted into these columns is matched against the
|
||||||
the referenced table and referenced columns using the given
|
values of the referenced table and referenced columns using the
|
||||||
match type. There are three match types: <literal>MATCH
|
given match type. There are three match types: <literal>MATCH
|
||||||
FULL</>, <literal>MATCH PARTIAL</>, and a default match type if
|
FULL</>, <literal>MATCH PARTIAL</>, and <literal>MATCH
|
||||||
none is specified. <literal>MATCH FULL</> will not allow one
|
SIMPLE</literal>, which is also the default. <literal>MATCH
|
||||||
column of a multicolumn foreign key to be NULL unless all
|
FULL</> will not allow one column of a multicolumn foreign key
|
||||||
foreign key columns are NULL. The default match type allows some
|
to be null unless all foreign key columns are null.
|
||||||
foreign key columns to be NULL while other parts of the foreign
|
<literal>MATCH SIMPLE</literal> allows some foreign key columns
|
||||||
key are not NULL. <literal>MATCH PARTIAL</> is not yet
|
to be null while other parts of the foreign key are not
|
||||||
implemented.
|
null. <literal>MATCH PARTIAL</> is not yet implemented.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In addition, when the data in the referenced columns is changed,
|
In addition, when the data in the referenced columns is changed,
|
||||||
certain actions are performed on the data in this table's
|
certain actions are performed on the data in this table's
|
||||||
columns. The <literal>ON DELETE</literal> clause specifies the
|
columns. The <literal>ON DELETE</literal> clause specifies the
|
||||||
action to do when a referenced row in the referenced table is
|
action to perform when a referenced row in the referenced table is
|
||||||
being deleted. Likewise, the <literal>ON UPDATE</literal>
|
being deleted. Likewise, the <literal>ON UPDATE</literal>
|
||||||
clause specifies the action to perform when a referenced column
|
clause specifies the action to perform when a referenced column
|
||||||
in the referenced table is being updated to a new value. If the
|
in the referenced table is being updated to a new value. If the
|
||||||
|
@ -434,7 +431,7 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<term><literal>SET NULL</literal></term>
|
<term><literal>SET NULL</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Set the referencing column values to NULL.
|
Set the referencing column values to null.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -449,19 +446,20 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If primary key column is updated frequently, it may be wise to
|
If primary key column is updated frequently, it may be wise to
|
||||||
add an index to the <literal>REFERENCES</literal> column so that
|
add an index to the foreign key column so that <literal>NO
|
||||||
<literal>NO ACTION</literal> and <literal>CASCADE</literal>
|
ACTION</literal> and <literal>CASCADE</literal> actions
|
||||||
actions associated with the <literal>REFERENCES</literal>
|
associated with the foreign key column can be more efficiently
|
||||||
column can be more efficiently performed.
|
performed.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><literal>DEFERRABLE</literal> or <literal>NOT DEFERRABLE</literal></term>
|
<term><literal>DEFERRABLE</literal></term>
|
||||||
|
<term><literal>NOT DEFERRABLE</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This controls whether the constraint can be deferred. A
|
This controls whether the constraint can be deferred. A
|
||||||
|
@ -477,7 +475,8 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><literal>INITIALLY IMMEDIATE</literal> or <literal>INITIALLY DEFERRED</literal></term>
|
<term><literal>INITIALLY IMMEDIATE</literal></term>
|
||||||
|
<term><literal>INITIALLY DEFERRED</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
If a constraint is deferrable, this clause specifies the default
|
If a constraint is deferrable, this clause specifies the default
|
||||||
|
@ -541,45 +540,16 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
<refsect1 id="SQL-CREATETABLE-diagnostics">
|
<refsect1 id="SQL-CREATETABLE-diagnostics">
|
||||||
<title>Diagnostics</title>
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
<msgset>
|
<variablelist>
|
||||||
<msgentry>
|
<varlistentry>
|
||||||
<msg>
|
<term><computeroutput>CREATE TABLE</computeroutput></term>
|
||||||
<msgmain>
|
<listitem>
|
||||||
<msgtext>
|
|
||||||
<simpara><computeroutput>CREATE TABLE</computeroutput></simpara>
|
|
||||||
</msgtext>
|
|
||||||
</msgmain>
|
|
||||||
</msg>
|
|
||||||
|
|
||||||
<msgexplan>
|
|
||||||
<para>
|
<para>
|
||||||
Message returned if table is successfully created.
|
Message returned if the table was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</msgexplan>
|
</listitem>
|
||||||
</msgentry>
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
<msgentry>
|
|
||||||
<msg>
|
|
||||||
<msgmain>
|
|
||||||
<msgtext>
|
|
||||||
<simpara><computeroutput>ERROR</computeroutput></simpara>
|
|
||||||
</msgtext>
|
|
||||||
</msgmain>
|
|
||||||
</msg>
|
|
||||||
|
|
||||||
<msgexplan>
|
|
||||||
<para>
|
|
||||||
Message returned if table creation failed. This is usually
|
|
||||||
accompanied by some descriptive text, such as:
|
|
||||||
<computeroutput>ERROR: Relation '<replaceable
|
|
||||||
class="parameter">table</replaceable>' already
|
|
||||||
exists</computeroutput>, which occurs at run time if the table
|
|
||||||
specified already exists in the database.
|
|
||||||
</para>
|
|
||||||
</msgexplan>
|
|
||||||
</msgentry>
|
|
||||||
</msgset>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
||||||
|
@ -622,17 +592,6 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The SQL92 standard says that <literal>CHECK</> column constraints
|
|
||||||
may only refer to the column they apply to; only
|
|
||||||
<literal>CHECK</> table constraints may refer to multiple
|
|
||||||
columns. <productname>PostgreSQL</productname> does not enforce
|
|
||||||
this restriction; it treats column and table check constraints
|
|
||||||
alike.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Unique constraints and primary keys are not inherited in the
|
Unique constraints and primary keys are not inherited in the
|
||||||
|
@ -653,19 +612,19 @@ and <replaceable class="PARAMETER">table_constraint</replaceable> is:
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE films (
|
CREATE TABLE films (
|
||||||
code CHARACTER(5) CONSTRAINT firstkey PRIMARY KEY,
|
code char(5) CONSTRAINT firstkey PRIMARY KEY,
|
||||||
title CHARACTER VARYING(40) NOT NULL,
|
title varchar(40) NOT NULL,
|
||||||
did DECIMAL(3) NOT NULL,
|
did integer NOT NULL,
|
||||||
date_prod DATE,
|
date_prod date,
|
||||||
kind CHAR(10),
|
kind varchar(10),
|
||||||
len INTERVAL HOUR TO MINUTE
|
len interval hour to minute
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3) PRIMARY KEY DEFAULT NEXTVAL('serial'),
|
did integer PRIMARY KEY DEFAULT nextval('serial'),
|
||||||
name VARCHAR(40) NOT NULL CHECK (name <> '')
|
name varchar(40) NOT NULL CHECK (name <> '')
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
@ -675,23 +634,24 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE array (
|
CREATE TABLE array (
|
||||||
vector INT[][]
|
vector int[][]
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Define a unique table constraint for the table films. Unique table
|
Define a unique table constraint for the table
|
||||||
constraints can be defined on one or more columns of the table:
|
<literal>films</literal>. Unique table constraints can be defined
|
||||||
|
on one or more columns of the table.
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE films (
|
CREATE TABLE films (
|
||||||
code CHAR(5),
|
code char(5),
|
||||||
title VARCHAR(40),
|
title varchar(40),
|
||||||
did DECIMAL(3),
|
did integer,
|
||||||
date_prod DATE,
|
date_prod date,
|
||||||
kind VARCHAR(10),
|
kind varchar(10),
|
||||||
len INTERVAL HOUR TO MINUTE,
|
len interval hour to minute,
|
||||||
CONSTRAINT production UNIQUE(date_prod)
|
CONSTRAINT production UNIQUE(date_prod)
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
@ -702,8 +662,8 @@ CREATE TABLE films (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3) CHECK (did > 100),
|
did integer CHECK (did > 100),
|
||||||
name VARCHAR(40)
|
name varchar(40)
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
@ -713,8 +673,8 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3),
|
did integer,
|
||||||
name VARCHAR(40)
|
name varchar(40)
|
||||||
CONSTRAINT con1 CHECK (did > 100 AND name <> '')
|
CONSTRAINT con1 CHECK (did > 100 AND name <> '')
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
@ -727,12 +687,12 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE films (
|
CREATE TABLE films (
|
||||||
code CHAR(5),
|
code char(5),
|
||||||
title VARCHAR(40),
|
title varchar(40),
|
||||||
did DECIMAL(3),
|
did integer,
|
||||||
date_prod DATE,
|
date_prod date,
|
||||||
kind VARCHAR(10),
|
kind varchar(10),
|
||||||
len INTERVAL HOUR TO MINUTE,
|
len interval hour to minute,
|
||||||
CONSTRAINT code_title PRIMARY KEY(code,title)
|
CONSTRAINT code_title PRIMARY KEY(code,title)
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
@ -746,33 +706,33 @@ CREATE TABLE films (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3),
|
did integer,
|
||||||
name CHAR VARYING(40),
|
name varchar(40),
|
||||||
PRIMARY KEY(did)
|
PRIMARY KEY(did)
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3) PRIMARY KEY,
|
did integer PRIMARY KEY,
|
||||||
name VARCHAR(40)
|
name varchar(40)
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This assigns a literal constant default value for the column
|
This assigns a literal constant default value for the column
|
||||||
<literal>name</literal>, and arranges for the default value of
|
<literal>name</literal>, arranges for the default value of column
|
||||||
column <literal>did</literal> to be generated by selecting the next
|
<literal>did</literal> to be generated by selecting the next value
|
||||||
value of a sequence object. The default value of
|
of a sequence object, and makes the default value of
|
||||||
<literal>modtime</literal> will be the time at which the row is
|
<literal>modtime</literal> be the time at which the row is
|
||||||
inserted.
|
inserted.
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
name VARCHAR(40) DEFAULT 'luso films',
|
name varchar(40) DEFAULT 'Luso Films',
|
||||||
did INTEGER DEFAULT NEXTVAL('distributors_serial'),
|
did integer DEFAULT nextval('distributors_serial'),
|
||||||
modtime TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
modtime timestamp DEFAULT current_timestamp
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
@ -784,8 +744,8 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3) CONSTRAINT no_null NOT NULL,
|
did integer CONSTRAINT no_null NOT NULL,
|
||||||
name VARCHAR(40) NOT NULL
|
name varchar(40) NOT NULL
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
@ -795,8 +755,8 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3),
|
did integer,
|
||||||
name VARCHAR(40) UNIQUE
|
name varchar(40) UNIQUE
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
||||||
|
@ -804,8 +764,8 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TABLE distributors (
|
CREATE TABLE distributors (
|
||||||
did DECIMAL(3),
|
did integer,
|
||||||
name VARCHAR(40),
|
name varchar(40),
|
||||||
UNIQUE(name)
|
UNIQUE(name)
|
||||||
);
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
@ -818,8 +778,7 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <command>CREATE TABLE</command> command conforms to SQL92
|
The <command>CREATE TABLE</command> command conforms to SQL92
|
||||||
and to a subset of SQL99, with exceptions listed below and in the
|
and to a subset of SQL99, with exceptions listed below.
|
||||||
descriptions above.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<refsect2>
|
<refsect2>
|
||||||
|
@ -827,27 +786,25 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Although the syntax of <literal>CREATE TEMPORARY TABLE</literal>
|
Although the syntax of <literal>CREATE TEMPORARY TABLE</literal>
|
||||||
resembles that of SQL92, the effect is not the same. In the standard,
|
resembles that of SQL standard, the effect is not the same. In the standard,
|
||||||
temporary tables are defined just once and automatically exist (starting
|
temporary tables are defined just once and automatically exist (starting
|
||||||
with empty contents) in every session that needs them.
|
with empty contents) in every session that needs them.
|
||||||
<productname>PostgreSQL</productname> instead
|
<productname>PostgreSQL</productname> instead
|
||||||
requires each session to issue its own <literal>CREATE TEMPORARY
|
requires each session to issue its own <literal>CREATE TEMPORARY
|
||||||
TABLE</literal> command for each temporary table to be used. This allows
|
TABLE</literal> command for each temporary table to be used. This allows
|
||||||
different sessions to use the same temporary table name for different
|
different sessions to use the same temporary table name for different
|
||||||
purposes, whereas the spec's approach constrains all instances of a
|
purposes, whereas the standard's approach constrains all instances of a
|
||||||
given temporary table name to have the same table structure.
|
given temporary table name to have the same table structure.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
<para>
|
||||||
The spec-mandated behavior of temporary tables is widely ignored.
|
The behavior of temporary tables mandated by the standard is
|
||||||
<productname>PostgreSQL</productname>'s behavior on this point is similar
|
widely ignored. <productname>PostgreSQL</productname>'s behavior
|
||||||
to that of several other RDBMSs.
|
on this point is similar to that of several other SQL databases.
|
||||||
</para>
|
</para>
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
SQL92's distinction between global and local temporary tables
|
The standard's distinction between global and local temporary tables
|
||||||
is not in <productname>PostgreSQL</productname>, since that distinction
|
is not in <productname>PostgreSQL</productname>, since that distinction
|
||||||
depends on the concept of modules, which
|
depends on the concept of modules, which
|
||||||
<productname>PostgreSQL</productname> does not have.
|
<productname>PostgreSQL</productname> does not have.
|
||||||
|
@ -855,12 +812,24 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <literal>ON COMMIT</literal> clause for temporary tables
|
The <literal>ON COMMIT</literal> clause for temporary tables
|
||||||
also resembles SQL92, but has some differences.
|
also resembles the SQL standard, but has some differences.
|
||||||
If the <literal>ON COMMIT</> clause is omitted, SQL92 specifies that the
|
If the <literal>ON COMMIT</> clause is omitted, SQL specifies that the
|
||||||
default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the
|
default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the
|
||||||
default behavior in <productname>PostgreSQL</productname> is
|
default behavior in <productname>PostgreSQL</productname> is
|
||||||
<literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT
|
<literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT
|
||||||
DROP</literal> option does not exist in SQL92.
|
DROP</literal> option does not exist in SQL.
|
||||||
|
</para>
|
||||||
|
</refsect2>
|
||||||
|
|
||||||
|
<refsect2>
|
||||||
|
<title>Column Check Constraints</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The SQL standard says that <literal>CHECK</> column constraints
|
||||||
|
may only refer to the column they apply to; only <literal>CHECK</>
|
||||||
|
table constraints may refer to multiple columns.
|
||||||
|
<productname>PostgreSQL</productname> does not enforce this
|
||||||
|
restriction; it treats column and table check constraints alike.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
|
|
||||||
|
@ -870,49 +839,13 @@ CREATE TABLE distributors (
|
||||||
<para>
|
<para>
|
||||||
The <literal>NULL</> <quote>constraint</quote> (actually a
|
The <literal>NULL</> <quote>constraint</quote> (actually a
|
||||||
non-constraint) is a <productname>PostgreSQL</productname>
|
non-constraint) is a <productname>PostgreSQL</productname>
|
||||||
extension to SQL92 that is included for compatibility with some
|
extension to the SQL standard that is included for compatibility with some
|
||||||
other RDBMSs (and for symmetry with the <literal>NOT
|
other database systems (and for symmetry with the <literal>NOT
|
||||||
NULL</literal> constraint). Since it is the default for any
|
NULL</literal> constraint). Since it is the default for any
|
||||||
column, its presence is simply noise.
|
column, its presence is simply noise.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
|
|
||||||
<refsect2>
|
|
||||||
<title>Assertions</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
An assertion is a special type of integrity constraint and shares
|
|
||||||
the same namespace as other constraints. However, an assertion is
|
|
||||||
not necessarily dependent on one particular table as constraints
|
|
||||||
are, so SQL92 provides the <command>CREATE ASSERTION</command>
|
|
||||||
statement as an alternate method for defining a constraint:
|
|
||||||
|
|
||||||
<synopsis>
|
|
||||||
CREATE ASSERTION <replaceable>name</replaceable> CHECK ( <replaceable>condition</replaceable> )
|
|
||||||
</synopsis>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<productname>PostgreSQL</> does not implement assertions at present.
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<!--
|
|
||||||
<para>
|
|
||||||
Domain constraints are defined by <command>CREATE
|
|
||||||
DOMAIN</command> or <command>ALTER DOMAIN</command> statements:
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Domain constraint:
|
|
||||||
|
|
||||||
<synopsis>
|
|
||||||
[ CONSTRAINT <replaceable>constraint_name</replaceable> ] CHECK <replaceable>constraint</replaceable>
|
|
||||||
[ {INITIALLY DEFERRED | INITIALLY IMMEDIATE} ]
|
|
||||||
[ [ NOT ] DEFERRABLE ]
|
|
||||||
</synopsis>
|
|
||||||
</para>
|
|
||||||
-->
|
|
||||||
|
|
||||||
<refsect2>
|
<refsect2>
|
||||||
<title>Inheritance</title>
|
<title>Inheritance</title>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.11 2002/11/21 23:34:43 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.12 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -18,16 +18,12 @@ PostgreSQL documentation
|
||||||
<synopsis>
|
<synopsis>
|
||||||
CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ]
|
CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ]
|
||||||
AS <replaceable>query</replaceable>
|
AS <replaceable>query</replaceable>
|
||||||
</synopsis>
|
</synopsis>
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>2001-03-20</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE TABLE AS</command> creates a table and fills it
|
<command>CREATE TABLE AS</command> creates a table and fills it
|
||||||
with data computed by a <command>SELECT</command> command. The
|
with data computed by a <command>SELECT</command> command. The
|
||||||
|
@ -75,10 +71,9 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replace
|
||||||
<term><replaceable>column_name</replaceable></term>
|
<term><replaceable>column_name</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name of a column in the new table. Multiple column names can
|
The name of a column in the new table. If column names are not
|
||||||
be specified using a comma-delimited list of column names. If
|
provided, they are taken from the output column names of the
|
||||||
column names are not provided, they are taken from the output
|
query.
|
||||||
column names of the query.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -124,21 +119,12 @@ CREATE [ [ LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replace
|
||||||
<para>
|
<para>
|
||||||
This command is modeled after an <productname>Oracle</productname>
|
This command is modeled after an <productname>Oracle</productname>
|
||||||
feature. There is no command with equivalent functionality in
|
feature. There is no command with equivalent functionality in
|
||||||
SQL92 or SQL99. However, a combination of <literal>CREATE
|
the SQL standard. However, a combination of <literal>CREATE
|
||||||
TABLE</literal> and <literal>INSERT ... SELECT</literal> can
|
TABLE</literal> and <literal>INSERT ... SELECT</literal> can
|
||||||
accomplish the same thing with little more effort.
|
accomplish the same thing with little more effort.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
|
||||||
<title>History</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The <command>CREATE TABLE AS</command> command has been available
|
|
||||||
since <productname>PostgreSQL</productname> 6.3.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>See Also</title>
|
<title>See Also</title>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.33 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_trigger.sgml,v 1.34 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,47 +8,92 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="SQL-CREATETRIGGER-TITLE">CREATE TRIGGER</refentrytitle>
|
<refentrytitle id="SQL-CREATETRIGGER-TITLE">CREATE TRIGGER</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE TRIGGER</refname>
|
||||||
CREATE TRIGGER
|
<refpurpose>define a new trigger</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new trigger
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsynopsisdivinfo>
|
|
||||||
<synopsis>
|
|
||||||
CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER } { <replaceable class="PARAMETER">event</replaceable> [ OR ... ] }
|
CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTER } { <replaceable class="PARAMETER">event</replaceable> [ OR ... ] }
|
||||||
ON <replaceable class="PARAMETER">table</replaceable> [ FOR [ EACH ] { ROW | STATEMENT } ]
|
ON <replaceable class="PARAMETER">table</replaceable> [ FOR [ EACH ] { ROW | STATEMENT } ]
|
||||||
EXECUTE PROCEDURE <replaceable class="PARAMETER">func</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> )
|
EXECUTE PROCEDURE <replaceable class="PARAMETER">func</replaceable> ( <replaceable class="PARAMETER">arguments</replaceable> )
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</refsynopsisdiv>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Description</title>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATETRIGGER-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-21</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
<para>
|
||||||
|
<command>CREATE TRIGGER</command> creates a new trigger. The
|
||||||
|
trigger will be associated with the specified table and will
|
||||||
|
execute the specified function <replaceable
|
||||||
|
class="parameter">func</replaceable> when certain events occur.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The trigger can be specified to fire either before before the
|
||||||
|
operation is attempted on a row (before constraints are checked and
|
||||||
|
the <command>INSERT</command>, <command>UPDATE</command>, or
|
||||||
|
<command>DELETE</command> is attempted) or after the operation has
|
||||||
|
completed (after constraints are checked and the
|
||||||
|
<command>INSERT</command>, <command>UPDATE</command>, or
|
||||||
|
<command>DELETE</command> has completed). If the trigger fires
|
||||||
|
before the event, the trigger may skip the operation for the
|
||||||
|
current row, or change the row being inserted (for
|
||||||
|
<command>INSERT</command> and <command>UPDATE</command> operations
|
||||||
|
only). If the trigger fires after the event, all changes, including
|
||||||
|
the last insertion, update, or deletion, are <quote>visible</quote>
|
||||||
|
to the trigger.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
A trigger that is marked <literal>FOR EACH ROW</literal> is called
|
||||||
|
once for every row that the operation modifies. For example, a
|
||||||
|
<command>DELETE</command> that affects 10 rows will cause any
|
||||||
|
<literal>ON DELETE</literal> triggers on the target relation to be
|
||||||
|
called 10 separate times, once for each deleted row. In contrast, a
|
||||||
|
trigger that is marked <literal>FOR EACH STATEMENT</literal> only
|
||||||
|
executes once for any given operation, regardless of how many rows
|
||||||
|
it modifies (in particular, an operation that modifies zero rows
|
||||||
|
will still result in the execution of any applicable <literal>FOR
|
||||||
|
EACH STATEMENT</literal> triggers).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
If multiple triggers of the same kind are defined for the same event,
|
||||||
|
they will be fired in alphabetical order by name.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<command>SELECT</command> does not modify any rows so you can not
|
||||||
|
create <command>SELECT</command> triggers. Rules and views are more
|
||||||
|
appropriate in such cases.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Refer to <xref linkend="triggers"> for more information about triggers.
|
||||||
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameters</title>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">name</replaceable></term>
|
<term><replaceable class="parameter">name</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name to give the new trigger. This must be distinct from the name
|
The name to give the new trigger. This must be distinct from
|
||||||
of any other trigger for the same table.
|
the name of any other trigger for the same table.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>BEFORE</term>
|
<term><literal>BEFORE</literal></term>
|
||||||
<term>AFTER</term>
|
<term><literal>AFTER</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Determines whether the function is called before or after the
|
Determines whether the function is called before or after the
|
||||||
|
@ -61,26 +106,27 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
|
||||||
<term><replaceable class="parameter">event</replaceable></term>
|
<term><replaceable class="parameter">event</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
One of <command>INSERT</command>, <command>DELETE</command> or
|
One of <command>INSERT</command>, <command>UPDATE</command>, or
|
||||||
<command>UPDATE</command>; this specifies the event that will
|
<command>DELETE</command>; this specifies the event that will
|
||||||
fire the trigger. Multiple events can be specified using
|
fire the trigger. Multiple events can be specified using
|
||||||
<literal>OR</literal>.
|
<literal>OR</literal>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">table</replaceable></term>
|
<term><replaceable class="parameter">table</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The name (optionally schema-qualified) of the table the
|
The name (optionally schema-qualified) of the table the trigger
|
||||||
trigger is for.
|
is for.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>FOR EACH ROW</term>
|
<term><literal>FOR EACH ROW</literal></term>
|
||||||
<term>FOR EACH STATEMENT</term>
|
<term><literal>FOR EACH STATEMENT</literal></term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
|
@ -97,113 +143,43 @@ CREATE TRIGGER <replaceable class="PARAMETER">name</replaceable> { BEFORE | AFTE
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
A user-supplied function that is declared as taking no arguments
|
A user-supplied function that is declared as taking no arguments
|
||||||
and returning type <literal>trigger</>.
|
and returning type <literal>trigger</>, which is executed when
|
||||||
|
the trigger fires.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">arguments</replaceable></term>
|
<term><replaceable class="parameter">arguments</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
An optional comma-separated list of arguments to be provided to
|
An optional comma-separated list of arguments to be provided to
|
||||||
the function when the trigger is executed, along with the standard
|
the function when the trigger is executed. The arguments are
|
||||||
trigger data such as old and new tuple contents. The arguments
|
literal string constants. Simple names and numeric constants
|
||||||
are literal string constants. Simple names and numeric constants
|
may be written here, too, but they will all be converted to
|
||||||
may be written here too, but they will all be converted to
|
strings. Please check the description of the implementation
|
||||||
strings. Note that these arguments are not provided as normal
|
language of the trigger function about how the trigger arguments
|
||||||
function parameters (since a trigger procedure must be declared to
|
are accessible within the function; it may be different from
|
||||||
take zero parameters), but are instead accessed through the
|
normal function arguments.
|
||||||
<literal>TG_ARGV</literal> array.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
</refsect1>
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATETRIGGER-2">
|
<refsect1>
|
||||||
<refsect2info>
|
<title>Diagnostics</title>
|
||||||
<date>1998-09-21</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>
|
<term><computeroutput>CREATE TRIGGER</computeroutput></term>
|
||||||
CREATE TRIGGER
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This message is returned if the trigger is successfully created.
|
Message returned if the trigger was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATETRIGGER-1">
|
|
||||||
<refsect1info>
|
|
||||||
<date>1998-09-21</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<command>CREATE TRIGGER</command> will enter a new trigger into the current
|
|
||||||
database. The trigger will be associated with the relation
|
|
||||||
<replaceable class="parameter">table</replaceable> and will execute
|
|
||||||
the specified function <replaceable class="parameter">func</replaceable>.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The trigger can be specified to fire either before BEFORE the
|
|
||||||
operation is attempted on a tuple (before constraints are checked and
|
|
||||||
the <command>INSERT</command>, <command>UPDATE</command> or
|
|
||||||
<command>DELETE</command> is attempted) or AFTER the operation has
|
|
||||||
been attempted (e.g., after constraints are checked and the
|
|
||||||
<command>INSERT</command>, <command>UPDATE</command> or
|
|
||||||
<command>DELETE</command> has completed). If the trigger fires before
|
|
||||||
the event, the trigger may skip the operation for the current tuple,
|
|
||||||
or change the tuple being inserted (for <command>INSERT</command> and
|
|
||||||
<command>UPDATE</command> operations only). If the trigger fires
|
|
||||||
after the event, all changes, including the last insertion, update,
|
|
||||||
or deletion, are <quote>visible</quote> to the trigger.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
A trigger that executes <literal>FOR EACH ROW</literal> of the
|
|
||||||
specified operation is called once for every row that the operation
|
|
||||||
modifies. For example, a <command>DELETE</command> that affects 10
|
|
||||||
rows will cause any <literal>ON DELETE</literal> triggers on the
|
|
||||||
target relation to be called 10 separate times, once for each
|
|
||||||
deleted tuple. In contrast, a trigger that executes <literal>FOR
|
|
||||||
EACH STATEMENT</literal> of the specified operation only executes
|
|
||||||
once for any given operation, regardless of how many rows it
|
|
||||||
modifies (in particular, an operation that modifies zero rows will
|
|
||||||
still result in the execution of any applicable <literal>FOR EACH
|
|
||||||
STATEMENT</literal> triggers).
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
If multiple triggers of the same kind are defined for the same event,
|
|
||||||
they will be fired in alphabetical order by name.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
<command>SELECT</command> does not modify any rows so you can not
|
|
||||||
create <command>SELECT</command> triggers. Rules and views are more
|
|
||||||
appropriate in such cases.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Refer to <xref linkend="server-programming"> for more information.
|
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="SQL-CREATETRIGGER-notes">
|
<refsect1 id="SQL-CREATETRIGGER-notes">
|
||||||
|
@ -219,13 +195,13 @@ CREATE TRIGGER
|
||||||
necessary to declare trigger functions as returning the placeholder
|
necessary to declare trigger functions as returning the placeholder
|
||||||
type <type>opaque</>, rather than <type>trigger</>. To support loading
|
type <type>opaque</>, rather than <type>trigger</>. To support loading
|
||||||
of old dump files, <command>CREATE TRIGGER</> will accept a function
|
of old dump files, <command>CREATE TRIGGER</> will accept a function
|
||||||
declared as returning <type>opaque</>, but it will issue a NOTICE and
|
declared as returning <type>opaque</>, but it will issue a notice and
|
||||||
change the function's declared return type to <type>trigger</>.
|
change the function's declared return type to <type>trigger</>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Refer to the <xref linkend="sql-droptrigger" endterm="sql-droptrigger-title"> command for
|
Use <xref linkend="sql-droptrigger"
|
||||||
information on how to remove triggers.
|
endterm="sql-droptrigger-title"> to remove a trigger.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
@ -233,62 +209,19 @@ CREATE TRIGGER
|
||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Check if the specified distributor code exists in the distributors
|
<xref linkend="trigger-example"> contains a complete example.
|
||||||
table before appending or updating a row in the table films:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
CREATE TRIGGER if_dist_exists
|
|
||||||
BEFORE INSERT OR UPDATE ON films FOR EACH ROW
|
|
||||||
EXECUTE PROCEDURE check_primary_key ('did', 'distributors', 'did');
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
Before cancelling a distributor or updating its code, remove every
|
|
||||||
reference to the table films:
|
|
||||||
<programlisting>
|
|
||||||
CREATE TRIGGER if_film_exists
|
|
||||||
BEFORE DELETE OR UPDATE ON distributors FOR EACH ROW
|
|
||||||
EXECUTE PROCEDURE check_foreign_key (1, 'CASCADE', 'did', 'films', 'did');
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
The second example can also be done by using a foreign key,
|
|
||||||
constraint as in:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
CREATE TABLE distributors (
|
|
||||||
did DECIMAL(3),
|
|
||||||
name VARCHAR(40),
|
|
||||||
CONSTRAINT if_film_exists
|
|
||||||
FOREIGN KEY(did) REFERENCES films
|
|
||||||
ON UPDATE CASCADE ON DELETE CASCADE
|
|
||||||
);
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="SQL-CREATETRIGGER-compatibility">
|
<refsect1 id="SQL-CREATETRIGGER-compatibility">
|
||||||
<title>Compatibility</title>
|
<title>Compatibility</title>
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term>SQL92</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
There is no <command>CREATE TRIGGER</command> statement in <acronym>SQL92</acronym>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term>SQL99</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
<para>
|
||||||
The <command>CREATE TRIGGER</command> statement in
|
The <command>CREATE TRIGGER</command> statement in
|
||||||
<productname>PostgreSQL</productname> implements a subset of the
|
<productname>PostgreSQL</productname> implements a subset of the
|
||||||
SQL99 standard. The following functionality is missing:
|
SQL99 standard. (There are no provisions for triggers in SQL92.)
|
||||||
|
The following functionality is missing:
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
|
@ -302,23 +235,22 @@ CREATE TABLE distributors (
|
||||||
SQL99 allows you to define aliases for the <quote>old</quote>
|
SQL99 allows you to define aliases for the <quote>old</quote>
|
||||||
and <quote>new</quote> rows or tables for use in the definition
|
and <quote>new</quote> rows or tables for use in the definition
|
||||||
of the triggered action (e.g., <literal>CREATE TRIGGER ... ON
|
of the triggered action (e.g., <literal>CREATE TRIGGER ... ON
|
||||||
tablename REFERENCING OLD ROW AS somename NEW ROW AS
|
tablename REFERENCING OLD ROW AS somename NEW ROW AS othername
|
||||||
othername ...</literal>). Since
|
...</literal>). Since <productname>PostgreSQL</productname>
|
||||||
<productname>PostgreSQL</productname> allows trigger
|
allows trigger procedures to be written in any number of
|
||||||
procedures to be written in any number of user-defined
|
user-defined languages, access to the data is handled in a
|
||||||
languages, access to the data is handled in a
|
|
||||||
language-specific way.
|
language-specific way.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<productname>PostgreSQL</productname> only allows the
|
<productname>PostgreSQL</productname> only allows the execution
|
||||||
execution of a stored procedure for the triggered action.
|
of a user-defined function for the triggered action. SQL99
|
||||||
SQL99 allows the execution of a number of other SQL commands,
|
allows the execution of a number of other SQL commands, such as
|
||||||
such as <command>CREATE TABLE</command> as triggered action.
|
<command>CREATE TABLE</command> as triggered action. This
|
||||||
This limitation is not hard to work around by creating a
|
limitation is not hard to work around by creating a user-defined
|
||||||
stored procedure that executes these commands.
|
function that executes the desired commands.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
@ -326,18 +258,15 @@ CREATE TABLE distributors (
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
SQL99 specifies that multiple triggers should be fired in
|
SQL99 specifies that multiple triggers should be fired in
|
||||||
time-of-creation order. <productname>PostgreSQL</productname>
|
time-of-creation order. <productname>PostgreSQL</productname> uses
|
||||||
uses name order, which was judged more convenient to work with.
|
name order, which was judged more convenient to work with.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The ability to specify multiple actions for a single trigger
|
The ability to specify multiple actions for a single trigger using
|
||||||
using <literal>OR</literal> is a <productname>PostgreSQL</>
|
<literal>OR</literal> is a <productname>PostgreSQL</> extension of
|
||||||
extension of the SQL standard.
|
the SQL standard.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.40 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_type.sgml,v 1.41 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,22 +8,17 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="sql-createtype-title">CREATE TYPE</refentrytitle>
|
<refentrytitle id="sql-createtype-title">CREATE TYPE</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE TYPE</refname>
|
||||||
CREATE TYPE
|
<refpurpose>define a new data type</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new data type
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>1999-07-20</date>
|
CREATE TYPE <replaceable class="parameter">typename</replaceable> (
|
||||||
</refsynopsisdivinfo>
|
INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
|
||||||
<synopsis>
|
, INTERNALLENGTH = { <replaceable class="parameter">internallength</replaceable> | VARIABLE }
|
||||||
CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <replaceable class="parameter">input_function</replaceable>, OUTPUT = <replaceable class="parameter">output_function</replaceable>
|
|
||||||
, INTERNALLENGTH = { <replaceable
|
|
||||||
class="parameter">internallength</replaceable> | VARIABLE }
|
|
||||||
[ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
|
[ , DEFAULT = <replaceable class="parameter">default</replaceable> ]
|
||||||
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
|
[ , ELEMENT = <replaceable class="parameter">element</replaceable> ] [ , DELIMITER = <replaceable class="parameter">delimiter</replaceable> ]
|
||||||
[ , PASSEDBYVALUE ]
|
[ , PASSEDBYVALUE ]
|
||||||
|
@ -32,184 +27,26 @@ CREATE TYPE <replaceable class="parameter">typename</replaceable> ( INPUT = <rep
|
||||||
)
|
)
|
||||||
|
|
||||||
CREATE TYPE <replaceable class="parameter">typename</replaceable> AS
|
CREATE TYPE <replaceable class="parameter">typename</replaceable> AS
|
||||||
( <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] )
|
( <replaceable class="PARAMETER">attribute_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [, ... ] )
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATETYPE-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-21</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">typename</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name (optionally schema-qualified) of a type to be created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">internallength</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
A literal value, which specifies the internal length of
|
|
||||||
the new type.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">input_function</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of a function, created by
|
|
||||||
<command>CREATE FUNCTION</command>, which
|
|
||||||
converts data from its external form to the type's
|
|
||||||
internal form.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">output_function</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of a function, created by
|
|
||||||
<command>CREATE FUNCTION</command>, which
|
|
||||||
converts data from its internal form to a form suitable
|
|
||||||
for display.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">element</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The type being created is an array; this specifies
|
|
||||||
the type of the array elements.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">delimiter</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The delimiter character to be used between values in arrays made
|
|
||||||
of this type.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">default</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The default value for the data type. Usually this is omitted,
|
|
||||||
so that the default is NULL.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">alignment</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Storage alignment requirement of the data type. If specified, must
|
|
||||||
be <literal>char</literal>, <literal>int2</literal>,
|
|
||||||
<literal>int4</literal>, or <literal>double</literal>;
|
|
||||||
the default is <literal>int4</literal>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">storage</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Storage technique for the data type. If specified, must
|
|
||||||
be <literal>plain</literal>, <literal>external</literal>,
|
|
||||||
<literal>extended</literal>, or <literal>main</literal>;
|
|
||||||
the default is <literal>plain</literal>.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="PARAMETER">column_name</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of a column of the composite type.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="PARAMETER">data_type</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name of an existing data type.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATETYPE-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>1998-09-21</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
CREATE TYPE
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
Message returned if the type is successfully created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATETYPE-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>1998-09-21</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE TYPE</command> allows the user to register a new data
|
<command>CREATE TYPE</command> registers a new data type for use in
|
||||||
type with <productname>PostgreSQL</> for use in the current data base.
|
the current data base. The user who defines a type becomes its
|
||||||
The user who defines a type becomes its owner.
|
owner.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If a schema name is given then the type is created in the
|
If a schema name is given then the type is created in the specified
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
schema. Otherwise it is created in the current schema. The type
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
name must be distinct from the name of any existing type or domain
|
||||||
The type name must be distinct from the name of any existing type or
|
in the same schema. (Because tables have associated data types,
|
||||||
domain in the same schema. (Because tables have associated data types,
|
the type name must also be distinct from the name of any existing
|
||||||
type names also must not conflict with table names in the same schema.)
|
table in the same schema.)
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<refsect2>
|
<refsect2>
|
||||||
|
@ -220,74 +57,59 @@ CREATE TYPE
|
||||||
(scalar type). It requires the
|
(scalar type). It requires the
|
||||||
registration of two functions (using <command>CREATE
|
registration of two functions (using <command>CREATE
|
||||||
FUNCTION</command>) before defining the
|
FUNCTION</command>) before defining the
|
||||||
type. The representation of a new base type is determined by
|
type. The internal representation of the new base type is determined by
|
||||||
<replaceable class="parameter">input_function</replaceable>, which
|
<replaceable class="parameter">input_function</replaceable>, which
|
||||||
converts the type's external representation to an internal
|
converts the type's external representation to an internal
|
||||||
representation usable by the
|
representation usable by the
|
||||||
operators and functions defined for the type. Naturally,
|
operators and functions defined for the type.
|
||||||
<replaceable class="parameter">output_function</replaceable>
|
<replaceable class="parameter">output_function</replaceable>
|
||||||
performs the reverse transformation. The input function may be
|
performs the reverse transformation. The input function may be
|
||||||
declared as taking one argument of type <type>cstring</type>,
|
declared as taking one argument of type <type>cstring</type>,
|
||||||
or as taking three arguments of types
|
or as taking three arguments of types
|
||||||
<type>cstring</type>, <type>OID</type>, <type>int4</type>.
|
<type>cstring</type>, <type>oid</type>, <type>integer</type>.
|
||||||
(The first argument is the input text as a C string, the second
|
The first argument is the input text as a C string, the second
|
||||||
argument is the element type in case this is an array type,
|
argument is the element type in case this is an array type,
|
||||||
and the third is the <literal>typmod</> of the destination column, if known.)
|
and the third is the <literal>typmod</> of the destination column, if known.
|
||||||
It should return a value of the data type itself.
|
It should return a value of the data type itself.
|
||||||
The output function may be
|
The output function may be
|
||||||
declared as taking one argument of the new data type, or as taking
|
declared as taking one argument of the new data type, or as taking
|
||||||
two arguments of which the second is type <type>OID</type>.
|
two arguments of which the second is type <type>oid</type>.
|
||||||
(The second argument is again the array element type for array types.)
|
The second argument is again the array element type for array types.
|
||||||
The output function should return type <type>cstring</type>.
|
The output function should return type <type>cstring</type>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
You should at this point be wondering how the input and output functions
|
You should at this point be wondering how the input and output functions
|
||||||
can be declared to have results or inputs of the new type, when they have
|
can be declared to have results or arguments of the new type, when they have
|
||||||
to be created before the new type can be created. The answer is that the
|
to be created before the new type can be created. The answer is that the
|
||||||
input function must be created first, then the output function, then the
|
input function must be created first, then the output function, then the
|
||||||
data type.
|
data type.
|
||||||
<productname>PostgreSQL</productname> will first see the name of the new
|
<productname>PostgreSQL</productname> will first see the name of the new
|
||||||
data type as the return type of the input function. It will create a
|
data type as the return type of the input function. It will create a
|
||||||
<quote>shell</> type, which is simply a placeholder entry in
|
<quote>shell</> type, which is simply a placeholder entry in
|
||||||
<literal>pg_type</>, and link the input function definition to the shell
|
the system catalog, and link the input function definition to the shell
|
||||||
type. Similarly the output function will be linked to the (now already
|
type. Similarly the output function will be linked to the (now already
|
||||||
existing) shell type. Finally, <command>CREATE TYPE</> replaces the
|
existing) shell type. Finally, <command>CREATE TYPE</> replaces the
|
||||||
shell entry with a complete type definition, and the new type can be used.
|
shell entry with a complete type definition, and the new type can be used.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
<para>
|
||||||
In <productname>PostgreSQL</productname> versions before 7.3, it was
|
Base data types can be fixed-length, in which case
|
||||||
customary to avoid creating a shell type by replacing the functions'
|
|
||||||
forward references to the type name with the placeholder pseudo-type
|
|
||||||
<type>OPAQUE</>. The <type>cstring</> inputs and
|
|
||||||
results also had to be declared as <type>OPAQUE</> before 7.3.
|
|
||||||
To support loading
|
|
||||||
of old dump files, <command>CREATE TYPE</> will accept functions
|
|
||||||
declared using <type>opaque</>, but it will issue a NOTICE and
|
|
||||||
change the function's declaration to use the correct types.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
|
|
||||||
<para>
|
|
||||||
New base data types can be fixed length, in which case
|
|
||||||
<replaceable class="parameter">internallength</replaceable> is a
|
<replaceable class="parameter">internallength</replaceable> is a
|
||||||
positive integer, or variable length, indicated by setting
|
positive integer, or variable length, indicated by setting
|
||||||
<replaceable class="parameter">internallength</replaceable>
|
<replaceable class="parameter">internallength</replaceable>
|
||||||
to <option>VARIABLE</option>. (Internally, this is represented
|
to <literal>VARIABLE</literal>. (Internally, this is represented
|
||||||
by setting <literal>typlen</> to -1.) The internal representation of all
|
by setting <literal>typlen</> to -1.) The internal representation of all
|
||||||
variable-length types must start with an integer giving the total
|
variable-length types must start with a 4-byte integer giving the total
|
||||||
length of this value of the type.
|
length of this value of the type.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
To indicate that a type is an array,
|
To indicate that a type is an array, specify the type of the array
|
||||||
specify the type of the array
|
elements using the <literal>ELEMENT</> key word. For example, to
|
||||||
elements using the <option>ELEMENT</> keyword. For example, to define
|
define an array of 4-byte integers (<type>int4</type>), specify
|
||||||
an array of 4-byte integers ("int4"), specify
|
<literal>ELEMENT = int4</literal> More details about array types
|
||||||
<programlisting>ELEMENT = int4</programlisting>
|
appear below.
|
||||||
More details about array types appear below.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -295,29 +117,28 @@ CREATE TYPE
|
||||||
representation of arrays of this type, <replaceable
|
representation of arrays of this type, <replaceable
|
||||||
class="parameter">delimiter</replaceable> can be
|
class="parameter">delimiter</replaceable> can be
|
||||||
set to a specific character. The default delimiter is the comma
|
set to a specific character. The default delimiter is the comma
|
||||||
('<literal>,</literal>'). Note that the delimiter is associated
|
(<literal>,</literal>). Note that the delimiter is associated
|
||||||
with the array element type, not the array type itself.
|
with the array element type, not the array type itself.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
A default value may be specified, in case a user wants columns of the
|
A default value may be specified, in case a user wants columns of the
|
||||||
data type to default to something other than NULL.
|
data type to default to something other than the null value.
|
||||||
Specify the default with the <option>DEFAULT</option> keyword.
|
Specify the default with the <literal>DEFAULT</literal> key word.
|
||||||
(Such a default may be overridden by an explicit <option>DEFAULT</option>
|
(Such a default may be overridden by an explicit <literal>DEFAULT</literal>
|
||||||
clause attached to a particular column.)
|
clause attached to a particular column.)
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The optional flag, <option>PASSEDBYVALUE</option>, indicates that
|
The optional flag <literal>PASSEDBYVALUE</literal> indicates that
|
||||||
values of this data type are passed
|
values of this data type are passed by value rather than by
|
||||||
by value rather than by reference. Note that you
|
reference. You may not pass by value types whose internal
|
||||||
may not pass by value types whose internal representation is
|
representation is larger than the size of the <type>Datum</> type
|
||||||
longer than the width of the <type>Datum</> type (four bytes on
|
(4 bytes on most machines, 8 bytes on a few).
|
||||||
most machines, eight bytes on a few).
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <replaceable class="parameter">alignment</replaceable> keyword
|
The <replaceable class="parameter">alignment</replaceable> parameter
|
||||||
specifies the storage alignment required for the data type. The
|
specifies the storage alignment required for the data type. The
|
||||||
allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
|
allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries.
|
||||||
Note that variable-length types must have an alignment of at least
|
Note that variable-length types must have an alignment of at least
|
||||||
|
@ -325,21 +146,22 @@ CREATE TYPE
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The <replaceable class="parameter">storage</replaceable> keyword
|
The <replaceable class="parameter">storage</replaceable> parameter
|
||||||
allows selection of storage strategies for variable-length data types
|
allows selection of storage strategies for variable-length data
|
||||||
(only <literal>plain</literal> is allowed for fixed-length types).
|
types. (Only <literal>plain</literal> is allowed for fixed-length
|
||||||
<literal>plain</literal> disables TOAST for the data type: it will always
|
types.) <literal>plain</literal> specifies that data of the type
|
||||||
be stored in-line and not compressed.
|
will always be stored in-line and not compressed.
|
||||||
<literal>extended</literal> gives full TOAST capability: the system will
|
<literal>extended</literal> specifies that the system will first
|
||||||
first try to compress a long data value, and will move the value out of
|
try to compress a long data value, and will move the value out of
|
||||||
the main table row if it's still too long.
|
the main table row if it's still too long.
|
||||||
<literal>external</literal> allows the value to be moved out of the main
|
<literal>external</literal> allows the value to be moved out of the
|
||||||
table, but the system will not try to compress it.
|
main table, but the system will not try to compress it.
|
||||||
<literal>main</literal> allows compression, but discourages moving the
|
<literal>main</literal> allows compression, but discourages moving
|
||||||
value out of the main table. (Data items with this storage method may
|
the value out of the main table. (Data items with this storage
|
||||||
still be moved out of the main table if there is no other way to make
|
strategy may still be moved out of the main table if there is no
|
||||||
a row fit, but they will be kept in the main table preferentially over
|
other way to make a row fit, but they will be kept in the main
|
||||||
<literal>extended</literal> and <literal>external</literal> items.)
|
table preferentially over <literal>extended</literal> and
|
||||||
|
<literal>external</literal> items.)
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
</refsect2>
|
||||||
|
|
||||||
|
@ -349,7 +171,7 @@ CREATE TYPE
|
||||||
<para>
|
<para>
|
||||||
The second form of <command>CREATE TYPE</command>
|
The second form of <command>CREATE TYPE</command>
|
||||||
creates a composite type.
|
creates a composite type.
|
||||||
The composite type is specified by a list of column names and data types.
|
The composite type is specified by a list of attribute names and data types.
|
||||||
This is essentially the same as the row type
|
This is essentially the same as the row type
|
||||||
of a table, but using <command>CREATE TYPE</command> avoids the need to
|
of a table, but using <command>CREATE TYPE</command> avoids the need to
|
||||||
create an actual table when all that is wanted is to define a type.
|
create an actual table when all that is wanted is to define a type.
|
||||||
|
@ -373,19 +195,19 @@ CREATE TYPE
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
You might reasonably ask <quote>why is there an <option>ELEMENT</>
|
You might reasonably ask why there is an <option>ELEMENT</>
|
||||||
option, if the system makes the correct array type automatically?</quote>
|
option, if the system makes the correct array type automatically.
|
||||||
The only case where it's useful to use <option>ELEMENT</> is when you are
|
The only case where it's useful to use <option>ELEMENT</> is when you are
|
||||||
making a fixed-length type that happens to be internally an array of N
|
making a fixed-length type that happens to be internally an array of a number of
|
||||||
identical things, and you want to allow the N things to be accessed
|
identical things, and you want to allow these things to be accessed
|
||||||
directly by subscripting, in addition to whatever operations you plan
|
directly by subscripting, in addition to whatever operations you plan
|
||||||
to provide for the type as a whole. For example, type <type>name</>
|
to provide for the type as a whole. For example, type <type>name</>
|
||||||
allows its constituent <type>char</>s to be accessed this way.
|
allows its constituent <type>char</> elements to be accessed this way.
|
||||||
A 2-D <type>point</> type could allow its two component floats to be
|
A 2-D <type>point</> type could allow its two component numbers to be
|
||||||
accessed like <literal>point[0]</> and <literal>point[1]</>.
|
accessed like <literal>point[0]</> and <literal>point[1]</>.
|
||||||
Note that
|
Note that
|
||||||
this facility only works for fixed-length types whose internal form
|
this facility only works for fixed-length types whose internal form
|
||||||
is exactly a sequence of N identical fixed-length fields. A subscriptable
|
is exactly a sequence of identical fixed-length fields. A subscriptable
|
||||||
variable-length type must have the generalized internal representation
|
variable-length type must have the generalized internal representation
|
||||||
used by <literal>array_in</> and <literal>array_out</>.
|
used by <literal>array_in</> and <literal>array_out</>.
|
||||||
For historical reasons (i.e., this is clearly wrong but it's far too
|
For historical reasons (i.e., this is clearly wrong but it's far too
|
||||||
|
@ -395,40 +217,195 @@ CREATE TYPE
|
||||||
</refsect2>
|
</refsect2>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Parameter</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">typename</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name (optionally schema-qualified) of a type to be created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">internallength</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
A numeric constant that specifies the internal length of the new
|
||||||
|
type.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">input_function</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of a function that converts data from the type's
|
||||||
|
external form to the its internal form.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">output_function</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of a function that converts data from the type's
|
||||||
|
internal form to a form suitable for display.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">element</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The type being created is an array; this specifies the type of
|
||||||
|
the array elements.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">delimiter</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The delimiter character to be used between values in arrays made
|
||||||
|
of this type.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">default</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The default value for the data type. If this is omitted, the
|
||||||
|
default is null.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">alignment</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The storage alignment requirement of the data type. If specified,
|
||||||
|
it must be <literal>char</literal>, <literal>int2</literal>,
|
||||||
|
<literal>int4</literal>, or <literal>double</literal>; the
|
||||||
|
default is <literal>int4</literal>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">storage</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The storage strateg for the data type. If specified, must be
|
||||||
|
<literal>plain</literal>, <literal>external</literal>,
|
||||||
|
<literal>extended</literal>, or <literal>main</literal>; the
|
||||||
|
default is <literal>plain</literal>.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">attribute_name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of an attribute of the composite type.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">data_type</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name of an existing data type.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE TYPE</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the type was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="SQL-CREATETYPE-notes">
|
<refsect1 id="SQL-CREATETYPE-notes">
|
||||||
<title>Notes</title>
|
<title>Notes</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
User-defined type names cannot begin with the underscore character
|
User-defined type names cannot begin with the underscore character
|
||||||
(<quote><literal>_</literal></quote>) and can only be 62
|
(<literal>_</literal>) and can only be 62 characters
|
||||||
characters long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than
|
long (or in general <symbol>NAMEDATALEN</symbol> - 2, rather than
|
||||||
the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other names).
|
the <symbol>NAMEDATALEN</symbol> - 1 characters allowed for other
|
||||||
Type names beginning with underscore are
|
names). Type names beginning with underscore are reserved for
|
||||||
reserved for internally-created array type names.
|
internally-created array type names.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In <productname>PostgreSQL</productname> versions before 7.3, it
|
||||||
|
was customary to avoid creating a shell type by replacing the
|
||||||
|
functions' forward references to the type name with the placeholder
|
||||||
|
pseudotype <type>opaque</>. The <type>cstring</> arguments and
|
||||||
|
results also had to be declared as <type>opaque</> before 7.3. To
|
||||||
|
support loading of old dump files, <command>CREATE TYPE</> will
|
||||||
|
accept functions declared using <type>opaque</>, but it will issue
|
||||||
|
a notice and change the function's declaration to use the correct
|
||||||
|
types.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Examples</title>
|
<title>Examples</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This example creates the <type>box</type> data type and then uses the
|
This example creates the data type <type>box</type> and then uses the
|
||||||
type in a table definition:
|
type in a table definition:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TYPE box (INTERNALLENGTH = 16,
|
CREATE TYPE box (
|
||||||
INPUT = my_procedure_1, OUTPUT = my_procedure_2);
|
INTERNALLENGTH = 16,
|
||||||
CREATE TABLE myboxes (id INT4, description box);
|
INPUT = my_box_in_function,
|
||||||
|
OUTPUT = my_box_out_function
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE TABLE myboxes (
|
||||||
|
id integer,
|
||||||
|
description box
|
||||||
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
If <type>box</type>'s internal structure were an array of four
|
If the internal structure of <type>box</type> were an array of four
|
||||||
<type>float4</>s, we might instead say
|
<type>float4</> elements, we might instead use
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TYPE box (INTERNALLENGTH = 16,
|
CREATE TYPE box (
|
||||||
INPUT = my_procedure_1, OUTPUT = my_procedure_2,
|
INTERNALLENGTH = 16,
|
||||||
ELEMENT = float4);
|
INPUT = my_box_in_function,
|
||||||
|
OUTPUT = my_box_out_function,
|
||||||
|
ELEMENT = float4
|
||||||
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
which would allow a box value's component floats to be accessed
|
which would allow a box value's component numbers to be accessed
|
||||||
by subscripting. Otherwise the type behaves the same as before.
|
by subscripting. Otherwise the type behaves the same as before.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
@ -436,20 +413,30 @@ CREATE TYPE box (INTERNALLENGTH = 16,
|
||||||
This example creates a large object type and uses it in
|
This example creates a large object type and uses it in
|
||||||
a table definition:
|
a table definition:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TYPE bigobj (INPUT = lo_filein, OUTPUT = lo_fileout,
|
CREATE TYPE bigobj (
|
||||||
INTERNALLENGTH = VARIABLE);
|
INPUT = lo_filein, OUTPUT = lo_fileout,
|
||||||
CREATE TABLE big_objs (id int4, obj bigobj);
|
INTERNALLENGTH = VARIABLE
|
||||||
|
);
|
||||||
|
CREATE TABLE big_objs (
|
||||||
|
id integer,
|
||||||
|
obj bigobj
|
||||||
|
);
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This example creates a composite type and uses it in
|
This example creates a composite type and uses it in
|
||||||
a table function definition:
|
a function definition:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE TYPE compfoo AS (f1 int, f2 text);
|
CREATE TYPE compfoo AS (f1 int, f2 text);
|
||||||
CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS 'SELECT fooid, fooname FROM foo' LANGUAGE SQL;
|
CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS 'SELECT fooid, fooname FROM foo' LANGUAGE SQL;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
More examples, including suitable input and output functions, are
|
||||||
|
in <xref linkend="extend">.
|
||||||
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="SQL-CREATETYPE-compatibility">
|
<refsect1 id="SQL-CREATETYPE-compatibility">
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.25 2003/03/25 16:15:39 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.26 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -33,17 +33,18 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
<title>Description</title>
|
<title>Description</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE USER</command> will add a new user to an instance
|
<command>CREATE USER</command> adds a new user to a
|
||||||
of <productname>PostgreSQL</productname>. Refer to <xref linkend="user-manag">
|
<productname>PostgreSQL</productname> database cluster. Refer to
|
||||||
for information about managing users and authentication. You must
|
<xref linkend="user-manag"> and <xref
|
||||||
be a database superuser to use this command.
|
linkend="client-authentication"> for information about managing
|
||||||
|
users and authentication. You must be a database superuser to use
|
||||||
|
this command.
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect2>
|
<refsect1>
|
||||||
<title>Parameters</title>
|
<title>Parameters</title>
|
||||||
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><replaceable class="parameter">username</replaceable></term>
|
<term><replaceable class="parameter">username</replaceable></term>
|
||||||
|
@ -60,9 +61,9 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
<para>
|
<para>
|
||||||
The <literal>SYSID</literal> clause can be used to choose the
|
The <literal>SYSID</literal> clause can be used to choose the
|
||||||
<productname>PostgreSQL</productname> user ID of the user that
|
<productname>PostgreSQL</productname> user ID of the user that
|
||||||
is being created. It is not at all necessary that those match
|
is being created. This is not normally not necessary, but may
|
||||||
the Unix user IDs, but some people choose to keep the numbers
|
be useful if you need to recreate the owner of an orphaned
|
||||||
the same.
|
object.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
If this is not specified, the highest assigned user ID plus one
|
If this is not specified, the highest assigned user ID plus one
|
||||||
|
@ -76,10 +77,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Sets the user's password. If you do not plan to use password
|
Sets the user's password. If you do not plan to use password
|
||||||
authentication you can omit this option, but the user
|
authentication you can omit this option, but then the user
|
||||||
won't be able to connect to a password-authenticated server.
|
won't be able to connect if you decide to switch to password
|
||||||
The password can be set or changed later, using
|
authentication. The password can be set or changed later,
|
||||||
<xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title">.
|
using <xref linkend="SQL-ALTERUSER"
|
||||||
|
endterm="SQL-ALTERUSER-title">.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -89,23 +91,22 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
<term><literal>UNENCRYPTED</></term>
|
<term><literal>UNENCRYPTED</></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
These keywords control whether the password is stored
|
These key words control whether the password is stored
|
||||||
encrypted in <literal>pg_shadow</>. (If neither is specified,
|
encrypted in the system catalogs. (If neither is specified,
|
||||||
the default behavior is determined by the
|
the default behavior is determined by the configuration
|
||||||
<varname>PASSWORD_ENCRYPTION</varname> server parameter.) If
|
parameter <varname>password_encryption</varname>.) If the
|
||||||
the presented string is already in MD5-encrypted format, then
|
presented password string is already in MD5-encrypted format,
|
||||||
it is stored as-is, regardless of whether
|
then it is stored encrypted as-is, regardless of whether
|
||||||
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified.
|
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
|
||||||
This allows reloading of encrypted passwords during
|
(since the system cannot decrypt the specified encrypted
|
||||||
dump/restore.
|
password string). This allows reloading of encrypted
|
||||||
|
passwords during dump/restore.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
See <xref linkend="client-authentication">
|
Note that older clients may lack support for the MD5
|
||||||
for details on how to set up authentication mechanisms. Note
|
authentication mechanism that is needed to work with passwords
|
||||||
that older clients may lack support for the MD5 authentication
|
that are stored encrypted.
|
||||||
mechanism that is needed to work with passwords that are
|
|
||||||
stored encrypted.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -160,26 +161,21 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Diagnostics</title>
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
<para>
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><computeroutput>CREATE USER</computeroutput></term>
|
<term><computeroutput>CREATE USER</computeroutput></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Message returned if the command completes successfully.
|
Message returned if the user account was successfully created.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</variablelist>
|
||||||
</para>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
@ -191,9 +187,12 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
|
||||||
endterm="SQL-DROPUSER-title"> to remove a user. Use <xref
|
endterm="SQL-DROPUSER-title"> to remove a user. Use <xref
|
||||||
linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
|
linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
|
||||||
user to groups or remove the user from groups.
|
user to groups or remove the user from groups.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
<productname>PostgreSQL</productname> includes a program <xref
|
<productname>PostgreSQL</productname> includes a program <xref
|
||||||
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has
|
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has
|
||||||
the same functionality as this command (in fact, it calls this
|
the same functionality as <command>CREATE USER</command> (in fact, it calls this
|
||||||
command) but can be run from the command shell.
|
command) but can be run from the command shell.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
@ -216,12 +215,12 @@ CREATE USER davide WITH PASSWORD 'jw8s0F4';
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Create a user with a password, whose account is valid until the end of 2001.
|
Create a user with a password that is valid until the end of 2004.
|
||||||
Note that after one second has ticked in 2002, the account is not
|
After one second has ticked in 2005, the password is no longer
|
||||||
valid:
|
valid.
|
||||||
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL 'Jan 1 2002';
|
CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
|
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.21 2002/11/21 23:34:43 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.22 2003/04/22 10:08:08 petere Exp $
|
||||||
PostgreSQL documentation
|
PostgreSQL documentation
|
||||||
-->
|
-->
|
||||||
|
|
||||||
|
@ -8,136 +8,26 @@ PostgreSQL documentation
|
||||||
<refentrytitle id="SQL-CREATEVIEW-TITLE">CREATE VIEW</refentrytitle>
|
<refentrytitle id="SQL-CREATEVIEW-TITLE">CREATE VIEW</refentrytitle>
|
||||||
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
||||||
</refmeta>
|
</refmeta>
|
||||||
|
|
||||||
<refnamediv>
|
<refnamediv>
|
||||||
<refname>
|
<refname>CREATE VIEW</refname>
|
||||||
CREATE VIEW
|
<refpurpose>define a new view</refpurpose>
|
||||||
</refname>
|
|
||||||
<refpurpose>
|
|
||||||
define a new view
|
|
||||||
</refpurpose>
|
|
||||||
</refnamediv>
|
</refnamediv>
|
||||||
|
|
||||||
<refsynopsisdiv>
|
<refsynopsisdiv>
|
||||||
<refsynopsisdivinfo>
|
<synopsis>
|
||||||
<date>2000-03-25</date>
|
CREATE [ OR REPLACE ] VIEW <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable
|
||||||
</refsynopsisdivinfo>
|
class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="PARAMETER">query</replaceable>
|
||||||
<synopsis>
|
</synopsis>
|
||||||
CREATE [ OR REPLACE ] VIEW <replaceable class="PARAMETER">view</replaceable> [ ( <replaceable
|
|
||||||
class="PARAMETER">column name list</replaceable> ) ] AS SELECT <replaceable class="PARAMETER">query</replaceable>
|
|
||||||
</synopsis>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEVIEW-1">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Inputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">view</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The name (optionally schema-qualified) of a view to be created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">column name list</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
An optional list of names to be used for columns of the view.
|
|
||||||
If given, these names override the column names that would be
|
|
||||||
deduced from the SQL query.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><replaceable class="parameter">query</replaceable></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
An SQL query (that is, a <command>SELECT</> statement)
|
|
||||||
which will provide the columns and rows of the view.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
Refer to <xref linkend="sql-select" endterm="sql-select-title"> for more information
|
|
||||||
about valid arguments.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEVIEW-2">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
Outputs
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
<variablelist>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
CREATE VIEW
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The message returned if the view is successfully created.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
ERROR: Relation '<replaceable class="parameter">view</replaceable>' already exists
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
This error occurs if the view specified already exists in the database.
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term><computeroutput>
|
|
||||||
WARNING: Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type
|
|
||||||
</computeroutput></term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The view will be created having a column with an unknown type
|
|
||||||
if you do not specify it. For example, the following command gives
|
|
||||||
a warning:
|
|
||||||
<programlisting>
|
|
||||||
CREATE VIEW vista AS SELECT 'Hello World'
|
|
||||||
</programlisting>
|
|
||||||
|
|
||||||
whereas this command does not:
|
|
||||||
|
|
||||||
<programlisting>
|
|
||||||
CREATE VIEW vista AS SELECT text 'Hello World'
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</para>
|
|
||||||
</refsect2>
|
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEVIEW-1">
|
<refsect1>
|
||||||
<refsect1info>
|
<title>Description</title>
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect1info>
|
|
||||||
<title>
|
|
||||||
Description
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>CREATE VIEW</command> defines a view of a query.
|
<command>CREATE VIEW</command> defines a view of a query. The view
|
||||||
The view is not physically materialized. Instead, a query
|
is not physically materialized. Instead, the query is run everytime
|
||||||
rewrite rule (an <literal>ON SELECT</> rule) is automatically generated to
|
the view is referenced in a query.
|
||||||
support SELECT operations on views.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -150,19 +40,87 @@ CREATE VIEW vista AS SELECT text 'Hello World'
|
||||||
<para>
|
<para>
|
||||||
If a schema name is given (for example, <literal>CREATE VIEW
|
If a schema name is given (for example, <literal>CREATE VIEW
|
||||||
myschema.myview ...</>) then the view is created in the
|
myschema.myview ...</>) then the view is created in the
|
||||||
specified schema. Otherwise it is created in the current schema (the one
|
specified schema. Otherwise it is created in the current schema.
|
||||||
at the front of the search path; see <literal>CURRENT_SCHEMA()</>).
|
|
||||||
The view name must be distinct from the name of any other view, table,
|
The view name must be distinct from the name of any other view, table,
|
||||||
sequence, or index in the same schema.
|
sequence, or index in the same schema.
|
||||||
</para>
|
</para>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEVIEW-3">
|
<refsect1>
|
||||||
<refsect2info>
|
<title>Parameters</title>
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
<variablelist>
|
||||||
<title>
|
<varlistentry>
|
||||||
Notes
|
<term><replaceable class="parameter">name</replaceable></term>
|
||||||
</title>
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The name (optionally schema-qualified) of a view to be created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">column_name</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
An optional list of names to be used for columns of the view.
|
||||||
|
If not given, the column names are deduced from the query.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><replaceable class="parameter">query</replaceable></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
A query (that is, a <command>SELECT</> statement) which will
|
||||||
|
provide the columns and rows of the view.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Refer to <xref linkend="sql-select" endterm="sql-select-title">
|
||||||
|
for more information about valid queries.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Diagnostics</title>
|
||||||
|
|
||||||
|
<variablelist>
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>CREATE VIEW</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Message returned if the view was successfully created.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
|
<varlistentry>
|
||||||
|
<term><computeroutput>WARNING: Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type</computeroutput></term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
The view will be created having a column with an unknown type if
|
||||||
|
you do not specify it. For example, the following command gives
|
||||||
|
this warning:
|
||||||
|
<programlisting>
|
||||||
|
CREATE VIEW vista AS SELECT 'Hello World'
|
||||||
|
</programlisting>
|
||||||
|
whereas this command does not:
|
||||||
|
<programlisting>
|
||||||
|
CREATE VIEW vista AS SELECT text 'Hello World'
|
||||||
|
</programlisting>
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
</refsect1>
|
||||||
|
|
||||||
|
<refsect1>
|
||||||
|
<title>Notes</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Currently, views are read only: the system will not allow an insert,
|
Currently, views are read only: the system will not allow an insert,
|
||||||
|
@ -175,75 +133,55 @@ CREATE VIEW vista AS SELECT text 'Hello World'
|
||||||
<para>
|
<para>
|
||||||
Use the <command>DROP VIEW</command> statement to drop views.
|
Use the <command>DROP VIEW</command> statement to drop views.
|
||||||
</para>
|
</para>
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEVIEW-2">
|
<refsect1>
|
||||||
<title>
|
<title>Examples</title>
|
||||||
Usage
|
|
||||||
</title>
|
|
||||||
<para>
|
|
||||||
Create a view consisting of all Comedy films:
|
|
||||||
|
|
||||||
<programlisting>
|
<para>
|
||||||
CREATE VIEW kinds AS
|
Create a view consisting of all comedy films:
|
||||||
|
|
||||||
|
<programlisting>
|
||||||
|
CREATE VIEW comedies AS
|
||||||
SELECT *
|
SELECT *
|
||||||
FROM films
|
FROM films
|
||||||
WHERE kind = 'Comedy';
|
WHERE kind = 'Comedy';
|
||||||
|
</programlisting>
|
||||||
SELECT * FROM kinds;
|
|
||||||
|
|
||||||
code | title | did | date_prod | kind | len
|
|
||||||
-------+---------------------------+-----+------------+--------+-------
|
|
||||||
UA502 | Bananas | 105 | 1971-07-13 | Comedy | 01:22
|
|
||||||
C_701 | There's a Girl in my Soup | 107 | 1970-06-11 | Comedy | 01:36
|
|
||||||
(2 rows)
|
|
||||||
</programlisting>
|
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1 id="R1-SQL-CREATEVIEW-3">
|
<refsect1>
|
||||||
<title>
|
<title>Compatibility</title>
|
||||||
Compatibility
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<refsect2 id="R2-SQL-CREATEVIEW-5">
|
|
||||||
<refsect2info>
|
|
||||||
<date>2000-03-25</date>
|
|
||||||
</refsect2info>
|
|
||||||
<title>
|
|
||||||
SQL92
|
|
||||||
</title>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
SQL92 specifies some additional capabilities for the
|
The SQL standard specifies some additional capabilities for the
|
||||||
<command>CREATE VIEW</command> statement:
|
<command>CREATE VIEW</command> statement:
|
||||||
</para>
|
<synopsis>
|
||||||
<synopsis>
|
CREATE VIEW <replaceable class="parameter">name</replaceable> [ ( <replaceable class="parameter">column</replaceable> [, ...] ) ]
|
||||||
CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable class="parameter">column</replaceable> [, ...] ]
|
AS query
|
||||||
AS SELECT <replaceable class="parameter">expression</replaceable> [ AS <replaceable class="parameter">colname</replaceable> ] [, ...]
|
|
||||||
FROM <replaceable class="parameter">table</replaceable> [ WHERE <replaceable class="parameter">condition</replaceable> ]
|
|
||||||
[ WITH [ CASCADE | LOCAL ] CHECK OPTION ]
|
[ WITH [ CASCADE | LOCAL ] CHECK OPTION ]
|
||||||
</synopsis>
|
</synopsis>
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The optional clauses for the full SQL92 command are:
|
The optional clauses for the full SQL command are:
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>CHECK OPTION</term>
|
<term><literal>CHECK OPTION</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
This option is to do with updatable views.
|
This option is to do with updatable views. All
|
||||||
All <command>INSERT</> and <command>UPDATE</> commands on the view will be
|
<command>INSERT</> and <command>UPDATE</> commands on the view
|
||||||
checked to ensure data satisfy the view-defining
|
will be checked to ensure data satisfy the view-defining
|
||||||
condition. If they do not, the update will be rejected.
|
condition (that is, the new data would be visible through the
|
||||||
|
view). If they do not, the update will be rejected.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>LOCAL</term>
|
<term><literal>LOCAL</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Check for integrity on this view.
|
Check for integrity on this view.
|
||||||
|
@ -252,11 +190,12 @@ CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable cla
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>CASCADE</term>
|
<term><literal>CASCADE</literal></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Check for integrity on this view and on any dependent
|
Check for integrity on this view and on any dependent
|
||||||
view. CASCADE is assumed if neither CASCADE nor LOCAL is specified.
|
view. <literal>CASCADE</> is assumed if neither
|
||||||
|
<literal>CASCADE</> nor <literal>LOCAL</> is specified.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -267,8 +206,6 @@ CREATE VIEW <replaceable class="parameter">view</replaceable> [ <replaceable cla
|
||||||
<command>CREATE OR REPLACE VIEW</command> is a
|
<command>CREATE OR REPLACE VIEW</command> is a
|
||||||
<productname>PostgreSQL</productname> language extension.
|
<productname>PostgreSQL</productname> language extension.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
</refsect2>
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
</refentry>
|
</refentry>
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue