MR::Tarantool::Box
A driver for an efficient Tarantool/Box NoSQL in-memory storage.
my $box = MR::Tarantool::Box->new({ servers => "127.0.0.1:33013", name => "My Box", # primarily used for debug purposes spaces => [ { indexes => [ { index_name => 'idx1', keys => [0], }, { index_name => 'idx2', keys => [1], }, ], space => 1, # space id, as set in Tarantool/Box config name => "primary", # self-descriptive space-id format => "QqLlSsCc&", # pack()-compatible, Qq must be supported by perl itself, & stands for byte-string. default_index => 'idx1', hashify => [qw/ id f2 field3 f4 f5 f6 f7 f8 misc_string /], # turn each tuple into hash, field names according to format }, { #... } ], default_space => "primary", timeout => 1.0, # seconds retry => 3, debug => 9, # output to STDERR some debugging info raise => 0, # dont raise an exception in case of error }); $box->Insert(1,2,3,4,5,6,7,8,"asdf") or die $box->ErrorStr; $box->Insert(1,2,3,4,5,6,7,8,"asdf",{space => "primary"}) or die $box->ErrorStr; my $tuples = $box->Select(1); my $tuples = $box->Select(1,{space => "primary", use_index => "idx1"});
my $box = $class->new(\%args);
%args:
%space:
Space id as set in Tarantool/Box config.
Self-descriptive space id, which will be mapped into space.
space
pack()-compatible tuple format string, allowed formats: QqLlSsCc&, where & stands for bytestring. Qq usable only if perl supports int64 itself. Tuples' fields are packed/unpacked according to this format.
pack()
QqLlSsCc&
&
Qq
format
Specify a callback to turn each tuple into a good-looking hash. It receives space id and resultset as arguments. No return value needed.
$coderef = sub { my ($space_id, $resultset) = @_; $_ = { FieldName1 => $_->[0], FieldName2 => $_->[1], ... } for @$resultset; };
Specify an arrayref of fields names according to format to turn each tuple into a good-looking hash. Names must begin with [A-Za-z].
[A-Za-z]
%index:
Index id as set in Tarantool/Box config within current space. If not set, order position in indexes is theated as id.
indexes
id
Self-descriptive index id, which will be mapped into index_id.
index_id
Properly ordered arrayref of fields' numbers which are indexed.
Index id or name to be used by default for the current space. Must be set if there are more than one \%indexes.
name
\%index
Space space or name to be used by default. Must be set if there are more than one \%spaces.
\%space
A common timeout for network operations.
Select queries timeout for network operations. See "select_retry".
A common retries number for network operations.
Select queries retries number for network operations.
Sometimes we need short timeout for select's and long timeout for critical update's, because in case of timeout we don't know if the update has succeeded. For the same reason we can't retry update operation.
So increasing timeout and setting retry => 1 for updates lowers possibility of such situations (but, of course, does not exclude them at all), and guarantees that we dont do the same more then once.
timeout
retry => 1
A common retries number for Tarantool/Box temporary errors (these marked by 1 in the lowest byte of error_code). In that case we know for sure that the request was declined by Tarantool/Box for some reason (a tuple was locked for another update, for example), and we can try it again.
error_code
This is also limited by retry/select_retry (depending on query type).
retry
select_retry
Specify a delay between retries for network operations.
Should we raise an exceptions? If so, exceptions are raised when no more retries left and all tries failed (with timeout, fatal, or temporary error).
Debug level, 0 - print nothing, 9 - print everything
A string used for self-description. Mainly used for debugging purposes.
Last error code, or 'fail' for some network reason, oftenly a timeout.
$box->Insert(@tuple) or die sprintf "Error %X", $box->Error; # die "Error 202"
Last error code and description in a single string.
$box->Insert(@tuple) or die $box->ErrorStr; # die "Error 00000202: Illegal Parameters"
Call a stored procedure. Returns an arrayref of the result tuple(s) upon success.
my $results = $box->Call('stored_procedure_name', \@procedure_params, \%options) or die $box->ErrorStr; # Call failed my $result_tuple = @$results && $results->[0] or warn "Call succeeded, but returned nothing";
An array of bytestrings to be passed as is to the procecedure.
Format to unpack the result tuple, the same as format option for new()
new()
$box->Add(@tuple) or die $box->ErrorStr; $box->Set(@tuple, { space => "main" }); $box->Replace(@tuple, { space => "secondary" });
Insert a @tuple into the storage into $options{space} or default_space space. All of them return true upon success.
@tuple
$options{space}
default_space
true
All of them have the same parameters:
A tuple to insert. All fields must be defined. All fields will be pack()ed according to format (see "new")
Specify storage space to work on.
The difference between them is the behaviour concerning tuple with the same primary key:
Add will succeed if and only if duplicate-key tuple does not exist
Replace will succeed if and only if a duplicate-key tuple exists
Set will suddeed anyway. Duplicate-key tuple will be overwritten
Select tuple(s) from storage
my $key = $id; my $key = [ $firstname, $lastname ]; my @keys = ($key, ...); my $tuple = $box->Select($key) or $box->Error && die $box->ErrorStr; my $tuple = $box->Select($key, \%options) or $box->Error && die $box->ErrorStr; my @tuples = $box->Select(@keys) or $box->Error && die $box->ErrorStr; my @tuples = $box->Select(@keys, \%options) or $box->Error && die $box->ErrorStr; my $tuples = $box->Select(\@keys) or die $box->ErrorStr; my $tuples = $box->Select(\@keys, \%options) or die $box->ErrorStr;
Specify keys to select. All keys must be defined.
Contextual behaviour:
In scalar context, you can select one $key, and the resulting tuple will be returned. Check $box->Error to see if there was an error or there is just no such key in the storage
$key
$box->Error
In list context, you can select several @keys, and the resulting tuples will be returned. Check $box->Error to see if there was an error or there is just no such keys in the storage
@keys
If you select \@keys then \@tuples will be returned upon success. @tuples will be empty if there are no such keys, and false will be returned in case of error.
\@keys
\@tuples
@tuples
Other notes:
If you select using index on multiple fields each $key should be given as a key-tuple $key = [ $key_field1, $key_field2, ... ].
$key = [ $key_field1, $key_field2, ... ]
Specify storage (by id or name) space to select from.
Specify index (by id or name) to use.
Don't hashify (see "new").
hashify
Return a hashref of the resultset. If you hashify the result set, then $by must be a field name of the hash you return, otherwise it must be a number of field of the tuple. False will be returned in case of error.
$by
False
Delete tuple from storage. Return false upon error.
my $n_deleted = $box->Delete($key) or die $box->ErrorStr; my $n_deleted = $box->Delete($key, \%options) or die $box->ErrorStr; warn "Nothing was deleted" unless int $n_deleted; my $deleted_tuple_set = $box->Delete($key, { want_deleted_tuples => 1 }) or die $box->ErrorStr; warn "Nothing was deleted" unless @$deleted_tuple_set;
Specify storage space (by id or name) to work on.
if $bool then return deleted tuple.
$bool
Apply several update operations to a tuple.
my @op = ([ f1 => add => 10 ], [ f1 => and => 0xFF], [ f2 => set => time() ], [ misc_string => cutend => 3 ]); my $n_updated = $box->UpdateMulti($key, @op) or die $box->ErrorStr; my $n_updated = $box->UpdateMulti($key, @op, \%options) or die $box->ErrorStr; warn "Nothing was updated" unless int $n_deleted; my $updated_tuple_set = $box->UpdateMulti($key, @op, { want_result => 1 }) or die $box->ErrorStr; warn "Nothing was updated" unless @$updated_tuple_set;
Different fields can be updated at one shot. The same field can be updated more than once. All update operations are done atomically. Returns false upon error.
Field-to-update number or name (see "fields").
Set $field to $value
$field
$value
Apply an arithmetic operation to $field with argument $value Currently arithmetic operations are supported only for int32 (4-byte length) fields (and $values too)
Apply a perl-like "splice" in perlfunc operation to $field. $value = [$OFFSET, $LENGTH, $REPLACE_WITH]. substr is just an alias.
Append or prepend $field with $value string.
Cut $value bytes from beginning or end of $field.
if $bool then return updated tuple.
http://tarantool.org
MR::Tarantool::Box::Singleton
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install MR::IProto, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MR::IProto
CPAN shell
perl -MCPAN -e shell install MR::IProto
For more information on module installation, please visit the detailed CPAN module installation guide.