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