module `tarantool.connection`¶

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError

call(func_name, *args, on_push=None, on_push_ctx=None)¶

Execute a CALL request: call a stored Lua function.

Parameters

func_name¶ (str) – Stored Lua function name.
args¶ (tuple) – Stored Lua function arguments.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, SchemaError, NetworkError, SslError

close()¶: Close a connection to the server. The method is idempotent.

connect()¶

Create a connection to the host and port specified on initialization. There is no need to call this method explicitly until you have set connect_now=False on initialization.

Raise: NetworkError, SslError, SchemaError, DatabaseError

crud_count(space_name: str, conditions: list = [], opts: dict = {}) → int¶

Gets rows count through the crud.

Parameters

space_name¶ (str) – The name of the target space.
conditions¶ (list, optional) – The conditions for the crud module.
opts¶ (dict, optional) – The opts for the crud module.

Return type

int

Raise

crud_delete(space_name: str, key: int, opts: dict = {}) → CrudResult¶

Deletes row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
key¶ (int) – The primary key value.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_get(space_name: str, key: int, opts: dict = {}) → CrudResult¶

Gets row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
key¶ (int) – The primary key value.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_insert(space_name: str, values: Union[tuple, list], opts: dict = {}) → CrudResult¶

Inserts row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_insert_many(space_name: str, values: Union[tuple, list], opts: dict = {}) → CrudResult¶

Inserts batch rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_insert_object(space_name: str, values: dict, opts: dict = {}) → CrudResult¶

Inserts object row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (dict) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_insert_object_many(space_name: str, values: Union[tuple, list], opts: dict = {}) → CrudResult¶

Inserts batch object rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_len(space_name: str, opts: dict = {}) → int¶

Gets the number of tuples in the space through the crud.

Parameters

space_name¶ (str) – The name of the target space.
opts¶ (dict, optional) – The opts for the crud module.

Return type

int

Raise

crud_max(space_name: str, index_name: str, opts: dict = {}) → CrudResult¶

Gets rows with maximum value in the specified index through the crud.

Parameters

space_name¶ (str) – The name of the target space.
index_name¶ (str) – The name of the index.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_min(space_name: str, index_name: str, opts: dict = {}) → CrudResult¶

Gets rows with minimum value in the specified index through the crud.

Parameters

space_name¶ (str) – The name of the target space.
index_name¶ (str) – The name of the index.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_replace(space_name: str, values: Union[tuple, list], opts: dict = {}) → CrudResult¶

Replaces row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_replace_many(space_name: str, values: Union[tuple, list], opts: dict = {}) → CrudResult¶

Replaces batch rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_replace_object(space_name: str, values: dict, opts: dict = {}) → CrudResult¶

Replaces object row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (dict) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_replace_object_many(space_name: str, values: Union[tuple, list], opts: dict = {}) → CrudResult¶

Replaces batch object rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_select(space_name: str, conditions: list = [], opts: dict = {}) → CrudResult¶

Selects rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
conditions¶ (list, optional) – The select conditions for the crud module.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

CrudModuleError, :exc:`~tarantool.error.DatabaseError`select

crud_stats(space_name: Optional[str] = None) → CrudResult¶

Gets statistics from the crud.

Parameters: space_name¶ (str, optional) – The name of the target space.
Return type: CrudResult
Raise: DatabaseError

crud_storage_info(opts: dict = {}) → dict¶

Gets storages status through the crud.

Parameters: opts¶ (dict, optional) – The opts for the crud module.
Return type: dict
Raise: CrudModuleError, DatabaseError

crud_truncate(space_name: str, opts: dict = {}) → bool¶

Truncate rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
opts¶ (dict, optional) – The opts for the crud module.

Return type

bool

Raise

crud_unflatten_rows(rows: list, metadata: list) → list¶

Makes rows unflatten through the crud.

Parameters

rows¶ (list) – The rows to unflatten.
metadata¶ (list) – The metadata to unflatten.

Return type

list

crud_update(space_name: str, key: int, operations: list = [], opts: dict = {}) → CrudResult¶

Updates row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
key¶ (int) – The primary key value.
operations¶ (list, optional) – The update operations for the crud module.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_upsert(space_name: str, values: Union[tuple, list], operations: list = [], opts: dict = {}) → CrudResult¶

Upserts row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (tuple or list) – Tuple to be inserted.
operations¶ (list, optional) – The update operations for the crud module.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_upsert_many(space_name: str, values_operation: Union[tuple, list], opts: dict = {}) → CrudResult¶

Upserts batch rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values_operation¶ (tuple or list) – The data with update operations.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_upsert_object(space_name: str, values: dict, operations: list = [], opts: dict = {}) → CrudResult¶

Upserts object row through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values¶ (dict) – Tuple to be inserted.
operations¶ (list, optional) – The update operations for the crud module.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

