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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/alter_opfamily.sgml,v 1.7 2010/04/03 07:22:57 petere Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-ALTEROPFAMILY">
   7  <refmeta>
   8   <refentrytitle>ALTER OPERATOR FAMILY</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>ALTER OPERATOR FAMILY</refname>
  15   <refpurpose>change the definition of an operator family</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-alteropfamily">
  19   <primary>ALTER OPERATOR FAMILY</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> ADD
  25   {  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> )
  26    | FUNCTION <replaceable class="parameter">support_number</replaceable> [ ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] ) ] <replaceable class="parameter">function_name</replaceable> ( <replaceable class="parameter">argument_type</replaceable> [, ...] )
  27   } [, ... ]
  28 ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> DROP
  29   {  OPERATOR <replaceable class="parameter">strategy_number</replaceable> ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] )
  30    | FUNCTION <replaceable class="parameter">support_number</replaceable> ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] )
  31   } [, ... ]
  32 ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> RENAME TO <replaceable>new_name</replaceable>
  33 ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> OWNER TO <replaceable>new_owner</replaceable>
  34 </synopsis>
  35  </refsynopsisdiv>
  36
  37  <refsect1>
  38   <title>Description</title>
  39
  40   <para>
  41    <command>ALTER OPERATOR FAMILY</command> changes the definition of
  42    an operator family.  You can add operators and support functions
  43    to the family, remove them from the family,
  44    or change the family's name or owner.
  45   </para>
  46
  47   <para>
  48    When operators and support functions are added to a family with
  49    <command>ALTER OPERATOR FAMILY</command>, they are not part of any
  50    specific operator class within the family, but are just <quote>loose</>
  51    within the family.  This indicates that these operators and functions
  52    are compatible with the family's semantics, but are not required for
  53    correct functioning of any specific index.  (Operators and functions
  54    that are so required should be declared as part of an operator class,
  55    instead; see <xref linkend="sql-createopclass">.)
  56    <productname>PostgreSQL</productname> will allow loose members of a
  57    family to be dropped from the family at any time, but members of an
  58    operator class cannot be dropped without dropping the whole class and
  59    any indexes that depend on it.
  60    Typically, single-data-type operators
  61    and functions are part of operator classes because they are needed to
  62    support an index on that specific data type, while cross-data-type
  63    operators and functions are made loose members of the family.
  64   </para>
  65
  66   <para>
  67    You must be a superuser to use <command>ALTER OPERATOR FAMILY</>.
  68    (This restriction is made because an erroneous operator family definition
  69    could confuse or even crash the server.)
  70   </para>
  71
  72   <para>
  73    <command>ALTER OPERATOR FAMILY</command> does not presently check
  74    whether the operator family definition includes all the operators and
  75    functions required by the index method, nor whether the operators and
  76    functions form a self-consistent set.  It is the user's
  77    responsibility to define a valid operator family.
  78   </para>
  79
  80   <para>
  81    Refer to <xref linkend="xindex"> for further information.
  82   </para>
  83  </refsect1>
  84
  85  <refsect1>
  86   <title>Parameters</title>
  87
  88   <variablelist>
  89    <varlistentry>
  90     <term><replaceable class="parameter">name</replaceable></term>
  91     <listitem>
  92      <para>
  93       The name (optionally schema-qualified) of an existing operator
  94       family.
  95      </para>
  96     </listitem>
  97    </varlistentry>
  98
  99    <varlistentry>
 100     <term><replaceable class="parameter">index_method</replaceable></term>
 101     <listitem>
 102      <para>
 103       The name of the index method this operator family is for.
 104      </para>
 105     </listitem>
 106    </varlistentry>
 107
 108    <varlistentry>
 109     <term><replaceable class="parameter">strategy_number</replaceable></term>
 110     <listitem>
 111      <para>
 112       The index method's strategy number for an operator
 113       associated with the operator family.
 114      </para>
 115     </listitem>
 116    </varlistentry>
 117
 118    <varlistentry>
 119     <term><replaceable class="parameter">operator_name</replaceable></term>
 120     <listitem>
 121      <para>
 122       The name (optionally schema-qualified) of an operator associated
 123       with the operator family.
 124      </para>
 125     </listitem>
 126    </varlistentry>
 127
 128    <varlistentry>
 129     <term><replaceable class="parameter">op_type</replaceable></term>
 130     <listitem>
 131      <para>
 132       In an <literal>OPERATOR</> clause,
 133       the operand data type(s) of the operator, or <literal>NONE</> to
 134       signify a left-unary or right-unary operator.  Unlike the comparable
 135       syntax in <command>CREATE OPERATOR CLASS</>, the operand data types
 136       must always be specified.
 137      </para>
 138
 139      <para>
 140       In an <literal>ADD FUNCTION</> clause, the operand data type(s) the
 141       function is intended to support, if different from
 142       the input data type(s) of the function.  For B-tree and hash indexes
 143       it is not necessary to specify <replaceable
 144       class="parameter">op_type</replaceable> since the function's input
 145       data type(s) are always the correct ones to use.  For GIN and GiST
 146       indexes it is necessary to specify the input data type the function
 147       is to be used with.
 148      </para>
 149
 150      <para>
 151       In a <literal>DROP FUNCTION</> clause, the operand data type(s) the
 152       function is intended to support must be specified.
 153      </para>
 154     </listitem>
 155    </varlistentry>
 156
 157    <varlistentry>
 158     <term><replaceable class="parameter">support_number</replaceable></term>
 159     <listitem>
 160      <para>
 161       The index method's support procedure number for a
 162       function associated with the operator family.
 163      </para>
 164     </listitem>
 165    </varlistentry>
 166
 167    <varlistentry>
 168     <term><replaceable class="parameter">function_name</replaceable></term>
 169     <listitem>
 170      <para>
 171       The name (optionally schema-qualified) of a function that is an
 172       index method support procedure for the operator family.
 173      </para>
 174     </listitem>
 175    </varlistentry>
 176
 177    <varlistentry>
 178     <term><replaceable class="parameter">argument_type</replaceable></term>
 179     <listitem>
 180      <para>
 181       The parameter data type(s) of the function.
 182      </para>
 183     </listitem>
 184    </varlistentry>
 185
 186    <varlistentry>
 187     <term><replaceable class="parameter">new_name</replaceable></term>
 188     <listitem>
 189      <para>
 190       The new name of the operator family.
 191      </para>
 192     </listitem>
 193    </varlistentry>
 194
 195    <varlistentry>
 196     <term><replaceable class="parameter">new_owner</replaceable></term>
 197     <listitem>
 198      <para>
 199       The new owner of the operator family.
 200      </para>
 201     </listitem>
 202    </varlistentry>
 203  </variablelist>
 204
 205   <para>
 206    The <literal>OPERATOR</> and <literal>FUNCTION</>
 207    clauses can appear in any order.
 208   </para>
 209
 210  </refsect1>
 211
 212  <refsect1>
 213   <title>Notes</title>
 214
 215   <para>
 216    Notice that the <literal>DROP</> syntax only specifies the <quote>slot</>
 217    in the operator family, by strategy or support number and input data
 218    type(s).  The name of the operator or function occupying the slot is not
 219    mentioned.  Also, for <literal>DROP FUNCTION</> the type(s) to specify
 220    are the input data type(s) the function is intended to support; for
 221    GIN and GiST indexes this might have nothing to do with the actual input
 222    argument types of the function.
 223   </para>
 224
 225   <para>
 226    Because the index machinery does not check access permissions on functions
 227    before using them, including a function or operator in an operator family
 228    is tantamount to granting public execute permission on it.  This is usually
 229    not an issue for the sorts of functions that are useful in an operator
 230    family.
 231   </para>
 232
 233   <para>
 234    The operators should not be defined by SQL functions.  A SQL function
 235    is likely to be inlined into the calling query, which will prevent
 236    the optimizer from recognizing that the query matches an index.
 237   </para>
 238
 239   <para>
 240    Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</>
 241    clause could include a <literal>RECHECK</> option.  This is no longer
 242    supported because whether an index operator is <quote>lossy</> is now
 243    determined on-the-fly at runtime.  This allows efficient handling of
 244    cases where an operator might or might not be lossy.
 245   </para>
 246  </refsect1>
 247
 248  <refsect1>
 249   <title>Examples</title>
 250
 251   <para>
 252    The following example command adds cross-data-type operators and
 253    support functions to an operator family that already contains B-tree
 254    operator classes for data types <type>int4</> and <type>int2</>.
 255   </para>
 256
 257 <programlisting>
 258 ALTER OPERATOR FAMILY integer_ops USING btree ADD
 259
 260   -- int4 vs int2
 261   OPERATOR 1 &lt; (int4, int2) ,
 262   OPERATOR 2 &lt;= (int4, int2) ,
 263   OPERATOR 3 = (int4, int2) ,
 264   OPERATOR 4 &gt;= (int4, int2) ,
 265   OPERATOR 5 &gt; (int4, int2) ,
 266   FUNCTION 1 btint42cmp(int4, int2) ,
 267
 268   -- int2 vs int4
 269   OPERATOR 1 &lt; (int2, int4) ,
 270   OPERATOR 2 &lt;= (int2, int4) ,
 271   OPERATOR 3 = (int2, int4) ,
 272   OPERATOR 4 &gt;= (int2, int4) ,
 273   OPERATOR 5 &gt; (int2, int4) ,
 274   FUNCTION 1 btint24cmp(int2, int4) ;
 275 </programlisting>
 276
 277   <para>
 278    To remove these entries again:
 279   </para>
 280
 281 <programlisting>
 282 ALTER OPERATOR FAMILY integer_ops USING btree DROP
 283
 284   -- int4 vs int2
 285   OPERATOR 1 (int4, int2) ,
 286   OPERATOR 2 (int4, int2) ,
 287   OPERATOR 3 (int4, int2) ,
 288   OPERATOR 4 (int4, int2) ,
 289   OPERATOR 5 (int4, int2) ,
 290   FUNCTION 1 (int4, int2) ,
 291
 292   -- int2 vs int4
 293   OPERATOR 1 (int2, int4) ,
 294   OPERATOR 2 (int2, int4) ,
 295   OPERATOR 3 (int2, int4) ,
 296   OPERATOR 4 (int2, int4) ,
 297   OPERATOR 5 (int2, int4) ,
 298   FUNCTION 1 (int2, int4) ;
 299 </programlisting>
 300  </refsect1>
 301
 302  <refsect1>
 303   <title>Compatibility</title>
 304
 305   <para>
 306    There is no <command>ALTER OPERATOR FAMILY</command> statement in
 307    the SQL standard.
 308   </para>
 309  </refsect1>
 310
 311  <refsect1>
 312   <title>See Also</title>
 313
 314   <simplelist type="inline">
 315    <member><xref linkend="sql-createopfamily"></member>
 316    <member><xref linkend="sql-dropopfamily"></member>
 317    <member><xref linkend="sql-createopclass"></member>
 318    <member><xref linkend="sql-alteropclass"></member>
 319    <member><xref linkend="sql-dropopclass"></member>
 320   </simplelist>
 321  </refsect1>
 322 </refentry>