DB API 2.0¶
This part of the documentation covers driver DB API.
-
clickhouse_driver.dbapi.
connect
(dsn=None, host=None, user='default', password='', port=9000, database='default', **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
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
Error
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
DataError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
DatabaseError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
ProgrammingError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
IntegrityError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
InterfaceError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
InternalError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
NotSupportedError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
exception
clickhouse_driver.dbapi.
OperationalError
¶ -
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
Connection¶
-
class
clickhouse_driver.dbapi.connection.
Connection
(dsn=None, host=None, user='default', password='', port=9000, database='default', **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, connection)¶ -
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
-