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

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