Tarantool User Guide, version 1.5.1-219-g1d00e15

box.process(op, request)

Process a request passed in as a binary string. This is an entry point into the server request processor. It can be used to insert, update, select and delete tuples from within a Lua procedure.

This is a low-level API, and it expects all arguments to be packed in accordance with the binary protocol (iproto header excluded). Normally, there is no need to use box.process() directly: box.select(), box.update() and other convenience wrappers invoke box.process() with correctly packed arguments.

Parameters

op — number, any Tarantool command code, except 22 (CALL). See doc/box-protocol.txt.

request — command arguments packed in binary format.

Returns

This function returns zero or more tuples. In Lua, a tuple is represented by a userdata object of type box.tuple. If a Lua procedure is called from the administrative console, returned tuples are printed out in YAML format. When called from the binary protocol, the binary format is used.

Errors

Any server error produced by the executed command.

Please note that, since all requests from Lua enter the core through box.process(), all checks and triggers run by the core automatically apply. For example, if the server is in read-only mode, an update or delete fails. Analogously, if a system-wide "instead of" trigger is defined, it is run.

box.select(space_no, index_no, ...)

Search for a tuple or tuples in the given space. A wrapper around box.process().

Parameters

space_no — space id,

index_no — index number in the space, to be used for match

...— index key, possibly multipart.

Returns

Returns zero or more tuples.

Errors

Same as in box.process(). Any error results in a Lua exception.

Example

localhost> call box.insert(0, 'test', 'my first tuple')
Call OK, 1 rows affected
['test', 'my first tuple']
localhost> call box.select(0, 0, 'test')
Call OK, 1 rows affected
['test', 'my first tuple']
localhost> lua box.insert(5, 'testtest', 'firstname', 'lastname')
---
 - 'testtest': {'firstname', 'lastname'}
...
localhost> lua box.select(5, 1, 'firstname', 'lastname')
---
 - 'testtest': {'firstname', 'lastname'}
...

box.insert(space_no, ...)

box.select_limit(space_no, index_no, offset, limit, ...)

Search for tuples in the given space. This is a full version of the built-in SELECT command, in which one can specify offset and limit for a multi-tuple return. The server may return multiple tuples when the index is non-unique or a partial key is used for search.

box.replace(space_no, ...)

Insert a tuple into a space. Tuple fields follow space_no. If a tuple with the same primary key already exists, box.insert() returns an error, while box.replace() replaces the existing tuple with a new one. These functions are wrappers around box.process()

Returns

Returns the inserted tuple.

box.update(space_no, key, format, ...)

Update a tuple identified by a primary key. If a key is multipart, it is passed in as a Lua table. Update arguments follow, described by format. The format and arguments are passed to box.pack() and the result is sent to box.process(). A correct format is a sequence of pairs: update operation, operation arguments. A single character of format describes either an operation which needs to take place or operation argument. A format specifier also works as a placeholder for the number of a field, which needs to be updated, or for an argument value. For example:

+p=p — add a value to one field and assign another,

:p — splice a field: start at offset, cut length bytes, and add a string.

#p — delete a field.

!p — insert a field (before the one specified).

Possible format specifiers are: “+” for addition, “-” for subtraction, “&” for bitwise AND, “|” for bitwise OR, “^” for bitwise exclusive OR (XOR), “:” for string splice and “p” for operation argument.

Returns

Returns the updated tuple.

Example

#Assume that the initial state of the database is ...
#  space[0] has one tuple set and one primary key whose type is 32-bit integer.
#  There is one row, with field[0] = 999 and field[1] = 'A'.

#In the following update ...
#  The first argument is 0, that is, the affected space is space[0]
#  The second argument is 999, that is, the affected tuple is identified by primary key value = 999
#  The third argument is '=p', that is, there is one operation, assignment to a field
#  The fourth argument is 1, that is, the affected field is field[1]
#  The fifth argument is 'B', that is, field[1] contents change to 'B'
#  Therefore, after the following update, field[0] = 999 and field[1] = 'B'.
lua box.update(0, 999, '=p', 1, 'B')

#In the following update, the arguments are the same, except that ...
#  the key is passed as a Lua table (inside braces). This is unnecessary
#  when the primary key has only one field, but would be necessary if the
#  primary key had more than one field.
#  Therefore, after the following update, field[0] = 999 and field[1] = 'B' (no change).
lua box.update(0, {999}, '=p', 1, 'B')

#In the following update, the arguments are the same, except that ...
#   The fourth argument is 2, that is the affected field is field[2].
#   It is okay that, until now, field[2] has not existed. It gets added.
#   Therefore, after the following update, field[0] = 999, field[1] = 'B', field[2] = 1.
lua box.update(0, 999, '=p', 2, 1)

#In the following update, the arguments are the same, except that ...
#   The third argument is '+p', that is, the operation is addition rather than assignment.
#   Since field[2] previously contained 10, this means we're adding 1 to 1.
#   Therefore, after the following update, field[0] = 999, field[1] = 'B', field[2] = 2.
lua box.update(0, 999, '+p', 2, 1)

#In the following update ...
#   The idea is to modify two fields at once.
#   The third argument is '|p=p', that is, there are two operations, OR and assignment.
#   The fourth and fifth arguments mean that field[2] gets ORed with 1.
#   The fifth and sixth arguments mean that field[1] gets assigned 'C'.
#   Therefore, after the following update, field[0] = 999, field[1] = 'C', field[2] = 3.
lua box.update(0, 999, '|p=p', 2, 1, 1, 'C')

#In the following update ...
#   The idea is to delete field[1], then subtract 3 from field[2], but ...
#   after the delete, there is a renumbering -- so field[2] becomes field[1]
#   before we subtract 3 from it, and that's why the sixth argument is 1 not 2.
#   Therefore, after the following update, field[0] = 999, field[1] = 0.
lua box.update(0, 999, '#p-p', 1, 0, 1, 3)

