# Welcome to clickhouse-driver

Release 0.2.5.

Welcome to clickhouse-driver’s documentation. Get started with Installation and then get an overview with the Quickstart where common queries are described.

## User’s Guide

This part of the documentation focuses on step-by-step instructions for development with clickhouse-driver.

Clickhouse-driver is designed to communicate with ClickHouse server from Python over native protocol.

ClickHouse server provides two protocols for communication:

- HTTP protocol (port 8123 by default);

- Native (TCP) protocol (port 9000 by default).

Each protocol has own advantages and disadvantages. Here we focus on advantages of native protocol:

- Native protocol is more configurable by various settings.

- Binary data transfer is more compact than text data.

- Building python types from binary data is more effective than from text data.

- LZ4 compression is faster than gzip. Gzip compression is used in HTTP protocol.

- Query profile info is available over native protocol. We can read rows before limit metric for example.

Once again: clickhouse-driver uses native protocol (port 9000).

There is an asynchronous wrapper for clickhouse-driver: aioch. It’s available here.

- Installation
  - Python Version
  - Build Dependencies
  - Dependencies
  - Installation from PyPI
  - NumPy support
  - Installation from github
- Quickstart
  - Selecting data
  - Selecting data with progress statistics
  - Streaming results
  - Inserting data
  - DDL
  - Async and multithreading
- Features
  - External data for query processing
  - Settings
  - Compression
  - Secure connection
  - Specifying query id
  - Retrieving results in columnar form
  - Data types checking on INSERT
  - Query execution statistics
  - Receiving server logs
  - Multiple hosts
  - Python DB API 2.0
  - NumPy/Pandas support
  - Automatic disposal
- Supported types
  - [U]Int8/16/32/64/128/256
  - Float32/64
  - Date/Date32
  - DateTime(‘timezone’)/DateTime64(‘timezone’)
  - String/FixedString(N)
  - Enum8/16
  - Array(T)
  - Nullable(T)
  - Bool
  - UUID
  - Decimal
  - IPv4/IPv6
  - LowCardinality(T)
  - SimpleAggregateFunction(F, T)
  - Tuple(T1, T2, …)
  - Nested(flatten_nested=1, default)
  - Nested(flatten_nested=0)
  - Map(key, value)
  - Geo
- Performance
  - Test data
  - Required packages
  - Versions
  - Benchmarking
  - Results
  - Conclusion
- Miscellaneous
  - Client configuring from URL
  - Inserting data from CSV file
  - Adding missed settings
  - Inserting NULL into NOT NULL columns
- Unsupported server versions

## API Reference

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

- API
  - Client
  - Connection
  - QueryResult
  - ProgressQueryResult
  - IterQueryResult
- DB API 2.0
  - `DataError`
  - `DatabaseError`
  - `Error`
  - `IntegrityError`
  - `InterfaceError`
  - `InternalError`
  - `NotSupportedError`
  - `OperationalError`
  - `ProgrammingError`
  - `Warning`
  - `connect()`
  - Connection
  - Cursor
  - Extras

## Additional Notes

Legal information, changelog and contributing are here for the interested.

- Development
  - Test configuration
  - Running tests locally
  - GitHub Actions in forked repository
- Changelog
- License
- How to Contribute