space_object:pairs()

space_object

Search for a tuple or a set of tuples in the given space, and allow iterating over one tuple at a time. To search by the specific index, use the box_index-pairs method.

Parameters:

• space_object (space_object) — an object reference

• key (scalar/table) — value to be matched against the index key, which may be multi-part

• iterator — the iterator type. The default iterator type is 'EQ'

• after — a tuple or the position of a tuple (tuple_pos) after which pairs starts the search. You can pass an empty string or box.NULL to this option to start the search from the first tuple.

Returns

The iterator, which can be used in a for/end loop or with totable().

Possible errors:

• no such space
• wrong type
• ER_TRANSACTION_CONFLICT if a transaction conflict is detected in the MVCC transaction mode
• iterator position is invalid

Complexity factors: Index size, Index type.

For information about iterators' internal structures, see the "Lua Functional library" documentation.

Examples:

Below are few examples of using pairs with different parameters. To try out these examples, you need to bootstrap a Tarantool instance as described in Using data operations.

 
-- Insert test data --tarantool> bands:insert{1, 'Roxette', 1986}           bands:insert{2, 'Scorpions', 1965}           bands:insert{3, 'Ace of Base', 1987}           bands:insert{4, 'The Beatles', 1960}           bands:insert{5, 'Pink Floyd', 1965}           bands:insert{6, 'The Rolling Stones', 1962}           bands:insert{7, 'The Doors', 1965}           bands:insert{8, 'Nirvana', 1987}           bands:insert{9, 'Led Zeppelin', 1968}           bands:insert{10, 'Queen', 1970}---...-- Select all tuples by the primary index --tarantool> for _, tuple in bands:pairs() do               print(tuple)           end[1, 'Roxette', 1986][2, 'Scorpions', 1965][3, 'Ace of Base', 1987][4, 'The Beatles', 1960][5, 'Pink Floyd', 1965][6, 'The Rolling Stones', 1962][7, 'The Doors', 1965][8, 'Nirvana', 1987][9, 'Led Zeppelin', 1968][10, 'Queen', 1970]---...-- Select all tuples whose primary key values are between 3 and 6 --tarantool> for _, tuple in bands:pairs(3, {iterator = "GE"}) do             if (tuple[1] > 6) then break end             print(tuple)           end[3, 'Ace of Base', 1987][4, 'The Beatles', 1960][5, 'Pink Floyd', 1965][6, 'The Rolling Stones', 1962]---...-- Select all tuples after the specified tuple --tarantool> for _, tuple in bands:pairs({}, {after={7, 'The Doors', 1965}}) do               print(tuple)           end[8, 'Nirvana', 1987][9, 'Led Zeppelin', 1968][10, 'Queen', 1970]---...