#In the following update ...
#   We're making a long string so that the splice will work in the next example.
#   Therefore, after the following update, field[0[ = 999, field[1] = 'XYZ'.
lua box.update(0, 999, '=p', 1, 'XYZ')

#In the following update ...
#   The third argument is ':p', that is, this is the example of splice.
#   The fifth argument is actually four arguments packed together ...
#      a filler, an offset, the number of bytes to cut (1), and the string to add ('!')
#   Therefore, after the following update, field[0[ = 999, field[1] = 'X!Z'.
lua box.update(0, 999, ':p', 1, box.pack('ppp', 1, 1, '!'))

box.delete(space_no, ...)

Delete a tuple identified by a primary key.

Returns

Returns the deleted tuple.

Example

localhost> call box.delete(0, 'test')
Call OK, 1 rows affected
['test', 'my first tuple']
localhost> call box.delete(0, 'test')
Call OK, 0 rows affected
localhost> call box.delete(0, 'tes')
Call ERROR, Illegal parameters, key is not u32 (ER_ILLEGAL_PARAMS)

box.select_range(space_no, index_no, limit, key, ...)

Select a range of tuples, starting from the offset specified by key. The key can be multipart. Limit selection with at most limit tuples. If no key is specified, start from the first key in the index.

For TREE indexes, this returns tuples in sorted order. For HASH indexes, the order of tuples is unspecified, and can change significantly if data is inserted or deleted between two calls to box.select_range(). If key is nil or unspecified, the selection starts from the start of the index. This is a simple wrapper around box.space[space_no]:select_range(index_no, ...). BITSET index does not support this call.

Example

localhost> show configuration
---
...
  space[4].cardinality: "-1"
  space[4].estimated_rows: "0"
  space[4].index[0].type: "HASH"
  space[4].index[0].unique: "true"
  space[4].index[0].key_field[0].fieldno: "0"
  space[4].index[0].key_field[0].type: "STR"
  space[4].index[1].type: "TREE"
  space[4].index[1].unique: "false"
  space[4].index[1].key_field[0].fieldno: "1"
  space[4].index[1].key_field[0].type: "STR"
...
localhost> insert into t4 values ('0', '0')
Insert OK, 1 rows affected
localhost> insert into t4 values ('1', '1')
Insert OK, 1 rows affected
localhost> insert into t4 values ('2', '2')
Insert OK, 1 rows affected
localhost> insert into t4 values ('3', '3')
Insert OK, 1 rows affected
ocalhost> lua box.select_range(4, 0, 10)
---
 - '3': {'3'}
 - '0': {'0'}
 - '1': {'1'}
 - '2': {'2'}
...
localhost> lua box.select_range(4, 1, 10)
---
 - '0': {'0'}
 - '1': {'1'}
 - '2': {'2'}
 - '3': {'3'}
...
localhost> lua box.select_range(4, 1, 2)
---
 - '0': {'0'}
 - '1': {'1'}
...
localhost> lua box.select_range(4, 1, 2, '1')
---
 - '1': {'1'}
 - '2': {'2'}
...

box.select_reverse_range(space_no, index_no, limit, key, ...)

Select a reverse range of tuples, starting from the offset specified by key. The key can be multipart. Limit selection with at most limit tuples. If no key is specified, start from the last key in the index.

For TREE indexes, this returns tuples in sorted order. For other index types this call is not supported. If key is nil or unspecified, the selection starts from the end of the index.

Example

localhost> show configuration
---
...
  space[4].cardinality: "-1"
  space[4].estimated_rows: "0"
  space[4].index[0].type: "HASH"
  space[4].index[0].unique: "true"
  space[4].index[0].key_field[0].fieldno: "0"
  space[4].index[0].key_field[0].type: "STR"
  space[4].index[1].type: "TREE"
  space[4].index[1].unique: "false"
  space[4].index[1].key_field[0].fieldno: "1"
  space[4].index[1].key_field[0].type: "STR"
...
localhost> insert into t4 values ('0', '0')
Insert OK, 1 rows affected
localhost> insert into t4 values ('1', '1')
Insert OK, 1 rows affected
localhost> insert into t4 values ('2', '2')
Insert OK, 1 rows affected
localhost> insert into t4 values ('3', '3')
Insert OK, 1 rows affected
localhost> lua box.select_reverse_range(4, 0, 10)
---
 error: 'Illegal parameters, hash iterator is forward only
...
localhost> lua box.select_reverse_range(4, 1, 10)
---
 - '3': {'3'}
 - '2': {'2'}
 - '1': {'1'}
 - '0': {'0'}
...
localhost> lua box.select_reverse_range(4, 1, 2)
---
 - '3': {'3'}
 - '2': {'2'}
...
localhost> lua box.select_reverse_range(4, 1, 2, '1')
---
 - '1': {'1'}
 - '0': {'0'}
...

box.pack(format, ...)

To use Tarantool binary protocol primitives from Lua, it's necessary to convert Lua variables to binary format. This helper function is prototyped after Perl 'pack'. It takes a format and a list of arguments, and returns a binary string with all arguments packed according to the format.

Format specifiers

b — converts Lua variable to a 1-byte integer, and stores the integer in the resulting string

s — converts Lua variable to a 2-byte integer, and stores the integer in the resulting string, low byte first,

i — converts Lua variable to a 4-byte integer, and stores the integer in the resulting string, low byte first,

l — converts Lua variable to a 8-byte integer, and stores the integer in the resulting string, low byte first,

n — converts Lua variable to a 2-byte integer, and stores the integer in the resulting string, big endian,

N — converts Lua variable to a 4-byte integer, and stores the integer in the resulting string, big endian,

Q — converts Lua variable to a 8-byte integer, and stores the integer in the resulting string, big endian,

f — converts Lua variable to a 4-byte float, and stores the float in the resulting string,

d — converts Lua variable to a 8-byte double, and stores the double in the resulting string,

w — converts Lua integer to a BER-encoded integer,

p — stores the length of the argument as a BER-encoded integer followed by the argument itself (a little-endian 4-byte integer for integers, and a binary blob for other types),