crud_upsert_object_many(space_name: str, values_operation: Union[tuple, list], opts: dict = {}) → CrudResult¶

Upserts batch object rows through the crud.

Parameters

space_name¶ (str) – The name of the target space.
values_operation¶ (tuple or list) – The data with update operations.
opts¶ (dict, optional) – The opts for the crud module.

Return type

Raise

delete(space_name, key, *, index=0, on_push=None, on_push_ctx=None)¶

Execute a DELETE request: delete a tuple in the space.

Parameters

space_name¶ (str or int) – Space name or space id.
key¶ – Key of a tuple to be deleted.
index¶ (str or int, optional) – Index name or index id. If you’re using a secondary index, it must be unique. Defaults to primary index.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError, NotSupportedError

eval(expr, *args, on_push=None, on_push_ctx=None)¶

Execute an EVAL request: evaluate a Lua expression.

Parameters

expr¶ (str) – Lua expression.
args¶ (tuple) – Lua expression arguments.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError

execute(query, params=None)¶

Execute an SQL request: see documentation for syntax reference.

The Tarantool binary protocol for SQL requests supports “qmark” and “named” param styles. A sequence of values can be used for “qmark” style. A mapping is used for “named” param style without the leading colon in the keys.

Example for “qmark” arguments:

args = ['email@example.com']
c.execute('select * from "users" where "email"=?', args)

Example for “named” arguments:

args = {'email': 'email@example.com'}
c.execute('select * from "users" where "email"=:email', args)

Parameters

query¶ (str) – SQL query.
params¶ (dict or list or None, optional) – SQL query bind values.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError

flush_schema()¶

Reload space and index schema.

Raise: SchemaError, DatabaseError

insert(space_name, values, on_push=None, on_push_ctx=None)¶

Execute an INSERT request: insert a tuple to the space. Throws an error if there is already a tuple with the same primary key.

Parameters

space_name¶ (str or int) – Space name or space id.
values¶ (tuple or list) – Record to be inserted.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError, NotSupportedError

is_closed()¶

Returns True if connection is closed. False otherwise.

Return type: bool

join(server_uuid)¶

Execute a JOIN request: join a replicaset.

Parameters: server_uuid¶ (str) – UUID of connector “server”.
Raise: AssertionError, DatabaseError, SchemaError, NetworkError, SslError

ping(notime=False)¶

Execute a PING request: send an empty request and receive an empty response from the server.

Parameters: notime¶ (bool, optional) – If False, returns response time. Otherwise, it returns 'Success'.
Returns: Response time or 'Success'.
Return type: float or str
Raise: AssertionError, DatabaseError, SchemaError, NetworkError, SslError

replace(space_name, values, on_push=None, on_push_ctx=None)¶

Execute a REPLACE request: replace a tuple in the space. Doesn’t throw an error if there is no tuple with the specified primary key.

Parameters

space_name¶ (str or int) – Space name or space id.
values¶ (tuple or list) – Tuple to be replaced.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError, NotSupportedError

select(space_name, key=None, *, offset=0, limit=4294967295, index=0, iterator=None, on_push=None, on_push_ctx=None)¶

Execute a SELECT request: select a tuple from the space.

Parameters

space_name¶ (str or int) – Space name or space id.
key¶ (optional) – Key of a tuple to be selected.
offset¶ (int, optional) – Number of tuples to skip.
limit¶ (str or int, optional) – Maximum number of tuples to select.
index¶ – Index name or index id to select. Defaults to primary index.

iterator¶ –

Index iterator type.

Iterator types for TREE indexes:

Iterator type

Arguments

Description

'EQ'

search value

The comparison operator is ‘==’ (equal to). If an index key is equal to a search value, it matches. Tuples are returned in ascending order by index key. This is the default.

'REQ'

search value

Matching is the same as for 'EQ'. Tuples are returned in descending order by index key.

'GT'

search value

The comparison operator is ‘>’ (greater than). If an index key is greater than a search value, it matches. Tuples are returned in ascending order by index key.

'GE'

search value

The comparison operator is ‘>=’ (greater than or equal to). If an index key is greater than or equal to a search value, it matches. Tuples are returned in ascending order by index key.

'ALL'

search value

Same as 'GE'

'LT'

search value

The comparison operator is ‘<’ (less than). If an index key is less than a search value, it matches. Tuples are returned in descending order by index key.

'LE'

search value

The comparison operator is ‘<=’ (less than or equal to). If an index key is less than or equal to a search value, it matches. Tuples are returned in descending order by index key.

Iterator types for HASH indexes:

Type

Arguments

Description

'ALL'

none

All index keys match. Tuples are returned in ascending order by hash of index key, which will appear to be random.

'EQ'

search value

