PK
"IFoa, mimetypeapplication/epub+zipPK "IF META-INF/container.xml
This chapter describes Oracle Data Cartridge Interface extensible indexing interfaces. This chapter contains this topic:
Table 20-1 summarizes the extensible indexing routines.
Caution: These routines are invoked by Oracle at the appropriate times based on SQL statements executed by the end user. Do not invoke these routines directly as this may result in corruption of index data. |
Table 20-1 Summary of System-Defined Extensible Indexing Interface Routines
Routine | Description |
---|---|
|
Invoked when an |
|
Invoked when a domain index or a domain index partition is altered using an |
|
Invoked to end the processing of an operator. |
|
Invoked when a domain index is created by a |
|
Invoked when a row is deleted from a table that has a domain index defined on one or more of its columns. |
|
Invoked when a domain index is dropped explicitly using a |
|
Invoked when an |
|
Invoked repeatedly to retrieve the rows satisfying the operator predicate. |
|
Returns a series of strings of PL/SQL code that comprise the non-dictionary metadata associated with the index. |
|
Invoked when a row or a set of rows is inserted into a table that has a domain index defined on one or more of its columns. |
|
Invoked to start the evaluation of an operator on an indexed column. |
|
Invoked when a row is updated in a table and the updated column has a domain index defined on. |
|
Invoked during partition maintenance operations. Patches the indextype metadata tables to correctly reflect the partition maintenance operation. |
|
Cleans up temporary states created by ODCIIndexUtilGetTableNames(). |
|
IDetermines if the secondary tables storing the index data should be transported. |
Invoked when an INDEXTYPE
is created by a CREATE
INDEXTYPE...
statement or is altered.
Syntax
FUNCTION ODCIGetInterfaces( ifclist OUT ODCIObjectList) RETURN NUMBER
Parameter | Description |
---|---|
ifclist | Contains information about the interfaces it supports |
Returns
ODCIConst.Success
on success or ODCIConst.Error
on error
Usage Notes
This function should be implemented as a static type method.
This function must return SYS.ODCIINDEX2
in the ODCIObjectList
if the indextype uses the second version of the ODCIIndex
interface, which was implemented in the current version of the Oracle Database and is described in this book.
Invoked when a domain index or a domain index partition is altered using one of the following methods:
ALTER INDEX
ALTER INDEX PARTITION
TRUNCATE TABLE
table_name
RENAME TABLE
ALTER TABLE...[ADD|TRUNCATE|SPLIT|MERGE]...PARTITION
ALTER TABLE RENAME
ALTER TABLE RENAME COLUMN
To populate the index partitions when creating local domain indexes, this method is invoked for each partition of the base table.
Syntax
STATIC FUNCTION ODCIIndexAlter( ia ODCIIndexInfo, parms IN OUT VARCHAR2, alter_option NUMBER, env ODCIEnv) RETURN NUMBER
Parameter | Description |
---|---|
ia | Contains information about the index and the indexed column |
parms (IN) | Parameter string
|
parms (OUT) | Parameter string
Valid only with |
alter_option | Specifies one of the following options:
|
env | The environment handle passed to the routine |
Returns
ODCIConst.Success
on success, ODCIConst.Error
on error, or ODCIConst.Warning
otherwise. When invoked to rebuild local index partitions, may also return ODCIConst.ErrContinue
.
Usage Notes
This function should be implemented as a static type method.
An ALTER
INDEX
statement can be invoked for domain indexes in multiple ways.
ALTER INDEX index_name PARAMETERS (parms);
or
ALTER INDEX index_name REBUILD PARAMETERS (parms);
The precise behavior in these two cases is defined by the implementation. One possibility is that the first statement would merely reorganize the index based on the parameters while the second would rebuild it from scratch.
The maximum length of the input parameters string is 1000 characters. The OUT
value of the parms
argument can be set to resultant parameters string to be stored in the system catalogs.
The ALTER
INDEX
statement can also be used to rename a domain index in the following way:
ALTER INDEX index_name RENAME TO new_index_name
When the name of the table on which a domain index is created changes, ODCIIndexAlter() is invoked with alter_option=AlterIndexRenameTab
, and new_table_name
is passed to the parms
argument:
ALTER TABLE table_name
RENAME new_table_name
or
RENAME table_name TO new_table_name
When the name of the column on which a domain index is created changes, ODCIIndexAlter() is invoked with alter_option=AlterIndexRenameCol
, and new_column_name
is passed to the parms
argument:
ALTER TABLE table_name
RENAME COLUMN column_name
TO new_column_name
If the PARALLEL
clause is omitted, then the domain index or local domain index partition is rebuilt sequentially.
If the PARALLEL
clause is specified, the parallel degree is passed to the ODCIIndexAlter() invocation in the IndexParaDegree
attribute of ODCIIndexInfo
, and the Parallel
bit of the IndexInfoFlags
attribute is set. The parallel degree is determined as follows:
If PARALLEL DEGREE
deg is specified, deg is passed.
If only PARALLEL
is specified, then a constant is passed to indicate that the default degree of parallelism was specified.
If the ODCIIndexAlter
routine returns with the ODCIConst
.Success
, the index is valid and usable. If the ODCIIndexAlter() routine returns with ODCIConst
.Warning
, the index is valid and usable but a warning message is returned to the user. If ODCIIndexAlter() returns with an error (or exception), the domain index is marked FAILED
.
When the ODCIIndexAlter() routine is being executed, the domain index is marked LOADING
.
Every SQL statement executed by ODCIIndexAlter() is treated as an independent operation. The changes made by ODCIIndexCreate() are not guaranteed to be atomic.
The AlterIndexUpdBlockRefs
alter option applies only to domain indexes on index-organized tables. When the end user executes an ALTER INDEX
domain_index
UPDATE BLOCK REFERENCES
, ODCIIndexAlter() is called with the AlterIndexUpdBlockRefs
bit set to give the cartridge developer the opportunity to update guesses as to the block locations of rows, stored in logical rowids.
The AlterIndexMigrate
alter options applies only to migration of user-managed domain indexes to system-managed domain indexes. When the user-managed domain index is marked INVALID
, but its indextype is system-managed, you must make an ALTER INDEX
domain_index
COMPILE
call to re-validate the domain index. This calls the ODCIIndexAlter() method with alter_option=AlterIndexMigrate
, to allow an opportunity to migrate the domain index to the system-managed approach.
Invoked to end the processing of an operator.
Syntax
FUNCTION ODCIIndexClose(
self IN impltype,
env ODCIEnv)
RETURN NUMBER
Parameter | Description |
---|---|
self(IN) | Is the value of the context returned by the previous invocation of ODCIIndexFetch() |
env | The environment handle passed to the routine |
Returns
ODCIConst.Success
on success
ODCIConst.Error
on error
Usage Notes
The index implementor can perform any appropriate actions to finish up the processing of an domain index scan, such as freeing memory and other resources.
Invoked when a domain index is created by a CREATE INDEX...INDEXTYPE IS...PARAMETERS...
statement issued by the user. The domain index can be either a non-partitioned index or a local partitioned domain index. The local partitioned domain index can be created in either a system- or a user-managed scheme.
Syntax
FUNCTION ODCIIndexCreate( ia ODCIIndexInfo, parms VARCHAR2, env ODCIEnv) RETURN NUMBER
Parameter | Description |
---|---|
ia | Contains information about the index and the indexed column |
parms | The PARAMETERS string passed in not interpreted by Oracle. The maximum size of the parameter string is 1,000 characters. |
env | The environment handle passed to the routine |
Returns
ODCIConst.Success
, ODCIConst.Error
, ODCIConst.Warning
, ODCIConst.ErrContinue
if the method is invoked at the partition level for creation of a local partitioned index, to continue to the next partition even in case of an error, or ODCIConst.Fatal
to signify that all dictionary entries for the index are cleaned up and that the CREATE INDEX
operation is rolled back. Returning this status code assumes that the cartridge code has not created any objects (or cleaned up any objects created).
Usage Notes
This function should be implemented as a STATIC
type method.
Creates objects (such as tables) to store the index data, generate the index data, and store the data in the index data tables.
This procedure should handle creation of indexes on both empty and non-empty tables. If the base table is not empty, the procedure can scan the entire table and generate index data.
When the ODCIIndexCreate() routine is running, the domain index is marked LOADING
.
Every SQL statement executed by ODCIIndexCreate() is treated as an independent operation. The changes made by ODCIIndexCreate() are not guaranteed to be atomic.
To create a non-partitioned domain index, the ODCIIndexCreate() method is invoked, and the only valid return codes are ODCIConst.Success
, ODCIConst.Warning
, ODCIConst.Error
, or ODCIConst.Fatal
. If the operation returns ODCIConst.Fatal
, the CREATE INDEX
statement is rolled back by the server.
In a non-partitioned domain index, the IndexPartition
, TablePartition
name, and the callProperty
should be NULL
.
For a non-partitioned domain index, the parallel degree is passed to the ODCIIndexCreate() invocation in the IndexParaDegree
attribute of ODCIIndexInfo
, and the Parallel
bit of the IndexInfoFlags
is set. The parallel degree is determined as follows:
If PARALLEL DEGREE
deg
is specified, deg
is passed.
If only PARALLEL
is specified, then a constant indicating that the default degree of parallelism was specified, is passed.
If the PARALLEL
clause is omitted entirely, the operation is performed sequentially.
If the ODCIIndexCreate() routine returns with the ODCIConst
.Success
, the index is valid and usable. If the ODCIIndexCreate() routine returns with ODCIConst
.Warning
, the index is valid and usable but a warning message is returned to the user. If the ODCIIndexCreate() routine returns with an ODCIConst
.Error
(or exception), the domain index is marked FAILED.
The only operations permitted on FAILED
domain indexes is DROP
INDEX
, TRUNCATE
TABLE
or ALTER
INDEX
REBUILD
.
If a domain index is created on an column of object type which contains a REF
attribute, do not dereference the REF
s while building your index. Dereferencing a REF
fetches data from a different table instance. If the data in the other table is modified, the domain index becomes incorrect. Note that the user is not notified.
The ODCIIndexCreate() method is invoked twice for the creation of system managed local domain indexes and the only valid return codes are ODCIConst.Success
, ODCIConst.Warning
or ODCIConst.Error
. ODCIConst.Fatal
can be returned by the first call and results in the CREATE INDEX
statement being rolled back by the server. The number of partitions is passed in as an argument ODCIIndexInfo.IndexPartitionTotal
. The first call should create all the index storage tables. All the index storage tables should preferably be system partitioned to get the benefits of local domain indexes. Also:
These tables must have the same number of partitions as the base table
The users should generate the create table statement with both object and partition level attributes
Note that the object level create routine only passes in the object level parameter string. However, to construct the storage attributes for all the partitions, it needs the partition level parameter strings. The cartridge indexing code must obtain them by querying the *_ind_partitions
views on the dictionary tables. The system partitioned tables should not be populated in this phase. The user should wait for the subsequent calls ODCIIndexAlter() to populate the partitions. Also, it is recommended that the users should derive the names of the storage tables and its partitions from the index name and the index partition names. In this case, the user should fetch the index partition names from the *_ind_partitions
view and construct the partition names for the storage table.
In the second ODCIIndexCreate() call, the user can create domain index storage table dependent objects, such as indexes, constraints, and triggers. These can be created as before by directly using the SQL callbacks. However, for system partitioned storage tables, the following types of indexes are disallowed:
non-partitioned index
globally partitioned index
Sequence numbers and synonyms can be created using callbacks and they are assumed to be partition-independent. The set of objects created for non-partitioned domain index is identical to that of a local partitioned index and these objects are not impacted when a table or partition maintenance operation is done. It is the users responsibility to drop these objects when the index is dropped.
Other (transient) objects needed for temporary use can be created using callbacks as before. It is the responsibility of user-supplied code to drop them by the end of the create call.
Temporary tables can be created for holding intermediate data. The server does not perform maintenance operations on these tables.
External Objects, such as files, can be created for temporary use.
All the tables left after the invocation of ODCIIndexCreate() or ODCIIndexAlter() are supposed to be system-managed, and the server takes appropriate actions on them during drop, truncate, or the partition maintenance operations.
Since this routine handles multiple things, such as creation of a non-partitioned index or creation of a local index, you must take special care to code it appropriately.