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

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