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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.36 2003/08/17 22:09:00 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEOPERATOR">
   7  <refmeta>
   8   <refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE OPERATOR</refname>
  14   <refpurpose>define a new operator</refpurpose>
  15  </refnamediv>
  16
  17  <refsynopsisdiv>
  18 <synopsis>
  19 CREATE OPERATOR <replaceable>name</replaceable> (
  20     PROCEDURE = <replaceable class="parameter">func_name</replaceable>
  21     [, LEFTARG = <replaceable class="parameter">lefttype</replaceable> ] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
  22     [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
  23     [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
  24     [, HASHES ] [, MERGES ]
  25     [, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
  26     [, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ]
  27 )
  28 </synopsis>
  29  </refsynopsisdiv>
  30
  31  <refsect1>
  32   <title>Description</title>
  33
  34   <para>
  35    <command>CREATE OPERATOR</command> defines a new operator,
  36    <replaceable class="parameter">name</replaceable>.  The user who
  37    defines an operator becomes its owner.  If a schema name is given
  38    then the operator is created in the specified schema.  Otherwise it
  39    is created in the current schema.
  40   </para>
  41
  42   <para>
  43    The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
  44    (63 by default) characters from the following list:
  45 <literallayout>
  46 + - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?
  47 </literallayout>
  48
  49    There are a few restrictions on your choice of name:
  50    <itemizedlist>
  51     <listitem>
  52      <para>
  53      <literal>--</literal> and <literal>/*</literal> cannot appear anywhere in an operator name,
  54      since they will be taken as the start of a comment.
  55      </para>
  56     </listitem>
  57     <listitem>
  58      <para>
  59      A multicharacter operator name cannot end in <literal>+</literal> or
  60      <literal>-</literal>,
  61      unless the name also contains at least one of these characters:
  62 <literallayout>
  63 ~ ! @ # % ^ &amp; | ` ?
  64 </literallayout>
  65      For example, <literal>@-</literal> is an allowed operator name,
  66      but <literal>*-</literal> is not.
  67      This restriction allows <productname>PostgreSQL</productname> to
  68      parse SQL-compliant commands without requiring spaces between tokens.
  69      </para>
  70     </listitem>
  71    </itemizedlist>
  72   </para>
  73
  74   <para>
  75    The operator <literal>!=</literal> is mapped to
  76    <literal>&lt;&gt;</literal> on input, so these two names are always
  77    equivalent.
  78   </para>
  79
  80   <para>
  81    At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined.  For
  82    binary operators, both must be defined. For right  unary
  83    operators, only <literal>LEFTARG</> should be defined, while for left
  84    unary operators only <literal>RIGHTARG</> should be defined.
  85   </para>
  86
  87   <para>
  88    The <replaceable class="parameter">func_name</replaceable>
  89    procedure must have been previously defined using <command>CREATE
  90    FUNCTION</command> and must be defined to accept the correct number
  91    of arguments (either one or two) of the indicated types.
  92   </para>
  93
  94   <para>
  95    The other clauses specify optional operator optimization clauses.
  96    Their meaning is detailed in <xref linkend="xoper">.
  97   </para>
  98  </refsect1>
  99
 100  <refsect1>
 101   <title>Parameters</title>
 102
 103     <variablelist>
 104      <varlistentry>
 105       <term><replaceable class="parameter">name</replaceable></term>
 106       <listitem>
 107        <para>
 108         The name of the operator to be defined. See above for allowable
 109         characters.  The name may be schema-qualified, for example
 110         <literal>CREATE OPERATOR myschema.+ (...)</>.  If not, then
 111         the operator is created in the current schema.  Two operators
 112         in the same schema can have the same name if they operate on
 113         different data types.  This is called
 114         <firstterm>overloading</>.
 115        </para>
 116       </listitem>
 117      </varlistentry>
 118
 119      <varlistentry>
 120       <term><replaceable class="parameter">func_name</replaceable></term>
 121       <listitem>
 122        <para>
 123         The function used to implement this operator.
 124        </para>
 125       </listitem>
 126      </varlistentry>
 127
 128      <varlistentry>
 129       <term><replaceable class="parameter">lefttype</replaceable></term>
 130       <listitem>
 131        <para>
 132         The type of the left-hand argument of the operator, if any.
 133         This option would be omitted for a left-unary operator.
 134        </para>
 135       </listitem>
 136      </varlistentry>
 137
 138      <varlistentry>
 139       <term><replaceable class="parameter">righttype</replaceable></term>
 140       <listitem>
 141        <para>
 142         The type of the right-hand argument of the operator, if any.
 143         This option would be omitted for a right-unary operator.
 144        </para>
 145       </listitem>
 146      </varlistentry>
 147
 148      <varlistentry>
 149       <term><replaceable class="parameter">com_op</replaceable></term>
 150       <listitem>
 151        <para>
 152         The commutator of this operator.
 153        </para>
 154       </listitem>
 155      </varlistentry>
 156
 157      <varlistentry>
 158       <term><replaceable class="parameter">neg_op</replaceable></term>
 159       <listitem>
 160        <para>
 161         The negator of this operator.
 162        </para>
 163       </listitem>
 164      </varlistentry>
 165
 166      <varlistentry>
 167       <term><replaceable class="parameter">res_proc</replaceable></term>
 168       <listitem>
 169        <para>
 170         The restriction selectivity estimator function for this operator.
 171        </para>
 172       </listitem>
 173      </varlistentry>
 174
 175      <varlistentry>
 176       <term><replaceable class="parameter">join_proc</replaceable></term>
 177       <listitem>
 178        <para>
 179         The join selectivity estimator function for this operator.
 180        </para>
 181       </listitem>
 182      </varlistentry>
 183
 184      <varlistentry>
 185       <term><literal>HASHES</literal></term>
 186       <listitem>
 187        <para>
 188        Indicates this operator can support a hash join.
 189        </para>
 190       </listitem>
 191      </varlistentry>
 192
 193      <varlistentry>
 194       <term><literal>MERGES</literal></term>
 195       <listitem>
 196        <para>
 197        Indicates this operator can support a merge join.
 198        </para>
 199       </listitem>
 200      </varlistentry>
 201
 202      <varlistentry>
 203       <term><replaceable class="parameter">left_sort_op</replaceable></term>
 204       <listitem>
 205        <para>
 206         If this operator can support a merge join, the less-than
 207         operator that sorts the left-hand data type of this operator.
 208        </para>
 209       </listitem>
 210      </varlistentry>
 211
 212      <varlistentry>
 213       <term><replaceable class="parameter">right_sort_op</replaceable></term>
 214       <listitem>
 215        <para>
 216         If this operator can support a merge join, the less-than
 217         operator that sorts the right-hand data type of this operator.
 218        </para>
 219       </listitem>
 220      </varlistentry>
 221
 222      <varlistentry>
 223       <term><replaceable class="parameter">less_than_op</replaceable></term>
 224       <listitem>
 225        <para>
 226         If this operator can support a merge join, the less-than
 227         operator that compares the input data types of this operator.
 228        </para>
 229       </listitem>
 230      </varlistentry>
 231
 232      <varlistentry>
 233       <term><replaceable class="parameter">greater_than_op</replaceable></term>
 234       <listitem>
 235        <para>
 236         If this operator can support a merge join, the greater-than
 237         operator that compares the input data types of this operator.
 238        </para>
 239       </listitem>
 240      </varlistentry>
 241     </variablelist>
 242
 243   <para>
 244    To give a schema-qualified operator name in <replaceable
 245    class="parameter">com_op</replaceable> or the other optional
 246    arguments, use the <literal>OPERATOR()</> syntax, for example
 247 <programlisting>
 248 COMMUTATOR = OPERATOR(myschema.===) ,
 249 </programlisting>
 250   </para>
 251  </refsect1>
 252
 253  <refsect1>
 254   <title>Diagnostics</title>
 255
 256   <variablelist>
 257    <varlistentry>
 258     <term><computeroutput>CREATE OPERATOR</computeroutput></term>
 259     <listitem>
 260      <para>
 261       Message returned if the operator was successfully created.
 262      </para>
 263     </listitem>
 264    </varlistentry>
 265   </variablelist>
 266  </refsect1>
 267
 268  <refsect1>
 269   <title>Notes</title>
 270
 271   <para>
 272    Refer to <xref linkend="xoper"> for further information.
 273   </para>
 274
 275   <para>
 276    Use <command>DROP OPERATOR</command> to delete user-defined
 277    operators from a database.
 278   </para>
 279  </refsect1>
 280
 281  <refsect1>
 282   <title>Examples</title>
 283
 284   <para>
 285    The following command defines a new operator, area-equality, for
 286    the data type <type>box</type>:
 287 <programlisting>
 288 CREATE OPERATOR === (
 289     LEFTARG = box,
 290     RIGHTARG = box,
 291     PROCEDURE = area_equal_procedure,
 292     COMMUTATOR = ===,
 293     NEGATOR = !==,
 294     RESTRICT = area_restriction_procedure,
 295     JOIN = area_join_procedure,
 296     HASHES,
 297     SORT1 = &lt;&lt;&lt;,
 298     SORT2 = &lt;&lt;&lt;
 299     -- Since sort operators were given, MERGES is implied.
 300     -- LTCMP and GTCMP are assumed to be &lt; and &gt; respectively
 301 );
 302 </programlisting>
 303   </para>
 304  </refsect1>
 305
 306  <refsect1>
 307   <title>Compatibility</title>
 308
 309   <para>
 310    <command>CREATE OPERATOR</command> is a
 311    <productname>PostgreSQL</productname> extension.  There are no
 312    provisions for user-defined operators in the SQL standard.
 313   </para>
 314  </refsect1>
 315 </refentry>
 316
 317 <!-- Keep this comment at the end of the file
 318 Local variables:
 319 mode: sgml
 320 sgml-omittag:nil
 321 sgml-shorttag:t
 322 sgml-minimize-attributes:nil
 323 sgml-always-quote-attributes:t
 324 sgml-indent-step:1
 325 sgml-indent-data:t
 326 sgml-parent-document:nil
 327 sgml-default-dtd-file:"../reference.ced"
 328 sgml-exposed-tags:nil
 329 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 330 sgml-local-ecat-files:nil
 331 End:
 332 -->