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

   1 <!--
   2 doc/src/sgml/ref/create_operator.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEOPERATOR">
   7  <refmeta>
   8   <refentrytitle>CREATE OPERATOR</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>CREATE OPERATOR</refname>
  15   <refpurpose>define a new operator</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-createoperator">
  19   <primary>CREATE OPERATOR</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE OPERATOR <replaceable>name</replaceable> (
  25     PROCEDURE = <replaceable class="parameter">function_name</replaceable>
  26     [, LEFTARG = <replaceable class="parameter">left_type</replaceable> ] [, RIGHTARG = <replaceable class="parameter">right_type</replaceable> ]
  27     [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
  28     [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
  29     [, HASHES ] [, MERGES ]
  30 )
  31 </synopsis>
  32  </refsynopsisdiv>
  33
  34  <refsect1>
  35   <title>Description</title>
  36
  37   <para>
  38    <command>CREATE OPERATOR</command> defines a new operator,
  39    <replaceable class="parameter">name</replaceable>.  The user who
  40    defines an operator becomes its owner.  If a schema name is given
  41    then the operator is created in the specified schema.  Otherwise it
  42    is created in the current schema.
  43   </para>
  44
  45   <para>
  46    The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
  47    (63 by default) characters from the following list:
  48 <literallayout>
  49 + - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?
  50 </literallayout>
  51
  52    There are a few restrictions on your choice of name:
  53    <itemizedlist>
  54     <listitem>
  55      <para><literal>--</literal> and <literal>/*</literal> cannot appear anywhere in an operator name,
  56      since they will be taken as the start of a comment.
  57      </para>
  58     </listitem>
  59     <listitem>
  60      <para>
  61      A multicharacter operator name cannot end in <literal>+</literal> or
  62      <literal>-</literal>,
  63      unless the name also contains at least one of these characters:
  64 <literallayout>
  65 ~ ! @ # % ^ &amp; | ` ?
  66 </literallayout>
  67      For example, <literal>@-</literal> is an allowed operator name,
  68      but <literal>*-</literal> is not.
  69      This restriction allows <productname>PostgreSQL</productname> to
  70      parse SQL-compliant commands without requiring spaces between tokens.
  71      </para>
  72     </listitem>
  73     <listitem>
  74      <para>
  75      The use of <literal>=&gt;</> as an operator name is deprecated.  It may
  76      be disallowed altogether in a future release.
  77      </para>
  78     </listitem>
  79    </itemizedlist>
  80   </para>
  81
  82   <para>
  83    The operator <literal>!=</literal> is mapped to
  84    <literal>&lt;&gt;</literal> on input, so these two names are always
  85    equivalent.
  86   </para>
  87
  88   <para>
  89    At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined.  For
  90    binary operators, both must be defined. For right  unary
  91    operators, only <literal>LEFTARG</> should be defined, while for left
  92    unary operators only <literal>RIGHTARG</> should be defined.
  93   </para>
  94
  95   <para>
  96    The <replaceable class="parameter">function_name</replaceable>
  97    procedure must have been previously defined using <command>CREATE
  98    FUNCTION</command> and must be defined to accept the correct number
  99    of arguments (either one or two) of the indicated types.
 100   </para>
 101
 102   <para>
 103    The other clauses specify optional operator optimization clauses.
 104    Their meaning is detailed in <xref linkend="xoper-optimization">.
 105   </para>
 106  </refsect1>
 107
 108  <refsect1>
 109   <title>Parameters</title>
 110
 111     <variablelist>
 112      <varlistentry>
 113       <term><replaceable class="parameter">name</replaceable></term>
 114       <listitem>
 115        <para>
 116         The name of the operator to be defined. See above for allowable
 117         characters.  The name can be schema-qualified, for example
 118         <literal>CREATE OPERATOR myschema.+ (...)</>.  If not, then
 119         the operator is created in the current schema.  Two operators
 120         in the same schema can have the same name if they operate on
 121         different data types.  This is called
 122         <firstterm>overloading</>.
 123        </para>
 124       </listitem>
 125      </varlistentry>
 126
 127      <varlistentry>
 128       <term><replaceable class="parameter">function_name</replaceable></term>
 129       <listitem>
 130        <para>
 131         The function used to implement this operator.
 132        </para>
 133       </listitem>
 134      </varlistentry>
 135
 136      <varlistentry>
 137       <term><replaceable class="parameter">left_type</replaceable></term>
 138       <listitem>
 139        <para>
 140         The data type of the operator's left operand, if any.
 141         This option would be omitted for a left-unary operator.
 142        </para>
 143       </listitem>
 144      </varlistentry>
 145
 146      <varlistentry>
 147       <term><replaceable class="parameter">right_type</replaceable></term>
 148       <listitem>
 149        <para>
 150         The data type of the operator's right operand, if any.
 151         This option would be omitted for a right-unary operator.
 152        </para>
 153       </listitem>
 154      </varlistentry>
 155
 156      <varlistentry>
 157       <term><replaceable class="parameter">com_op</replaceable></term>
 158       <listitem>
 159        <para>
 160         The commutator of this operator.
 161        </para>
 162       </listitem>
 163      </varlistentry>
 164
 165      <varlistentry>
 166       <term><replaceable class="parameter">neg_op</replaceable></term>
 167       <listitem>
 168        <para>
 169         The negator of this operator.
 170        </para>
 171       </listitem>
 172      </varlistentry>
 173
 174      <varlistentry>
 175       <term><replaceable class="parameter">res_proc</replaceable></term>
 176       <listitem>
 177        <para>
 178         The restriction selectivity estimator function for this operator.
 179        </para>
 180       </listitem>
 181      </varlistentry>
 182
 183      <varlistentry>
 184       <term><replaceable class="parameter">join_proc</replaceable></term>
 185       <listitem>
 186        <para>
 187         The join selectivity estimator function for this operator.
 188        </para>
 189       </listitem>
 190      </varlistentry>
 191
 192      <varlistentry>
 193       <term><literal>HASHES</literal></term>
 194       <listitem>
 195        <para>
 196        Indicates this operator can support a hash join.
 197        </para>
 198       </listitem>
 199      </varlistentry>
 200
 201      <varlistentry>
 202       <term><literal>MERGES</literal></term>
 203       <listitem>
 204        <para>
 205        Indicates this operator can support a merge join.
 206        </para>
 207       </listitem>
 208      </varlistentry>
 209     </variablelist>
 210
 211   <para>
 212    To give a schema-qualified operator name in <replaceable
 213    class="parameter">com_op</replaceable> or the other optional
 214    arguments, use the <literal>OPERATOR()</> syntax, for example:
 215 <programlisting>
 216 COMMUTATOR = OPERATOR(myschema.===) ,
 217 </programlisting></para>
 218  </refsect1>
 219
 220  <refsect1>
 221   <title>Notes</title>
 222
 223   <para>
 224    Refer to <xref linkend="xoper"> for further information.
 225   </para>
 226
 227   <para>
 228    It is not possible to specify an operator's lexical precedence in
 229    <command>CREATE OPERATOR</>, because the parser's precedence behavior
 230    is hard-wired.  See <xref linkend="sql-precedence"> for precedence details.
 231   </para>
 232
 233   <para>
 234    The obsolete options <literal>SORT1</>, <literal>SORT2</>,
 235    <literal>LTCMP</>, and <literal>GTCMP</> were formerly used to
 236    specify the names of sort operators associated with a merge-joinable
 237    operator.  This is no longer necessary, since information about
 238    associated operators is found by looking at B-tree operator families
 239    instead.  If one of these options is given, it is ignored except
 240    for implicitly setting <literal>MERGES</> true.
 241   </para>
 242
 243   <para>
 244    Use <xref linkend="sql-dropoperator"> to delete user-defined operators
 245    from a database.  Use <xref linkend="sql-alteroperator"> to modify operators in a
 246    database.
 247   </para>
 248  </refsect1>
 249
 250  <refsect1>
 251   <title>Examples</title>
 252
 253   <para>
 254    The following command defines a new operator, area-equality, for
 255    the data type <type>box</type>:
 256 <programlisting>
 257 CREATE OPERATOR === (
 258     LEFTARG = box,
 259     RIGHTARG = box,
 260     PROCEDURE = area_equal_procedure,
 261     COMMUTATOR = ===,
 262     NEGATOR = !==,
 263     RESTRICT = area_restriction_procedure,
 264     JOIN = area_join_procedure,
 265     HASHES, MERGES
 266 );
 267 </programlisting></para>
 268  </refsect1>
 269
 270  <refsect1>
 271   <title>Compatibility</title>
 272
 273   <para>
 274    <command>CREATE OPERATOR</command> is a
 275    <productname>PostgreSQL</productname> extension.  There are no
 276    provisions for user-defined operators in the SQL standard.
 277   </para>
 278  </refsect1>
 279
 280  <refsect1>
 281   <title>See Also</title>
 282
 283   <simplelist type="inline">
 284    <member><xref linkend="sql-alteroperator"></member>
 285    <member><xref linkend="sql-createopclass"></member>
 286    <member><xref linkend="sql-dropoperator"></member>
 287   </simplelist>
 288  </refsect1>
 289 </refentry>