FairCom DB API for C

ctdbAddIndex

Add a new index to a table.

Declaration

CTHANDLE ctdbAddIndex(CTHANDLE Handle, cpTEXT name, CTDBKEY key_type,

CTBOOL AllowDuplicates, CTBOOL NullFlag)

Description

ctdbAddIndex() adds a new index to a table. An index makes record seeking faster and more efficient, and provides a convenient way to sort a table. Since an index file resides in the same folder as its table, it is not necessary to specify a path when adding an index to a table. After adding an index to a table with this function, add one or more segments to the index, using the ctdbAddSegment___() functions.

Use ctdbDelIndex() to delete indexes from a table.

Use ctdbGetIndexKeyType() to retrieve the key type of an index. ctdbAddIndex() does the allocation of the index handle. Index handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll(). After the segments, indexes, and fields have been defined, the table can be created or altered by calling ctdbCreateTable() or ctdbAlterTable().

Handle [in] the table handle.
name [in] the name of the new index.
key_type [in] the index key type. Allowed index key types are listed in Index Key Types.
AllowDuplicates [in] the indication if the index allows duplicate keys (YES or NO are the valid values).
NullFlag [in] the indication if the index allows null keys (YES or NO are the valid values).

Background Load on Index Creation

Background key loading can improve performance when adding new indexes. A new background loading mode can be OR-d in with an existing key mode from a ctdbAddIndex (ctdbAddIndex, ctdbAddIndex)() call indicating initial index loading must be done in the background.

Once ctdbAddIndex() is called, ctdbAlterTable() initiates the changes to the file and begins the load once the new index is successfully created.

Check the status of index loading with the new ctdbCheckIndexBackgroundLoad() (ctdbCheckIndexBackgroundLoad, ctdbCheckIndexBackgroundLoad) API, useful for monitoring index loading on tables.

Example

This example demonstrates using a background index load option.

ctdbAddIndex(hTable, "test541_i1", CTINDEX_FIXED| CTINDEX_BCKLOAD, YES, NO)

ctdbAlterTable() will fail if a CTINDEX_BCKLOAD is added and it does not have a filename associated (i.e. ctdbSetIndexFilename() has not been called on the index) or ctdbAlterTable() needs to perform any operation other than adding new CTINDEX_BCKLOAD indexes. If the preconditions are met, ctdbAlterTable() is executed without opening the file in exclusive mode and the background load is immediately started.

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

Example

pMyField0 = ctdbAddField(pMyTable, "Name" , CT_FSTRING,32);

pMyField1 = ctdbAddField(pMyTable, "Balance", CT_SFLOAT, 4);

pMyIndex = ctdbAddIndex(pMyTable, "iName", CTINDEX_FIXED,NO,NO);

pMyIseg = ctdbAddSegment(pMyIndex, pMyField0, 2);

RetVal = ctdbCreateTable(pMyTable,"Table1",CTCREATE_NORMAL);

Returns

ctdbAddIndex() returns the index handle on success, or NULL on failure.