begriffs open source - ai-pg/blob - full-docs/txt/sql-createopclass.txt

   1
   2 CREATE OPERATOR CLASS
   3
   4    CREATE OPERATOR CLASS — define a new operator class
   5
   6 Synopsis
   7
   8 CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type
   9   USING index_method [ FAMILY family_name ] AS
  10   {  OPERATOR strategy_number operator_name [ ( op_type, op_type ) ] [ FOR SEARC
  11 H | FOR ORDER BY sort_family_name ]
  12    | FUNCTION support_number [ ( op_type [ , op_type ] ) ] function_name ( argum
  13 ent_type [, ...] )
  14    | STORAGE storage_type
  15   } [, ... ]
  16
  17 Description
  18
  19    CREATE OPERATOR CLASS creates a new operator class. An operator class
  20    defines how a particular data type can be used with an index. The
  21    operator class specifies that certain operators will fill particular
  22    roles or “strategies” for this data type and this index method. The
  23    operator class also specifies the support functions to be used by the
  24    index method when the operator class is selected for an index column.
  25    All the operators and functions used by an operator class must be
  26    defined before the operator class can be created.
  27
  28    If a schema name is given then the operator class is created in the
  29    specified schema. Otherwise it is created in the current schema. Two
  30    operator classes in the same schema can have the same name only if they
  31    are for different index methods.
  32
  33    The user who defines an operator class becomes its owner. Presently,
  34    the creating user must be a superuser. (This restriction is made
  35    because an erroneous operator class definition could confuse or even
  36    crash the server.)
  37
  38    CREATE OPERATOR CLASS does not presently check whether the operator
  39    class definition includes all the operators and functions required by
  40    the index method, nor whether the operators and functions form a
  41    self-consistent set. It is the user's responsibility to define a valid
  42    operator class.
  43
  44    Related operator classes can be grouped into operator families. To add
  45    a new operator class to an existing family, specify the FAMILY option
  46    in CREATE OPERATOR CLASS. Without this option, the new class is placed
  47    into a family named the same as the new class (creating that family if
  48    it doesn't already exist).
  49
  50    Refer to Section 36.16 for further information.
  51
  52 Parameters
  53
  54    name
  55           The name of the operator class to be created. The name can be
  56           schema-qualified.
  57
  58    DEFAULT
  59           If present, the operator class will become the default operator
  60           class for its data type. At most one operator class can be the
  61           default for a specific data type and index method.
  62
  63    data_type
  64           The column data type that this operator class is for.
  65
  66    index_method
  67           The name of the index method this operator class is for.
  68
  69    family_name
  70           The name of the existing operator family to add this operator
  71           class to. If not specified, a family named the same as the
  72           operator class is used (creating it, if it doesn't already
  73           exist).
  74
  75    strategy_number
  76           The index method's strategy number for an operator associated
  77           with the operator class.
  78
  79    operator_name
  80           The name (optionally schema-qualified) of an operator associated
  81           with the operator class.
  82
  83    op_type
  84           In an OPERATOR clause, the operand data type(s) of the operator,
  85           or NONE to signify a prefix operator. The operand data types can
  86           be omitted in the normal case where they are the same as the
  87           operator class's data type.
  88
  89           In a FUNCTION clause, the operand data type(s) the function is
  90           intended to support, if different from the input data type(s) of
  91           the function (for B-tree comparison functions and hash
  92           functions) or the class's data type (for B-tree sort support
  93           functions, B-tree equal image functions, and all functions in
  94           GiST, SP-GiST, GIN and BRIN operator classes). These defaults
  95           are correct, and so op_type need not be specified in FUNCTION
  96           clauses, except for the case of a B-tree sort support function
  97           that is meant to support cross-data-type comparisons.
  98
  99    sort_family_name
 100           The name (optionally schema-qualified) of an existing btree
 101           operator family that describes the sort ordering associated with
 102           an ordering operator.
 103
 104           If neither FOR SEARCH nor FOR ORDER BY is specified, FOR SEARCH
 105           is the default.
 106
 107    support_number
 108           The index method's support function number for a function
 109           associated with the operator class.
 110
 111    function_name
 112           The name (optionally schema-qualified) of a function that is an
 113           index method support function for the operator class.
 114
 115    argument_type
 116           The parameter data type(s) of the function.
 117
 118    storage_type
 119           The data type actually stored in the index. Normally this is the
 120           same as the column data type, but some index methods (currently
 121           GiST, GIN, SP-GiST and BRIN) allow it to be different. The
 122           STORAGE clause must be omitted unless the index method allows a
 123           different type to be used. If the column data_type is specified
 124           as anyarray, the storage_type can be declared as anyelement to
 125           indicate that the index entries are members of the element type
 126           belonging to the actual array type that each particular index is
 127           created for.
 128
 129    The OPERATOR, FUNCTION, and STORAGE clauses can appear in any order.
 130
 131 Notes
 132
 133    Because the index machinery does not check access permissions on
 134    functions before using them, including a function or operator in an
 135    operator class is tantamount to granting public execute permission on
 136    it. This is usually not an issue for the sorts of functions that are
 137    useful in an operator class.
 138
 139    The operators should not be defined by SQL functions. An SQL function
 140    is likely to be inlined into the calling query, which will prevent the
 141    optimizer from recognizing that the query matches an index.
 142
 143 Examples
 144
 145    The following example command defines a GiST index operator class for
 146    the data type _int4 (array of int4). See the intarray module for the
 147    complete example.
 148 CREATE OPERATOR CLASS gist__int_ops
 149     DEFAULT FOR TYPE _int4 USING gist AS
 150         OPERATOR        3       &&,
 151         OPERATOR        6       = (anyarray, anyarray),
 152         OPERATOR        7       @>,
 153         OPERATOR        8       <@,
 154         OPERATOR        20      @@ (_int4, query_int),
 155         FUNCTION        1       g_int_consistent (internal, _int4, smallint, oid
 156 , internal),
 157         FUNCTION        2       g_int_union (internal, internal),
 158         FUNCTION        3       g_int_compress (internal),
 159         FUNCTION        4       g_int_decompress (internal),
 160         FUNCTION        5       g_int_penalty (internal, internal, internal),
 161         FUNCTION        6       g_int_picksplit (internal, internal),
 162         FUNCTION        7       g_int_same (_int4, _int4, internal);
 163
 164 Compatibility
 165
 166    CREATE OPERATOR CLASS is a PostgreSQL extension. There is no CREATE
 167    OPERATOR CLASS statement in the SQL standard.
 168
 169 See Also
 170
 171    ALTER OPERATOR CLASS, DROP OPERATOR CLASS, CREATE OPERATOR FAMILY,
 172    ALTER OPERATOR FAMILY