Spaces is a collections of tuples. Usually, tuples in one space represent objects of the same type, although this is not necessary.
Note
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 Connection.space() and an instance of Space.
Example:
>>> customer = connection.space(0)
>>> customer.insert(('FFFF', 'Foxtrot'))
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).
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 = connection.space('users')
>>> demo.insert((0, 12, u'this is unicode string'))
>>> demo.select(0)
[(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
>>> connection.call("box.select", '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)]
>>> connection.call("box.select", '0', '1', 184L, field_defs = field_defs, default_type = tarantool.STR);
[(0, 12, u'this is unicode string')]
Note
Python 2.6 adds bytes as a synonym for the str type, and it also supports the b'' notation.
Note
utf-8 allways used for type conversion between unicode and bytes
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.
To connect to the server it is required to use tarantool.connect() method. It returns an Connection instance.
Example:
>>> import tarantool
>>> connection = tarantool.connect("localhost", 33013)
>>> type(connection)
<class 'tarantool.connection.Connection'>
There are four basic operations supported by Tarantool: insert, delete, update and select.
Note
НЕОБХОДИМО ОБЪЯСНИТЬ КАКИЕ ДАННЫЕ ИСПОЛЬЗУЮТСЯ ДЛЯ ПРИМЕРА
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.
Note
In case of insert request Response.rowcount is always equals to 1
To delete records Space.delete() method should be used:
>>> user.delete(primary_key)
Note
If the record was deleted Response.rowcount equals to 1. If the record was not found Response.rowcount equals to 0.
Update request in Tarantool allows to simultaneous and atomic update multiple fields of a tuple.
To update records Space.update() method should be used.
Example:
>>> 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.
Note
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
Warning
'splice' operation is not implemented yet
To select records Space.select() method should be used. SELECT query can return one or many records.
Select by primary key
Select a record using its primary key 3800:
>>> world.select(3800)
[(3800, u'USA', u'Texas', u'Dallas', 1188580)]
Select using secondary index
>>> world.select('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.
Note
Secondary indexes must be explicitly declared in the server configuration
Select records using several keys
Note
This conforms to where key in (k1, k2, k3...)
Select records with primary key values 3800, 3805 and 3796:
>>> world.select([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:
>>> world.select([('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.
A server-side function written in Lua can select and modify data, access configuration and perform administrative tasks.
To call stored function Connection.call() method should be used. Also, this method has an alias Space.call().
Example:
>>> server.call("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