← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/postgresql-9.1/oneiric-security

« back to all changes in this revision

Viewing changes to doc/src/sgml/html/sql-createoperator.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2011-05-11 10:41:53 UTC
  • Revision ID: james.westby@ubuntu.com-20110511104153-psbh2o58553fv1m0
Tags: upstream-9.1~beta1
Import upstream version 9.1~beta1

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/src/sgml/html/sql-createoperator.html
 
1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 
2
<HTML
 
3
><HEAD
 
4
><TITLE
 
5
>CREATE OPERATOR</TITLE
 
6
><META
 
7
NAME="GENERATOR"
 
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
 
9
REV="MADE"
 
10
HREF="mailto:pgsql-docs@postgresql.org"><LINK
 
11
REL="HOME"
 
12
TITLE="PostgreSQL 9.1beta1 Documentation"
 
13
HREF="index.html"><LINK
 
14
REL="UP"
 
15
TITLE="SQL Commands"
 
16
HREF="sql-commands.html"><LINK
 
17
REL="PREVIOUS"
 
18
TITLE="CREATE LANGUAGE"
 
19
HREF="sql-createlanguage.html"><LINK
 
20
REL="NEXT"
 
21
TITLE="CREATE OPERATOR CLASS"
 
22
HREF="sql-createopclass.html"><LINK
 
23
REL="STYLESHEET"
 
24
TYPE="text/css"
 
25
HREF="stylesheet.css"><META
 
26
HTTP-EQUIV="Content-Type"
 
27
CONTENT="text/html; charset=ISO-8859-1"><META
 
28
NAME="creation"
 
29
CONTENT="2011-04-27T21:20:33"></HEAD
 
30
><BODY
 
31
CLASS="REFENTRY"
 
32
><DIV
 
33
CLASS="NAVHEADER"
 
34
><TABLE
 
35
SUMMARY="Header navigation table"
 
36
WIDTH="100%"
 
37
BORDER="0"
 
38
CELLPADDING="0"
 
39
CELLSPACING="0"
 
40
><TR
 
41
><TH
 
42
COLSPAN="5"
 
43
ALIGN="center"
 
44
VALIGN="bottom"
 
45
><A
 
46
HREF="index.html"
 
47
>PostgreSQL 9.1beta1 Documentation</A
 
48
></TH
 
49
></TR
 
50
><TR
 
51
><TD
 
52
WIDTH="10%"
 
53
ALIGN="left"
 
54
VALIGN="top"
 
55
><A
 
56
TITLE="CREATE LANGUAGE"
 
57
HREF="sql-createlanguage.html"
 
58
ACCESSKEY="P"
 
59
>Prev</A
 
60
></TD
 
61
><TD
 
62
WIDTH="10%"
 
63
ALIGN="left"
 
64
VALIGN="top"
 
65
><A
 
66
TITLE="CREATE LANGUAGE"
 
67
HREF="sql-createlanguage.html"
 
68
>Fast Backward</A
 
69
></TD
 
70
><TD
 
71
WIDTH="60%"
 
72
ALIGN="center"
 
73
VALIGN="bottom"
 
74
></TD
 
75
><TD
 
76
WIDTH="10%"
 
77
ALIGN="right"
 
78
VALIGN="top"
 
79
><A
 
80
TITLE="CREATE OPERATOR CLASS"
 
81
HREF="sql-createopclass.html"
 
82
>Fast Forward</A
 
83
></TD
 
84
><TD
 
85
WIDTH="10%"
 
86
ALIGN="right"
 
87
VALIGN="top"
 
88
><A
 
89
TITLE="CREATE OPERATOR CLASS"
 
90
HREF="sql-createopclass.html"
 
91
ACCESSKEY="N"
 
92
>Next</A
 
93
></TD
 
94
></TR
 
95
></TABLE
 
96
><HR
 
97
ALIGN="LEFT"
 
98
WIDTH="100%"></DIV
 
99
><H1
 
100
><A
 
101
NAME="SQL-CREATEOPERATOR"
 
102
></A
 
103
>CREATE OPERATOR</H1
 
104
><DIV
 
105
CLASS="REFNAMEDIV"
 
106
><A
 
107
NAME="AEN66013"
 
108
></A
 
109
><H2
 
110
>Name</H2
 
111
>CREATE OPERATOR&nbsp;--&nbsp;define a new operator</DIV
 
