Index

Data Structures
struct	db_indexfield_t
	Index field definition. More...
struct	db_indexdef_t
	Index definition. More...
Functions
db_result_t	db_indexfield_init (db_indexfield_t *)
db_result_t	db_indexfield_destroy (db_indexfield_t *)
db_result_t	db_indexdef_init (db_indexdef_t *, db_heap_t heap)
db_result_t	db_indexdef_destroy (db_indexdef_t *)
db_result_t	db_indexdef_set_indextype (db_indexdef_t *, db_indextype_t)
db_result_t	db_indexdef_set_field_count (db_indexdef_t *, db_fieldno_t)
db_result_t	db_indexdef_set_field (db_indexdef_t *, db_fieldno_t nfield, const db_indexfield_t *field)
db_result_t	db_tabledef_set_index_count (db_tabledef_t *, db_len_t nindexes)
db_result_t	db_tabledef_set_indexes (db_tabledef_t *, const db_indexdef_t *, db_len_t nindexes)
db_result_t	db_tabledef_set_index (db_tabledef_t *, db_len_t index, const db_indexdef_t *)
db_result_t	db_create_index (db_t, const db_objname_t *table, const db_objname_t *index, const db_indexdef_t *)
db_result_t	db_drop_index (db_t, const db_objname_t *table, const db_objname_t *index)
db_result_t	db_describe_index (db_t, const db_objname_t *table, const db_objname_t *index, db_indexdef_t *)
Index Mode
#define	DB_MULTISET_INDEX   _DB_MULTISET_INDEX
#define	DB_UNIQUE_INDEX   _DB_UNIQUE_INDEX
#define	DB_PRIMARY_INDEX   _DB_PRIMARY_INDEX
#define	DB_NUMBERED_INDEX   _DB_NUMBERED_INDEX
#define	DB_CLUSTERING_INDEX   _DB_CLUSTERING_INDEX
#define	DB_INDEX_MASK   _DB_INDEX_MASK
#define	DB_INDEX_MODE_MASK   _DB_INDEX_MODE_MASK
Index Types
#define	DB_INDEXTYPE_DEFAULT   _DB_INDEXTYPE_DEFAULT
#define	DB_INDEXTYPE_BTREE   _DB_INDEXTYPE_BTREE

---

Detailed Description

An index is used to optimize seek, sort, and filter operations.

---

Define Documentation

#define DB_MULTISET_INDEX   _DB_MULTISET_INDEX

Multiset (non-unique) index.

Examples:

phonebook_c_schema.c.

#define DB_INDEXTYPE_DEFAULT   _DB_INDEXTYPE_DEFAULT

Default index type.

Examples:

phonebook_c_schema.c.

#define DB_UNIQUE_INDEX   _DB_UNIQUE_INDEX

Unique index.

#define DB_PRIMARY_INDEX   _DB_PRIMARY_INDEX

Primary key index.

Examples:

phonebook_c_schema.c.

#define DB_NUMBERED_INDEX   _DB_NUMBERED_INDEX

Numbered index.

See also:

db_get_row_num.

#define DB_CLUSTERING_INDEX   _DB_CLUSTERING_INDEX

The index used to cluster a table.

See also:

DB_TABLETYPE_CLUSTERED.

---

Function Documentation

db_result_t db_indexfield_init

(

db_indexfield_t *

idef

)

Initialize index field definition.

Parameters:

idef	Index field definition.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Index field defintion is null.

See also:

db_indexfield_destroy,
get_db_error, clear_db_error, Error Handling

db_result_t db_indexfield_destroy

(

db_indexfield_t *

idef

)

Destroy index field definition.

Parameters:

idef	Index field definition.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Index feild definition is null.

See also:

db_indexfield_init,
get_db_error, clear_db_error, Error Handling

db_result_t db_indexdef_init	(	db_indexdef_t *	idef,
		db_heap_t	heap
	)

Initialize an index schema definition.

Parameters:

idef	Index configuration.
heap	Pointer to heap.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Index configuration is null.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_indexdef_destroy

(

db_indexdef_t *

idef

)

Destroy an index schema definition.

Parameters:

idef	Index configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Required parameter is null.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_indexdef_set_indextype	(	db_indexdef_t *	idef,
		db_indextype_t	itype
	)

Set the index type for an index definition.

Parameters:

idef	Index configuration.
itype	Index type.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

