begriffs open source - ai-pg/blob - full-docs/man7/CREATE_OPERATOR.7

   1 '\" t
   2 .\"     Title: CREATE OPERATOR
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE OPERATOR" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_OPERATOR \- define a new operator
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE OPERATOR \fIname\fR (
  36     {FUNCTION|PROCEDURE} = \fIfunction_name\fR
  37     [, LEFTARG = \fIleft_type\fR ] [, RIGHTARG = \fIright_type\fR ]
  38     [, COMMUTATOR = \fIcom_op\fR ] [, NEGATOR = \fIneg_op\fR ]
  39     [, RESTRICT = \fIres_proc\fR ] [, JOIN = \fIjoin_proc\fR ]
  40     [, HASHES ] [, MERGES ]
  41 )
  42 .fi
  43 .SH "DESCRIPTION"
  44 .PP
  45 \fBCREATE OPERATOR\fR
  46 defines a new operator,
  47 \fIname\fR\&. The user who defines an operator becomes its owner\&. If a schema name is given then the operator is created in the specified schema\&. Otherwise it is created in the current schema\&.
  48 .PP
  49 The operator name is a sequence of up to
  50 NAMEDATALEN\-1 (63 by default) characters from the following list:
  51 .sp
  52 .if n \{\
  53 .RS 4
  54 .\}
  55 .nf
  56 + \- * / < > = ~ ! @ # % ^ & | ` ?
  57 .fi
  58 .if n \{\
  59 .RE
  60 .\}
  61 .sp
  62 There are a few restrictions on your choice of name:
  63 .sp
  64 .RS 4
  65 .ie n \{\
  66 \h'-04'\(bu\h'+03'\c
  67 .\}
  68 .el \{\
  69 .sp -1
  70 .IP \(bu 2.3
  71 .\}
  72 \-\-
  73 and
  74 /*
  75 cannot appear anywhere in an operator name, since they will be taken as the start of a comment\&.
  76 .RE
  77 .sp
  78 .RS 4
  79 .ie n \{\
  80 \h'-04'\(bu\h'+03'\c
  81 .\}
  82 .el \{\
  83 .sp -1
  84 .IP \(bu 2.3
  85 .\}
  86 A multicharacter operator name cannot end in
  87 +
  88 or
  89 \-, unless the name also contains at least one of these characters:
  90 .sp
  91 .if n \{\
  92 .RS 4
  93 .\}
  94 .nf
  95 ~ ! @ # % ^ & | ` ?
  96 .fi
  97 .if n \{\
  98 .RE
  99 .\}
 100 .sp
 101 For example,
 102 @\-
 103 is an allowed operator name, but
 104 *\-
 105 is not\&. This restriction allows
 106 PostgreSQL
 107 to parse SQL\-compliant commands without requiring spaces between tokens\&.
 108 .RE
 109 .sp
 110 .RS 4
 111 .ie n \{\
 112 \h'-04'\(bu\h'+03'\c
 113 .\}
 114 .el \{\
 115 .sp -1
 116 .IP \(bu 2.3
 117 .\}
 118 The symbol
 119 =>
 120 is reserved by the SQL grammar, so it cannot be used as an operator name\&.
 121 .RE
 122 .PP
 123 The operator
 124 !=
 125 is mapped to
 126 <>
 127 on input, so these two names are always equivalent\&.
 128 .PP
 129 For binary operators, both
 130 LEFTARG
 131 and
 132 RIGHTARG
 133 must be defined\&. For prefix operators only
 134 RIGHTARG
 135 should be defined\&. The
 136 \fIfunction_name\fR
 137 function must have been previously defined using
 138 \fBCREATE FUNCTION\fR
 139 and must be defined to accept the correct number of arguments (either one or two) of the indicated types\&.
 140 .PP
 141 In the syntax of
 142 CREATE OPERATOR, the keywords
 143 FUNCTION
 144 and
 145 PROCEDURE
 146 are equivalent, but the referenced function must in any case be a function, not a procedure\&. The use of the keyword
 147 PROCEDURE
 148 here is historical and deprecated\&.
 149 .PP
 150 The other clauses specify optional operator optimization attributes\&. Their meaning is detailed in
 151 Section\ \&36.15\&.
 152 .PP
 153 To be able to create an operator, you must have
 154 USAGE
 155 privilege on the argument types and the return type, as well as
 156 EXECUTE
 157 privilege on the underlying function\&. If a commutator or negator operator is specified, you must own those operators\&.
 158 .SH "PARAMETERS"
 159 .PP
 160 \fIname\fR
 161 .RS 4
 162 The name of the operator to be defined\&. See above for allowable characters\&. The name can be schema\-qualified, for example
 163 CREATE OPERATOR myschema\&.+ (\&.\&.\&.)\&. If not, then the operator is created in the current schema\&. Two operators in the same schema can have the same name if they operate on different data types\&. This is called
 164 overloading\&.
 165 .RE
 166 .PP
 167 \fIfunction_name\fR
 168 .RS 4
 169 The function used to implement this operator\&.
 170 .RE
 171 .PP
 172 \fIleft_type\fR
 173 .RS 4
 174 The data type of the operator\*(Aqs left operand, if any\&. This option would be omitted for a prefix operator\&.
 175 .RE
 176 .PP
 177 \fIright_type\fR
 178 .RS 4
 179 The data type of the operator\*(Aqs right operand\&.
 180 .RE
 181 .PP
 182 \fIcom_op\fR
 183 .RS 4
 184 The commutator of this operator\&.
 185 .RE
 186 .PP
 187 \fIneg_op\fR
 188 .RS 4
 189 The negator of this operator\&.
 190 .RE
 191 .PP
 192 \fIres_proc\fR
 193 .RS 4
 194 The restriction selectivity estimator function for this operator\&.
 195 .RE
 196 .PP
 197 \fIjoin_proc\fR
 198 .RS 4
 199 The join selectivity estimator function for this operator\&.
 200 .RE
 201 .PP
 202 HASHES
 203 .RS 4
 204 Indicates this operator can support a hash join\&.
 205 .RE
 206 .PP
 207 MERGES
 208 .RS 4
 209 Indicates this operator can support a merge join\&.
 210 .RE
 211 .PP
 212 To give a schema\-qualified operator name in
 213 \fIcom_op\fR
 214 or the other optional arguments, use the
 215 OPERATOR()
 216 syntax, for example:
 217 .sp
 218 .if n \{\
 219 .RS 4
 220 .\}
 221 .nf
 222 COMMUTATOR = OPERATOR(myschema\&.===) ,
 223 .fi
 224 .if n \{\
 225 .RE
 226 .\}
 227 .SH "NOTES"
 228 .PP
 229 Refer to
 230 Section\ \&36.14
 231 and
 232 Section\ \&36.15
 233 for further information\&.
 234 .PP
 235 When you are defining a self\-commutative operator, you just do it\&. When you are defining a pair of commutative operators, things are a little trickier: how can the first one to be defined refer to the other one, which you haven\*(Aqt defined yet? There are three solutions to this problem:
 236 .sp
 237 .RS 4
 238 .ie n \{\
 239 \h'-04'\(bu\h'+03'\c
 240 .\}
 241 .el \{\
 242 .sp -1
 243 .IP \(bu 2.3
 244 .\}
 245 One way is to omit the
 246 COMMUTATOR
 247 clause in the first operator that you define, and then provide one in the second operator\*(Aqs definition\&. Since
 248 PostgreSQL
 249 knows that commutative operators come in pairs, when it sees the second definition it will automatically go back and fill in the missing
 250 COMMUTATOR
 251 clause in the first definition\&.
 252 .RE
 253 .sp
 254 .RS 4
 255 .ie n \{\
 256 \h'-04'\(bu\h'+03'\c
 257 .\}
 258 .el \{\
 259 .sp -1
 260 .IP \(bu 2.3
 261 .\}
 262 Another, more straightforward way is just to include
 263 COMMUTATOR
 264 clauses in both definitions\&. When
 265 PostgreSQL
 266 processes the first definition and realizes that
 267 COMMUTATOR
 268 refers to a nonexistent operator, the system will make a dummy entry for that operator in the system catalog\&. This dummy entry will have valid data only for the operator name, left and right operand types, and owner, since that\*(Aqs all that
 269 PostgreSQL
 270 can deduce at this point\&. The first operator\*(Aqs catalog entry will link to this dummy entry\&. Later, when you define the second operator, the system updates the dummy entry with the additional information from the second definition\&. If you try to use the dummy operator before it\*(Aqs been filled in, you\*(Aqll just get an error message\&.
 271 .RE
 272 .sp
 273 .RS 4
 274 .ie n \{\
 275 \h'-04'\(bu\h'+03'\c
 276 .\}
 277 .el \{\
 278 .sp -1
 279 .IP \(bu 2.3
 280 .\}
 281 Alternatively, both operators can be defined without
 282 COMMUTATOR
 283 clauses and then
 284 \fBALTER OPERATOR\fR
 285 can be used to set their commutator links\&. It\*(Aqs sufficient to
 286 \fBALTER\fR
 287 either one of the pair\&.
 288 .RE
 289 .sp
 290 In all three cases, you must own both operators in order to mark them as commutators\&.
 291 .PP
 292 Pairs of negator operators can be defined using the same methods as for commutator pairs\&.
 293 .PP
 294 It is not possible to specify an operator\*(Aqs lexical precedence in
 295 \fBCREATE OPERATOR\fR, because the parser\*(Aqs precedence behavior is hard\-wired\&. See
 296 Section\ \&4.1.6
 297 for precedence details\&.
 298 .PP
 299 The obsolete options
 300 SORT1,
 301 SORT2,
 302 LTCMP, and
 303 GTCMP
 304 were formerly used to specify the names of sort operators associated with a merge\-joinable operator\&. This is no longer necessary, since information about associated operators is found by looking at B\-tree operator families instead\&. If one of these options is given, it is ignored except for implicitly setting
 305 MERGES
 306 true\&.
 307 .PP
 308 Use
 309 \fBDROP OPERATOR\fR
 310 to delete user\-defined operators from a database\&. Use
 311 \fBALTER OPERATOR\fR
 312 to modify operators in a database\&.
 313 .SH "EXAMPLES"
 314 .PP
 315 The following command defines a new operator, area\-equality, for the data type
 316 box:
 317 .sp
 318 .if n \{\
 319 .RS 4
 320 .\}
 321 .nf
 322 CREATE OPERATOR === (
 323     LEFTARG = box,
 324     RIGHTARG = box,
 325     FUNCTION = area_equal_function,
 326     COMMUTATOR = ===,
 327     NEGATOR = !==,
 328     RESTRICT = area_restriction_function,
 329     JOIN = area_join_function,
 330     HASHES, MERGES
 331 );
 332 .fi
 333 .if n \{\
 334 .RE
 335 .\}
 336 .SH "COMPATIBILITY"
 337 .PP
 338 \fBCREATE OPERATOR\fR
 339 is a
 340 PostgreSQL
 341 extension\&. There are no provisions for user\-defined operators in the SQL standard\&.
 342 .SH "SEE ALSO"
 343 ALTER OPERATOR (\fBALTER_OPERATOR\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), DROP OPERATOR (\fBDROP_OPERATOR\fR(7))