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.19 2001/05/08 17:51:30 momjian Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEOPERATOR">
   7  <refmeta>
   8   <refentrytitle id="sql-createoperator-title">
   9    CREATE OPERATOR
  10   </refentrytitle>
  11   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    CREATE OPERATOR
  16   </refname>
  17   <refpurpose>
  18    Defines a new user operator
  19   </refpurpose>
  20   </refnamediv>
  21  <refsynopsisdiv>
  22   <refsynopsisdivinfo>
  23    <date>2000-03-25</date>
  24   </refsynopsisdivinfo>
  25   <synopsis>
  26 CREATE OPERATOR <replaceable>name</replaceable> ( PROCEDURE = <replaceable class="parameter">func_name</replaceable>
  27      [, LEFTARG = <replaceable class="parameter">lefttype</replaceable>
  28      ] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
  29      [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
  30      [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
  31      [, HASHES ] [, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ] )
  32   </synopsis>
  33
  34   <refsect2 id="R2-SQL-CREATEOPERATOR-1">
  35    <refsect2info>
  36     <date>2000-03-25</date>
  37    </refsect2info>
  38    <title>
  39     Inputs
  40    </title>
  41    <para>
  42
  43     <variablelist>
  44      <varlistentry>
  45       <term><replaceable class="parameter">name</replaceable></term>
  46       <listitem>
  47        <para>
  48         The operator to be defined. See below for allowable characters.
  49        </para>
  50       </listitem>
  51      </varlistentry>
  52      <varlistentry>
  53       <term><replaceable class="parameter">func_name</replaceable></term>
  54       <listitem>
  55        <para>
  56         The function used to implement this operator.
  57        </para>
  58       </listitem>
  59      </varlistentry>
  60      <varlistentry>
  61       <term><replaceable class="parameter">lefttype</replaceable></term>
  62       <listitem>
  63        <para>
  64         The type of the left-hand argument of the operator, if any.
  65         This option would be omitted for a left-unary operator.
  66        </para>
  67       </listitem>
  68      </varlistentry>
  69      <varlistentry>
  70       <term><replaceable class="parameter">righttype</replaceable></term>
  71       <listitem>
  72        <para>
  73         The type of the right-hand argument of the operator, if any.
  74         This option would be omitted for a right-unary operator.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78      <varlistentry>
  79       <term><replaceable class="parameter">com_op</replaceable></term>
  80       <listitem>
  81        <para>
  82         The commutator of this operator.
  83        </para>
  84       </listitem>
  85      </varlistentry>
  86      <varlistentry>
  87       <term><replaceable class="parameter">neg_op</replaceable></term>
  88       <listitem>
  89        <para>
  90         The negator of this operator.
  91        </para>
  92       </listitem>
  93      </varlistentry>
  94      <varlistentry>
  95       <term><replaceable class="parameter">res_proc</replaceable></term>
  96       <listitem>
  97        <para>
  98         The restriction selectivity estimator function for this operator.
  99        </para>
 100       </listitem>
 101      </varlistentry>
 102      <varlistentry>
 103       <term><replaceable class="parameter">join_proc</replaceable></term>
 104       <listitem>
 105        <para>
 106         The join selectivity estimator function for this operator.
 107        </para>
 108       </listitem>
 109      </varlistentry>
 110      <varlistentry>
 111       <term>HASHES</term>
 112       <listitem>
 113        <para>
 114        Indicates this operator can support a hash join.
 115        </para>
 116       </listitem>
 117      </varlistentry>
 118      <varlistentry>
 119       <term><replaceable class="parameter">left_sort_op</replaceable></term>
 120       <listitem>
 121        <para>
 122         If this operator can support a merge join, the
 123         operator that sorts the left-hand data type of this operator.
 124        </para>
 125       </listitem>
 126      </varlistentry>
 127      <varlistentry>
 128       <term><replaceable class="parameter">right_sort_op</replaceable></term>
 129       <listitem>
 130        <para>
 131         If this operator can support a merge join, the
 132         operator that sorts the right-hand data type of this operator.
 133        </para>
 134       </listitem>
 135      </varlistentry>
 136     </variablelist>
 137    </para>
 138   </refsect2>
 139
 140   <refsect2 id="R2-SQL-CREATEOPERATOR-2">
 141    <refsect2info>
 142     <date>2000-03-25</date>
 143    </refsect2info>
 144    <title>
 145     Outputs
 146    </title>
 147    <para>
 148     <variablelist>
 149      <varlistentry>
 150       <term><computeroutput>
 151 CREATE
 152        </computeroutput></term>
 153       <listitem>
 154        <para>
 155         Message returned if the operator is successfully created.
 156        </para>
 157       </listitem>
 158      </varlistentry>
 159     </variablelist>
 160    </para>
 161   </refsect2>
 162  </refsynopsisdiv>
 163
 164  <refsect1 id="R1-SQL-CREATEOPERATOR-1">
 165   <refsect1info>
 166    <date>2000-03-25</date>
 167   </refsect1info>
 168   <title>
 169    Description
 170   </title>
 171   <para>
 172    <command>CREATE OPERATOR</command>  defines a new operator,
 173    <replaceable class="parameter">name</replaceable>.
 174    The user who defines an operator becomes its owner.
 175   </para>
 176   <para>
 177    The operator <replaceable class="parameter">name</replaceable>
 178    is a sequence of up to NAMEDATALEN-1 (31 by default) characters
 179    from the following list:
 180    <literallayout>
 181 + - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ? $
 182    </literallayout>
 183
 184    There are a few restrictions on your choice of name:
 185    <itemizedlist>
 186     <listitem>
 187      <para>
 188      "$" cannot be defined as a single-character operator,
 189      although it can be part of a multi-character operator name.
 190      </para>
 191     </listitem>
 192     <listitem>
 193      <para>
 194      "--" and "/*" cannot appear anywhere in an operator name,
 195      since they will be taken as the start of a comment.
 196      </para>
 197     </listitem>
 198     <listitem>
 199      <para>
 200      A multi-character operator name cannot end in "+" or "-",
 201      unless the name also contains at least one of these characters:
 202      <literallayout>
 203 ~ ! @ # % ^ &amp; | ` ? $
 204      </literallayout>
 205      For example, <literal>@-</literal> is an allowed operator name,
 206      but <literal>*-</literal> is not.
 207      This restriction allows <productname>Postgres</productname> to
 208      parse SQL-compliant queries without requiring spaces between tokens.
 209      </para>
 210     </listitem>
 211    </itemizedlist>
 212
 213    <note>
 214     <para>
 215      When working with non-SQL-standard operator names, you will usually
 216      need to separate adjacent operators with spaces to avoid ambiguity.
 217      For example, if you have defined a left-unary operator named "@",
 218      you cannot write <literal>X*@Y</literal>; you must write
 219      <literal>X* @Y</literal> to ensure that
 220      <productname>Postgres</productname> reads it as two operator names
 221      not one.
 222      </para>
 223    </note>
 224   </para>
 225   <para>
 226    The operator "!=" is mapped to "&lt;&gt;" on input, so these two names
 227    are always equivalent.
 228   </para>
 229   <para>
 230    At least one of LEFTARG and RIGHTARG must be defined.  For
 231    binary operators, both should be defined. For right  unary
 232    operators,  only  LEFTARG  should  be defined, while for left
 233    unary operators only RIGHTARG should be defined.
 234   </para>
 235   <para>
 236    The
 237    <replaceable class="parameter">func_name</replaceable> procedure must have
 238    been previously defined using <command>CREATE FUNCTION</command> and  must
 239    be defined to accept the correct number of arguments
 240    (either  one or two) of the indicated types.
 241   </para>
 242   <para>
 243    The commutator operator should be identified if one exists,
 244    so that <productname>Postgres</productname> can
 245    reverse the order of the operands if it wishes.
 246    For example, the operator area-less-than, &lt;&lt;&lt;,
 247    would probably have a commutator
 248    operator, area-greater-than, &gt;&gt;&gt;.
 249    Hence, the query optimizer could freely  convert:
 250
 251    <programlisting>
 252 box '((0,0), (1,1))'  &gt;&gt;&gt; MYBOXES.description
 253    </programlisting>
 254
 255    to
 256
 257    <programlisting>
 258 MYBOXES.description &lt;&lt;&lt; box '((0,0), (1,1))'
 259    </programlisting>
 260   </para>
 261   <para>
 262    This  allows  the  execution code to always use the latter
 263    representation and simplifies the  query  optimizer  somewhat.
 264   </para>
 265   <para>
 266    Similarly, if there is a negator operator then it should be
 267    identified.
 268    Suppose  that  an
 269    operator,  area-equal, ===, exists, as well as an area not
 270    equal, !==.
 271    The negator link allows the query optimizer to simplify
 272    <programlisting>
 273 NOT MYBOXES.description === box '((0,0), (1,1))'
 274    </programlisting>
 275    to
 276    <programlisting>
 277 MYBOXES.description !== box '((0,0), (1,1))'
 278    </programlisting>
 279   </para>
 280   <para>
 281    If  a  commutator  operator  name  is  supplied,
 282    <productname>Postgres</productname>
 283    searches  for  it  in  the catalog.  If it is found and it
 284    does not yet have a commutator itself, then the commutator's
 285    entry is updated to have the newly created operator as its
 286    commutator.  This applies to the negator, as well.
 287    This  is to allow the definition of two operators that are
 288    the commutators or the negators of each other.  The  first
 289    operator should be defined without a commutator or negator
 290    (as appropriate).  When the second  operator  is  defined,
 291    name  the  first  as the commutator or negator.  The first
 292    will be updated as a side effect.  (As of Postgres 6.5,
 293    it also works to just have both operators refer to each other.)
 294   </para>
 295   <para>
 296    The HASHES, SORT1, and SORT2 options are  present  to  support  the
 297    query  optimizer in performing joins.
 298    <productname>Postgres</productname> can always
 299    evaluate a join (i.e., processing a clause with two  tuple
 300    variables separated by an operator that returns a boolean)
 301    by iterative substitution [WONG76].
 302    In addition, <productname>Postgres</productname>
 303    can use a hash-join algorithm along
 304    the lines of [SHAP86]; however, it must know whether  this
 305    strategy  is  applicable.   The current hash-join algorithm
 306    is only correct for operators that represent equality tests;
 307    furthermore, equality of the data type must mean bitwise equality
 308    of the representation of the type.  (For example, a data type that
 309    contains unused bits that don't matter for equality tests could
 310    not be hashjoined.)
 311    The HASHES flag indicates to the query optimizer that a hash join
 312    may safely be used with this operator.</para>
 313   <para>
 314    Similarly, the two sort operators indicate  to  the  query
 315    optimizer whether merge-sort is a usable join strategy and
 316    which operators should be used  to  sort  the  two  operand
 317    classes.  Sort operators should only be provided for an equality
 318    operator, and they should refer to less-than operators for the
 319    left and right side data types respectively.
 320   </para>
 321   <para>
 322    If  other join strategies are found to be practical,
 323    <productname>Postgres</productname>
 324    will change the optimizer and run-time system to  use
 325    them  and  will  require  additional specification when an
 326    operator is defined.  Fortunately, the research  community
 327    invents  new  join  strategies infrequently, and the added
 328    generality of user-defined join strategies was not felt to
 329    be worth the complexity involved.
 330   </para>
 331   <para>
 332    The RESTRICT and JOIN options assist the query optimizer in estimating
 333    result sizes.  If a clause of the form:
 334    <programlisting>
 335 MYBOXES.description &lt;&lt;&lt; box '((0,0), (1,1))'
 336    </programlisting>
 337    is present in the qualification,
 338    then <productname>Postgres</productname> may have to
 339    estimate the fraction of the  instances  in  MYBOXES  that
 340    satisfy  the clause.  The function
 341    <replaceable class="parameter">res_proc</replaceable>
 342    must be a registered function (meaning  it  is  already  defined  using
 343    <command>CREATE FUNCTION</command>) which accepts arguments of the correct
 344    data types and returns a floating point  number.   The
 345    query  optimizer  simply  calls this function, passing the
 346    parameter <literal>((0,0), (1,1))</literal> and multiplies the result by the relation
 347    size to get the expected number of instances.
 348   </para>
 349   <para>
 350    Similarly, when the operands of the operator both  contain
 351    instance  variables, the query optimizer must estimate the
 352    size of the resulting join.  The function  join_proc  will
 353    return  another floating point number which will be multiplied
 354    by the cardinalities of the two tables involved  to
 355    compute the expected result size.
 356   </para>
 357   <para>
 358    The difference between the function
 359    <programlisting>
 360 my_procedure_1 (MYBOXES.description, box '((0,0), (1,1))')
 361    </programlisting>
 362    and the operator
 363    <programlisting>
 364 MYBOXES.description === box '((0,0), (1,1))'
 365    </programlisting>
 366    is  that  <productname>Postgres</productname>
 367    attempts to optimize operators and can
 368    decide to use an index to restrict the search  space  when
 369    operators  are  involved.  However, there is no attempt to
 370    optimize functions, and they are performed by brute force.
 371    Moreover, functions can have any number of arguments while
 372    operators are restricted to one or two.
 373   </para>
 374
 375   <refsect2 id="R2-SQL-CREATEOPERATOR-3">
 376    <refsect2info>
 377     <date>2000-03-25</date>
 378    </refsect2info>
 379    <title>
 380     Notes
 381    </title>
 382    <para>
 383     Refer to the chapter on operators in the
 384     <citetitle>PostgreSQL User's Guide</citetitle>
 385     for further information.
 386     Refer to <command>DROP OPERATOR</command> to delete
 387     user-defined operators from a database.
 388    </para>
 389   </refsect2>
 390  </refsect1>
 391
 392  <refsect1 id="R1-SQL-CREATEOPERATOR-2">
 393   <title>
 394    Usage
 395   </title>
 396   <para>The following command defines a new operator,
 397    area-equality, for the BOX data type:
 398   </para>
 399   <programlisting>
 400 CREATE OPERATOR === (
 401    LEFTARG = box,
 402    RIGHTARG = box,
 403    PROCEDURE = area_equal_procedure,
 404    COMMUTATOR = ===,
 405    NEGATOR = !==,
 406    RESTRICT = area_restriction_procedure,
 407    JOIN = area_join_procedure,
 408    HASHES,
 409    SORT1 = <<<,
 410    SORT2 = <<<
 411 );
 412   </programlisting>
 413  </refsect1>
 414
 415  <refsect1 id="R1-SQL-CREATEOPERATOR-3">
 416   <title>
 417    Compatibility
 418   </title>
 419
 420   <refsect2 id="R2-SQL-CREATEOPERATOR-4">
 421    <refsect2info>
 422     <date>2000-03-25</date>
 423    </refsect2info>
 424    <title>
 425     SQL92
 426    </title>
 427
 428    <para>
 429     <command>CREATE OPERATOR</command>
 430     is a <productname>Postgres</productname> extension.
 431     There is no <command>CREATE OPERATOR</command>
 432     statement in <acronym>SQL92</acronym>.
 433    </para>
 434   </refsect2>
 435  </refsect1>
 436 </refentry>
 437
 438 <!-- Keep this comment at the end of the file
 439 Local variables:
 440 mode: sgml
 441 sgml-omittag:nil
 442 sgml-shorttag:t
 443 sgml-minimize-attributes:nil
 444 sgml-always-quote-attributes:t
 445 sgml-indent-step:1
 446 sgml-indent-data:t
 447 sgml-parent-document:nil
 448 sgml-default-dtd-file:"../reference.ced"
 449 sgml-exposed-tags:nil
 450 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 451 sgml-local-ecat-files:nil
 452 End:
 453 -->