• DB_EINVAL Caused by: index configuration is null, index defintion is null.
  • DB_ERANGE Caused by: field number < 0, field number > index defition fields.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_indexdef_set_field_count	(	db_indexdef_t *	idef,
		db_fieldno_t	nfields
	)

Set the number of fields in an index definition.

Parameters:

idef	Index configuration.
nfields	Number of fields.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

• DB_EINVAL Caused by: index definition pointer is null, number of fields< 0.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_indexdef_set_field	(	db_indexdef_t *	idef,
		db_fieldno_t	nfield,
		const db_indexfield_t *	ifield
	)

Set a field in an index definition.

Parameters:

idef	Index configuration.
nfield	Field number.
ifield	Index definition field.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

• DB_EINVAL Caused by: index configuration is null, index defintion is null.
  • DB_ERANGE Caused by: field number < 0, field number > index defition fields.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_index_count	(	db_tabledef_t *	tdef,
		db_len_t	nindexes
	)

Set the number of indexes in a table definition.

Parameters:

tdef	Table configuration.
nindexes	Number of indexes.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: Table configuration is null, number of indexes is <0.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_indexes	(	db_tabledef_t *	tdef,
		const db_indexdef_t *	indexes,
		db_len_t	nindexes
	)

Set all of the indexes for a table definition.

Parameters:

tdef	Table configuration.
indexes	Index configuration(s).
nindexes	Number of indexes.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: Table configuration is null, number of indexes is <0.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_tabledef_set_index	(	db_tabledef_t *	tdef,
		db_len_t	nindex,
		const db_indexdef_t *	idef
	)

Set an index in a table definition.

Parameters:

tdef	Table configuration.
nindex	Number of index to set.
idef	Index configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: Table configuration is null, index configuration is null.
• DB_ERANGE Caused by: number of index is <0, number of indexe >= table configuration's number of indexes.

See also:

get_db_error, clear_db_error, Error Handling

db_result_t db_create_index	(	db_t	hdb,
		const db_objname_t *	table,
		const db_objname_t *	index,
		const db_indexdef_t *	param
	)

Create an index on a table using an index schema definition.

Parameters:

hdb	Database handle.
table	Table name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.
index	Index name. A name must start with a letter and can be followed by one or more letters, numbers, or underscores.
param	Index configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, table is null, index name is null, index configuration is null .
• DB_ENAME Invalid name.
• DB_EFIELD Caused by: number of fields in index definition <=0, index field can not be of blob type.
• DB_EINDEX Index error. Can not have duplicate indexes.
• DB_ELOCKED Table is locked by cursor or concurrent transaction.
• DB_ETXSTATE A transaction is active.

Invariant:

No transaction is active on hdb.

A table can only be altered or dropped when there is no active transaction. If a transaction has been started, db_commit_tx or db_abort_tx must be used before db_drop_table can be called.

If index->index_mode is DB_PRIMARY_INDEX, all index fields must have been created with the flag DB_NOT_NULL. Only one index can be created with the DB_PRIMARY_INDEX flag.

See also:

db_drop_index, db_describe_index,
get_db_error, clear_db_error, Error Handling

db_result_t db_drop_index	(	db_t	hdb,
		const db_objname_t *	table,
		const db_objname_t *	index
	)

Removes an index from a table.

Parameters:

hdb	Database handle.
table	Table name.
index	Index name.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, field binding is null, invalid table information.
• DB_EINDEX General index error. Unable to find the index with the specified name.
• DB_ELOCKED Table is locked by cursor or concurrent transaction.
• DB_ETXSTATE A transaction is active.

Invariant:

No transaction is active on hdb.

A table can only be altered or dropped when there is no active transaction. If a transaction has been started, db_commit_tx or db_abort_tx must be used before db_drop_table can be called.

See also:

db_create_index, db_describe_index,
get_db_error, clear_db_error, Error Handling

db_result_t db_describe_index	(	db_t	hdb,
		const db_objname_t *	table,
		const db_objname_t *	index,
		db_indexdef_t *	params
	)

Retrieves the schema definition for an index on a table.

Parameters:

hdb	Database handle.
table	Table name.
index	Index name.
params	Returned index configuration.

Returns:

• DB_OK when successful.
• DB_FAIL on failure.

On failure, one of the following error codes is set:

• DB_EINVAL Caused by: invalid database handle, table name is null, index name is null or index configuration is null.
• DB_ENOTFOUND Not found. Unable to find index with specified name.

See also:

db_create_index, db_drop_index,
get_db_error, clear_db_error, Error Handling