Product Documentation

c-treeDB API for C++ - Developers Guide

Previous Topic

Next Topic

Adding or deleting indexes

Indexes and index segments are key-based search tools that make record seeking faster and more efficient. An index is a mapping table that contains keys describing certain records and pointers to those records. An index segment describes the table field from which the keys are created.

Indexes are added to the table definition in the order they are declared. The c-treeDB API also includes a set of functions that will allow an index to be deleted from the table index definition.

CTTable::AddIndex() will add a new index at the end of the table index definition. For each index added to the table, one or more index segments should also be added to define which field combination form a particular index. CTTable::AddSegment() overloaded methods will accomplish the task of adding segments to an index.

// create a new table object

CTTable ATable(ADatabase);


// add two fields to the table record definition

ATable.AddField("Field1", CT_INTEGER, 4);

ATable.AddField("Field2", CT_CHAR, 30);


// add index 0 - the first index

ATable.AddIndex("MyIndex1", CTINDEX_FIXED, YES, NO);


// add index 0 segments

ATable.AddSegment("MyIndex1", "Field1", CTSEG_SCHSEG);


// add index 1 - the second index

ATable.AddIndex("MyIndex2", CTINDEX_FIXED, NO, NO);


// add index 1 segments

ATable.AddSegment("MyIndex2", "Field2", CTSEG_SCHSEG);

ATable.AddSegment("MyIndex2", "Field1", CTSEG_SCHSEG);


// create the table

try

{

ATable.Create("MyTable", CTCREATE_NORMAL);

}

catch (CTException &err)

{

printf("Create table failed with error %d\n", err.GetErrorCode());

}

The CTTable::AddIndex() method takes an index name, index type, and two Boolean flags indicating if the index accepts duplicate keys and if the index should process null keys. The valid index types are:

c-treeDB
Index Type

c-treeDB .NET
Index Type


Description

CTINDEX_FIXED

FIXED_INDEX

Fixed-length key

CTINDEX_LEADING

LEADING_INDEX

Fixed-length keys that are likely to have leading character duplication among the key values

CTINDEX_PADDING

PADDING_INDEX

Variable-length keys for which not much leading character duplication is expected.

CTINDEX_LEADPAD

LEADPAD_INDEX

Variable-length keys for which much leading character duplication is expected.

CTINDEX_ERROR

ERROR_INDEX

Index type error.

CTINDEX_DFRIDX

DFRIDX_INDEX.

Indicates a deferred index (V11 and later).

CTINDEX_NOMOD

NOMOD_INDEX

Indicates an index with unmodifiable ISAM and c-treeDB keys (V11 and later).

CTINDEX_BCKLOAD

BCKLOAD_INDEX

Perform initial key load in background.
(V11.7 and later)

CTINDEX_VARIABLE

VARIABLE_INDEX

Node-level compression with trailing spaces and metadata compression to fit more in each page block

CTINDEX_VARIABLE_RLE

VARIABLE_RLE_INDEX

Use sRLE key compression for shorter index entries / smaller index files

Note: c-treeDB .NET Index Key Types are defined in the KEY_TYPE enum.

Deferred Indexing (V11 and later)

The c-treeDB add, delete, and update operations perform key insert and deletes on every index associated with a data file:

  • a record add inserts a key value for each associated index.
  • a record delete deletes a key value for each associated index.
  • a record update deletes the old key and inserts the new key for each associated index (for those keys whose values changed).

However, each additional index operation can impose measurable performance loss, especially when numerous indexes are involved. If these immediate key operations could be held off for a period of time, applications can gain substantial performance in many circumstances. In V11 (and later), FairCom addressed these challenges with deferred maintenance modes. By delaying select index operations, applications can quickly create and/or update files with large numbers of indexes very quickly.

Background Loading (V11.7 and later)

ctdbCheckIndexBackgroundLoad() function can be used to monitor the status of the index loading on tables.

See Also:

NAV (c-treeDB) API Variable Length Keys with Compression

The add and insert segment functions require a segment mode to be passed as the last parameter. Please refer to "Segment Modes" describing the valid segment modes.

An index can be deleted from the table index definition by calling one of CTTable::DelIndex() overloaded methods.

// create a new table object

CTTable ATable(ADatabase);


// add two fields to the table record definition

ATable.AddField("Field1", CT_INTEGER, 4);

ATable.AddField("Field2", CT_CHAR, 30);


// add index 0 - the first index

ATable.AddIndex("MyIndex1", CTINDEX_FIXED, YES, NO);


// add index 0 segments

ATable.AddSegment("MyIndex1", "Field1", CTSEG_SCHSEG);


// add index 1 - the second index

ATable.AddIndex("MyIndex2", CTINDEX_FIXED, NO, NO);


// add index 1 segments

ATable.AddSegment("MyIndex2", "Field2", CTSEG_SCHSEG);

ATable.AddSegment("MyIndex2", "Field1", CTSEG_SCHSEG);


// delete index 0

ATable.DelIndex("MyIndex1");


// create the table

try

{

ATable.Create("MyTable", CTCREATE_NORMAL);

}

catch (CTException &err)

{

printf("Create table failed with error %d\n", err.GetErrorCode());

}

TOCIndex