=, +, &, |, ^, : — stores the corresponding Tarantool UPDATE operation code: field assignment, addition, conjunction, disjunction, exclusive disjunction, splice (from Perl SPLICE function). Expects field number to update as an argument. These format specifiers only store the corresponding operation code and field number to update, but do not describe operation arguments.

Errors

Unknown format specifier.

Example

localhost> lua box.insert(0, 0, 'hello world')
---
 - 0: {'hello world'}
...
localhost> lua box.update(0, 0, "=p", 1, 'bye world')
---
 - 0: {'bye world'}
...
localhost> lua box.update(0, 0, ":p", 1, box.pack('ppp', 0, 3, 'hello'))
---
 - 0: {'hello world'}
...
localhost> lua box.update(0, 0, "=p", 1, 4)
---
 - 0: {4}
...
localhost> lua box.update(0, 0, "+p", 1, 4)
---
 - 0: {8}
...
localhost> lua box.update(0, 0, "^p", 1, 4)
---
 - 0: {12}
...

box.unpack(format, binary)

Counterpart to box.pack().

Example

localhost> lua tuple=box.replace(2, 0)
---
...
localhost> lua string.len(tuple[0])
---
 - 4
...
localhost> lua box.unpack('i', tuple[0])
---
 - 0
...
localhost> lua box.unpack('bsil', box.pack('bsil', 255, 65535, 4294967295, tonumber64('18446744073709551615')))
---
 - 255
 - 65535
 - 4294967295
 - 18446744073709551615
...
localhost> lua num, str, num64 = box.unpack('ppp', box.pack('ppp', 666, 'string', tonumber64('666666666666666')))
---
...
localhost> lua print(box.unpack('i', num));
---
666
...
localhost> lua print(str);
---
string
...
localhost> lua print(box.unpack('l', num64))
---
666666666666666
...
localhost> lua box.unpack('=p', box.pack('=p', 1, '666'))
---
 - 1
 - 666

box.print(...)

Redefines Lua print() built-in to print either to the log file (when Lua is used from the binary port) or back to the user (for the administrative console).

When printing to the log file, INFO log level is used. When printing to the administrative console, all output is sent directly to the socket.

Note: the administrative console output must be YAML-compatible.

box.dostring(s, ...)

Evaluates an arbitrary chunk of Lua code passed in s. If there is a compilation error, it's raised as a Lua error. In case of compilation success, all arguments which follow s are passed to the compiled chunk and the chunk is invoked.

This function is mainly useful to define and run an arbitrary piece of Lua code, without having to introduce changes to the global Lua environment.

Example

lua box.dostring('abc')
---
error: '[string "abc"]:1: ''='' expected near ''<eof>'''
...
lua box.dostring('return 1')
---
 - 1
...
lua box.dostring('return ...', 'hello', 'world')
---
 - hello
 - world
...
lua box.dostring('local f = function(key) t=box.select(0, 0, key); if t ~= nil then return t[0] else return nil end end return f(...)', 0)
---
 - nil
...

box.time()

Returns current system time (in seconds) as a Lua number. The time is taken from the event loop clock, which makes this call very cheap, but still useful for constructing artificial tuple keys.

box.time64()

Returns current system time (in seconds) as a 64-bit integer. The time is taken from the event loop clock.

box.uuid()

Generate 128-bit (16 bytes) unique id. The id is returned in binary form.

Requires libuuid library to be installed. The library is loaded at runtime, and if the library is not available, this function returns an error.

box.uuid_hex()

Generate hex-string of 128-bit (16 bytes) unique id. Return 32-byte string.

Example

                lua box.uuid_hex()
                ---
                 - a4f29fa0eb6d11e19f7737696d7fa8ff
                ...
            

box.raise(errcode, errtext)

Raises a client error. The difference between this function and the built-in error() function in Lua is that when the error reaches the client, its error code is preserved, whereas every Lua error is presented to the client as ER_PROC_LUA. This function makes it possible to emulate any kind of native exception, such as unique constraint violation, no such space/index, etc. A complete list of errors is present in errcode.h file in the source tree. Lua constants which correspond to Tarantool errors are defined in box.error module. The error message can be arbitrary. Throws client error. Lua procedure can emulate any request errors (for example: unique key exception).

Example

                lua box.raise(box.error.ER_WAL_IO, 'Wal I/O error')
                ---
                error: 'Wal I/O error'
                ...
            

box.auto_increment(space_no, ...)

Insert values into space designated by space_no, using an auto-increment primary key. The space must have a NUM or NUM64 primary key index of type TREE.

Example

localhost> lua box.auto_increment(0, "I am a duplicate")
---
 - 1: {'I am a duplicate'}
...
localhost> lua box.auto_increment(0, "I am a duplicate")
---
 - 2: {'I am a duplicate'}
...
            

box.counter.inc(space_no, key)

Increments a counter identified by the key. The key can be multipart, but there must be an index covering all fields of the key. If there is no tuple identified by the given key, creates a new one with initial counter value set to 1. Returns the new counter value.

Example

localhost> lua box.counter.inc(0, 'top.mail.ru')
---
 - 1
...
localhost> lua box.counter.inc(0, 'top.mail.ru')
---
 - 2
...

box.counter.dec(space_no, key)

Decrements a counter identified by the given key. If the key is not found, is a no-op. When counter value drops to 0, the tuple is deleted.

Example

localhost> lua box.counter.dec(0, 'top.mail.ru')
---
 - 1
...
localhost> lua box.counter.dec(0, 'top.mail.ru')
---
 - 0
...

This package provides read-only access for the box.tuple userdata type. It allows, for a single tuple: selective retrieval of the field contents, retrieval of information about size, iteration over all the fields, and conversion to a Lua table.

box.tuple.new(...)

Construct a new tuple from a Lua table or a scalar. Alternatively, one can get new tuples from tarantool's SQL-like statements: SELECT, INSERT, UPDATE, REPLACE, which can be regarded as statements that do new() implicitly. In the following example, x and t will be new tuple objects. Saying lua t returns the entire tuple t.

Example

localhost>localhost> lua x=box.insert(0,'a',tonumber('1'),tonumber64('2')):totable()
---
...
localhost> lua t=box.tuple.new({'abc','def','ghi','abc'})
---
...
localhost> lua t
---
 - 'abc': {'def', 'ghi', 'abc'}
...

#

The # operand in Lua means "return count of components". So, if t is a tuple instance, #t will return the number of fields. In the following example, a tuple named t is created and then the number of fields in t is returned.

Example

localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4'})
---
...
localhost> lua #t
---
 - 4
...

bsize()

If t is a tuple instance, t:bsize() will return the number of bytes in the tuple. It is useful to check this number when making changes to data, because there is a fixed maximum: one megabyte. Every field has one or more "length" bytes preceding the actual contents, so bsize() returns a value which is slightly greater than the sum of the lengths of the contents. In the following example, a tuple named t is created which has three fields, and for each field it takes one byte to store the length and three bytes to store the contents, so bsize() returns 3*(1+3).

Example

localhost> lua t=box.tuple.new({'aaa','bbb','ccc'})
---
...
localhost> lua t:bsize()
---
 - 12
...

[ ]

If t is a tuple instance, t[n] will return the nth field in the tuple. The first field is t[0]. In the following example, a tuple named t is created and then the second field in t is returned.

Example

localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4'})
---
...
localhost> lua t[1]
---
 - Field#2
...

find() or findall()

If t is a tuple instance, t:find(search-value) will return the number of the first field in t that matches search-value, and t:findall(search-value) will return numbers of all fields in t that match search-value. Optionally one can put a numeric argument n before the search-value to indicate “start searching at field number n.” In the following example, a tuple named t is created and then: the number of the first field in t which matches 'a' is returned, then the numbers of all the fields in t which match 'a' are returned, then the numbers of all the fields in t which match 'a' and are at or after the second field are returned.

Example

localhost> lua t=box.tuple.new({'a','b','c','a'})
---
...
localhost> lua t:find('a')
---
 - 0
...
localhost> lua t:findall('a')
---
 - 0
 - 3
...
localhost> lua t:findall(1,'a')
---
 - 3
...

transform()

If t is a tuple instance, t:transform(n1,n2) will return a tuple where, starting from field n1, a number of fields (n2) are removed. Optionally one can add more arguments after n2 to indicate new values that will replace what was removed. In the following example, a tuple named t is created and then, starting from the second field, two fields are removed but one new one is added, then the result is returned.

Example

localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4','Field#5'})
---
...
localhost> lua t:transform(1,2,'x')
---
 - 'Field#1': {'x', 'Field#4', 'Field#5'}
...

slice()

If t is a tuple instance, t:slice(n) will return all fields starting with field number n, and t:slice(n1,n2) will return a tuple containing fields starting with field number n1, but stopping before field number n2. In the following example, a tuple named t is created and then, starting from the second field, fields before the fourth field are selected, then the result is returned.

Example

localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4','Field#5'})
---
...
localhost> lua t:slice(1,3)
---
 - Field#2
 - Field#3
...

unpack()

If t is a tuple instance, t:unpack(n) will return all fields. In effect, unpack() is the same as slice(0,-1). In the following example, a tuple named t is created and then all its fields are selected, then the result is returned.

Example

localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4','Field#5'})
---
...
localhost> lua t:unpack()
---
 - Field#1
 - Field#2
 - Field#3
 - Field#4
 - Field#5
...

pairs()

In Lua, pairs() is a method which returns: function, value, nil. It is useful for Lua iterators, because Lua iterators traverse a value's components until an end marker is reached. In the following example, a tuple named t is created and then all its fields are selected using a Lua for-end loop.

Example

localhost> lua t=box.tuple.new({'Field#1','Field#2','Field#3','Field#4','Field#5'})
---
...
localhost> lua for k,v in t:pairs() do print(v) end
---
Field#1
Field#2
Field#3
Field#4
Field#5
...

This package provides JSON manipulation routines. It's based on the Lua-CJSON package by Mark Pulford. For a complete manual on Lua-CJSON please read the official documentation.

box.cjson.encode(object)

Convert a Lua object to a JSON string.

box.cjson.decode(string)

Convert a JSON string to a Lua object.

This package is a container for all configured spaces. A space object provides access to space attributes, such as id, whether or not a space is enabled, space cardinality, and estimated number of rows. It also contains object-oriented versions of box functions. For example, instead of box.insert(0, ...) one can write box.space[0]:insert(...). Package source code is available in file src/box/lua/box.lua

A list of all space members follows.

space.n

Ordinal space number, box.space[i].n == i

space.enabled

Whether or not this space is enabled in the configuration file.

space.cardinality

A limit on tuple field count for tuples in this space. This limit can be set in the configuration file. Value 0 stands for “unlimited”.

space.index[]

A container for all defined indexes. An index is a Lua object of type box.index with methods to search tuples and iterate over them in predefined order.

space:select(index_no, ...)

space:select_range(index_no, limit, key)

Select a range of tuples, starting from the offset specified by key. The key can be multipart. Limit selection with at most limit tuples. If no key is specified, start from the first key in the index.

For TREE indexes, this returns tuples in sorted order. For other indexes, the order of tuples is unspecified, and can change significantly if data is inserted or deleted between two calls to select_range(). If key is nil or unspecified, the selection starts from the start of the index.

space:select_reverse_range(limit, key)

Select a reverse range of tuples, limited by limit, starting from key. The key can be multipart. For TREE indexes, this returns tuples in descending order. For other index types this call is not supported.

space:insert(...)

space:replace(...)

space:delete(key)

space:update(key, format, ...)

space:insert(...)

Object-oriented forms of respective box methods.

space:len()

Returns number of tuples in the space.

space:truncate()

Deletes all tuples.

space:pairs()

A helper function to iterate over all space tuples, Lua style.

Example

localhost> lua for k,v in box.space[0]:pairs() do print(v) end
---
1: {'hello'}
2: {'my     '}
3: {'Lua    '}
4: {'world'}
...

This package implements methods of type box.index. Indexes are contained in box.space[i].index[] array within each space object. They provide an API for ordered iteration over tuples. This API is a direct binding to corresponding methods of index objects in the storage engine.

index.unique

Boolean, true if the index is unique.

index.type

A string for index type, either 'TREE', 'HASH', or 'BITSET'.

index.key_field[]

An array describing index key fields.

index.idx

The underlying userdata which does all the magic.

index:iterator(type, ...)

This method provides iteration support within an index. Parameter type is used to identify the semantics of iteration. Different index types support different iterators. The remaining arguments of the function are varying and depend on the iteration type. For example, a TREE index maintains a strict order of keys and can return all tuples in ascending or descending order, starting from the specified key. Other index types, however, do not support ordering.

To understand consistency of tuples returned by an iterator, it's essential to know the principles of the Tarantool transaction processing subsystem. An iterator in Tarantool does not own a consistent read view. Instead, each procedure is granted exclusive access to all tuples and spaces until it encounters a "context switch": by causing a write to disk, network, or by an explicit call to box.fiber.yield(). When the execution flow returns to the yielded procedure, the data set could have changed significantly. Iteration, resumed after a yield point, does not preserve the read view, but continues with the new content of the database.

Parameters

type — iteration strategy as defined in tables below.

Returns

This method returns an iterator closure, i.e. a function which can be used to get the next value on each invocation.

Errors

Selected iteration type is not supported in the subject index type or supplied parameters do not match iteration type.

Table 4.1. Common iterator types

Type	Arguments	HASH	TREE	BITSET	Description
box.index.ALL	none	yes	yes	yes	Iterate over all tuples in an index. When iterating over a TREE index, tuples are returned in ascending order of the key. When iterating over a HASH or BITSET index, tuples are returned in physical order or, in other words, unordered.
box.index.EQ	key	yes	yes	yes	Equality iterator: iterate over all tuples matching the key. Parts of a multipart key need to be separated by comma. Semantics of the match depends on the index. A HASH index only supports exact match: all parts of a key participating in the index must be provided. In case of TREE index, only few parts of a key or a key prefix are accepted for search. In this case, all tuples with the same prefix or matching key parts are considered matching the search criteria. When a TREE index is not unique, or only part of a key is given as a search criteria, matching tuples are returned in ascending order. BITSET and HASH indexes are always unique.
box.index.GT	key	yes (*)	yes	no	Iterate over tuples strictly greater than the search key. For TREE indexes, a key prefix or key part can be sufficient. If the key is nil, iteration starts from the smallest key in the index. The tuples are returned in ascending order of the key. HASH index also supports this iterator type, but returns tuples in unspecified order. However, if the server does not receive updates, this iterator can be used to retrieve all tuples via a HASH index piece by piece, by supplying the last key from the previous range as the start key for an iterator over the next range. BITSET index does not support this iteration type yet.

Table 4.2. TREE iterator types

Type	Arguments	Description
box.index.REQ	key or key part	Reverse equality iterator. Is equivalent to box.index.EQ with only distinction that the order of returned tuples is descending, not ascending.
box.index.GE	key or key part	Iterate over all tuples for which the corresponding fields are greater or equal to the search key. The tuples are returned in ascending order. Similarly to box.index.EQ, key prefix or key part can be used to seed the iterator. If the key is nil, iteration starts from the smallest key in the index.
box.index.LT	key or key part	Similar to box.index.GT, but returns all tuples which are strictly less than the search key. The tuples are returned in the descending order of the key. nil key can be used to start from the end of the index range.
box.index.LE	key or key part	Similar to box.index.GE, but returns all tuples which are less or equal to the search key or key prefix, and returns tuples in descending order, from biggest to smallest. If the key is nil, iteration starts from the end of the index range.

Table 4.3. BITSET iterator types

Type	Arguments	Description
box.index.BITS_ALL_SET	bit mask	Matches tuples in which all specified bits are set.
box.index.BITS_ANY_SET	bit mask	Matches tuples in which any of the specified bits is set.
box.index.BITS_ALL_NOT_SET	bit mask	Matches tuples in which none of the specified bits is set.

Examples

localhost> show configuration
---
...
  space[0].enabled: "true"
  space[0].index[0].type: "HASH"
  space[0].index[0].unique: "true"
  space[0].index[0].key_field[0].fieldno: "0"
  space[0].index[0].key_field[0].type: "NUM"
  space[0].index[1].type: "TREE"
  space[0].index[1].unique: "false"
  space[0].index[1].key_field[0].fieldno: "1"
  space[0].index[1].key_field[0].type: "NUM"
  space[0].index[1].key_field[1].fieldno: "2"
  space[0].index[1].key_field[1].type: "NUM"
...
localhost> INSERT INTO t0 VALUES (1, 1, 0)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (2, 1, 1)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (3, 1, 2)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (4, 2, 0)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (5, 2, 1)
Insert OK, 1 rows affected
localhost> INSERT INTO t0 VALUES (6, 2, 2)
Insert OK, 1 rows affected
localhost> lua it = box.space[0].index[1]:iterator(box.index.EQ, 1); print(it(), " ", it(), " ", it());
---
1: {1, 0} 2: {1, 1} 3: {1, 2}
...
localhost> lua it = box.space[0].index[1]:iterator(box.index.EQ, 1, 2); print(it(), " ", it(), " ", it());
---
3: {1, 2} nil nil
...
localhost> lua i = box.space[0].index[1]:iterator(box.index.GE, 2, 1);  print(it(), " ", it(), " ", it());
---
5: {2, 1} 6: {2, 2} nil
...
localhost> lua for v in box.space[0].index[1]:iterator(box.index.ALL) do print(v) end
---
1: {1, 0}
2: {1, 1}
3: {1, 2}
4: {2, 0}
5: {2, 1}
6: {2, 2}
...
localhost> lua i = box.space[0].index[0]:iterator(box.index.LT, 1);
---
error: 'Iterator type is not supported'

index:min()

The smallest value in the index. Available only for indexes of type 'TREE'.

index:max()

The biggest value in the index. Available only for indexes of type 'TREE'.

index:random(randint)

Return a random value from an index. A random non-negative integer must be supplied as input, and a value is selected accordingly in index-specific fashion. This method is useful when it's important to get insight into data distribution in an index without having to iterate over the entire data set.

index:count()

Iterate over an index, counting the number of tuples which equal the provided search criteria. The argument can either point to a tuple, a key, or one or more key parts. Returns the number of matched tuples.

box.fiber.id(fiber)

Return a numeric id of the fiber.

box.fiber.self()

Return box.fiber userdata object for the currently scheduled fiber.

box.fiber.find(id)

Locate a fiber userdata object by id.

box.fiber.create(function)

Create a fiber for a function.

Errors

Can hit a recursion limit.

box.fiber.resume(fiber, ...)

Resume a created or suspended fiber.

box.fiber.yield(...)

Yield control to the calling fiber, if the fiber is attached, or to sched otherwise.

If the fiber is attached, whatever arguments are passed to this call, are passed on to the calling fiber. If the fiber is detached, box.fiber.yield() returns back everything passed into it after temporarily yielding control back to the scheduler.

box.fiber.detach()

Detach the current fiber. This is a cancellation point. This is a yield point.

box.fiber.wrap(function, ...)

This is a quick way to create and start a detached fiber. The fiber function is passed in the first argument, the function arguments follow. The fiber is created, detached, and resumed immediately.

box.fiber.sleep(time)

Yield to the sched fiber and sleep time seconds. Only the current fiber can be made to sleep.

box.fiber.status(fiber)

Returns the status of the fiber. If no argument is provided, the current fiber's status is returned. The status can be either “dead”, “suspended”, “attached” or “running”.

box.fiber.cancel(fiber)

Cancel a fiber. Running and suspended fibers can be canceled. Returns an error if the subject fiber does not permit cancel.

box.fiber.testcancel()

Check if the current fiber has been canceled and throw an exception if this is the case.

box.session.id()

Return a unique monotonic identifier of the current session. The identifier can be used to check whether or not a session is alive. 0 means there is no session (e.g. a procedure is running in a detached fiber).

box.session.fd(id)

Return an integer file descriptor associated with the connected client.

box.session.exists(id)

Return true if a session is alive, false otherwise.

box.session.peer(id)

Return the host address and port for the session peer, for example "127.0.0.1:55457", or "0.0.0.0:0" if the session is not connected.

box.ipc.channel(capacity)

Create a new communication channel with predefined capacity. The channel can be used to synchronously exchange messages between stored procedures. The channel is garbage collected when no one is using it, just like any other Lua object. Channels can be worked with using functional or object-oriented syntax. For example, the following two lines are equivalent:

    channel:put(message)
    box.ipc.channel.put(channel, message)

box.ipc.channel.put(channel, message, timeout)

Send a message using a channel. If the channel is full, box.ipc.channel.put() blocks until there is a free slot in the channel. If timeout is provided, and the channel doesn't become empty for the duration of the timeout, box.ipc.channel.put() returns false. Otherwise it returns true.

box.ipc.channel.get(channel, timeout)

Fetch a message from a channel. If the channel is empty, box.ipc.channel.get() blocks until there is a message. If timeout is provided, and there are no new messages for the duration of the timeout, box.ipc.channel.get() returns error.

box.ipc.channel.broadcast(channel, message, timeout)

If the channel is empty, is equivalent to box.ipc.channel.put(). Otherwise sends the message to all readers of the channel.

box.ipc.channel.is_empty(channel)

Check if the channel is empty (has no messages).

box.ipc.channel.is_full(channel)

Check if the channel is full (has no room for a new message).

box.ipc.channel.has_readers(channel)

Check if the channel is empty and has readers waiting for a message.

box.ipc.channel.has_writers(channel)

Check if the channel is full and has writers waiting for empty room.

Example

local channel = box.ipc.channel(10)
function consumer_fiber()
    while true do
        local task = channel:get()
        ...
    end
end

function consumer2_fiber()
    while true do
        local task = channel:get(10)        -- 10 seconds
        if task ~= nil then
            ...
        else
            print("timeout!")
        end
    end
end

function producer_fiber()
    while true do
        task = box.select(...)
        ...
        if channel:is_empty() then
            # channel is empty
        end

        if channel:is_full() then
            # channel is full
        end

        ...
        if channel:has_readers() then
            # there are some fibers that wait data
        end
        ...

        if channel:has_writers() then
            # there are some fibers that wait readers
        end
        channel:put(task)
    end
end

function producer2_fiber()
    while true do
        task = box.select(...)

        if channel:put(task, 10) then       -- 10 seconds
            ...
        else
            print("timeout!")
        end
    end
end

BSD sockets is a mechanism to exchange data with a local or remote host in connection-oriented (TCP) or datagram-oriented (UDP) mode. Semantics of the calls in the box.socket API closely follow semantics of the corresponding POSIX calls. Function names and signatures are mostly compatible with luasocket.

Similarly to luasocket, box.socket doesn't throw exceptions on errors. On success, most calls return a socket object. On error, a multiple return of nil, status, errno, errstr is produced. Status can be one of "error", "timeout", "eof" or "limit". On success, status is always nil. A call which returns data (recv(), recvfrom(), readline()) on success returns a Lua string of the requested size and nil status. On error or timeout, an empty string is followed by the corresponding status, error number and message. A call which sends data (send(), sendto()) on success returns the number of bytes sent, and the status is, again, nil. On error or timeout 0 is returned, followed by status, error number and message.

The last error can be retrieved from the socket using socket:error(). Any call except error() clears the last error first (but may set a new one).

