space_object:select()
-
object
space_object
¶ -
space_object:
select
([key[, options]])¶ Search for a tuple or a set of tuples in the given space by the primary key. To search by the specific index, use the index_object:select() method.
Note
Note that this method doesn’t yield. For details, see Cooperative multitasking.
Parameters: - space_object (
space_object
) – an object reference. - key (
scalar/table
) – a value to be matched against the index key, which may be multi-part. - options (
table/nil
) –none, any, or all of the same options that index_object:select() allows:
options.iterator
– the iterator type. The default iterator type is ‘EQ’.options.limit
– the maximum number of tuples.options.offset
– the number of tuples to skip.options.after
– a tuple or the position of a tuple (tuple_pos) after whichselect
starts the search. You can pass an empty string or box.NULL to this option to start the search from the first tuple.options.fetch_pos
– if true, theselect
method returns the position of the last selected tuple as the second value.Note
The
after
andfetch_pos
options are supported for theTREE
index only.
Return: This function might return one or two values:
- The tuples whose primary-key fields are equal to the fields of the passed key.
If the number of passed fields is less than the
number of fields in the primary key, then only the passed
fields are compared, so
select{1,2}
matches a tuple whose primary key is{1,2,3}
. - (Optionally) If
options.fetch_pos
is set to true, returns a base64-encoded string representing the position of the last selected tuple as the second value. If no tuples are fetched, returnsnil
.
Rtype: - array of tuples
- (Optionally) string
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.
Examples:
Below are few examples of using
select
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 a tuple by the specified primary key -- tarantool> bands:select(4) --- - - [4, 'The Beatles', 1960] ... -- Select maximum 3 tuples with the primary key value greater than 3 -- tarantool> bands:select({3}, {iterator='GT', limit = 3}) --- - - [4, 'The Beatles', 1960] - [5, 'Pink Floyd', 1965] - [6, 'The Rolling Stones', 1962] ... -- Select maximum 3 tuples after the specified tuple -- tarantool> bands:select({}, {after = {4, 'The Beatles', 1960}, limit = 3}) --- - - [5, 'Pink Floyd', 1965] - [6, 'The Rolling Stones', 1962] - [7, 'The Doors', 1965] ... -- Select first 3 tuples and fetch a last tuple's position -- tarantool> result, position = bands:select({}, {limit = 3, fetch_pos = true}) --- ... -- Then, pass this position as the 'after' parameter -- tarantool> bands:select({}, {limit = 3, after = position}) --- - - [4, 'The Beatles', 1960] - [5, 'Pink Floyd', 1965] - [6, 'The Rolling Stones', 1962] ...
Note
You can get a field from a tuple both by the field number and field name. See example: using field names instead of field numbers.
- space_object (
-