From ea4686e3e1f00910a19e18dd59f5c518345bb431 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Mon, 29 Jul 2002 22:14:11 +0000
Subject: Implement CREATE/DROP OPERATOR CLASS. Work still remains: need more
documentation (xindex.sgml should be rewritten), need to teach pg_dump about
it, need to update contrib modules that currently build pg_opclass entries by
hand. Original patch by Bill Studenmund, grammar adjustments and general
update for 7.3 by Tom Lane.
---
doc/src/sgml/ref/allfiles.sgml | 4 +-
doc/src/sgml/ref/create_opclass.sgml | 316 +++++++++++++++++++++++++++++++++++
doc/src/sgml/ref/drop_opclass.sgml | 184 ++++++++++++++++++++
doc/src/sgml/ref/drop_operator.sgml | 6 +-
doc/src/sgml/reference.sgml | 4 +-
doc/src/sgml/release.sgml | 3 +-
6 files changed, 509 insertions(+), 8 deletions(-)
create mode 100644 doc/src/sgml/ref/create_opclass.sgml
create mode 100644 doc/src/sgml/ref/drop_opclass.sgml
(limited to 'doc/src')
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index a37d58ab7d9..1ee6f2f2004 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
@@ -61,6 +61,7 @@ Complete list of usable sgml source files in this directory.
+
@@ -82,6 +83,7 @@ Complete list of usable sgml source files in this directory.
+
diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml
new file mode 100644
index 00000000000..6d00f081f81
--- /dev/null
+++ b/doc/src/sgml/ref/create_opclass.sgml
@@ -0,0 +1,316 @@
+
+
+
+
+ CREATE OPERATOR CLASS
+ SQL - Language Statements
+
+
+
+ CREATE OPERATOR CLASS
+
+
+ define a new operator class for indexes
+
+
+
+
+ 2002-07-28
+
+
+CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type USING access_method AS
+ { OPERATOR strategy_number operator_id [ ( type, type ) ] [ RECHECK ]
+ | FUNCTION support_number func_name ( parameter_types )
+ | STORAGE storage_type
+ } [, ... ]
+
+
+
+
+ 2002-07-28
+
+
+ Inputs
+
+
+
+
+
+ name
+
+
+ The name of the operator class to be created.
+ The name may be schema-qualified.
+
+
+
+
+ DEFAULT
+
+
+ If present, the operator class will become the default index
+ operator class for its datatype. At most one operator class
+ can be the default for a specific datatype and access method.
+
+
+
+
+ data_type
+
+
+ The column datatype that this operator class is for.
+
+
+
+
+ access_method
+
+
+ The name of the index access method this operator class is for.
+
+
+
+
+ strategy_number
+
+
+ The index access method's strategy number for an operator associated
+ with the operator class.
+
+
+
+
+ operator_id
+
+
+ The identifier (optionally schema-qualified) of an operator associated
+ with the operator class.
+
+
+
+
+ type
+
+
+ The input datatype(s) of an operator, or NONE to
+ signify a left-unary or right-unary operator. The input datatypes
+ may be omitted in the normal case where they are the same as the
+ operator class's datatype.
+
+
+
+
+ RECHECK
+
+
+ If present, the index is lossy for this operator,
+ and so the tuples retrieved using the index must be rechecked
+ to verify that they actually satisfy the qualification clause
+ involving this operator.
+
+
+
+
+ support_number
+
+
+ The index access method's support procedure number for a function
+ associated with the operator class.
+
+
+
+
+ func_name
+
+
+ The name (optionally schema-qualified) of a function that is
+ an index access method support procedure for the operator class.
+
+
+
+
+ parameter_types
+
+
+ The parameter datatype(s) of the function.
+
+
+
+
+ storage_type
+
+
+ The datatype actually stored in the index. Normally this is the
+ same as the column datatype, but some index access methods (only
+ GIST at this writing) allow it to be different. The
+ STORAGE clause must be omitted unless the index access
+ method allows a different type to be used.
+
+
+
+
+
+
+
+
+
+ 2002-07-28
+
+
+ Outputs
+
+
+
+
+
+CREATE OPERATOR CLASS
+
+
+
+ Message returned if the operator class is successfully created.
+
+
+
+
+
+
+
+
+
+
+ 2002-07-28
+
+
+ Description
+
+
+ CREATE OPERATOR CLASS defines a new operator class,
+ name.
+
+
+ An operator class defines how a particular datatype can be used with
+ an index. The operator class specifies that certain operators will fill
+ particular roles or strategies for this datatype and this
+ access method. The operator class also specifies the support procedures to
+ be used by
+ the index access 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.
+
+
+
+ If a schema name is given then the operator class is created in the
+ specified schema. Otherwise it is created in the current schema (the one
+ at the front of the search path; see CURRENT_SCHEMA()).
+ Two operator classes in the same schema can have the same name only if they
+ are for different index access methods.
+
+
+ The user who defines an operator class becomes its owner. The user
+ must own the datatype for which the operator class is being defined,
+ and must have execute permission for all referenced operators and functions.
+
+
+
+ CREATE OPERATOR CLASS does not presently check
+ whether the class definition includes all the operators and functions
+ required by the index access method. It is the user's
+ responsibility to define a valid operator class.
+
+
+
+ Refer to the chapter on interfacing extensions to indexes in the
+ PostgreSQL Programmer's Guide
+ for further information.
+
+
+
+
+ 2002-07-28
+
+
+ Notes
+
+
+ Refer to
+
+ to delete user-defined operator classes from a database.
+
+
+
+
+
+
+ Usage
+
+
+ The following example command defines a GiST index operator class
+ for datatype _int4 (array of int4). See
+ contrib/intarray/ for the complete example.
+
+
+
+CREATE OPERATOR CLASS gist__int_ops
+ DEFAULT FOR TYPE _int4 USING gist AS
+ OPERATOR 3 &&,
+ OPERATOR 6 = RECHECK,
+ OPERATOR 7 @,
+ OPERATOR 8 ~,
+ OPERATOR 20 @@ (_int4, query_int),
+ FUNCTION 1 g_int_consistent (opaque, _int4, int4),
+ FUNCTION 2 g_int_union (bytea, opaque),
+ FUNCTION 3 g_int_compress (opaque),
+ FUNCTION 4 g_int_decompress (opaque),
+ FUNCTION 5 g_int_penalty (opaque, opaque, opaque),
+ FUNCTION 6 g_int_picksplit (opaque, opaque),
+ FUNCTION 7 g_int_same (_int4, _int4, opaque);
+
+
+
+ The OPERATOR, FUNCTION, and STORAGE
+ clauses may appear in any order.
+
+
+
+
+
+ Compatibility
+
+
+
+
+ 2002-07-28
+
+
+ SQL92
+
+
+
+ CREATE OPERATOR CLASS
+ is a PostgreSQL extension.
+ There is no CREATE OPERATOR CLASS
+ statement in SQL92.
+
+
+
+
+
+
diff --git a/doc/src/sgml/ref/drop_opclass.sgml b/doc/src/sgml/ref/drop_opclass.sgml
new file mode 100644
index 00000000000..631a45aaeba
--- /dev/null
+++ b/doc/src/sgml/ref/drop_opclass.sgml
@@ -0,0 +1,184 @@
+
+
+
+
+ DROP OPERATOR CLASS
+ SQL - Language Statements
+
+
+
+ DROP OPERATOR CLASS
+
+
+ remove a user-defined operator class
+
+
+
+
+
+ 2002-07-28
+
+
+DROP OPERATOR CLASS name USING access_method [ CASCADE | RESTRICT ]
+
+
+
+
+ 2002-07-28
+
+
+ Inputs
+
+
+
+
+ name
+
+
+ The name (optionally schema-qualified) of an existing operator class.
+
+
+
+
+ access_method
+
+
+ The name of the index access method the operator class is for.
+
+
+
+
+ CASCADE
+
+
+ Automatically drop objects that depend on the operator class.
+
+
+
+
+ RESTRICT
+
+
+ Refuse to drop the operator class if there are any dependent objects.
+ This is the default.
+
+
+
+
+
+
+
+
+
+ 2002-07-28
+
+
+ Outputs
+
+
+
+
+
+
+DROP OPERATOR CLASS
+
+
+
+ The message returned if the command is successful.
+
+
+
+
+
+
+
+
+
+
+ 2002-07-28
+
+
+ Description
+
+
+ DROP OPERATOR CLASS drops an existing operator class
+ from the database.
+ To execute this command you must be the owner of the operator class.
+
+
+
+
+ 2002-07-28
+
+
+ Notes
+
+
+ The DROP OPERATOR CLASS statement is a
+ PostgreSQL
+ language extension.
+
+
+ Refer to
+
+ for information on how to create operator classes.
+
+
+
+
+
+
+ Usage
+
+
+ Remove btree operator class widget_ops:
+
+
+DROP OPERATOR CLASS widget_ops USING btree;
+
+
+ This command will not execute if there are any existing indexes
+ that use the operator class. Add CASCADE to drop
+ such indexes along with the operator class.
+
+
+
+
+
+ Compatibility
+
+
+
+
+ 2002-07-28
+
+
+ SQL92
+
+
+ There is no DROP OPERATOR CLASS in
+ SQL92.
+
+
+
+
+
+
diff --git a/doc/src/sgml/ref/drop_operator.sgml b/doc/src/sgml/ref/drop_operator.sgml
index 1cfb824090c..edd99bd75e3 100644
--- a/doc/src/sgml/ref/drop_operator.sgml
+++ b/doc/src/sgml/ref/drop_operator.sgml
@@ -1,5 +1,5 @@
@@ -172,10 +172,6 @@ ERROR: RemoveOperator: right unary operator 'oper
for information on how to create operators.
-
- It is the user's responsibility to remove any access method
- operator classes that rely on the deleted operator.
-
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index e2491f54082..2101dfe8a1b 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,5 +1,5 @@
@@ -70,6 +70,7 @@ PostgreSQL Reference Manual
&createIndex;
&createLanguage;
&createOperator;
+ &createOperatorClass;
&createRule;
&createSchema;
&createSequence;
@@ -91,6 +92,7 @@ PostgreSQL Reference Manual
&dropIndex;
&dropLanguage;
&dropOperator;
+ &dropOperatorClass;
&dropRule;
&dropSchema;
&dropSequence;
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index 47f36858f92..af82154d8c7 100644
--- a/doc/src/sgml/release.sgml
+++ b/doc/src/sgml/release.sgml
@@ -1,5 +1,5 @@
@@ -24,6 +24,7 @@ CDATA means the content is "SGML-free", so you can write without
worries about funny characters.
-->