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