From a33cf1041f99ed5f19bb7d24584db79ada07d8a4 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Tue, 23 Jan 2007 05:07:18 +0000
Subject: Add CREATE/ALTER/DROP OPERATOR FAMILY commands, also COMMENT ON
OPERATOR FAMILY; and add FAMILY option to CREATE OPERATOR CLASS to allow
adding a class to a pre-existing family. Per previous discussion. Man, what
a tedious lot of cutting and pasting ...
---
doc/src/sgml/ref/allfiles.sgml | 5 +-
doc/src/sgml/ref/alter_opclass.sgml | 3 +-
doc/src/sgml/ref/alter_opfamily.sgml | 312 ++++++++++++++++++++++++++++++++++
doc/src/sgml/ref/comment.sgml | 6 +-
doc/src/sgml/ref/create_opclass.sgml | 48 +++++-
doc/src/sgml/ref/create_opfamily.sgml | 125 ++++++++++++++
doc/src/sgml/ref/drop_opclass.sgml | 24 ++-
doc/src/sgml/ref/drop_opfamily.sgml | 135 +++++++++++++++
doc/src/sgml/reference.sgml | 5 +-
9 files changed, 651 insertions(+), 12 deletions(-)
create mode 100644 doc/src/sgml/ref/alter_opfamily.sgml
create mode 100644 doc/src/sgml/ref/create_opfamily.sgml
create mode 100644 doc/src/sgml/ref/drop_opfamily.sgml
(limited to 'doc/src')
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index a481500525a..3b9b8b952ee 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
@@ -16,6 +16,7 @@ Complete list of usable sgml source files in this directory.
+
@@ -45,6 +46,7 @@ Complete list of usable sgml source files in this directory.
+
@@ -70,6 +72,7 @@ Complete list of usable sgml source files in this directory.
+
diff --git a/doc/src/sgml/ref/alter_opclass.sgml b/doc/src/sgml/ref/alter_opclass.sgml
index aa79f5704a9..586d54940c3 100644
--- a/doc/src/sgml/ref/alter_opclass.sgml
+++ b/doc/src/sgml/ref/alter_opclass.sgml
@@ -1,5 +1,5 @@
@@ -102,6 +102,7 @@ ALTER OPERATOR CLASS name USING
+
diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml
new file mode 100644
index 00000000000..09906488e94
--- /dev/null
+++ b/doc/src/sgml/ref/alter_opfamily.sgml
@@ -0,0 +1,312 @@
+
+
+
+
+ ALTER OPERATOR FAMILY
+ SQL - Language Statements
+
+
+
+ ALTER OPERATOR FAMILY
+ change the definition of an operator family
+
+
+
+ ALTER OPERATOR FAMILY
+
+
+
+
+ALTER OPERATOR FAMILY name USING index_method ADD
+ { OPERATOR strategy_number operator_name ( op_type, op_type ) [ RECHECK ]
+ | FUNCTION support_number [ ( op_type [ , op_type ] ) ] funcname ( argument_type [, ...] )
+ } [, ... ]
+ALTER OPERATOR FAMILY name USING index_method DROP
+ { OPERATOR strategy_number ( op_type [ , op_type ] )
+ | FUNCTION support_number ( op_type [ , op_type ] )
+ } [, ... ]
+ALTER OPERATOR FAMILY name USING index_method RENAME TO newname
+ALTER OPERATOR FAMILY name USING index_method OWNER TO newowner
+
+
+
+
+ Description
+
+
+ ALTER OPERATOR FAMILY changes the definition of
+ an operator family. You can add operators and support functions
+ to the family, remove them from the family,
+ or change the family's name or owner.
+
+
+
+ When operators and support functions are added to a family with
+ ALTER OPERATOR FAMILY, they are not part of any
+ specific operator class within the family, but are just loose
+ within the family. This indicates that these operators and functions
+ are compatible with the family's semantics, but are not required for
+ correct functioning of any specific index. (Operators and functions
+ that are so required should be declared as part of an operator class,
+ instead; see .)
+ PostgreSQL will allow loose members of a
+ family to be dropped from the family at any time, but members of an
+ operator class cannot be dropped without dropping the whole class and
+ any indexes that depend on it.
+ Typically, single-data-type operators
+ and functions are part of operator classes because they are needed to
+ support an index on that specific data type, while cross-data-type
+ operators and functions are made loose members of the family.
+
+
+
+ You must be a superuser to use ALTER OPERATOR FAMILY.
+
+
+
+
+ Parameters
+
+
+
+ name
+
+
+ The name (optionally schema-qualified) of an existing operator
+ family.
+
+
+
+
+
+ index_method
+
+
+ The name of the index method this operator family is for.
+
+
+
+
+
+ strategy_number
+
+
+ The index method's strategy number for an operator
+ associated with the operator family.
+
+
+
+
+
+ operator_name
+
+
+ The name (optionally schema-qualified) of an operator associated
+ with the operator family.
+
+
+
+
+
+ op_type
+
+
+ In an OPERATOR clause,
+ the operand data type(s) of the operator, or NONE to
+ signify a left-unary or right-unary operator. Unlike the comparable
+ syntax in CREATE OPERATOR CLASS, the operand data types
+ must always be specified.
+
+
+
+ In an ADD FUNCTION clause, the operand data type(s) the
+ function is intended to support, if different from
+ the input data type(s) of the function. For B-tree and hash indexes
+ it is not necessary to specify op_type since the function's input
+ data type(s) are always the correct ones to use. For GIN and GiST
+ indexes it is necessary to specify the input data type the function
+ is to be used with.
+
+
+
+ In a DROP FUNCTION clause, the operand data type(s) the
+ function is intended to support must be specified.
+
+
+
+
+
+ RECHECK
+
+
+ If present, the index is lossy for this operator, and
+ so the rows retrieved using the index must be rechecked to
+ verify that they actually satisfy the qualification clause
+ involving this operator.
+
+
+
+
+
+ support_number
+
+
+ The index method's support procedure number for a
+ function associated with the operator family.
+
+
+
+
+
+ funcname
+
+
+ The name (optionally schema-qualified) of a function that is an
+ index method support procedure for the operator family.
+
+
+
+
+
+ argument_types
+
+
+ The parameter data type(s) of the function.
+
+
+
+
+
+ newname
+
+
+ The new name of the operator family.
+
+
+
+
+
+ newowner
+
+
+ The new owner of the operator family.
+
+
+
+
+
+
+ The OPERATOR and FUNCTION
+ clauses may appear in any order.
+
+
+
+
+
+ Notes
+
+
+ Notice that the DROP syntax only specifies the slot
+ in the operator family, by strategy or support number and input data
+ type(s). The name of the operator or function occupying the slot is not
+ mentioned. Also, for DROP FUNCTION the type(s) to specify
+ are the input data type(s) the function is intended to support; for
+ GIN and GiST indexes this may have nothing to do with the actual input
+ argument types of the function.
+
+
+
+ Because the index machinery does not check access permissions on functions
+ before using them, including a function or operator in an operator family
+ is tantamount to granting public execute permission on it. This is usually
+ not an issue for the sorts of functions that are useful in an operator
+ family.
+
+
+
+ The operators should not be defined by SQL functions. A SQL function
+ is likely to be inlined into the calling query, which will prevent
+ the optimizer from recognizing that the query matches an index.
+
+
+
+
+ Examples
+
+
+ The following example command adds cross-data-type operators and
+ support functions to an operator family that already contains B-tree
+ operator classes for data types int4 and int2.
+
+
+
+ALTER OPERATOR FAMILY integer_ops USING btree ADD
+
+ -- int4 vs int2
+ OPERATOR 1 < (int4, int2) ,
+ OPERATOR 2 <= (int4, int2) ,
+ OPERATOR 3 = (int4, int2) ,
+ OPERATOR 4 >= (int4, int2) ,
+ OPERATOR 5 > (int4, int2) ,
+ FUNCTION 1 btint42cmp(int4, int2) ,
+
+ -- int2 vs int4
+ OPERATOR 1 < (int2, int4) ,
+ OPERATOR 2 <= (int2, int4) ,
+ OPERATOR 3 = (int2, int4) ,
+ OPERATOR 4 >= (int2, int4) ,
+ OPERATOR 5 > (int2, int4) ,
+ FUNCTION 1 btint24cmp(int2, int4) ;
+
+
+
+ To remove these entries again:
+
+
+
+ALTER OPERATOR FAMILY integer_ops USING btree DROP
+
+ -- int4 vs int2
+ OPERATOR 1 (int4, int2) ,
+ OPERATOR 2 (int4, int2) ,
+ OPERATOR 3 (int4, int2) ,
+ OPERATOR 4 (int4, int2) ,
+ OPERATOR 5 (int4, int2) ,
+ FUNCTION 1 (int4, int2) ,
+
+ -- int2 vs int4
+ OPERATOR 1 (int2, int4) ,
+ OPERATOR 2 (int2, int4) ,
+ OPERATOR 3 (int2, int4) ,
+ OPERATOR 4 (int2, int4) ,
+ OPERATOR 5 (int2, int4) ,
+ FUNCTION 1 (int2, int4) ;
+
+
+
+
+ Compatibility
+
+
+ There is no ALTER OPERATOR FAMILY statement in
+ the SQL standard.
+
+
+
+
+ See Also
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index d2cf39a20c4..bc3ab8f26d8 100644
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -1,5 +1,5 @@
@@ -35,6 +35,7 @@ COMMENT ON
LARGE OBJECT large_object_oid |
OPERATOR op (leftoperand_type, rightoperand_type) |
OPERATOR CLASS object_name USING index_method |
+ OPERATOR FAMILY object_name USING index_method |
[ PROCEDURAL ] LANGUAGE object_name |
ROLE object_name |
RULE rule_name ON table_name |
@@ -92,7 +93,7 @@ COMMENT ON
The name of the object to be commented. Names of tables,
aggregates, domains, functions, indexes, operators, operator classes,
- sequences, types, and views may be schema-qualified.
+ operator families, sequences, types, and views may be schema-qualified.
@@ -247,6 +248,7 @@ COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR - (NONE, text) IS 'This is a prefix operator on text';
COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
+COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
COMMENT ON ROLE my_role IS 'Administration group for finance tables';
COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
COMMENT ON SCHEMA my_schema IS 'Departmental data';
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
index 524be85f978..85a31e3b195 100644
--- a/doc/src/sgml/ref/create_opclass.sgml
+++ b/doc/src/sgml/ref/create_opclass.sgml
@@ -1,5 +1,5 @@
@@ -20,9 +20,10 @@ PostgreSQL documentation
-CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type USING index_method AS
+CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type
+ USING index_method [ FAMILY family_name ] AS
{ OPERATOR strategy_number operator_name [ ( op_type, op_type ) ] [ RECHECK ]
- | FUNCTION support_number funcname ( argument_type [, ...] )
+ | FUNCTION support_number [ ( op_type [ , op_type ] ) ] funcname ( argument_type [, ...] )
| STORAGE storage_type
} [, ... ]
@@ -40,7 +41,7 @@ CREATE OPERATOR CLASS name [ DEFAUL
be used by
the index method when the operator class is selected for an
index column. All the operators and functions used by an operator
- class must be defined before the operator class is created.
+ class must be defined before the operator class can be created.
@@ -65,6 +66,15 @@ CREATE OPERATOR CLASS name [ DEFAUL
responsibility to define a valid operator class.
+
+ Related operator classes can be grouped into operator
+ families. To add a new operator class to an existing family,
+ specify the FAMILY option in CREATE OPERATOR
+ CLASS. Without this option, the new class is placed into
+ a family named the same as the new class (creating that family if
+ it doesn't already exist).
+
+
Refer to for further information.
@@ -113,6 +123,17 @@ CREATE OPERATOR CLASS name [ DEFAUL
+
+ family_name
+
+
+ The name of the existing operator family to add this operator class to.
+ If not specified, a family named the same as the operator class is
+ used (creating it, if it doesn't already exist).
+
+
+
+
strategy_number
@@ -137,11 +158,24 @@ CREATE OPERATOR CLASS name [ DEFAUL
op_type
- The operand data type(s) of an operator, or NONE to
+ In an OPERATOR clause,
+ the operand data type(s) of the operator, or NONE to
signify a left-unary or right-unary operator. The operand data
types may be omitted in the normal case where they are the same
as the operator class's data type.
+
+
+ In a FUNCTION clause, the operand data type(s) the
+ function is intended to support, if different from
+ the input data type(s) of the function (for B-tree and hash indexes)
+ or the class's data type (for GIN and GiST indexes). These defaults
+ are always correct, so there is no point in specifying op_type in a FUNCTION clause
+ in CREATE OPERATOR CLASS, but the option is provided
+ for consistency with the comparable syntax in
+ ALTER OPERATOR FAMILY.
+
@@ -192,7 +226,7 @@ CREATE OPERATOR CLASS name [ DEFAUL
The data type actually stored in the index. Normally this is
the same as the column data type, but some index methods
- (GIN and GiST for now) allow it to be different. The
+ (currently GIN and GiST) allow it to be different. The
STORAGE clause must be omitted unless the index
method allows a different type to be used.
@@ -268,6 +302,8 @@ CREATE OPERATOR CLASS gist__int_ops
+
+
diff --git a/doc/src/sgml/ref/create_opfamily.sgml b/doc/src/sgml/ref/create_opfamily.sgml
new file mode 100644
index 00000000000..d8ddb683b9e
--- /dev/null
+++ b/doc/src/sgml/ref/create_opfamily.sgml
@@ -0,0 +1,125 @@
+
+
+
+
+ CREATE OPERATOR FAMILY
+ SQL - Language Statements
+
+
+
+ CREATE OPERATOR FAMILY
+ define a new operator family
+
+
+
+ CREATE OPERATOR FAMILY
+
+
+
+
+CREATE OPERATOR FAMILY name USING index_method
+
+
+
+
+ Description
+
+
+ CREATE OPERATOR FAMILY creates a new operator family.
+ An operator family defines a collection of related operator classes,
+ and perhaps some additional operators and support functions that are
+ compatible with these operator classes but not essential for the
+ functioning of any individual index. (Operators and functions that
+ are essential to indexes should be grouped within the relevant operator
+ class, rather than being loose in the operator family.
+ Typically, single-data-type operators are bound to operator classes,
+ while cross-data-type operators can be loose in an operator family
+ containing operator classes for both data types.)
+
+
+
+ The new operator family is initially empty. It should be populated
+ by issuing subsequent CREATE OPERATOR CLASS commands
+ to add contained operator classes, and optionally
+ ALTER OPERATOR FAMILY commands to add loose
+ operators and their corresponding support functions.
+
+
+
+ If a schema name is given then the operator family is created in the
+ specified schema. Otherwise it is created in the current schema.
+ Two operator families in the same schema can have the same name only if they
+ are for different index methods.
+
+
+
+ The user who defines an operator family becomes its owner. Presently,
+ the creating user must be a superuser. (This restriction is made because
+ an erroneous operator family definition could confuse or even crash the
+ server.)
+
+
+
+ CREATE OPERATOR FAMILY does not presently check
+ whether the operator family definition includes all the operators and
+ functions required by the index method, nor whether the operators and
+ functions form a self-consistent set. It is the user's
+ responsibility to define a valid operator family.
+
+
+
+ Refer to for further information.
+
+
+
+
+ Parameters
+
+
+
+ name
+
+
+ The name of the operator family to be created. The name may be
+ schema-qualified.
+
+
+
+
+
+ index_method
+
+
+ The name of the index method this operator family is for.
+
+
+
+
+
+
+
+ Compatibility
+
+
+ CREATE OPERATOR FAMILY is a
+ PostgreSQL extension. There is no
+ CREATE OPERATOR FAMILY statement in the SQL
+ standard.
+
+
+
+
+ See Also
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/ref/drop_opclass.sgml b/doc/src/sgml/ref/drop_opclass.sgml
index 42cc1cd0f8d..ce00ff40fd5 100644
--- a/doc/src/sgml/ref/drop_opclass.sgml
+++ b/doc/src/sgml/ref/drop_opclass.sgml
@@ -1,5 +1,5 @@
@@ -31,6 +31,13 @@ DROP OPERATOR CLASS [ IF EXISTS ] nameDROP OPERATOR CLASS drops an existing operator class.
To execute this command you must be the owner of the operator class.
+
+
+ DROP OPERATOR CLASS does not drop any of the operators
+ or functions referenced by the class. If there are any indexes depending
+ on the operator class, you will need to specify
+ CASCADE for the drop to complete.
+
@@ -86,6 +93,20 @@ DROP OPERATOR CLASS [ IF EXISTS ] name
+
+
+ Notes
+
+
+ DROP OPERATOR CLASS will not drop the operator family
+ containing the class, even if there is nothing else left in the
+ family (in particular, in the case where the family was implicitly
+ created by CREATE OPERATOR CLASS). An empty operator
+ family is harmless, but for the sake of tidiness you may wish to
+ remove the family with DROP OPERATOR FAMILY; or perhaps
+ better, use DROP OPERATOR FAMILY in the first place.
+
+
Examples
@@ -118,6 +139,7 @@ DROP OPERATOR CLASS widget_ops USING btree;
+
diff --git a/doc/src/sgml/ref/drop_opfamily.sgml b/doc/src/sgml/ref/drop_opfamily.sgml
new file mode 100644
index 00000000000..e2dcaf72af1
--- /dev/null
+++ b/doc/src/sgml/ref/drop_opfamily.sgml
@@ -0,0 +1,135 @@
+
+
+
+
+ DROP OPERATOR FAMILY
+ SQL - Language Statements
+
+
+
+ DROP OPERATOR FAMILY
+ remove an operator family
+
+
+
+ DROP OPERATOR FAMILY
+
+
+
+
+DROP OPERATOR FAMILY [ IF EXISTS ] name USING index_method [ CASCADE | RESTRICT ]
+
+
+
+
+ Description
+
+
+ DROP OPERATOR FAMILY drops an existing operator family.
+ To execute this command you must be the owner of the operator family.
+
+
+
+ DROP OPERATOR FAMILY includes dropping any operator
+ classes contained in the family, but it does not drop any of the operators
+ or functions referenced by the family. If there are any indexes depending
+ on operator classes within the family, you will need to specify
+ CASCADE for the drop to complete.
+
+
+
+
+ Parameters
+
+
+
+
+ IF EXISTS
+
+
+ Do not throw an error if the operator family does not exist.
+ A notice is issued in this case.
+
+
+
+
+
+ name
+
+
+ The name (optionally schema-qualified) of an existing operator family.
+
+
+
+
+
+ index_method
+
+
+ The name of the index access method the operator family is for.
+
+
+
+
+
+ CASCADE
+
+
+ Automatically drop objects that depend on the operator family.
+
+
+
+
+
+ RESTRICT
+
+
+ Refuse to drop the operator family if any objects depend on it.
+ This is the default.
+
+
+
+
+
+
+
+ Examples
+
+
+ Remove the B-tree operator family float_ops:
+
+
+DROP OPERATOR FAMILY float_ops USING btree;
+
+
+ This command will not succeed if there are any existing indexes
+ that use operator classes within the family. Add CASCADE to
+ drop such indexes along with the operator family.
+
+
+
+
+ Compatibility
+
+
+ There is no DROP OPERATOR FAMILY statement in the
+ SQL standard.
+
+
+
+
+ See Also
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index 64330928c4e..9b3cbda575e 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,4 +1,4 @@
-
+
Reference
@@ -44,6 +44,7 @@
&alterLanguage;
&alterOperator;
&alterOperatorClass;
+ &alterOperatorFamily;
&alterRole;
&alterSchema;
&alterSequence;
@@ -73,6 +74,7 @@
&createLanguage;
&createOperator;
&createOperatorClass;
+ &createOperatorFamily;
&createRole;
&createRule;
&createSchema;
@@ -98,6 +100,7 @@
&dropLanguage;
&dropOperator;
&dropOperatorClass;
+ &dropOperatorFamily;
&dropOwned;
&dropRole;
&dropRule;
--
cgit v1.2.3