ClickHouse Connect driver API

# Using tuple parameters
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)
```

#### Query with server-side parameters[​](#query-with-server-side-parameters "Direct link to Query with server-side parameters")

```
import clickhouse_connect

client = clickhouse_connect.get_client()

# Server-side binding (more secure, better performance for SELECT queries)
query = "SELECT * FROM system.tables WHERE database = {db:String} AND name = {tbl:String}"
parameters = {"db": "system", "tbl": "query_log"}

result = client.query(query, parameters=parameters)
```

#### Query with settings[​](#query-with-settings "Direct link to Query with settings")

```
import clickhouse_connect

client = clickhouse_connect.get_client()

# Pass ClickHouse settings with the query
result = client.query(
    "SELECT sum(number) FROM numbers(1000000)",
    settings={
        "max_block_size": 100000,
        "max_execution_time": 30
    }
)
```

### The `QueryResult` object[​](#the-queryresult-object "Direct link to the-queryresult-object")

The base `query` method returns a `QueryResult` object with the following public properties:

- `result_rows` -- A matrix of the data returned in the form of a Sequence of rows, with each row element being a sequence of column values.
- `result_columns` -- A matrix of the data returned in the form of a Sequence of columns, with each column element being a sequence of the row values for that column
- `column_names` -- A tuple of strings representing the column names in the `result_set`
- `column_types` -- A tuple of ClickHouseType instances representing the ClickHouse data type for each column in the `result_columns`
- `query_id` -- The ClickHouse query\_id (useful for examining the query in the `system.query_log` table)
- `summary` -- Any data returned by the `X-ClickHouse-Summary` HTTP response header
- `first_item` -- A convenience property for retrieving the first row of the response as a dictionary (keys are column names)
- `first_row` -- A convenience property to return the first row of the result
- `column_block_stream` -- A generator of query results in column oriented format. This property shouldn't be referenced directly (see below).
- `row_block_stream` -- A generator of query results in row oriented format. This property shouldn't be referenced directly (see below).
- `rows_stream` -- A generator of query results that yields a single row per invocation. This property shouldn't be referenced directly (see below).
- `summary` -- As described under the `command` method, a dictionary of summary information returned by ClickHouse

The `*_stream` properties return a Python Context that can be used as an iterator for the returned data. They should only be accessed indirectly using the Client `*_stream` methods.

The complete details of streaming query results (using StreamContext objects) are outlined in [Advanced Queries (Streaming Queries)](/docs/integrations/language-clients/python/advanced-querying#streaming-queries).

## Consuming query results with NumPy, Pandas or Arrow[​](#consuming-query-results-with-numpy-pandas-or-arrow "Direct link to Consuming query results with NumPy, Pandas or Arrow")

ClickHouse Connect provides specialized query methods for NumPy, Pandas, and Arrow data formats. For detailed information on using these methods, including examples, streaming capabilities, and advanced type handling, see [Advanced Querying (NumPy, Pandas and Arrow Queries)](/docs/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries).

## 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: