Module index | Tarantool
Reference C API reference Module index

Module index

type box_iterator_t

A space iterator

enum iterator_type

Controls how to iterate over tuples in an index. Different index types support different iterator types. For example, one can start iteration from a particular value (request key) and then retrieve all tuples where keys are greater or equal (= GE) to this key.

If iterator type is not supported by the selected index type, iterator constructor must fail with ER_UNSUPPORTED. To be selectable for primary key, an index must support at least ITER_EQ and ITER_GE types.

NULL value of request key corresponds to the first or last key in the index, depending on iteration direction. (first key for GE and GT types, and last key for LE and LT). Therefore, to iterate over all tuples in an index, one can use ITER_GE or ITER_LE iteration types with start key equal to NULL. For ITER_EQ, the key must not be NULL.

enumerator ::ITER_EQ

key == x ASC order

enumerator ::ITER_REQ

key == x DESC order

enumerator ::ITER_ALL

all tuples

enumerator ::ITER_LT

key < x

enumerator ::ITER_LE

key <= x

enumerator ::ITER_GE

key >= x

enumerator ::ITER_GT

key > x

enumerator ::ITER_BITS_ALL_SET

all bits from x are set in key

enumerator ::ITER_BITS_ANY_SET

at least one x’s bit is set

enumerator ::ITER_BITS_ALL_NOT_SET

all bits are not set

enumerator ::ITER_OVERLAPS

key overlaps x

enumerator ::ITER_NEIGHBOR

tuples in distance ascending order from specified point

box_iterator_t *box_index_iterator(uint32_t space_id, uint32_t index_id, int type, const char *key, const char *key_end)

Allocate and initialize iterator for space_id, index_id.

The returned iterator must be destroyed by box_iterator_free.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
  • type (int) – iterator_type
  • key (const char*) – encode key in MsgPack Array format ([part1, part2, …])
  • key_end (const char*) – the end of encoded key
Returns:

NULL on error (check box_error_last)

Returns:

iterator otherwise

See also box_iterator_next, box_iterator_free

int box_iterator_next(box_iterator_t *iterator, box_tuple_t **result)

Retrieve the next item from the iterator.

Parameters:
Returns:

-1 on error (check box_error_last)

Returns:

0 on success. The end of data is not an error.

void box_iterator_free(box_iterator_t *iterator)

Destroy and deallocate iterator.

Parameters:
int iterator_direction(enum iterator_type type)

Determine a direction of the given iterator type: -1 for REQ, LT, LE, and +1 for all others.

ssize_t box_index_len(uint32_t space_id, uint32_t index_id)

Return the number of element in the index.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
Returns:

-1 on error (check box_error_last)

Returns:

>= 0 otherwise

ssize_t box_index_bsize(uint32_t space_id, uint32_t index_id)

Return the number of bytes used in memory by the index.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
Returns:

-1 on error (check box_error_last)

Returns:

>= 0 otherwise

int box_index_random(uint32_t space_id, uint32_t index_id, uint32_t rnd, box_tuple_t **result)

Return a random tuple from the index (useful for statistical analysis).

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
  • rnd (uint32_t) – random seed
  • result (box_tuple_t**) – output argument. result a tuple or NULL if there is no tuples in space

See also: index_object:random()

int box_index_get(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, box_tuple_t **result)

Get a tuple from index by the key.

Please note that this function works much more faster than index_object:select() or box_index_iterator + box_iterator_next.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
  • key (const char*) – encode key in MsgPack Array format ([part1, part2, …])
  • key_end (const char*) – the end of encoded key
  • result (box_tuple_t**) – output argument. result a tuple or NULL if there is no tuples in space
Returns:

-1 on error (check box_error_last)

Returns:

0 on success

See also: index_object.get()

int box_index_min(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, box_tuple_t **result)

Return a first (minimal) tuple matched the provided key.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
  • key (const char*) – encode key in MsgPack Array format ([part1, part2, …])
  • key_end (const char*) – the end of encoded key
  • result (box_tuple_t**) – output argument. result a tuple or NULL if there is no tuples in space
Returns:

-1 on error (check box_error_last())

Returns:

0 on success

See also: index_object:min()

int box_index_max(uint32_t space_id, uint32_t index_id, const char *key, const char *key_end, box_tuple_t **result)

Return a last (maximal) tuple matched the provided key.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
  • key (const char*) – encode key in MsgPack Array format ([part1, part2, …])
  • key_end (const char*) – the end of encoded key
  • result (box_tuple_t**) – output argument. result a tuple or NULL if there is no tuples in space
Returns:

-1 on error (check box_error_last())

Returns:

0 on success

See also: index_object:max()

ssize_t box_index_count(uint32_t space_id, uint32_t index_id, int type, const char *key, const char *key_end)

Count the number of tuple matched the provided key.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
  • type (int) – iterator_type
  • key (const char*) – encode key in MsgPack Array format ([part1, part2, …])
  • key_end (const char*) – the end of encoded key
Returns:

-1 on error (check box_error_last())

Returns:

0 on success

See also: index_object.count()

const box_key_def_t *box_index_key_def(uint32_t space_id, uint32_t index_id)

Return key definition for an index

Returned object is valid until the next yield.

Parameters:
  • space_id (uint32_t) – space identifier
  • index_id (uint32_t) – index identifier
Returns:

key definition on success

Returns:

NULL on error

See also: box_tuple_compare(),
box_tuple_format_new()
Found what you were looking for?
Feedback