Module index

A space iterator

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.

key == x ASC order

key == x DESC order

all tuples

key < x

key <= x

key >= x

key > x

all bits from x are set in key

at least one x's bit is set

all bits are not set

key overlaps x

tuples in distance ascending order from specified point

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

Retrieve the next item from the iterator.

• iterator (box_iterator_t*) — an iterator returned by box_index_iterator

• result (box_tuple_t**) — output argument. result a tuple or NULL if there is no more data.

Returns

-1 on error (check box_error_last)

Returns

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

Destroy and deallocate iterator.

• iterator (box_iterator_t*) — an iterator returned by box_index_iterator

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

Return the number of element in the index.

• space_id (uint32_t) — space identifier

• index_id (uint32_t) — index identifier

Returns

-1 on error (check box_error_last)

Returns

= 0 otherwise

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

• space_id (uint32_t) — space identifier

• index_id (uint32_t) — index identifier

Returns

-1 on error (check box_error_last)

Returns

= 0 otherwise

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

• 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()

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.

• 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()

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

• 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()

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

• 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()

Count the number of tuple matched the provided key.

• 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 otherwise

See also: index_object.count()

Return key definition for an index

Returned object is valid until the next yield.

• 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()