NAME

MR::Tarantool::Box

A driver for an efficient Tarantool/Box NoSQL in-memory storage.

SYNOPSIS

    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',
        }, {
            #...
        } ],
        default_space => "primary",

        timeout   => 1,
        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"});

DESCRIPTION

new

    my $box = $class->new(\%args);

%args:

spaces => [ \%space, ... ]

%space:

space => $space_id_uint32

Space id as set in Tarantool/Box config.

name => $space_name_string

Self-descriptive space id, which will be mapped into space.

format => $format_string

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.

indexes => [ \%index, ... ]

%index:

id => $index_id_uint32

Index id as set in Tarantool/Box config within current space. If not set, order position in indexes is theated as id.

name => $index_name_string

Self-descriptive index id, which will be mapped into index_id.

keys => [ $field_no_uint32, ... ]

Properly ordered arrayref of fields' numbers which are indexed.

default_index => $default_index_name_string_or_id_uint32

Index id or name to be used by default for the current space. Must be set if there are more than one \%indexes.

default_space => $default_space_name_string_or_id_uint32

Space space or name to be used by default. Must be set if there are more than one \%spaces.

timeout => $timeout_fractional_seconds_float || 23

A common timeout for network operations.

select_timeout => $select_timeout_fractional_seconds_float || 2

Select queries timeout for network operations. See select_retry.

retry => $retry_int || 1

A common retries number for network operations.

select_retry => $select_retry_int || 3

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.

soft_retry => $soft_retry_int || 3

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.

This is also limited by retry/select_retry (depending on query type).

raise => $raise_bool || 1

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 => $debug_level_int || 0

Debug level, 0 - print nothing, 9 - print everything

name => $name

A string used for self-description. Mainly used for debugging purposes.

Error

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"

ErrorStr

Last error code and description in a single string.

    $box->Insert(@tuple) or die $box->ErrorStr;                  # die "Error 00000202: Illegal Parameters"

Call

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";

@procedure_params

An array of bytestrings to be passed as is to the procecedure.

%options

unpack_format

Format to unpack the result tuple, the same as format option for new()

Add, Set, Replace

    $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.

All of them have the same parameters:

@tuple

A tuple to insert. All fields must be defined. All fields will be pack()ed according to format (see new)

%options

space => $space_id_uint32_or_name_string

Specify storage space to work on.

The difference between them is the behaviour concerning tuple with the same primary key:

• Add will fail if a duplicate-key tuple exists

• Replace will fail if a duplicate-key tuple does not exists

• Set will overwrite a duplicate-key tuple

Select

Select tuple(s) from storage

    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;

$key, @keys, \@keys

Specify keys to select. All keys must be defined.

• 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

• 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

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

%options

space => $space_id_uint32_or_name_string

Specify storage (by id or name) space to select from.

use_index => $index_id_uint32_or_name_string

Specify index (by id or name) to use.

hashify => $coderef

Override hashify option (see new).

raw => $bool

Don't hashify.

hash_by => $by

Return a hashref of the resultset. If you hashify the result set, then $by must be a field name of the hash you return, else it must be a number of field of the tuple. False will be returned in case of error.

Delete

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;

%options

space => $space_id_uint32_or_name_string

Specify storage space (by id or name) to work on.

want_deleted_tuples => $bool

if $bool then return arrayref of deleted tuple(s).

Update

Update tuple in storage. Return false upon error.

    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;

@op = ([ $field_num => $op => $value ], ...)

$field_num

Field-to-update number.

$op

set

Set $field_num field to $value

add, and, xor, or

Apply an arithmetic operation to $field_num with argument $value Currently arithmetic operations are supported only for int32 (4-byte length) fields (and $values too)

splice, substr

Apply a perl-like splice operation to $field_num. $value = [$OFFSET, $LENGTH, $REPLACE_WITH]. substr is just an alias.

append, prepend

Append or prepend $field_num with $value string.

cutbeg, cutend

Cut $value bytes from beginning or end of $field_num.

%options

space => $space_id_uint32_or_name_string

Specify storage space (by id or name) to work on.

want_result => $bool

if $bool then return arrayref of deleted tuple(s).

cpanm MR::IProto

perl -MCPAN -e shell
install MR::IProto