Description
The VoltDB Python client library is a native Python implementation of the VoltDB wire protocol. It provides the functionality of connecting to a VoltDB server, authenticating the client, and making procedure calls. The client supports Python 3.6 or later.
PLEASE NOTE
The VoltDB Python client library has for some time now been included in the repository for VoltDB itself, VoltDB/voltdb. The present repository, VoltDB/voltdb-client-python, has been updated to contain code that is identical to the library for VoltDB V11.0. However, VoltDB recommends that to ensure you have the latest client code going forward, you get it from VoltDB/voltdb.
The most recent VoltDB Python client library source code is at
https://github.com/VoltDB/voltdb/tree/master/lib/python
The core of the Python client library is the FastSerializer class. It manages the connection to the server and serializes/deserializes the VoltDB primitive types. There are higher level classes which wraps around the FastSerializer class to handle compound objects, namely procedure, response, table, and exception. VoltProcedure, VoltResponse, VoltTable, and VoltException classes handles them, respectively. Note that none of the classes in the Python client library is thread safe.
Each VoltDB primitive type is mapped to a Python primitive type. The following table shows the mapping.
+------------------+
| VoltDB | Python |
|---|---|
| NULL | None |
| TINYINT | integer |
| SMALLINT | integer |
| INTEGER | integer |
| BIGINT | integer |
| FLOAT | float |
| STRING | string |
| DECIMAL | decimal |
| +------------------+ |
Although Python does not distinguish between the different integer types, the size of the integer being serialized needs to fit the corresponding type.
The common work flow is to create a FastSerializer object and connect to the server. Then create a VoltProcedure object for each stored procedure you want to call, passing the FastSerializer object to it. For each call, you will get a VoltResponse object, which may or may not contain a list of VoltTable objects. In case of failure, a VoltException object may be included.
API
FastSerializer.VOLTTYPE_NULL FastSerializer.VOLTTYPE_TINYINT FastSerializer.VOLTTYPE_SMALLINT FastSerializer.VOLTTYPE_INTEGER FastSerializer.VOLTTYPE_BIGINT FastSerializer.VOLTTYPE_FLOAT FastSerializer.VOLTTYPE_STRING FastSerializer.VOLTTYPE_TIMESTAMP FastSerializer.VOLTTYPE_DECIMAL FastSerializer.VOLTTYPE_DECIMAL_STRING FastSerializer.VOLTTYPE_VOLTTABLE VoltDB types.
FastSerializer(host, port, username, password, dump_file) Create a connection to host (string) on port (integer). If username (string) and password (string) is given, authenticate the client using them. If dump_file (string) is given, all the data received from and sent to the server will be written into the file pointed to by dump_file.
FastSerializer.close() Closes the connection. No further use of the object is valid.
VoltProcedure(fser, name, paramtypes) Create a procedure object which can be used to call the stored procedure name (string) with parameters of types paramtypes (list). The parameter types are defined in the FastSerializer class as VoltDB types. For parameter of type array, you specify the type in the same way as primitive types. fser is the FastSerializer object with a valid connection to the server.
VoltProcedure.call(params, response, timeout) Make a stored procedure invocation with the parameters params (list). The parameters has to match the types defined in the VoltProcedure constructor. If a parameter is an array, pass it in as a list. If response (bool) is given and False, the invocation will return None. If timeout (float) is given, the invocation will wait for timeout seconds at most if the server does not respond. A socket.timeout exception will be raised if timeout seconds has elapsed. A successful invocation will return a VoltReponse object.
VoltResponse.status The status code (integer) for a stored procedure invocation. For a list of status code, please refer to the VoltDB documentation.
VoltResponse.statusString A human-friendly string of the meaning of the status code.
VoltResponse.roundtripTime The round-trip time (integer) of the invocation in milliseconds.
VoltResponse.exception The VoltException object in case of failure, may be None.
VoltResponse.tables A list of VoltTable objects as the result of the invocation. May be None.
VoltException.type The type of the VoltDB exception. Can be the following values, VOLTEXCEPTION_NONE, VOLTEXCEPTION_EEEXCEPTION, VOLTEXCEPTION_SQLEXCEPTION, VOLTEXCEPTION_CONSTRAINTFAILURE, VOLTEXCEPTION_GENERIC.
VoltException.message A string explaining the exception.
VoltTable.columns A list of VoltColumn objects, representing the columns in the table.
VoltTable.tuples A list of rows in the table. A row a list of values deserialized in Python types.
VoltColumn.type The type of the column. A list of types is defined in the FastSerializer class.
VoltColumn.name The name of the column as a string.
Example
The following example shows how to make a connection to a VoltDB server instance running on port 21212 on localhost, and make a single call to the stored procedure named "Select", which takes a single parameter of type string. Assume the server is not secure, so that it does not require authentication.
>>> client = FastSerializer("localhost", 21212)
>>> proc = VoltProcedure(client, "Select", [FastSerializer.VOLTTYPE_STRING])
>>> response = proc.call(["English"])
>>> client.close()
>>> print response
The output will be a human-readable form of the VoltResponse object.