Calls which require a socket address and in POSIX expect struct sockaddr_in, in box.socket simply accept host name and port as additional arguments. Name resolution is done automatically. If it fails, status is set to "error", errno is set to -1 and error string is set to "Host name resolution failed".

All calls that can take time block the calling fiber and can get it preempted. The implementation, however, uses non-blocking cooperative I/O, so Tarantool continues processing queries while a call is blocked. A timeout can be provided for any socket call which can take a long time.

As with all other box libraries, the API can be used in procedural style (e.g. box.socket.close(socket)) as well as in object-oriented style (socket:close()).

A closed socket should not be used any more. Alternatively, the socket will be closed when its userdata is garbage collected by Lua.

box.socket.tcp()

Create a new TCP socket.

Returns

A new socket or nil.

box.socket.udp()

Create a new UDP socket.

Returns

A new socket or nil.

socket:connect(host, port, [timeout])

Connect a socket to a remote host. Can be used with IPv6 and IPv4 addresses, as well as domain names. If multiple addresses correspond to a domain, tries them all until successfully connected.

Returns

Returns a connected socket on success, nil, status, errno, errstr on error or timeout.

socket:send(data, [timeout])

Send data over a connected socket.

Returns

The number of bytes sent. On success, this is exactly the length of data. In case of error or timeout, returns the number of bytes sent before error, followed by status, errno, errstr.

socket:recv(size, [timeout])

Read size bytes from a connected socket. An internal read-ahead buffer is used to reduce the cost of this call.

Returns

A string of the requested length on success. On error or timeout, returns an empty string, followed by status, errno, errstr. If there was some data read before a timeout occurred, it will be available on the next call. In case the writing side has closed its end, returns the remainder read from the socket (possibly an empty string), followed by "eof" status.

socket:readline([limit], [separator list], [timeout])

Read a line from a connected socket.

socket:readline() with no arguments reads data from a socket until '\n' or eof. If a limit is set, the call reads data until a separator is found, or the limit is reached. By default, there is no limit. Instead of the default separator, a Lua table can be used with one or multiple separators. Then the data is read until the first matching separator is found.

Returns

A Lua string with data in case of success or an empty string in case of error. When multiple separators were provided in a separator table, the matched separator is returned as the third argument.

Table 4.4. readline() returns

data, nil, separator	success
"", "timeout", ETIMEDOUT, errstr	timeout
"", "error", errno, errstr	error
data, "limit"	limit
data, "eof"	eof

socket:bind(host, port[, timeout])

Bind a socket to the given host/port. A UDP socket after binding can be used to receive data (see recvfrom()). A TCP socket can be used to accept new connections, after it's been put in listen mode. The timeout is used for name resolution only. If host name is an IP address, the call never yields and the timeout is unused.

Returns

Socket object on success, nil, status, errno, errstr on error.

socket:listen()

Start listening for incoming connections. The listen backlog, on Linux, is taken from /proc/sys/net/core/somaxconn, whereas on BSD it is set to SOMAXCONN.

Returns

Socket on success, nil, "error", errno, errstr on error.

socket:accept([timeout])

Wait for a new client connection and create a connected socket.

Returns

peer_socket, nil, peer_host, peer_port on success. nil, status, errno, errstr on error.

socket:sendto(data, host, port, [timeout])

Send a message on a UDP socket to a specified host.

Returns

The number of bytes sent on success, 0, status, errno, errstr on error or timeout.

socket:recvfrom(limit[, timeout])

Receive a message on a UDP socket.

Returns

Message, nil, client address, client port on success, "", status, errno, errstr on error or timeout.

socket:shutdown(how)

Shutdown a reading, writing or both ends of a socket. Accepts box.socket.SHUT_RD, box.socket.SHUT_WR and box.socket.SHUT_RDWR.

Returns

Socket on success, nil, "error", errno, errstr on error.

socket:close()

Close (destroy) a socket. A closed socket should not be used any more.

socket:error()

Retrieve the last error that occurred on a socket.

Returns

errno, errstr. 0, "Success" if there is no error.

The basic object provided by box.net.box library is a connection. A connection is created by calling box.net.box.new(). To execute remote requests, simply invoke methods of the connection object, a physical connection is established upon request and is re-established if necessary. When done, issue conn:close(). Connection objects are garbage collected just like any other objects in Lua, so an explicit destruction is not mandatory. However, since close() is a system call, it is a good programming practice to close a connection explicitly when it is no longer needed, to avoid lengthy stalls of the garbage collector.

The library also provides a pre-created connection object to the local server, box.net.self. This connection is always “established”. The purpose of this object is to make polymorphic use of the box.net.box API easier. There is an important difference, however, between the embedded connection and a remote one. With the embedded connection, requests which do not modify data do not yield. When using a remote connection, it is important to keep in mind that any request can yield, and local database state may have changed by the time it returns.

All box.net.box methods are fiber-safe. It's safe to share and use the same connection object across multiple concurrent fibers. In fact, it's perhaps the best programming practice with Tarantool: when multiple fibers use the same connection, all requests are pipelined through the same network socket, but each fiber gets a correct response back. Reducing the number of active sockets lowers the overhead of system calls and increases the overall server performance. There are, however cases, when a single connection is not enough: when it's necessary to prioritize requests, use different authentication ids, etc.

All remote calls support execution timeouts. A specialized wrapper, box.net.box.timeout() allows setting a timeout. Using a wrapper object makes the remote connection API compatible with the local one, removing the need for a separate timeout argument, ignored by the local version. Once sent, a request can not be revoked from the remote server even if a timeout expires: the expired timeout only aborts the wait for the remote server response. box.net.box.timeout(),

Object-oriented and functional APIs are equivalent: conn:close() is identical to box.net.box.close(conn).

conn = box.net.box.new(host, port [, reconnect_interval])

Create a new connection. The connection is established on demand, at the time of the first request. It is re-established automatically after a disconnect. The argument reconnect_interval (in seconds) is responsible for the amount of time the server sleeps between failing attempts to reconnect. The returned object supports methods for making remote calls, such as select, update or delete.

