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. -->