112
><DIV
 
113
CLASS="REFSYNOPSISDIV"
 
114
><A
 
115
NAME="AEN66018"
 
116
></A
 
117
><H2
 
118
>Synopsis</H2
 
119
><PRE
 
120
CLASS="SYNOPSIS"
 
121
>CREATE OPERATOR <TT
 
122
CLASS="REPLACEABLE"
 
123
><I
 
124
>name</I
 
125
></TT
 
126
> (
 
127
    PROCEDURE = <TT
 
128
CLASS="REPLACEABLE"
 
129
><I
 
130
>function_name</I
 
131
></TT
 
132
>
 
133
    [, LEFTARG = <TT
 
134
CLASS="REPLACEABLE"
 
135
><I
 
136
>left_type</I
 
137
></TT
 
138
> ] [, RIGHTARG = <TT
 
139
CLASS="REPLACEABLE"
 
140
><I
 
141
>right_type</I
 
142
></TT
 
143
> ]
 
144
    [, COMMUTATOR = <TT
 
145
CLASS="REPLACEABLE"
 
146
><I
 
147
>com_op</I
 
148
></TT
 
149
> ] [, NEGATOR = <TT
 
150
CLASS="REPLACEABLE"
 
151
><I
 
152
>neg_op</I
 
153
></TT
 
154
> ]
 
155
    [, RESTRICT = <TT
 
156
CLASS="REPLACEABLE"
 
157
><I
 
158
>res_proc</I
 
159
></TT
 
160
> ] [, JOIN = <TT
 
161
CLASS="REPLACEABLE"
 
162
><I
 
163
>join_proc</I
 
164
></TT
 
165
> ]
 
166
    [, HASHES ] [, MERGES ]
 
167
)</PRE
 
168
></DIV
 
169
><DIV
 
170
CLASS="REFSECT1"
 
171
><A
 
172
NAME="AEN66028"
 
173
></A
 
174
><H2
 
175
>Description</H2
 
176
><P
 
177
>   <TT
 
178
CLASS="COMMAND"
 
179
>CREATE OPERATOR</TT
 
180
> defines a new operator,
 
181
   <TT
 
182
CLASS="REPLACEABLE"
 
183
><I
 
184
>name</I
 
185
></TT
 
186
>.  The user who
 
187
   defines an operator becomes its owner.  If a schema name is given
 
188
   then the operator is created in the specified schema.  Otherwise it
 
189
   is created in the current schema.
 
190
  </P
 
191
><P
 
192
>   The operator name is a sequence of up to <TT
 
193
CLASS="SYMBOL"
 
194
>NAMEDATALEN</TT
 
195
>-1
 
196
   (63 by default) characters from the following list:
 
197
<P
 
198
CLASS="LITERALLAYOUT"
 
199
>+&nbsp;-&nbsp;*&nbsp;/&nbsp;&lt;&nbsp;&gt;&nbsp;=&nbsp;~&nbsp;!&nbsp;@&nbsp;#&nbsp;%&nbsp;^&nbsp;&amp;&nbsp;|&nbsp;`&nbsp;?</P
 
200
>
 
201
 
 
202
   There are a few restrictions on your choice of name:
 
203
   <P
 
204
></P
 
205
></P><UL
 
206
><LI
 
207
><P
 
208
>     <TT
 
209
CLASS="LITERAL"
 
210
>--</TT
 
211
> and <TT
 
212
CLASS="LITERAL"
 
