diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/ref/allfiles.sgml | 5 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_opclass.sgml | 3 | ||||
| -rw-r--r-- | doc/src/sgml/ref/alter_opfamily.sgml | 312 | ||||
| -rw-r--r-- | doc/src/sgml/ref/comment.sgml | 6 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_opclass.sgml | 48 | ||||
| -rw-r--r-- | doc/src/sgml/ref/create_opfamily.sgml | 125 | ||||
| -rw-r--r-- | doc/src/sgml/ref/drop_opclass.sgml | 24 | ||||
| -rw-r--r-- | doc/src/sgml/ref/drop_opfamily.sgml | 135 | ||||
| -rw-r--r-- | doc/src/sgml/reference.sgml | 5 |
9 files changed, 651 insertions, 12 deletions
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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.68 2006/09/18 19:54:01 tgl Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.69 2007/01/23 05:07:16 tgl Exp $ PostgreSQL documentation Complete list of usable sgml source files in this directory. --> @@ -16,6 +16,7 @@ Complete list of usable sgml source files in this directory. <!entity alterLanguage system "alter_language.sgml"> <!entity alterOperator system "alter_operator.sgml"> <!entity alterOperatorClass system "alter_opclass.sgml"> +<!entity alterOperatorFamily system "alter_opfamily.sgml"> <!entity alterRole system "alter_role.sgml"> <!entity alterSchema system "alter_schema.sgml"> <!entity alterSequence system "alter_sequence.sgml"> @@ -45,6 +46,7 @@ Complete list of usable sgml source files in this directory. <!entity createLanguage system "create_language.sgml"> <!entity createOperator system "create_operator.sgml"> <!entity createOperatorClass system "create_opclass.sgml"> +<!entity createOperatorFamily system "create_opfamily.sgml"> <!entity createRole system "create_role.sgml"> <!entity createRule system "create_rule.sgml"> <!entity createSchema system "create_schema.sgml"> @@ -70,6 +72,7 @@ Complete list of usable sgml source files in this directory. <!entity dropLanguage system "drop_language.sgml"> <!entity dropOperator system "drop_operator.sgml"> <!entity dropOperatorClass system "drop_opclass.sgml"> +<!entity dropOperatorFamily system "drop_opfamily.sgml"> <!entity dropOwned system "drop_owned.sgml"> <!entity dropRole system "drop_role.sgml"> <!entity dropRule system "drop_rule.sgml"> 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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/alter_opclass.sgml,v 1.7 2006/09/16 00:30:16 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/alter_opclass.sgml,v 1.8 2007/01/23 05:07:17 tgl Exp $ PostgreSQL documentation --> @@ -102,6 +102,7 @@ ALTER OPERATOR CLASS <replaceable>name</replaceable> USING <replaceable class="p <simplelist type="inline"> <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member> <member><xref linkend="sql-dropopclass" endterm="sql-dropopclass-title"></member> + <member><xref linkend="sql-alteropfamily" endterm="sql-alteropfamily-title"></member> </simplelist> </refsect1> </refentry> 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 @@ +<!-- +$PostgreSQL: pgsql/doc/src/sgml/ref/alter_opfamily.sgml,v 1.1 2007/01/23 05:07:17 tgl Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-ALTEROPFAMILY"> + <refmeta> + <refentrytitle id="SQL-ALTEROPFAMILY-TITLE">ALTER OPERATOR FAMILY</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>ALTER OPERATOR FAMILY</refname> + <refpurpose>change the definition of an operator family</refpurpose> + </refnamediv> + + <indexterm zone="sql-alteropfamily"> + <primary>ALTER OPERATOR FAMILY</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> ADD + { OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_name</replaceable> ( <replaceable class="parameter">op_type</replaceable>, <replaceable class="parameter">op_type</replaceable> ) [ RECHECK ] + | FUNCTION <replaceable class="parameter">support_number</replaceable> [ ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] ) ] <replaceable class="parameter">funcname</replaceable> ( <replaceable class="parameter">argument_type</replaceable> [, ...] ) + } [, ... ] +ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> DROP + { OPERATOR <replaceable class="parameter">strategy_number</replaceable> ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] ) + | FUNCTION <replaceable class="parameter">support_number</replaceable> ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] ) + } [, ... ] +ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> RENAME TO <replaceable>newname</replaceable> +ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class="parameter">index_method</replaceable> OWNER TO <replaceable>newowner</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>ALTER OPERATOR FAMILY</command> 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. + </para> + + <para> + When operators and support functions are added to a family with + <command>ALTER OPERATOR FAMILY</command>, they are not part of any + specific operator class within the family, but are just <quote>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 <xref linkend="sql-createopclass" + endterm="sql-createopclass-title">.) + <productname>PostgreSQL</productname> 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. + </para> + + <para> + You must be a superuser to use <command>ALTER OPERATOR FAMILY</>. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an existing operator + family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">index_method</replaceable></term> + <listitem> + <para> + The name of the index method this operator family is for. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">strategy_number</replaceable></term> + <listitem> + <para> + The index method's strategy number for an operator + associated with the operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">operator_name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an operator associated + with the operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">op_type</replaceable></term> + <listitem> + <para> + In an <literal>OPERATOR</> clause, + the operand data type(s) of the operator, or <literal>NONE</> to + signify a left-unary or right-unary operator. Unlike the comparable + syntax in <command>CREATE OPERATOR CLASS</>, the operand data types + must always be specified. + </para> + + <para> + In an <literal>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 <replaceable + class="parameter">op_type</replaceable> 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. + </para> + + <para> + In a <literal>DROP FUNCTION</> clause, the operand data type(s) the + function is intended to support must be specified. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RECHECK</></term> + <listitem> + <para> + If present, the index is <quote>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. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">support_number</replaceable></term> + <listitem> + <para> + The index method's support procedure number for a + function associated with the operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">funcname</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of a function that is an + index method support procedure for the operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">argument_types</replaceable></term> + <listitem> + <para> + The parameter data type(s) of the function. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">newname</replaceable></term> + <listitem> + <para> + The new name of the operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">newowner</replaceable></term> + <listitem> + <para> + The new owner of the operator family. + </para> + </listitem> + </varlistentry> + </variablelist> + + <para> + The <literal>OPERATOR</> and <literal>FUNCTION</> + clauses may appear in any order. + </para> + + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + Notice that the <literal>DROP</> syntax only specifies the <quote>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 <literal>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. + </para> + + <para> + 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. + </para> + + <para> + 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. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + 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 <type>int4</> and <type>int2</>. + </para> + +<programlisting> +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) ; +</programlisting> + + <para> + To remove these entries again: + </para> + +<programlisting> +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) ; +</programlisting> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>ALTER OPERATOR FAMILY</command> statement in + the SQL standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createopfamily" endterm="sql-createopfamily-title"></member> + <member><xref linkend="sql-dropopfamily" endterm="sql-dropopfamily-title"></member> + <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member> + <member><xref linkend="sql-alteropclass" endterm="sql-alteropclass-title"></member> + <member><xref linkend="sql-dropopclass" endterm="sql-dropopclass-title"></member> + </simplelist> + </refsect1> +</refentry> 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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.33 2006/10/23 18:10:32 petere Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/comment.sgml,v 1.34 2007/01/23 05:07:17 tgl Exp $ PostgreSQL documentation --> @@ -35,6 +35,7 @@ COMMENT ON LARGE OBJECT <replaceable class="PARAMETER">large_object_oid</replaceable> | OPERATOR <replaceable class="PARAMETER">op</replaceable> (<replaceable class="PARAMETER">leftoperand_type</replaceable>, <replaceable class="PARAMETER">rightoperand_type</replaceable>) | OPERATOR CLASS <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> | + OPERATOR FAMILY <replaceable class="PARAMETER">object_name</replaceable> USING <replaceable class="parameter">index_method</replaceable> | [ PROCEDURAL ] LANGUAGE <replaceable class="PARAMETER">object_name</replaceable> | ROLE <replaceable class="PARAMETER">object_name</replaceable> | RULE <replaceable class="PARAMETER">rule_name</replaceable> ON <replaceable class="PARAMETER">table_name</replaceable> | @@ -92,7 +93,7 @@ COMMENT ON <para> 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. </para> </listitem> </varlistentry> @@ -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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.18 2006/10/16 17:28:03 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/create_opclass.sgml,v 1.19 2007/01/23 05:07:17 tgl Exp $ PostgreSQL documentation --> @@ -20,9 +20,10 @@ PostgreSQL documentation <refsynopsisdiv> <synopsis> -CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAULT ] FOR TYPE <replaceable class="parameter">data_type</replaceable> USING <replaceable class="parameter">index_method</replaceable> AS +CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAULT ] FOR TYPE <replaceable class="parameter">data_type</replaceable> + USING <replaceable class="parameter">index_method</replaceable> [ FAMILY <replaceable class="parameter">family_name</replaceable> ] AS { OPERATOR <replaceable class="parameter">strategy_number</replaceable> <replaceable class="parameter">operator_name</replaceable> [ ( <replaceable class="parameter">op_type</replaceable>, <replaceable class="parameter">op_type</replaceable> ) ] [ RECHECK ] - | FUNCTION <replaceable class="parameter">support_number</replaceable> <replaceable class="parameter">funcname</replaceable> ( <replaceable class="parameter">argument_type</replaceable> [, ...] ) + | FUNCTION <replaceable class="parameter">support_number</replaceable> [ ( <replaceable class="parameter">op_type</replaceable> [ , <replaceable class="parameter">op_type</replaceable> ] ) ] <replaceable class="parameter">funcname</replaceable> ( <replaceable class="parameter">argument_type</replaceable> [, ...] ) | STORAGE <replaceable class="parameter">storage_type</replaceable> } [, ... ] </synopsis> @@ -40,7 +41,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ 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. </para> <para> @@ -66,6 +67,15 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </para> <para> + Related operator classes can be grouped into <firstterm>operator + families</>. To add a new operator class to an existing family, + specify the <literal>FAMILY</> option in <command>CREATE OPERATOR + CLASS</command>. 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). + </para> + + <para> Refer to <xref linkend="xindex"> for further information. </para> </refsect1> @@ -114,6 +124,17 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </varlistentry> <varlistentry> + <term><replaceable class="parameter">family_name</replaceable></term> + <listitem> + <para> + 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). + </para> + </listitem> + </varlistentry> + + <varlistentry> <term><replaceable class="parameter">strategy_number</replaceable></term> <listitem> <para> @@ -137,11 +158,24 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <term><replaceable class="parameter">op_type</replaceable></term> <listitem> <para> - The operand data type(s) of an operator, or <literal>NONE</> to + In an <literal>OPERATOR</> clause, + the operand data type(s) of the operator, or <literal>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. </para> + + <para> + In a <literal>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 <replaceable + class="parameter">op_type</replaceable> in a <literal>FUNCTION</> clause + in <command>CREATE OPERATOR CLASS</>, but the option is provided + for consistency with the comparable syntax in + <command>ALTER OPERATOR FAMILY</>. + </para> </listitem> </varlistentry> @@ -192,7 +226,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <para> 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 <literal>STORAGE</> clause must be omitted unless the index method allows a different type to be used. </para> @@ -268,6 +302,8 @@ CREATE OPERATOR CLASS gist__int_ops <simplelist type="inline"> <member><xref linkend="sql-alteropclass" endterm="sql-alteropclass-title"></member> <member><xref linkend="sql-dropopclass" endterm="sql-dropopclass-title"></member> + <member><xref linkend="sql-createopfamily" endterm="sql-createopfamily-title"></member> + <member><xref linkend="sql-alteropfamily" endterm="sql-alteropfamily-title"></member> </simplelist> </refsect1> </refentry> 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 @@ +<!-- +$PostgreSQL: pgsql/doc/src/sgml/ref/create_opfamily.sgml,v 1.1 2007/01/23 05:07:17 tgl Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-CREATEOPFAMILY"> + <refmeta> + <refentrytitle id="sql-createopfamily-title">CREATE OPERATOR FAMILY</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE OPERATOR FAMILY</refname> + <refpurpose>define a new operator family</refpurpose> + </refnamediv> + + <indexterm zone="sql-createopfamily"> + <primary>CREATE OPERATOR FAMILY</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +CREATE OPERATOR FAMILY <replaceable class="parameter">name</replaceable> USING <replaceable class="parameter">index_method</replaceable> +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>CREATE OPERATOR FAMILY</command> 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 <quote>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.) + </para> + + <para> + The new operator family is initially empty. It should be populated + by issuing subsequent <command>CREATE OPERATOR CLASS</command> commands + to add contained operator classes, and optionally + <command>ALTER OPERATOR FAMILY</command> commands to add <quote>loose</> + operators and their corresponding support functions. + </para> + + <para> + 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. + </para> + + <para> + 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.) + </para> + + <para> + <command>CREATE OPERATOR FAMILY</command> 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. + </para> + + <para> + Refer to <xref linkend="xindex"> for further information. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name of the operator family to be created. The name may be + schema-qualified. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">index_method</replaceable></term> + <listitem> + <para> + The name of the index method this operator family is for. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>CREATE OPERATOR FAMILY</command> is a + <productname>PostgreSQL</productname> extension. There is no + <command>CREATE OPERATOR FAMILY</command> statement in the SQL + standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alteropfamily" endterm="sql-alteropfamily-title"></member> + <member><xref linkend="sql-dropopfamily" endterm="sql-dropopfamily-title"></member> + <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member> + <member><xref linkend="sql-alteropclass" endterm="sql-alteropclass-title"></member> + <member><xref linkend="sql-dropopclass" endterm="sql-dropopclass-title"></member> + </simplelist> + </refsect1> +</refentry> 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 @@ <!-- -$PostgreSQL: pgsql/doc/src/sgml/ref/drop_opclass.sgml,v 1.10 2006/09/16 00:30:18 momjian Exp $ +$PostgreSQL: pgsql/doc/src/sgml/ref/drop_opclass.sgml,v 1.11 2007/01/23 05:07:17 tgl Exp $ PostgreSQL documentation --> @@ -31,6 +31,13 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab <command>DROP OPERATOR CLASS</command> drops an existing operator class. To execute this command you must be the owner of the operator class. </para> + + <para> + <command>DROP OPERATOR CLASS</command> 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 + <literal>CASCADE</> for the drop to complete. + </para> </refsect1> <refsect1> @@ -86,6 +93,20 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab </varlistentry> </variablelist> </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + <command>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 <command>CREATE OPERATOR CLASS</>). An empty operator + family is harmless, but for the sake of tidiness you may wish to + remove the family with <command>DROP OPERATOR FAMILY</>; or perhaps + better, use <command>DROP OPERATOR FAMILY</> in the first place. + </para> + </refsect1> <refsect1> <title>Examples</title> @@ -118,6 +139,7 @@ DROP OPERATOR CLASS widget_ops USING btree; <simplelist type="inline"> <member><xref linkend="sql-alteropclass" endterm="sql-alteropclass-title"></member> <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member> + <member><xref linkend="sql-dropopfamily" endterm="sql-dropopfamily-title"></member> </simplelist> </refsect1> 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 @@ +<!-- +$PostgreSQL: pgsql/doc/src/sgml/ref/drop_opfamily.sgml,v 1.1 2007/01/23 05:07:17 tgl Exp $ +PostgreSQL documentation +--> + +<refentry id="SQL-DROPOPFAMILY"> + <refmeta> + <refentrytitle id="SQL-DROPOPFAMILY-TITLE">DROP OPERATOR FAMILY</refentrytitle> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>DROP OPERATOR FAMILY</refname> + <refpurpose>remove an operator family</refpurpose> + </refnamediv> + + <indexterm zone="sql-dropopfamily"> + <primary>DROP OPERATOR FAMILY</primary> + </indexterm> + + <refsynopsisdiv> +<synopsis> +DROP OPERATOR FAMILY [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> USING <replaceable class="PARAMETER">index_method</replaceable> [ CASCADE | RESTRICT ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>DROP OPERATOR FAMILY</command> drops an existing operator family. + To execute this command you must be the owner of the operator family. + </para> + + <para> + <command>DROP OPERATOR FAMILY</command> 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 + <literal>CASCADE</> for the drop to complete. + </para> + </refsect1> + + <refsect1> + <title>Parameters</title> + + <variablelist> + + <varlistentry> + <term><literal>IF EXISTS</literal></term> + <listitem> + <para> + Do not throw an error if the operator family does not exist. + A notice is issued in this case. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">name</replaceable></term> + <listitem> + <para> + The name (optionally schema-qualified) of an existing operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">index_method</replaceable></term> + <listitem> + <para> + The name of the index access method the operator family is for. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>CASCADE</literal></term> + <listitem> + <para> + Automatically drop objects that depend on the operator family. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>RESTRICT</literal></term> + <listitem> + <para> + Refuse to drop the operator family if any objects depend on it. + This is the default. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + Remove the B-tree operator family <literal>float_ops</literal>: + +<programlisting> +DROP OPERATOR FAMILY float_ops USING btree; +</programlisting> + + This command will not succeed if there are any existing indexes + that use operator classes within the family. Add <literal>CASCADE</> to + drop such indexes along with the operator family. + </para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + There is no <command>DROP OPERATOR FAMILY</command> statement in the + SQL standard. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-alteropfamily" endterm="sql-alteropfamily-title"></member> + <member><xref linkend="sql-createopfamily" endterm="sql-createopfamily-title"></member> + <member><xref linkend="sql-alteropclass" endterm="sql-alteropclass-title"></member> + <member><xref linkend="sql-createopclass" endterm="sql-createopclass-title"></member> + <member><xref linkend="sql-dropopclass" endterm="sql-dropopclass-title"></member> + </simplelist> + </refsect1> + +</refentry> 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 @@ -<!-- $PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.60 2006/09/18 19:54:01 tgl Exp $ --> +<!-- $PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.61 2007/01/23 05:07:17 tgl Exp $ --> <part id="reference"> <title>Reference</title> @@ -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; |