ClickHouse Connect driver API

## Client streaming query methods[​](#client-streaming-query-methods "Direct link to Client streaming query methods")

For streaming large result sets, ClickHouse Connect provides multiple streaming methods. See [Advanced Queries (Streaming Queries)](/docs/integrations/language-clients/python/advanced-querying#streaming-queries) for details and examples.

## Client `insert` Method[​](#client-insert-method "Direct link to client-insert-method")

For the common use case of inserting multiple records into ClickHouse, there is the `Client.insert` method. It takes the following parameters:

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Parameter Type Default Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | table str *Required* The ClickHouse table to insert into. The full table name (including database) is permitted.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | data Sequence of Sequences *Required* The matrix of data to insert, either a Sequence of rows, each of which is a sequence of column values, or a Sequence of columns, each of which is a sequence of row values.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | column\_names Sequence of str, or str '\*' A list of column\_names for the data matrix. If '\*' is used instead, ClickHouse Connect will execute a "pre-query" to retrieve all of the column names for the table.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | database str '' The target database of the insert. If not specified, the database for the client will be assumed.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | column\_types Sequence of ClickHouseType *None* A list of ClickHouseType instances. If neither column\_types or column\_type\_names is specified, ClickHouse Connect will execute a "pre-query" to retrieve all the column types for the table.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | column\_type\_names Sequence of ClickHouse type names *None* A list of ClickHouse datatype names. If neither column\_types or column\_type\_names is specified, ClickHouse Connect will execute a "pre-query" to retrieve all the column types for the table.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | column\_oriented bool False If True, the `data` argument is assumed to be a Sequence of columns (and no "pivot" will be necessary to insert the data). Otherwise `data` is interpreted as a Sequence of rows.| settings dict *None* See [settings description](#settings-argument).| context InsertContext *None* A reusable InsertContext object can be used to encapsulate the above method arguments. See [Advanced Inserts (InsertContexts)](/docs/integrations/language-clients/python/advanced-inserting#insertcontexts)| transport\_settings dict *None* Optional dictionary of HTTP headers to include with this request. Each key-value pair is added as an HTTP header (e.g., `{'X-Custom-Header': 'value'}`). Useful for proxy authentication, request tracing, or passing headers required by intermediate infrastructure. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

This method returns a "query summary" dictionary as described under the "command" method. An exception will be raised if the insert fails for any reason.

For specialized insert methods that work with Pandas DataFrames, PyArrow Tables, and Arrow-backed DataFrames, see [Advanced Inserting (Specialized Insert Methods)](/docs/integrations/language-clients/python/advanced-inserting#specialized-insert-methods).

Note

A NumPy array is a valid Sequence of Sequences and can be used as the `data` argument to the main `insert` method, so a specialized method isn't required.

### Examples[​](#examples "Direct link to Examples")

The examples below assume an existing table `users` with schema `(id UInt32, name String, age UInt8)`.

#### Basic row-oriented insert[​](#basic-row-oriented-insert "Direct link to Basic row-oriented insert")

```
import clickhouse_connect

client = clickhouse_connect.get_client()

# Row-oriented data: each inner list is a row
data = [
    [1, "Alice", 25],
    [2, "Bob", 30],
    [3, "Joe", 28],
]

client.insert("users", data, column_names=["id", "name", "age"])
```

#### Column-oriented insert[​](#column-oriented-insert "Direct link to Column-oriented insert")

```
import clickhouse_connect

client = clickhouse_connect.get_client()

# Column-oriented data: each inner list is a column
data = [
    [1, 2, 3],  # id column
    ["Alice", "Bob", "Joe"],  # name column
    [25, 30, 28],  # age column
]

client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)
```

#### Insert with explicit column types[​](#insert-with-explicit-column-types "Direct link to Insert with explicit column types")

```
import clickhouse_connect

client = clickhouse_connect.get_client()

# Useful when you want to avoid a DESCRIBE query to the server
data = [
    [1, "Alice", 25],
    [2, "Bob", 30],
    [3, "Joe", 28],
]

client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    column_type_names=["UInt32", "String", "UInt8"],
)
```

#### Insert into specific database[​](#insert-into-specific-database "Direct link to Insert into specific database")

```
import clickhouse_connect

client = clickhouse_connect.get_client()

data = [
    [1, "Alice", 25],
    [2, "Bob", 30],
]

# Insert into a table in a specific database
client.insert(
    "users",
    data,
    column_names=["id", "name", "age"],
    database="production",
)
```

## File Inserts[​](#file-inserts "Direct link to File Inserts")

For inserting data directly from files into ClickHouse tables, see [Advanced Inserting (File Inserts)](/docs/integrations/language-clients/python/advanced-inserting#file-inserts).

## Raw API[​](#raw-api "Direct link to Raw API")

For advanced use cases requiring direct access to ClickHouse HTTP interfaces without type transformations, see [Advanced Usage (Raw API)](/docs/integrations/language-clients/python/advanced-usage#raw-api).

## Utility classes and functions[​](#utility-classes-and-functions "Direct link to Utility classes and functions")