213
>/*</TT
 
214
> cannot appear anywhere in an operator name,
 
215
     since they will be taken as the start of a comment.
 
216
     </P
 
217
></LI
 
218
><LI
 
219
><P
 
220
>     A multicharacter operator name cannot end in <TT
 
221
CLASS="LITERAL"
 
222
>+</TT
 
223
> or
 
224
     <TT
 
225
CLASS="LITERAL"
 
226
>-</TT
 
227
>,
 
228
     unless the name also contains at least one of these characters:
 
229
<P
 
230
CLASS="LITERALLAYOUT"
 
231
>~&nbsp;!&nbsp;@&nbsp;#&nbsp;%&nbsp;^&nbsp;&amp;&nbsp;|&nbsp;`&nbsp;?</P
 
232
>
 
233
     For example, <TT
 
234
CLASS="LITERAL"
 
235
>@-</TT
 
236
> is an allowed operator name,
 
237
     but <TT
 
238
CLASS="LITERAL"
 
239
>*-</TT
 
240
> is not.
 
241
     This restriction allows <SPAN
 
242
CLASS="PRODUCTNAME"
 
243
>PostgreSQL</SPAN
 
244
> to
 
245
     parse SQL-compliant commands without requiring spaces between tokens.
 
246
     </P
 
247
></LI
 
248
><LI
 
249
><P
 
250
>     The use of <TT
 
251
CLASS="LITERAL"
 
252
>=&gt;</TT
 
253
> as an operator name is deprecated.  It may
 
254
     be disallowed altogether in a future release.
 
255
     </P
 
256
></LI
 
257
></UL
 
258
><P>
 
259
  </P
 
260
><P
 
261
>   The operator <TT
 
262
CLASS="LITERAL"
 
263
>!=</TT
 
264
> is mapped to
 
265
   <TT
 
266
CLASS="LITERAL"
 
267
>&lt;&gt;</TT
 
268
> on input, so these two names are always
 
269
   equivalent.
 
270
  </P
 
271
><P
 
272
>   At least one of <TT
 
273
CLASS="LITERAL"
 
274
>LEFTARG</TT
 
275
> and <TT
 
276
CLASS="LITERAL"
 
277
>RIGHTARG</TT
 
278
> must be defined.  For
 
279
   binary operators, both must be defined. For right  unary
 
280
   operators, only <TT
 
281
CLASS="LITERAL"
 
282
>LEFTARG</TT
 
283
> should be defined, while for left
 
284
   unary operators only <TT
 
285
CLASS="LITERAL"
 
286
>RIGHTARG</TT
 
287
> should be defined.
 
288
  </P
 
289
><P
 
290
>   The <TT
 
291
CLASS="REPLACEABLE"
 
292
><I
 
293
>function_name</I
 
294
></TT
 
295
>
 
296
   procedure must have been previously defined using <TT
 
297
CLASS="COMMAND"
 
298
>CREATE
 
299
   FUNCTION</TT
 
300
> and must be defined to accept the correct number
 
301
   of arguments (either one or two) of the indicated types.
 
302
  </P
 
303
><P
 
304
>   The other clauses specify optional operator optimization clauses.
 
305
   Their meaning is detailed in <A
 
306
HREF="xoper-optimization.html"
 
307
>Section 35.13</A
 
308
>.
 
309
  </P
 
310
></DIV
 
311
><DIV
 
312
CLASS="REFSECT1"
 
313
><A
 
314
NAME="AEN66065"
 
315
></A
 
316
><H2
 
317
>Parameters</H2
 
318
><P
 
319
></P
 
320
><DIV
 
321
CLASS="VARIABLELIST"
 
322
><DL
 
323
><DT
 
324
><TT
 
325
CLASS="REPLACEABLE"
 
326
><I
 
327
>name</I
 
328
></TT
 
329
></DT
 
330
><DD
 
331
><P
 
332
>        The name of the operator to be defined. See above for allowable
 
333
        characters.  The name can be schema-qualified, for example
 
334
        <TT
 
335
CLASS="LITERAL"
 
336
>CREATE OPERATOR myschema.+ (...)</TT
 
337
>.  If not, then
 
338
        the operator is created in the current schema.  Two operators
 
339
        in the same schema can have the same name if they operate on
 
340
        different data types.  This is called
 
341
        <I
 
342
CLASS="FIRSTTERM"
 
343
>overloading</I
 
344
>.
 
345
       </P
 
346
></DD
 
347
><DT
 
348
><TT
 
349
CLASS="REPLACEABLE"
 
350
><I
 
351
>function_name</I
 
352
></TT
 
353
></DT
 
354
><DD
 
355
><P
 
356
>        The function used to implement this operator.
 
357
       </P
 
358
></DD
 
359
><DT
 
360
><TT
 
361
CLASS="REPLACEABLE"
 
362
><I
 
363
>left_type</I
 
364
></TT
 
365
></DT
 
366
><DD
 
367
><P
 
368
>        The data type of the operator's left operand, if any.
 
369
        This option would be omitted for a left-unary operator.
 
370
       </P
 
371
></DD
 
372
><DT
 
373
><TT
 
374
CLASS="REPLACEABLE"
 
375
><I
 
376
>right_type</I
 
377
></TT
 
378
></DT
 
379
><DD
 
380
><P
 
381
>        The data type of the operator's right operand, if any.
 
382
        This option would be omitted for a right-unary operator.
 
383
       </P
 
384
></DD
 
385
><DT
 
386
><TT
 
387
CLASS="REPLACEABLE"
 
388
><I
 
389
>com_op</I
 
390
></TT
 
391
></DT
 
392
><DD
 
393
><P
 
394
>        The commutator of this operator.
 
395
       </P
 
396
></DD
 
397
><DT
 
398
><TT
 
399
CLASS="REPLACEABLE"
 
400
><I
 
401
>neg_op</I
 
402
></TT
 
403
></DT
 
404
><DD
 
405
><P
 
406
>        The negator of this operator.
 
407
       </P
 
408
></DD
 
409
><DT
 
410
><TT
 
411
CLASS="REPLACEABLE"
 
412
><I
 
413
>res_proc</I
 
414
></TT
 
415
></DT
 
416
><DD
 
417
><P
 
418
>        The restriction selectivity estimator function for this operator.
 
419
       </P
 
420
></DD
 
421
><DT
 
422
><TT
 
423
CLASS="REPLACEABLE"
 
424
><I
 
425
>join_proc</I
 
426
></TT
 
427
></DT
 
428
><DD
 
429
><P
 
430
>        The join selectivity estimator function for this operator.
 
431
       </P
 
432
></DD
 
433
><DT
 
434
><TT
 
435
CLASS="LITERAL"
 
436
>HASHES</TT
 
437
></DT
 
438
><DD
 
439
><P
 
440
>       Indicates this operator can support a hash join.
 
441
       </P
 
442
></DD
 
443
><DT
 
444
><TT
 
445
CLASS="LITERAL"
 
446
>MERGES</TT
 
447
></DT
 
448
><DD
 
449
><P
 
450
>       Indicates this operator can support a merge join.
 
451
       </P
 
452
></DD
 
453
></DL
 
454
></DIV
 
455
><P
 
456
>   To give a schema-qualified operator name in <TT
 
457
CLASS="REPLACEABLE"
 
458
><I
 
459
>com_op</I
 
460
></TT
 
461
> or the other optional
 
462
   arguments, use the <TT
 
463
CLASS="LITERAL"
 
464
>OPERATOR()</TT
 
465
> syntax, for example:
 
466
</P><PRE
 
467
CLASS="PROGRAMLISTING"
 
468
>COMMUTATOR = OPERATOR(myschema.===) ,</PRE
 
469
><P>
 
470
  </P
 
471
></DIV
 
472
><DIV
 
473
CLASS="REFSECT1"
 
474
><A
 
475
NAME="AEN66124"
 
476
></A
 
477
><H2
 
478
>Notes</H2
 
479
><P
 
480
>   Refer to <A
 
481
HREF="xoper.html"
 
482
>Section 35.12</A
 
483
> for further information.
 
484
  </P
 
485
><P
 
486
>   It is not possible to specify an operator's lexical precedence in
 
487
   <TT
 
488
CLASS="COMMAND"
 
489
>CREATE OPERATOR</TT
 
490
>, because the parser's precedence behavior
 
491
   is hard-wired.  See <A
 
492
HREF="sql-syntax-lexical.html#SQL-PRECEDENCE"
 
493
>Section 4.1.6</A
 
494
> for precedence details.
 
495
  </P
 
496
><P
 
497
>   The obsolete options <TT
 
498
CLASS="LITERAL"
 
499
>SORT1</TT
 
500
>, <TT
 
501
CLASS="LITERAL"
 
502
>SORT2</TT
 
503
>,
 
504
   <TT
 
505
CLASS="LITERAL"
 
506
>LTCMP</TT
 
507
>, and <TT
 
508
CLASS="LITERAL"
 
509
>GTCMP</TT
 
510
> were formerly used to
 
511
   specify the names of sort operators associated with a merge-joinable
 
512
   operator.  This is no longer necessary, since information about
 
513
   associated operators is found by looking at B-tree operator families
 
514
   instead.  If one of these options is given, it is ignored except
 
515
   for implicitly setting <TT
 
516
CLASS="LITERAL"
 
517
>MERGES</TT
 
518
> true.
 
519
  </P
 
520
><P
 
521
>   Use <A
 
522
HREF="sql-dropoperator.html"
 
523
>DROP OPERATOR</A
 
524
> to delete user-defined operators
 
525
   from a database.  Use <A
 
526
HREF="sql-alteroperator.html"
 
527
>ALTER OPERATOR</A
 
528
> to modify operators in a
 
529
   database.
 
530
  </P
 
531
></DIV
 
532
><DIV
 
533
CLASS="REFSECT1"
 
534
><A
 
535
NAME="AEN66140"
 
536
></A
 
537
><H2
 
538
>Examples</H2
 
539
><P
 
540
>   The following command defines a new operator, area-equality, for
 
541
   the data type <TT
 
542
CLASS="TYPE"
 
543
>box</TT
 
544
>:
 
545
</P><PRE
 
546
CLASS="PROGRAMLISTING"
 
547
>CREATE OPERATOR === (
 
548
    LEFTARG = box,
 
549
    RIGHTARG = box,
 
550
    PROCEDURE = area_equal_procedure,
 
551
    COMMUTATOR = ===,
 
552
    NEGATOR = !==,
 
553
    RESTRICT = area_restriction_procedure,
 
554
    JOIN = area_join_procedure,
 
555
    HASHES, MERGES
 
556
);</PRE
 
557
><P>
 
558
  </P
 
559
></DIV
 
560
><DIV
 
561
CLASS="REFSECT1"
 
562
><A
 
563
NAME="AEN66145"
 
564
></A
 
565
><H2
 
566
>Compatibility</H2
 
567
><P
 
568
>   <TT
 
569
CLASS="COMMAND"
 
570
>CREATE OPERATOR</TT
 
571
> is a
 
572
   <SPAN
 
573
CLASS="PRODUCTNAME"
 
574
>PostgreSQL</SPAN
 
575
> extension.  There are no
 
576
   provisions for user-defined operators in the SQL standard.
 
577
  </P
 
578
></DIV
 
579
><DIV
 
580
CLASS="REFSECT1"
 
581
><A
 
582
NAME="AEN66150"
 
583
></A
 
584
><H2
 
585
>See Also</H2
 
586
><A
 
587
HREF="sql-alteroperator.html"
 
588
>ALTER OPERATOR</A
 
589
>, <A
 
590
HREF="sql-createopclass.html"
 
591
>CREATE OPERATOR CLASS</A
 
592
>, <A
 
593
HREF="sql-dropoperator.html"
 
594
>DROP OPERATOR</A
 
595
></DIV
 
596
><DIV
 
597
CLASS="NAVFOOTER"
 
598
><HR
 
599
ALIGN="LEFT"
 
600
WIDTH="100%"><TABLE
 
601
SUMMARY="Footer navigation table"
 
602
WIDTH="100%"
 
603
BORDER="0"
 
604
CELLPADDING="0"
 
605
CELLSPACING="0"
 
606
><TR
 
607
><TD
 
608
WIDTH="33%"
 
609
ALIGN="left"
 
610
VALIGN="top"
 
611
><A
 
612
HREF="sql-createlanguage.html"
 
613
ACCESSKEY="P"
 
614
>Prev</A
 
615
></TD
 
616
><TD
 
617
WIDTH="34%"
 
618
ALIGN="center"
 
619
VALIGN="top"
 
620
><A
 
621
HREF="index.html"
 
622
ACCESSKEY="H"
 
623
>Home</A
 
624
></TD
 
625
><TD
 
626
WIDTH="33%"
 
627
ALIGN="right"
 
628
VALIGN="top"
 
629
><A
 
630
HREF="sql-createopclass.html"
 
631
ACCESSKEY="N"
 
632
>Next</A
 
633
></TD
 
634
></TR
 
635
><TR
 
636
><TD
 
637
WIDTH="33%"
 
638
ALIGN="left"
 
639
VALIGN="top"
 
640
>CREATE LANGUAGE</TD
 
641
><TD
 
642
WIDTH="34%"
 
643
ALIGN="center"
 
644
VALIGN="top"
 
645
><A
 
646
HREF="sql-commands.html"
 
647
ACCESSKEY="U"
 
648
>Up</A
 
649
></TD
 
650
><TD
 
651
WIDTH="33%"
 
652
ALIGN="right"
 
653
VALIGN="top"
 
654
>CREATE OPERATOR CLASS</TD
 
655
></TR
 
656
></TABLE
 
657
></DIV
 
658
></BODY
 
659
></HTML
 
660
>
 
 
b'\\ No newline at end of file'