conn:ping()

Execute a PING command. Returns true on success, false on error.

conn:close()

Close a connection. The connection is also closed when it's garbage collected. It's still recommended to close connections explicitly, to spare the garbage collector from heavy work such as closing the socket.

conn:select(space_no, index_no, ...)

See box.select(...). Please note, that unlike a local box.select() any call to a remote server yields, thus local data may change while remote select() is running.

conn:select_limit(space_no, index_no, offset, limit, ...)

See box.select_limit(...)

conn:select_range(space_no, index_no, limit, key, ...)

See box.select_range(...).

conn:insert(space_no, ...)

See box.insert(...).

conn:replace(space_no, ...)

See box.replace(...).

conn:update(...)

See box.update(...).

conn:delete(space_no, key)

See box.delete(...).

conn:call(proc_name, ...)

Call a remote stored procedure, such as box.select_reverse_range(). Please keep in mind that the call is using the binary protocol to pack procedure arguments, and since the latter is type-agnostic it's recommended to pass all arguments of remote stored procedure as strings, for example:

    conn:call("box.select_reverse_range", "1", "4", "10", "Smith")

conn:timeout(timeout)

Returns a closure which is identical to the invoked function, except for the added timeout functionality.

-- wait for 'update' until it is finished
local tuple = conn:update('1', 'key', ...)

-- send update but don't bother to wait for results
local other = conn:timeout(0):update('1', 'arg1', ...)

Package box.cfg

This package provides read-only access to all server configuration parameters.

box.cfg

Example

localhost> lua for k, v in pairs(box.cfg) do print(k, " = ", v) end
---
io_collect_interval = 0
pid_file = box.pid
panic_on_wal_error = false
slab_alloc_factor = 2
slab_alloc_minimal = 64
admin_port = 33015
logger = cat - >> tarantool.log
...

Package box.info

This package provides access to information about server variables: pid, uptime, version and such. Its contents are identical to the output from SHOW INFO.

box.info()

Since box.info contents are dynamic, it's not possible to iterate over keys with the Lua pairs() function. For this purpose, box.info() builds and returns a Lua table with all keys and values provided in the package.

Example

localhost> lua for k,v in pairs(box.info()) do print(k, ": ", v) end
---
version: 1.4.7-92-g4ba95ca
status: primary
pid: 1747
lsn: 1712
recovery_last_update: 1306964594.980
recovery_lag: 0.000
uptime: 39
build: table: 0x419cb880
logger_pid: 1748
config: /home/unera/work/tarantool/test/box/tarantool_good.cfg
...

box.info.status, box.info.pid, box.info.lsn, ...

Example

localhost> lua box.info.pid
---
 - 1747
...
localhost> lua box.info.logger_pid
---
 - 1748
...
localhost> lua box.info.version
---
 - 1.4.7-92-g4ba95ca
...
localhost> lua box.info.config
---
 - /home/unera/work/tarantool/test/box/tarantool_good.cfg
...
localhost> lua box.info.uptime
---
 - 3672
...
localhost> lua box.info.lsn
---
 - 1712
...
localhost> lua box.info.status
---
 - primary
...
localhost> lua box.info.recovery_lag
---
 - 0.000
...
localhost> lua box.info.recovery_last_update
---
 - 1306964594.980
...
localhost> lua box.info.snapshot_pid
---
 - 0
...
localhost> lua for k, v in pairs(box.info.build) do print(k .. ': ', v) end
---
flags:  -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -DCORO_ASM -fno-omit-frame-pointer -fno-stack-protector -fexceptions -funwind-tables -fgnu89-inline -pthread  -Wno-sign-compare -Wno-strict-aliasing -std=gnu99 -Wall -Wextra -Werror
target: Linux-x86_64-Debug
compiler: /usr/bin/gcc
options: cmake . -DCMAKE_INSTALL_PREFIX=/usr/local -DENABLE_STATIC=OFF -DENABLE_GCOV=OFF -DENABLE_TRACE=ON -DENABLE_BACKTRACE=ON -DENABLE_CLIENT=OFF
...

Package box.slab

This package provides access to slab allocator statistics.

box.slab

Example

localhost> lua box.slab.arena_used
---
 - 4194304
...
localhost> lua box.slab.arena_size
---
 - 104857600
...
localhost> lua for k, v in pairs(box.slab.slabs) do print(k) end
---
64
128
...
localhost> lua for k, v in pairs(box.slab.slabs[64]) do print(k, ':', v) end
---
items:1
bytes_used:160
item_size:64
slabs:1
bytes_free:4194144
...

Package box.stat

This package provides access to request statistics.

box.stat

Example

localhost> lua box.stat -- a virtual table
---
 - table: 0x41a07a08
...
localhost> lua box.stat() -- a full table (the same)
---
 - table: 0x41a0ebb0
...
localhost> lua for k, v in pairs(box.stat()) do print(k) end
---
DELETE
SELECT
REPLACE
CALL
UPDATE
DELETE_1_3
...
localhost> lua for k, v in pairs(box.stat().DELETE) do print(k, ': ', v) end
---
total: 23210
rps: 22
...
localhost> lua for k, v in pairs(box.stat.DELETE) do print(k, ': ', v) end -- the same
---
total: 23210
rps: 22
...
localhost> lua for k, v in pairs(box.stat.SELECT) do print(k, ': ', v) end
---
total: 34553330
rps: 23
...
localhost>

box.session.on_connect(chunk)

Set a callback (trigger) invoked on each connected session. The callback doesn't get any arguments, but is the first thing invoked in the scope of the newly created session. If the trigger fails by raising an error, the error is sent to the client and the connection is shut down. Returns the old value of the trigger.

Warning

If a trigger always results in an error, it may become impossible to connect to the server to reset it.

box.session.on_disconnect(chunk)

Set a trigger invoked after a client has disconnected. Returns the old value of the trigger. If the trigger raises an error, the error is logged but otherwise is ignored. The trigger is invoked while the session associated with the client still exists and can access session properties, such as id.