The comparison operator is ‘==’ (equal to). If an index key is equal to a search value, it matches. The number of returned tuples will be 0 or 1. This is the default.

'GT'

search value

The comparison operator is ‘>’ (greater than). If a hash of an index key is greater than a hash of a search value, it matches. Tuples are returned in ascending order by hash of index key, which will appear to be random. Provided that the space is not being updated, one can retrieve all the tuples in a space, N tuples at a time, by using iterator='GT',limit=N in each search, and using the last returned value from the previous result as the start search value for the next search.

Iterator types for BITSET indexes:

Type

Arguments

Description

'ALL'

none

All index keys match. Tuples are returned in their order within the space.

'EQ'

bitset value

If an index key is equal to a bitset value, it matches. Tuples are returned in their order within the space. This is the default.

'BITS_ALL_SET'

bitset value

If all of the bits which are 1 in the bitset value are 1 in the index key, it matches. Tuples are returned in their order within the space.

'BITS_ANY_SET'

bitset value

If any of the bits which are 1 in the bitset value are 1 in the index key, it matches. Tuples are returned in their order within the space.

'BITS_ALL_NOT_SET'

bitset value

If all of the bits which are 1 in the bitset value are 0 in the index key, it matches. Tuples are returned in their order within the space.

on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError, NotSupportedError

space(space_name)¶

Create a Space instance for a particular space.

Parameters: space_name¶ (str or int) – Space name or space id.
Return type: Space
Raise: SchemaError

subscribe(cluster_uuid, server_uuid, vclock=None)¶

Execute a SUBSCRIBE request: subscribe to a replicaset updates. Connection is closed after subscribing.

Parameters

cluster_uuid¶ (str) – UUID of replicaset cluster.
server_uuid¶ (str) – UUID of connector “server”.
vclock¶ (dict or None, optional) – Connector “server” vclock.

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError

update(space_name, key, op_list, *, index=0, on_push=None, on_push_ctx=None)¶

Execute an UPDATE request: update a tuple in the space.

Parameters

space_name¶ (str or int) – Space name or space id.
key¶ – Key of a tuple to be updated.
op_list¶ (tuple or list) –
The list of operations to update individual fields. Each operation is a tuple of three (or more) values: (operator, field_identifier, value).

Possible operators are:
- '+' for addition. values must be numeric
- '-' for subtraction. values must be numeric
- '&' for bitwise AND. values must be unsigned numeric
- '|' for bitwise OR. values must be unsigned numeric
- '^' for bitwise XOR. values must be unsigned numeric
- ':' for string splice. you must provide offset, count, and value for this operation
- '!' for insertion. provide any element to insert)
- '=' for assignment. (provide any element to assign)
- '#' for deletion. provide count of fields to delete)
Possible field_identifiers are:
- Positive field number. The first field is 1, the second field is 2, and so on.
- Negative field number. The last field is -1, the second-last field is -2, and so on. In other words: (#tuple + negative field number + 1).
- Name. If the space was formatted with space_object:format(), then this can be a string for the field name (Since Tarantool 2.3.1).
Operation examples:
```
# 'ADD' 55 to the second field
# Assign 'x' to the third field
[('+', 2, 55), ('=', 3, 'x')]
# 'OR' the third field with '1'
# Cut three symbols, starting from the second,
# and replace them with '!!'
# Insert 'hello, world' field before the fifth element of the tuple
[('|', 3, 1), (':', 2, 2, 3, '!!'), ('!', 5, 'hello, world')]
# Delete two fields, starting with the second field
[('#', 2, 2)]
```
index¶ (str or int, optional) – Index name or index id. If you’re using a secondary index, it must be unique. Defaults to primary index.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type

Raise

AssertionError, DatabaseError, SchemaError, NetworkError, SslError, NotSupportedError

upsert(space_name, tuple_value, op_list, *, index=0, on_push=None, on_push_ctx=None)¶

Execute an UPSERT request: upsert a tuple to the space.

If an existing tuple matches the key fields of tuple_value, then the request has the same effect as UPDATE and the [(field_1, symbol_1, arg_1), ...] parameter is used.

If there is no tuple matching the key fields of tuple_value, then the request has the same effect as INSERT and the tuple_value parameter is used. However, unlike insert or update, upsert will neither read the tuple nor perform error checks before returning – this is a design feature which enhances throughput but requires more caution on the part of the user.

Parameters

space_name¶ (str or int) – Space name or space id.
tuple_value¶ (tuple or list) – Tuple to be upserted.
op_list¶ (tuple or list) – Refer to update() op_list.
index¶ (str or int, optional) – Index name or index id. If you’re using a secondary index, it must be unique. Defaults to primary index.
on_push¶ (function, optional) – Сallback for processing out-of-band messages.
on_push_ctx¶ (optional) – Сontext for working with on_push callback.

Return type