Skip Headers
Oracle® Database Data Cartridge Developer's Guide
11g Release 2 (11.2)

Part Number E10765-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub
ADDCI5162

A User-Managed Local Domain Indexes

The user-managed approach for partitioning domain indexes has been the only method available until Oracle Database 11g Release 1, when system-managed partitioning was introduced. The user-managed approach has three significant limitations:

Oracle recommends that you use the system-managed approach, as described in Chapter 8, "Building Domain Indexes".

Oracle plans to deprecate the user-managed approach in a future release. Information provided in this appendix documents the specific differences between the user-managed and system managed processes and APIs.

ADDCI5163

Comparing User-Managed and System-Managed Domain Indexes

An alternative approach would be to use system-managed domain indexes. It addresses these limitations and has the following benefits:

ADDCI5164

Truncating Domain Indexes

There is no explicit statement for truncating a domain index. However, when the corresponding table is truncated, your indextype's truncate method is invoked. For example:

TRUNCATE TABLE MyEmployees;

truncates ResumeTextIndex by calling your ODCIIndexTruncate() method.

ADDCI5165

Creating Indextypes

Use the following syntax to create indextypes for the user-managed domain indexes.

CREATE INDEXTYPE TextIndexType
FOR Contains (VARCHAR2, VARCHAR2)
USING TextIndexMethods;
ADDCI5166

Using Domain Indexes for the Indextype

In order for the indextype to be able to use local domain indexes, the methods have to be declared when the indextype is created:

CREATE INDEXTYPE TextIndexType
  FOR Contains (VARCHAR2, VARCHAR2)
  USING TextIndexMethods
  WITH LOCAL RANGE PARTITION;
ADDCI5167

Partitioning Domain Indexes

The user-managed approach uses the methods ODCIIndexMergePartition() and ODCIIndexSplitPartition() to support local domain indexes.

ADDCI5168

APIs for User-Managed Domain Indexes

The following methods are used only in the user-managed implementation of domain indexes.

ADDCI5169

ODCIIndexTruncate()

This is an index definition method. When a user issues a TRUNCATE statement against a table that contains a column or object type attribute indexed by your indextype, Oracle calls your ODCIIndexTruncate() method. This method should leave the domain index empty.

ADDCI5170Syntax

FUNCTION ODCIIndexTruncate(
   ia ODCIIndexInfo, 
   env ODCIEnv) 
RETURN NUMBER
Parameter Description
ia
Contains information about the indexed column
env
The environment handle passed to the routine

ADDCI5171Returns

ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.

While truncating a local domain index, the first N+1 calls can return ODCIConst.ErrContinue too.

ADDCI5172Usage Notes

  • This function should be implemented as a static type method.

  • After this function executes, the domain index should be empty (corresponding to the empty base table).

  • While the ODCIIndexTruncate() routine is being executed, the domain index is marked LOADING. If the ODCIIndexTruncate() routine returns with an ODCIConst.Error (or exception), the domain index is marked FAILED. The only operation permitted on FAILED domain indexes is DROP INDEX, TRUNCATE TABLE or ALTER INDEX REBUILD. If ODCIIndexTruncate() returns with ODCIConst.Warning, the operation succeeds but a warning message is returned to the user.

  • Every SQL statement executed by ODCIIndexTruncate() is treated as an independent operation. The changes made by ODCIIndexTruncate() are not guaranteed to be atomic.

  • This method is invoked for truncating a non-partitioned index, truncating a local domain index, and also for truncating a single index partition during ALTER TABLE TRUNCATE PARTITION.

    For truncating a non-partitioned index, the ODCIIndexTruncate() is invoked with the IndexPartition, TablePartition and callProperty set to NULL.

    For truncating a local domain index, the routine is invoked N+2 times, where N is the number of partitions.

    For truncating a single index partition during ALTER TABLE TRUNCATE PARTITION, this routine is invoked with the IndexPartition and the TablePartition filled in and the callProperty set to NULL.

ADDCI5173

ODCIIndexMergePartition()

Invoked when a ALTER TABLE MERGE PARTITION is issued on range partitioned table on which a domain index is defined.

ADDCI5174Syntax

FUNCTION ODCIIndexMergePartition(
   ia ODCIIndexInfo, 
   part_name1 ODCIPartInfo, 
   part_name2 ODCIPartInfo, 
   parms VARCHAR2, 
   env ODCIEnv) 
RETURN NUMBER
Parameter Description
ia
Contains index and table partition name for one of the partitions to be merged
part_name1
Contains index and table partition name for the second partition to be merged
part_name2
Holds index and table partition name for the new merged partition
parms
Contains the parameter string for the resultant merged partition, essentially the default parameter string associated with the index.
env
The environment handle passed to the routine

ADDCI5175Returns

ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.

ADDCI5176Usage Notes

  • The function should be implemented as a static type method.

  • You should create a new table representing the resultant merged partition and populate it with data from the merged partitions. Then drop the tables corresponding to the merged index partitions.

  • The newly created partition should pick the default parameter string associated with the index level. Resulting local index partitions are marked UNUSABLE; you should not attempt to populate the data in the new partition until after an ALTER INDEX REBUILD PARTITION call.

  • The old table and the dictionary entries for the old index partitions are deleted before the call to ODCIIndexMergePartition(), so the cartridge code for this routine should not rely on the existence of this data in the views.

ADDCI5177

ODCIIndexSplitPartition()

Invoked when an ALTER TABLE SPLIT PARTITION is invoked on a partitioned table where a domain index is defined.

ADDCI5178Syntax

FUNCTION ODCIIndexSplitPartition(
   ia ODCIIndexInfo, 
   part_name1 ODCIPartInfo, 
   part_name2 ODCIPartInfo, 
   parms VARCHAR2, 
   env ODCIEnv) 
RETURN NUMBER
Parameter Description
ia
Contains the information about the partition to be split
part_name1
Holds the index and table partition names for one of the new partitions
part_name2
Holds the index and table partition names for the other new partition
parms
Contains the parameter string for the new partitions, the string associated with the index partition that is being split.
env
The environment handle passed to the routine

ADDCI5179Returns

ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.

ADDCI5180Usage Notes

  • The function should be implemented as a static type method.

  • You must to drop the metadata corresponding to the partition that is split, and create metadata for the two newly created partitions.

  • The new tables should pick up the default parameter string associated with the split partition.

  • The index data corresponding to these partitions need not be computed since the indexes are marked UNUSABLE. The indexes can be built after an ALTER INDEX REBUILD PARTITION call makes the indexes usable again.

  • The old table and the old index partition's dictionary entries are deleted before the call to ODCIIndexSplitPartition(), so the cartridge code for this routine should not rely on the existence of this data in the views.

Reader Comment

   

Comments, corrections, and suggestions are forwarded to authors every week. By submitting, you confirm you agree to the terms and conditions. Use the OTN forums for product questions. For support or consulting, file a service request through My Oracle Support.

Hide Navigation

Quick Lookup

Database Library · Master Index · Master Glossary · Book List · Data Dictionary · SQL Keywords · Initialization Parameters · Advanced Search · Error Messages

Main Categories

This Page

This Document

New and changed documents:
RSS Feed HTML RSS Feed PDF