Developer’s guide

Basic concepts


Spaces is a collections of tuples. Usually, tuples in one space represent objects of the same type, although this is not necessary.


The analogue of spaces is tables in traditional (SQL) databases.

Spaces have integer identifiers defined in the server configuration. To access the space as a named object it is possible to use the method and an instance of Space.


>>> customer =
>>> customer.insert(('FFFF', 'Foxtrot'))

Field types

Three field types are supported in Tarantool: STR, NUM and NUM64. These types are used only for index configuration but not saved in tuple’s data and not transferred between the client and server. Thus, from the client point of view, fields are raw byte arrays without explicitly definde types.

It is much easier to use native types for python developer: int, long, unicode (int and str for Python 3.x). For raw binary data bytes should be used (in this case the type casting is not performed).

Tarantool data types corresponds to the following Python types:
  • RAW - bytes
  • STR - unicode (str for Python 3.x)
  • NUM - int
  • NUM64 - int or long (int for Python 3.x)

Please define spaces schema to enable automatic type casting:

>>> import tarantool
>>> schema = {
        0: { # Space description
            'name': 'users', # Space name
            'default_type': tarantool.STR, # Type that used to decode fields that are not listed below
            'fields': {
                0: ('numfield', tarantool.NUM), # (field name, field type)
                1: ('num64field', tarantool.NUM64),
                2: ('strfield', tarantool.STR),
                #2: { 'name': 'strfield', 'type': tarantool.STR }, # Alternative syntax
                #2: tarantool.STR # Alternative syntax
            'indexes': {
                0: ('pk', [0]), # (name, [field_no])
                #0: { 'name': 'pk', 'fields': [0]}, # Alternative syntax
                #0: [0], # Alternative syntax
>>> connection = tarantool.connect(host = 'localhost', port=33013, schema = schema)
>>> demo ='users')
>>> demo.insert((0, 12, u'this is unicode string'))
[(0, 12, u'this is unicode string')]

As you can see, original “raw” fields were casted to native types as defined in the schema.

Tarantool’s tuple can contain any number of fields. If some fields are not defined then default_type will be used.

To prevent implicit type casting for strings use RAW type. Raw byte fields should be used if the application uses binary data (eg, images or python objects packed with picke).

You can also specify schema for CALL results:

>>> ...
# Copy schema decription from 'users' space
>>>"", '0', '0', 0L, space_name='users');
[(0, 12, u'this is unicode string')]
# Provide schema description explicitly
>>> field_defs = [('numfield', tarantool.NUM), ('num64field', tarantool.NUM)]
>>>"", '0', '1', 184L, field_defs = field_defs, default_type = tarantool.STR);
[(0, 12, u'this is unicode string')]


Python 2.6 adds bytes as a synonym for the str type, and it also supports the b'' notation.


utf-8 allways used for type conversion between unicode and bytes

Request response

Requests (insert(), delete(), update(), select()) return a Response instance.

Class Response inherited from list, so in fact response can be used as a list of a tuples.

In addition Response instance has the rowcount attribute. The value of rowcount equals to the number of records affected by the request. For example for delete() request rowcount is equals to 1 if record was deleted.

Connect to the server

To connect to the server it is required to use tarantool.connect() method. It returns an Connection instance.


>>> import tarantool
>>> connection = tarantool.connect("localhost", 33013)
>>> type(connection)
<class 'tarantool.connection.Connection'>

Data manipulation

There are four basic operations supported by Tarantool: insert, delete, update and select.



Inserting and replacing records

To insert or replace records Space.insert() method should be used:

>>> user.insert((user_id, email, int(time.time())))

The first element of the tuple is always its unique primary key.

If an entry with the same key already exists, it will be replaced without any warning or error message.


In case of insert request Response.rowcount is always equals to 1

Deleting Records

To delete records Space.delete() method should be used:

>>> user.delete(primary_key)


If the record was deleted Response.rowcount equals to 1. If the record was not found Response.rowcount equals to 0.

Updating Records

Update request in Tarantool allows to simultaneous and atomic update multiple fields of a tuple.

To update records Space.update() method should be used.


>>> user.update(1001, [('=', 1, 'John'), ('=', 2, 'Smith')])

In this example new values for fields 1 and 2 are assigned.

Space.update() method allows to change multiple fields of the tuple at a time.

The following update operations are supported by Tarantool:
  • '=' – assign new value to the field
  • '+' – add argument to the field (both arguments are treated as signed 32-bit ints)
  • '^' – bitwise AND (only for 32-bit integers)
  • '|' – bitwise XOR (only for 32-bit integers)
  • '&' – bitwise OR (only for 32-bit integers)
  • 'splice' – implementation of Perl splice function


The zero (i.e. [0]) field of the tuple can not be updated, because it is the primary key

See also

See Space.update() documentation for details


'splice' operation is not implemented yet

Selecting Records

To select records method should be used. SELECT query can return one or many records.

Select by primary key

Select a record using its primary key 3800:

[(3800, u'USA', u'Texas', u'Dallas', 1188580)]

Select using secondary index

>>>'USA', index=1)
[(3796, u'USA', u'Texas', u'Houston', 1953631),
 (3801, u'USA', u'Texas', u'Huston', 10000),
 (3802, u'USA', u'California', u'Los Angeles', 10000),
 (3805, u'USA', u'California', u'San Francisco', 776733),
 (3800, u'USA', u'Texas', u'Dallas', 1188580),
 (3794, u'USA', u'California', u'Los Angeles', 3694820)]

Argument index = 1 indicates that secondary index (1) should be used. The primary key (index=0) is used by default.


Secondary indexes must be explicitly declared in the server configuration

Select records using several keys


This conforms to where key in (k1, k2, k3...)

Select records with primary key values 3800, 3805 and 3796:

>>>[3800, 3805, 3796])
[(3800, u'USA', u'Texas', u'Dallas', 1188580),
 (3805, u'USA', u'California', u'San Francisco', 776733),
 (3796, u'USA', u'Texas', u'Houston', 1953631)]

Retrieve a record by using a composite index

Select data on cities in Texas:

>>>[('USA', 'Texas')], index=1)
[(3800, u'USA', u'Texas', u'Dallas', 1188580), (3796, u'USA', u'Texas', u'Houston', 1953631)]

Select records explicitly specifying field types

Tarantool has no strict schema so all fields are raw binary byte arrays. You can specify field types in the schema parameter to a connection.

Call server-side functions

A server-side function written in Lua can select and modify data, access configuration and perform administrative tasks.

To call stored function method should be used. Also, this method has an alias


>>>"box.select_range", (1, 3, 2, 'AAAA'))
[(3800, u'USA', u'Texas', u'Dallas', 1188580), (3794, u'USA', u'California', u'Los Angeles', 3694820)]

See also

Tarantool/Box User Guide » Writing stored procedures in Lua