1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/create_operator.sgml
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refentry id="sql-createoperator">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="sql-createoperator">
|
|
|
|
<primary>CREATE OPERATOR</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>CREATE OPERATOR</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<refname>CREATE OPERATOR</refname>
|
|
|
|
<refpurpose>define a new operator</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2003-04-22 12:08:08 +02:00
|
|
|
<synopsis>
|
|
|
|
CREATE OPERATOR <replaceable>name</replaceable> (
|
2018-08-15 18:05:46 +02:00
|
|
|
{FUNCTION|PROCEDURE} = <replaceable class="parameter">function_name</replaceable>
|
2009-09-19 12:23:27 +02:00
|
|
|
[, LEFTARG = <replaceable class="parameter">left_type</replaceable> ] [, RIGHTARG = <replaceable class="parameter">right_type</replaceable> ]
|
2003-04-22 12:08:08 +02:00
|
|
|
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
|
|
|
|
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
|
|
|
|
[, HASHES ] [, MERGES ]
|
|
|
|
)
|
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE OPERATOR</command> defines a new operator,
|
|
|
|
<replaceable class="parameter">name</replaceable>. 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.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The operator name is a sequence of up to <symbol>NAMEDATALEN</symbol>-1
|
2003-04-22 12:08:08 +02:00
|
|
|
(63 by default) characters from the following list:
|
|
|
|
<literallayout>
|
2003-08-18 00:09:00 +02:00
|
|
|
+ - * / < > = ~ ! @ # % ^ & | ` ?
|
2003-04-22 12:08:08 +02:00
|
|
|
</literallayout>
|
|
|
|
|
|
|
|
There are a few restrictions on your choice of name:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
2011-08-07 09:49:45 +02:00
|
|
|
<para><literal>--</literal> and <literal>/*</literal> cannot appear anywhere in an operator name,
|
2003-04-22 12:08:08 +02:00
|
|
|
since they will be taken as the start of a comment.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
A multicharacter operator name cannot end in <literal>+</literal> or
|
|
|
|
<literal>-</literal>,
|
|
|
|
unless the name also contains at least one of these characters:
|
|
|
|
<literallayout>
|
2003-08-18 00:09:00 +02:00
|
|
|
~ ! @ # % ^ & | ` ?
|
2003-04-22 12:08:08 +02:00
|
|
|
</literallayout>
|
|
|
|
For example, <literal>@-</literal> is an allowed operator name,
|
|
|
|
but <literal>*-</literal> is not.
|
|
|
|
This restriction allows <productname>PostgreSQL</productname> to
|
|
|
|
parse SQL-compliant commands without requiring spaces between tokens.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2010-06-22 13:36:16 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The use of <literal>=></literal> as an operator name is deprecated. It may
|
2010-06-22 13:36:16 +02:00
|
|
|
be disallowed altogether in a future release.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
2003-04-22 12:08:08 +02:00
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The operator <literal>!=</literal> is mapped to
|
|
|
|
<literal><></literal> on input, so these two names are always
|
|
|
|
equivalent.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
Remove support for postfix (right-unary) operators.
This feature has been a thorn in our sides for a long time, causing
many grammatical ambiguity problems. It doesn't seem worth the
pain to continue to support it, so remove it.
There are some follow-on improvements we can make in the grammar,
but this commit only removes the bare minimum number of productions,
plus assorted backend support code.
Note that pg_dump and psql continue to have full support, since
they may be used against older servers. However, pg_dump warns
about postfix operators. There is also a check in pg_upgrade.
Documentation-wise, I (tgl) largely removed the "left unary"
terminology in favor of saying "prefix operator", which is
a more standard and IMO less confusing term.
I included a catversion bump, although no initial catalog data
changes here, to mark the boundary at which oprkind = 'r'
stopped being valid in pg_operator.
Mark Dilger, based on work by myself and Robert Haas;
review by John Naylor
Discussion: https://postgr.es/m/38ca86db-42ab-9b48-2902-337a0d6b8311@2ndquadrant.com
2020-09-18 01:38:05 +02:00
|
|
|
For binary operators, both <literal>LEFTARG</literal> and
|
|
|
|
<literal>RIGHTARG</literal> must be defined. For prefix operators only
|
|
|
|
<literal>RIGHTARG</literal> should be defined.
|
2009-09-19 12:23:27 +02:00
|
|
|
The <replaceable class="parameter">function_name</replaceable>
|
2018-08-15 17:01:39 +02:00
|
|
|
function must have been previously defined using <command>CREATE
|
2003-04-22 12:08:08 +02:00
|
|
|
FUNCTION</command> and must be defined to accept the correct number
|
|
|
|
of arguments (either one or two) of the indicated types.
|
|
|
|
</para>
|
|
|
|
|
2018-08-15 18:05:46 +02:00
|
|
|
<para>
|
|
|
|
In the syntax of <literal>CREATE OPERATOR</literal>, the keywords
|
|
|
|
<literal>FUNCTION</literal> and <literal>PROCEDURE</literal> are
|
|
|
|
equivalent, but the referenced function must in any case be a function, not
|
|
|
|
a procedure. The use of the keyword <literal>PROCEDURE</literal> here is
|
|
|
|
historical and deprecated.
|
|
|
|
</para>
|
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<para>
|
|
|
|
The other clauses specify optional operator optimization clauses.
|
2017-11-23 15:39:47 +01:00
|
|
|
Their meaning is detailed in <xref linkend="xoper-optimization"/>.
|
2003-04-22 12:08:08 +02:00
|
|
|
</para>
|
2011-12-19 23:05:19 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
To be able to create an operator, you must have <literal>USAGE</literal>
|
|
|
|
privilege on the argument types and the return type, as well
|
|
|
|
as <literal>EXECUTE</literal> privilege on the underlying function. If a
|
|
|
|
commutator or negator operator is specified, you must own these operators.
|
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The name of the operator to be defined. See above for allowable
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
characters. The name can be schema-qualified, for example
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>CREATE OPERATOR myschema.+ (...)</literal>. If not, then
|
2004-06-25 23:55:59 +02:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
<firstterm>overloading</firstterm>.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2009-09-19 12:23:27 +02:00
|
|
|
<term><replaceable class="parameter">function_name</replaceable></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The function used to implement this operator.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2009-09-19 12:23:27 +02:00
|
|
|
<term><replaceable class="parameter">left_type</replaceable></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The data type of the operator's left operand, if any.
|
Remove support for postfix (right-unary) operators.
This feature has been a thorn in our sides for a long time, causing
many grammatical ambiguity problems. It doesn't seem worth the
pain to continue to support it, so remove it.
There are some follow-on improvements we can make in the grammar,
but this commit only removes the bare minimum number of productions,
plus assorted backend support code.
Note that pg_dump and psql continue to have full support, since
they may be used against older servers. However, pg_dump warns
about postfix operators. There is also a check in pg_upgrade.
Documentation-wise, I (tgl) largely removed the "left unary"
terminology in favor of saying "prefix operator", which is
a more standard and IMO less confusing term.
I included a catversion bump, although no initial catalog data
changes here, to mark the boundary at which oprkind = 'r'
stopped being valid in pg_operator.
Mark Dilger, based on work by myself and Robert Haas;
review by John Naylor
Discussion: https://postgr.es/m/38ca86db-42ab-9b48-2902-337a0d6b8311@2ndquadrant.com
2020-09-18 01:38:05 +02:00
|
|
|
This option would be omitted for a prefix operator.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2009-09-19 12:23:27 +02:00
|
|
|
<term><replaceable class="parameter">right_type</replaceable></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
Remove support for postfix (right-unary) operators.
This feature has been a thorn in our sides for a long time, causing
many grammatical ambiguity problems. It doesn't seem worth the
pain to continue to support it, so remove it.
There are some follow-on improvements we can make in the grammar,
but this commit only removes the bare minimum number of productions,
plus assorted backend support code.
Note that pg_dump and psql continue to have full support, since
they may be used against older servers. However, pg_dump warns
about postfix operators. There is also a check in pg_upgrade.
Documentation-wise, I (tgl) largely removed the "left unary"
terminology in favor of saying "prefix operator", which is
a more standard and IMO less confusing term.
I included a catversion bump, although no initial catalog data
changes here, to mark the boundary at which oprkind = 'r'
stopped being valid in pg_operator.
Mark Dilger, based on work by myself and Robert Haas;
review by John Naylor
Discussion: https://postgr.es/m/38ca86db-42ab-9b48-2902-337a0d6b8311@2ndquadrant.com
2020-09-18 01:38:05 +02:00
|
|
|
The data type of the operator's right operand.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">com_op</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The commutator of this operator.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">neg_op</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The negator of this operator.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">res_proc</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The restriction selectivity estimator function for this operator.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">join_proc</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2004-06-25 23:55:59 +02:00
|
|
|
The join selectivity estimator function for this operator.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal>HASHES</literal></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2000-03-18 19:03:12 +01:00
|
|
|
Indicates this operator can support a hash join.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2002-04-17 01:08:12 +02:00
|
|
|
<varlistentry>
|
2003-04-22 12:08:08 +02:00
|
|
|
<term><literal>MERGES</literal></term>
|
2002-04-17 01:08:12 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Indicates this operator can support a merge join.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1999-07-06 19:16:42 +02:00
|
|
|
</variablelist>
|
|
|
|
|
2002-04-23 04:07:16 +02:00
|
|
|
<para>
|
2003-04-22 12:08:08 +02:00
|
|
|
To give a schema-qualified operator name in <replaceable
|
|
|
|
class="parameter">com_op</replaceable> or the other optional
|
2017-10-09 03:44:17 +02:00
|
|
|
arguments, use the <literal>OPERATOR()</literal> syntax, for example:
|
2003-04-22 12:08:08 +02:00
|
|
|
<programlisting>
|
|
|
|
COMMUTATOR = OPERATOR(myschema.===) ,
|
2011-08-07 09:49:45 +02:00
|
|
|
</programlisting></para>
|
2003-04-22 12:08:08 +02:00
|
|
|
</refsect1>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
2000-03-18 19:03:12 +01:00
|
|
|
|
1998-07-14 05:47:34 +02:00
|
|
|
<para>
|
2017-11-23 15:39:47 +01:00
|
|
|
Refer to <xref linkend="xoper"/> for further information.
|
1998-07-14 05:47:34 +02:00
|
|
|
</para>
|
2003-04-22 12:08:08 +02:00
|
|
|
|
2010-07-08 18:30:13 +02:00
|
|
|
<para>
|
|
|
|
It is not possible to specify an operator's lexical precedence in
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>CREATE OPERATOR</command>, because the parser's precedence behavior
|
2017-11-23 15:39:47 +01:00
|
|
|
is hard-wired. See <xref linkend="sql-precedence"/> for precedence details.
|
2010-07-08 18:30:13 +02:00
|
|
|
</para>
|
|
|
|
|
2006-12-23 01:43:13 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The obsolete options <literal>SORT1</literal>, <literal>SORT2</literal>,
|
|
|
|
<literal>LTCMP</literal>, and <literal>GTCMP</literal> were formerly used to
|
2007-11-28 16:42:31 +01:00
|
|
|
specify the names of sort operators associated with a merge-joinable
|
2006-12-23 01:43:13 +01:00
|
|
|
operator. This is no longer necessary, since information about
|
2007-11-28 16:42:31 +01:00
|
|
|
associated operators is found by looking at B-tree operator families
|
2006-12-23 01:43:13 +01:00
|
|
|
instead. If one of these options is given, it is ignored except
|
2017-10-09 03:44:17 +02:00
|
|
|
for implicitly setting <literal>MERGES</literal> true.
|
2006-12-23 01:43:13 +01:00
|
|
|
</para>
|
|
|
|
|
1998-07-14 05:47:34 +02:00
|
|
|
<para>
|
Improve <xref> vs. <command> formatting in the documentation
SQL commands are generally marked up as <command>, except when a link
to a reference page is used using <xref>. But the latter doesn't
create monospace markup, so this looks strange especially when a
paragraph contains a mix of links and non-links.
We considered putting <command> in the <refentrytitle> on the target
side, but that creates some formatting side effects elsewhere.
Generally, it seems safer to solve this on the link source side.
We can't put the <xref> inside the <command>; the DTD doesn't allow
this. DocBook 5 would allow the <command> to have the linkend
attribute itself, but we are not there yet.
So to solve this for now, convert the <xref>s to <link> plus
<command>. This gives the correct look and also gives some more
flexibility what we can put into the link text (e.g., subcommands or
other clauses). In the future, these could then be converted to
DocBook 5 style.
I haven't converted absolutely all xrefs to SQL command reference
pages, only those where we care about the appearance of the link text
or where it was otherwise appropriate to make the appearance match a
bit better. Also in some cases, the links where repetitive, so in
those cases the links where just removed and replaced by a plain
<command>. In cases where we just want the link and don't
specifically care about the generated link text (typically phrased
"for further information see <xref ...>") the xref is kept.
Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
|
|
|
Use <link linkend="sql-dropoperator"><command>DROP OPERATOR</command></link> to delete user-defined operators
|
|
|
|
from a database. Use <link linkend="sql-alteroperator"><command>ALTER OPERATOR</command></link> to modify operators in a
|
2004-09-20 02:04:19 +02:00
|
|
|
database.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
1998-12-29 03:24:47 +01:00
|
|
|
</refsect1>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The following command defines a new operator, area-equality, for
|
|
|
|
the data type <type>box</type>:
|
|
|
|
<programlisting>
|
1999-07-06 19:16:42 +02:00
|
|
|
CREATE OPERATOR === (
|
2003-04-22 12:08:08 +02:00
|
|
|
LEFTARG = box,
|
|
|
|
RIGHTARG = box,
|
2018-08-15 18:05:46 +02:00
|
|
|
FUNCTION = area_equal_function,
|
2003-04-22 12:08:08 +02:00
|
|
|
COMMUTATOR = ===,
|
|
|
|
NEGATOR = !==,
|
2018-08-15 17:01:39 +02:00
|
|
|
RESTRICT = area_restriction_function,
|
|
|
|
JOIN = area_join_function,
|
2006-12-23 01:43:13 +01:00
|
|
|
HASHES, MERGES
|
1999-07-06 19:16:42 +02:00
|
|
|
);
|
2011-08-07 09:49:45 +02:00
|
|
|
</programlisting></para>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsect1>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2003-04-22 12:08:08 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE OPERATOR</command> is a
|
|
|
|
<productname>PostgreSQL</productname> extension. There are no
|
|
|
|
provisions for user-defined operators in the SQL standard.
|
|
|
|
</para>
|
1998-07-14 05:47:34 +02:00
|
|
|
</refsect1>
|
2005-01-04 01:39:53 +01:00
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2017-11-23 15:39:47 +01:00
|
|
|
<member><xref linkend="sql-alteroperator"/></member>
|
|
|
|
<member><xref linkend="sql-createopclass"/></member>
|
|
|
|
<member><xref linkend="sql-dropoperator"/></member>
|
2005-01-04 01:39:53 +01:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|