'\" t .\" Title: CREATE OPERATOR .\" Author: The PostgreSQL Global Development Group .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 2021 .\" Manual: PostgreSQL 13.4 Documentation .\" Source: PostgreSQL 13.4 .\" Language: English .\" .TH "CREATE OPERATOR" "7" "2021" "PostgreSQL 13.4" "PostgreSQL 13.4 Documentation" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" CREATE_OPERATOR \- define a new operator .SH "SYNOPSIS" .sp .nf CREATE OPERATOR \fIname\fR ( {FUNCTION|PROCEDURE} = \fIfunction_name\fR [, LEFTARG = \fIleft_type\fR ] [, RIGHTARG = \fIright_type\fR ] [, COMMUTATOR = \fIcom_op\fR ] [, NEGATOR = \fIneg_op\fR ] [, RESTRICT = \fIres_proc\fR ] [, JOIN = \fIjoin_proc\fR ] [, HASHES ] [, MERGES ] ) .fi .SH "DESCRIPTION" .PP \fBCREATE OPERATOR\fR defines a new operator, \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\&. .PP The operator name is a sequence of up to NAMEDATALEN\-1 (63 by default) characters from the following list: .sp .if n \{\ .RS 4 .\} .nf + \- * / < > = ~ ! @ # % ^ & | ` ? .fi .if n \{\ .RE .\} .sp There are a few restrictions on your choice of name: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \-\- and /* cannot appear anywhere in an operator name, since they will be taken as the start of a comment\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} A multicharacter operator name cannot end in + or \-, unless the name also contains at least one of these characters: .sp .if n \{\ .RS 4 .\} .nf ~ ! @ # % ^ & | ` ? .fi .if n \{\ .RE .\} .sp For example, @\- is an allowed operator name, but *\- is not\&. This restriction allows PostgreSQL to parse SQL\-compliant commands without requiring spaces between tokens\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} The use of => as an operator name is deprecated\&. It may be disallowed altogether in a future release\&. .RE .PP The operator != is mapped to <> on input, so these two names are always equivalent\&. .PP At least one of LEFTARG and RIGHTARG must be defined\&. For binary operators, both must be defined\&. For right unary operators, only LEFTARG should be defined, while for left unary operators only RIGHTARG should be defined\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP Right unary, also called postfix, operators are deprecated and will be removed in PostgreSQL version 14\&. .sp .5v .RE .PP The \fIfunction_name\fR function must have been previously defined using \fBCREATE FUNCTION\fR and must be defined to accept the correct number of arguments (either one or two) of the indicated types\&. .PP In the syntax of CREATE OPERATOR, the keywords FUNCTION and PROCEDURE are equivalent, but the referenced function must in any case be a function, not a procedure\&. The use of the keyword PROCEDURE here is historical and deprecated\&. .PP The other clauses specify optional operator optimization clauses\&. Their meaning is detailed in Section\ \&37.15\&. .PP To be able to create an operator, you must have USAGE privilege on the argument types and the return type, as well as EXECUTE privilege on the underlying function\&. If a commutator or negator operator is specified, you must own these operators\&. .SH "PARAMETERS" .PP \fIname\fR .RS 4 The name of the operator to be defined\&. See above for allowable characters\&. The name can be schema\-qualified, for example 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 overloading\&. .RE .PP \fIfunction_name\fR .RS 4 The function used to implement this operator\&. .RE .PP \fIleft_type\fR .RS 4 The data type of the operator\*(Aqs left operand, if any\&. This option would be omitted for a left\-unary operator\&. .RE .PP \fIright_type\fR .RS 4 The data type of the operator\*(Aqs right operand, if any\&. This option would be omitted for a right\-unary operator\&. .RE .PP \fIcom_op\fR .RS 4 The commutator of this operator\&. .RE .PP \fIneg_op\fR .RS 4 The negator of this operator\&. .RE .PP \fIres_proc\fR .RS 4 The restriction selectivity estimator function for this operator\&. .RE .PP \fIjoin_proc\fR .RS 4 The join selectivity estimator function for this operator\&. .RE .PP HASHES .RS 4 Indicates this operator can support a hash join\&. .RE .PP MERGES .RS 4 Indicates this operator can support a merge join\&. .RE .PP To give a schema\-qualified operator name in \fIcom_op\fR or the other optional arguments, use the OPERATOR() syntax, for example: .sp .if n \{\ .RS 4 .\} .nf COMMUTATOR = OPERATOR(myschema\&.===) , .fi .if n \{\ .RE .\} .SH "NOTES" .PP Refer to Section\ \&37.14 for further information\&. .PP It is not possible to specify an operator\*(Aqs lexical precedence in \fBCREATE OPERATOR\fR, because the parser\*(Aqs precedence behavior is hard\-wired\&. See Section\ \&4.1.6 for precedence details\&. .PP The obsolete options SORT1, SORT2, LTCMP, and GTCMP 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 MERGES true\&. .PP Use DROP OPERATOR (\fBDROP_OPERATOR\fR(7)) to delete user\-defined operators from a database\&. Use ALTER OPERATOR (\fBALTER_OPERATOR\fR(7)) to modify operators in a database\&. .SH "EXAMPLES" .PP The following command defines a new operator, area\-equality, for the data type box: .sp .if n \{\ .RS 4 .\} .nf CREATE OPERATOR === ( LEFTARG = box, RIGHTARG = box, FUNCTION = area_equal_function, COMMUTATOR = ===, NEGATOR = !==, RESTRICT = area_restriction_function, JOIN = area_join_function, HASHES, MERGES ); .fi .if n \{\ .RE .\} .SH "COMPATIBILITY" .PP \fBCREATE OPERATOR\fR is a PostgreSQL extension\&. There are no provisions for user\-defined operators in the SQL standard\&. .SH "SEE ALSO" ALTER OPERATOR (\fBALTER_OPERATOR\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), DROP OPERATOR (\fBDROP_OPERATOR\fR(7))