DB API 2.0

This part of the documentation covers driver DB API.

clickhouse_driver.dbapi.connect(dsn=None, user=None, password=None, host=None, port=None, database=None, **kwargs)

Create a new database connection.

The connection can be specified via DSN:

conn = connect("clickhouse://localhost/test?param1=value1&...")

or using database and credentials arguments:

conn = connect(database="test", user="default", password="default", host="localhost", **kwargs)

The basic connection parameters are:

  • host: host with running ClickHouse server.
  • port: port ClickHouse server is bound to.
  • database: database connect to.
  • user: database user.
  • password: user’s password.

See defaults in Connection constructor.

DSN or host is required.

Any other keyword parameter will be passed to the underlying Connection class.

Returns:a new connection.
exception clickhouse_driver.dbapi.Warning
exception clickhouse_driver.dbapi.Error
exception clickhouse_driver.dbapi.DataError
exception clickhouse_driver.dbapi.DatabaseError
exception clickhouse_driver.dbapi.ProgrammingError
exception clickhouse_driver.dbapi.IntegrityError
exception clickhouse_driver.dbapi.InterfaceError
exception clickhouse_driver.dbapi.InternalError
exception clickhouse_driver.dbapi.NotSupportedError
exception clickhouse_driver.dbapi.OperationalError

Connection

class clickhouse_driver.dbapi.connection.Connection(dsn=None, user=None, password=None, host=None, port=None, database=None, **kwargs)

Creates new Connection for accessing ClickHouse database.

Connection is just wrapper for handling multiple cursors (clients) and do not initiate actual connections to the ClickHouse server.

See parameters description in Connection.

close()

Close the connection now. The connection will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the connection. The same applies to all cursor objects trying to use the connection.

commit()

Do nothing since ClickHouse has no transactions.

cursor()
Returns:a new Cursor Object using the connection.
rollback()

Do nothing since ClickHouse has no transactions.

Cursor

class clickhouse_driver.dbapi.cursor.Cursor(client)
close()

Close the cursor now. The cursor will be unusable from this point forward; an Error (or subclass) exception will be raised if any operation is attempted with the cursor.

columns_with_types
Returns:list of column names with corresponding types of the last .execute*(). E.g. [(‘x’, ‘UInt64’)].
execute(operation, parameters=None)

Prepare and execute a database operation (query or command).

Parameters:
  • operation – query or command to execute.
  • parameters – sequence or mapping that will be bound to variables in the operation.
Returns:

None

executemany(operation, seq_of_parameters)

Prepare a database operation (query or command) and then execute it against all parameter sequences found in the sequence seq_of_parameters.

Parameters:
  • operation – query or command to execute.
  • seq_of_parameters – sequences or mappings for execution.
Returns:

None

fetchall()

Fetch all (remaining) rows of a query result, returning them as a sequence of sequences (e.g. a list of tuples).

Returns:list of fetched rows.
fetchmany(size=None)

Fetch the next set of rows of a query result, returning a sequence of sequences (e.g. a list of tuples). An empty sequence is returned when no more rows are available.

Parameters:size – amount of rows to return.
Returns:list of fetched rows or empty list.
fetchone()

Fetch the next row of a query result set, returning a single sequence, or None when no more data is available.

Returns:the next row of a query result set or None.
rowcount
Returns:the number of rows that the last .execute*() produced.
set_external_table(name, structure, data)

Adds external table to cursor context.

If the same table is specified more than once the last one is used.

Parameters:
  • name – name of external table
  • structure – list of tuples (name, type) that defines table structure. Example [(x, ‘Int32’)].
  • data – sequence of rows of tuples or dicts for transmission.
Returns:

None

set_query_id(query_id)

Specifies the query identifier for cursor.

Parameters:query_id – the query identifier.
Returns:None
set_settings(settings)

Specifies settings for cursor.

Parameters:settings – dictionary of query settings
Returns:None
set_stream_results(stream_results, max_row_buffer)

Toggles results streaming from server. Driver will consume block-by-block of max_row_buffer size and yield row-by-row from each block.

Parameters:
  • stream_results – enable or disable results streaming.
  • max_row_buffer – specifies the maximum number of rows to buffer at a time.
Returns:

None

set_types_check(types_check)

Toggles type checking for sequence of INSERT parameters. Disabled by default.

Parameters:types_check – new types check value.
Returns:None