← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/ref/create_operator.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/ref/create_operator.sgml
 
1
<!--
 
2
$PostgreSQL: pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.44 2005-01-04 00:39:53 tgl Exp $
 
3
PostgreSQL documentation
 
4
-->
 
5
 
 
6
<refentry id="SQL-CREATEOPERATOR">
 
7
 <refmeta>
 
8
  <refentrytitle id="sql-createoperator-title">CREATE OPERATOR</refentrytitle>
 
9
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 
10
 </refmeta>
 
11
 
 
12
 <refnamediv>
 
13
  <refname>CREATE OPERATOR</refname>
 
14
  <refpurpose>define a new operator</refpurpose>
 
15
 </refnamediv>
 
16
 
 
17
 <indexterm zone="sql-createoperator">
 
18
  <primary>CREATE OPERATOR</primary>
 
19
 </indexterm>
 
20
 
 
21
 <refsynopsisdiv>
 
22
<synopsis>
 
23
CREATE OPERATOR <replaceable>name</replaceable> (
 
24
    PROCEDURE = <replaceable class="parameter">funcname</replaceable>
 
25
    [, LEFTARG = <replaceable class="parameter">lefttype</replaceable> ] [, RIGHTARG = <replaceable class="parameter">righttype</replaceable> ]
 
26
    [, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
 
27
    [, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
 
28
    [, HASHES ] [, MERGES ]
 
29
    [, SORT1 = <replaceable class="parameter">left_sort_op</replaceable> ] [, SORT2 = <replaceable class="parameter">right_sort_op</replaceable> ]
 
30
    [, LTCMP = <replaceable class="parameter">less_than_op</replaceable> ] [, GTCMP = <replaceable class="parameter">greater_than_op</replaceable> ]
 
31
)
 
32
</synopsis>
 
33
 </refsynopsisdiv>
 
34
 
 
35
 <refsect1>
 
36
  <title>Description</title>
 
37
 
 
38
  <para>
 
39
   <command>CREATE OPERATOR</command> defines a new operator,
 
40
   <replaceable class="parameter">name</replaceable>.  The user who
 
41
   defines an operator becomes its owner.  If a schema name is given
 
42
   then the operator is created in the specified schema.  Otherwise it
 
43
   is created in the current schema.
 
44
  </para>
 
45
 
 
46
  <para>
 
47
   The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1
 
48
   (63 by default) characters from the following list:
 
49
<literallayout>
 
50
+ - * / &lt; &gt; = ~ ! @ # % ^ &amp; | ` ?
 
51
</literallayout>
 
52
 
 
53
   There are a few restrictions on your choice of name:
 
54
   <itemizedlist>
 
55
    <listitem>
 
56
     <para>
 
57
     <literal>--</literal> and <literal>/*</literal> cannot appear anywhere in an operator name,
 
58
     since they will be taken as the start of a comment.
 
59
     </para>
 
60
    </listitem>
 
61
    <listitem>
 
62
     <para>
 
63
     A multicharacter operator name cannot end in <literal>+</literal> or
 
64
     <literal>-</literal>,
 
65
     unless the name also contains at least one of these characters:
 
66
<literallayout>
 
67
~ ! @ # % ^ &amp; | ` ?
 
68
</literallayout>
 
69
     For example, <literal>@-</literal> is an allowed operator name,
 
70
     but <literal>*-</literal> is not.
 
71
     This restriction allows <productname>PostgreSQL</productname> to
 
72
     parse SQL-compliant commands without requiring spaces between tokens.
 
73
     </para>
 
74
    </listitem>
 
75
   </itemizedlist>
 
76
  </para>
 
77
 
 
78
  <para>
 
79
   The operator <literal>!=</literal> is mapped to
 
80
   <literal>&lt;&gt;</literal> on input, so these two names are always
 
81
   equivalent.
 
82
  </para>
 
83
 
 
84
  <para>
 
85
   At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined.  For
 
86
   binary operators, both must be defined. For right  unary
 
87
   operators, only <literal>LEFTARG</> should be defined, while for left
 
88
   unary operators only <literal>RIGHTARG</> should be defined.
 
89
  </para>
 
90
 
 
91
  <para>
 
92
   The <replaceable class="parameter">funcname</replaceable>
 
93
   procedure must have been previously defined using <command>CREATE
 
94
   FUNCTION</command> and must be defined to accept the correct number
 
95
   of arguments (either one or two) of the indicated types.
 
96
  </para>
 
97
 
 
98
  <para>
 
99
   The other clauses specify optional operator optimization clauses.
 
100
   Their meaning is detailed in <xref linkend="xoper-optimization">.
 
101
  </para>
 
102
 </refsect1>
 
103
 
 
104
 <refsect1>
 
105
  <title>Parameters</title>
 
106
 
 
107
    <variablelist>
 
108
     <varlistentry>
 
109
      <term><replaceable class="parameter">name</replaceable></term>
 
110
      <listitem>
 
111
       <para>
 
112
        The name of the operator to be defined. See above for allowable
 
113
        characters.  The name may be schema-qualified, for example
 
114
        <literal>CREATE OPERATOR myschema.+ (...)</>.  If not, then
 
115
        the operator is created in the current schema.  Two operators
 
116
        in the same schema can have the same name if they operate on
 
117
        different data types.  This is called
 
118
        <firstterm>overloading</>.
 
119
       </para>
 
120
      </listitem>
 
121
     </varlistentry>
 
122
 
 
123
     <varlistentry>
 
124
      <term><replaceable class="parameter">funcname</replaceable></term>
 
125
      <listitem>
 
126
       <para>
 
127
        The function used to implement this operator.
 
128
       </para>
 
129
      </listitem>
 
130
     </varlistentry>
 
131
 
 
132
     <varlistentry>
 
133
      <term><replaceable class="parameter">lefttype</replaceable></term>
 
134
      <listitem>
 
135
       <para>
 
136
        The data type of the operator's left operand, if any.
 
137
        This option would be omitted for a left-unary operator.
 
138
       </para>
 
139
      </listitem>
 
140
     </varlistentry>
 
141
 
 
142
     <varlistentry>
 
143
      <term><replaceable class="parameter">righttype</replaceable></term>
 
144
      <listitem>
 
145
       <para>
 
146
        The data type of the operator's right operand, if any.
 
147
        This option would be omitted for a right-unary operator.
 
148
       </para>
 
149
      </listitem>
 
150
     </varlistentry>
 
151
 
 
152
     <varlistentry>
 
153
      <term><replaceable class="parameter">com_op</replaceable></term>
 
154
      <listitem>
 
155
       <para>
 
156
        The commutator of this operator.
 
157
       </para>
 
158
      </listitem>
 
159
     </varlistentry>
 
160
 
 
161
     <varlistentry>
 
162
      <term><replaceable class="parameter">neg_op</replaceable></term>
 
163
      <listitem>
 
164
       <para>
 
165
        The negator of this operator.
 
166
       </para>
 
167
      </listitem>
 
168
     </varlistentry>
 
169
 
 
170
     <varlistentry>
 
171
      <term><replaceable class="parameter">res_proc</replaceable></term>
 
172
      <listitem>
 
173
       <para>
 
174
        The restriction selectivity estimator function for this operator.
 
175
       </para>
 
176
      </listitem>
 
177
     </varlistentry>
 
178
 
 
179
     <varlistentry>
 
180
      <term><replaceable class="parameter">join_proc</replaceable></term>
 
181
      <listitem>
 
182
       <para>
 
183
        The join selectivity estimator function for this operator.
 
184
       </para>
 
185
      </listitem>
 
186
     </varlistentry>
 
187
 
 
188
     <varlistentry>
 
189
      <term><literal>HASHES</literal></term>
 
190
      <listitem>
 
191
       <para>
 
192
       Indicates this operator can support a hash join.
 
193
       </para>
 
194
      </listitem>
 
195
     </varlistentry>
 
196
 
 
197
     <varlistentry>
 
198
      <term><literal>MERGES</literal></term>
 
199
      <listitem>
 
200
       <para>
 
201
       Indicates this operator can support a merge join.
 
202
       </para>
 
203
      </listitem>
 
204
     </varlistentry>
 
205
 
 
206
     <varlistentry>
 
207
      <term><replaceable class="parameter">left_sort_op</replaceable></term>
 
208
      <listitem>
 
209
       <para>
 
210
        If this operator can support a merge join, the less-than
 
211
        operator that sorts the left-hand data type of this operator.
 
212
       </para>
 
213
      </listitem>
 
214
     </varlistentry>
 
215
 
 
216
     <varlistentry>
 
217
      <term><replaceable class="parameter">right_sort_op</replaceable></term>
 
218
      <listitem>
 
219
       <para>
 
220
        If this operator can support a merge join, the less-than
 
221
        operator that sorts the right-hand data type of this operator.
 
222
       </para>
 
223
      </listitem>
 
224
     </varlistentry>
 
225
 
 
226
     <varlistentry>
 
227
      <term><replaceable class="parameter">less_than_op</replaceable></term>
 
228
      <listitem>
 
229
       <para>
 
230
        If this operator can support a merge join, the less-than
 
231
        operator that compares the input data types of this operator.
 
232
       </para>
 
233
      </listitem>
 
234
     </varlistentry>
 
235
 
 
236
     <varlistentry>
 
237
      <term><replaceable class="parameter">greater_than_op</replaceable></term>
 
238
      <listitem>
 
239
       <para>
 
240
        If this operator can support a merge join, the greater-than
 
241
        operator that compares the input data types of this operator.
 
242
       </para>
 
243
      </listitem>
 
244
     </varlistentry>
 
245
    </variablelist>
 
246
 
 
247
  <para>
 
248
   To give a schema-qualified operator name in <replaceable
 
249
   class="parameter">com_op</replaceable> or the other optional
 
250
   arguments, use the <literal>OPERATOR()</> syntax, for example
 
251
<programlisting>
 
252
COMMUTATOR = OPERATOR(myschema.===) ,
 
253
</programlisting>  
 
254
  </para>
 
255
 </refsect1>
 
256
  
 
257
 <refsect1>
 
258
  <title>Notes</title>
 
259
 
 
260
  <para>
 
261
   Refer to <xref linkend="xoper"> for further information.
 
262
  </para>
 
263
 
 
264
  <para>
 
265
   Use <xref linkend="sql-dropoperator"
 
266
   endterm="sql-dropoperator-title"> to delete user-defined operators
 
267
   from a database.  Use <xref linkend="sql-alteroperator"
 
268
   endterm="sql-alteroperator-title"> to modify operators in a
 
269
   database.
 
270
  </para>
 
271
 </refsect1>
 
272
  
 
273
 <refsect1>
 
274
  <title>Examples</title>
 
275
 
 
276
  <para>
 
277
   The following command defines a new operator, area-equality, for
 
278
   the data type <type>box</type>:
 
279
<programlisting>
 
280
CREATE OPERATOR === (
 
281
    LEFTARG = box,
 
282
    RIGHTARG = box,
 
283
    PROCEDURE = area_equal_procedure,
 
284
    COMMUTATOR = ===,
 
285
    NEGATOR = !==,
 
286
    RESTRICT = area_restriction_procedure,
 
287
    JOIN = area_join_procedure,
 
288
    HASHES,
 
289
    SORT1 = &lt;&lt;&lt;,
 
290
    SORT2 = &lt;&lt;&lt;
 
291
    -- Since sort operators were given, MERGES is implied.
 
292
    -- LTCMP and GTCMP are assumed to be &lt; and &gt; respectively
 
293
);
 
294
</programlisting>  
 
295
  </para>
 
296
 </refsect1>
 
297
 
 
298
 <refsect1>
 
299
  <title>Compatibility</title>
 
300
 
 
301
  <para>
 
302
   <command>CREATE OPERATOR</command> is a
 
303
   <productname>PostgreSQL</productname> extension.  There are no
 
304
   provisions for user-defined operators in the SQL standard.
 
305
  </para>
 
306
 </refsect1>
 
307
 
 
308
 <refsect1>
 
309
  <title>See Also</title>
 
310
 
 
311
  <simplelist type="inline">
 
312
   <member><xref linkend="sql-alteroperator" endterm="sql-alteroperator-title"></member>
 
313
   <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member>
 
314
   <member><xref linkend="sql-dropoperator" endterm="sql-dropoperator-title"></member>
 
315
  </simplelist>
 
316
 </refsect1>
 
317
</refentry>
 
318
 
 
319
<!-- Keep this comment at the end of the file
 
320
Local variables:
 
321
mode: sgml
 
322
sgml-omittag:nil
 
323
sgml-shorttag:t
 
324
sgml-minimize-attributes:nil
 
325
sgml-always-quote-attributes:t
 
326
sgml-indent-step:1
 
327
sgml-indent-data:t
 
328
sgml-parent-document:nil
 
329
sgml-default-dtd-file:"../reference.ced"
 
330
sgml-exposed-tags:nil
 
331
sgml-local-catalogs:"/usr/lib/sgml/catalog"
 
332
sgml-local-ecat-files:nil
 
333
End:
 
334
-->