}` 형식의 표현식이 감지되면 이 모드를 사용합니다. 값은 Python 딕셔너리로 전달하십시오.
널 허용 값에는 Python `None`을 사용하십시오. 중첩된 `None` 값은 `Array` 및 `Tuple` 매개변수 내부와 `dict_parameter_format`이 `"map"`으로 설정된 경우 `Map` 리터럴 내부에서 지원됩니다.
* Python 딕셔너리, DateTime 값, 문자열 값을 사용하는 서버 측 바인딩
```python theme={null}
import datetime
my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)
parameters = {
"table": "my_table",
"v1": my_date,
"v2": "a string with a single quote'",
}
client.query(
"SELECT * FROM {table:Identifier} "
"WHERE date >= {v1:DateTime} AND string ILIKE {v2:String}",
parameters=parameters,
)
```
이는 다음과 같습니다:
```sql theme={null}
SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
AND string ILIKE 'a string with a single quote\''
```
Server-side binding은 `SELECT` 쿼리에서 지원됩니다. `ALTER`, `DELETE`, `INSERT` 또는 기타 문 유형에서는 지원되지 않습니다.
#### 클라이언트 측 바인딩
ClickHouse Connect는 클라이언트 측 매개변수 바인딩도 지원하며, 이를 통해 템플릿 기반 SQL 쿼리를 더 유연하게 생성할 수 있습니다. 클라이언트 측 바인딩에서는 `parameters` 인수가 딕셔너리 또는 시퀀스여야 합니다. 클라이언트 측 바인딩은 매개변수 치환을 위해 Python의 ["printf" 스타일](https://docs.python.org/3/library/stdtypes.html#old-string-formatting) 문자열 포맷팅을 사용합니다.
서버 측 바인딩과 달리 클라이언트 측 바인딩은 데이터베이스, 테이블, 컬럼 이름과 같은 데이터베이스 식별자에는 사용할 수 없습니다. Python 스타일 포맷팅은 서로 다른 문자열 타입을 구분하지 못하며, 이러한 값은 서로 다른 방식으로 포맷팅해야 하기 때문입니다(데이터베이스 식별자에는 backticks 또는 큰따옴표를 사용하고, 데이터 값에는 작은따옴표를 사용).
* Python 딕셔너리, DateTime 값, 문자열 이스케이프를 사용하는 예시
```python theme={null}
import datetime
my_date = datetime.datetime(2022, 10, 1, 15, 20, 5)
parameters = {"v1": my_date, "v2": "a string with a single quote'"}
client.query(
"SELECT * FROM my_table "
"WHERE date >= %(v1)s AND string ILIKE %(v2)s",
parameters=parameters,
)
```
그러면 서버에서 다음 쿼리가 생성됩니다:
```sql theme={null}
SELECT *
FROM my_table
WHERE date >= '2022-10-01 15:20:05'
AND string ILIKE 'a string with a single quote\''
```
* Python 시퀀스(Tuple), Float64, IPv4Address 사용 예시
```python theme={null}
import ipaddress
parameters = (35200.44, ipaddress.IPv4Address(0x443d04fe))
client.query(
"SELECT * FROM some_table WHERE metric >= %s AND ip_address = %s",
parameters=parameters,
)
```
그러면 서버에서 다음 쿼리가 생성됩니다:
```sql theme={null}
SELECT *
FROM some_table
WHERE metric >= 35200.44
AND ip_address = '68.61.4.254'
```
Datetime 바인딩은 naive 값을 wall time으로 처리합니다. 클라이언트는 naive `datetime`을 그대로 포맷합니다. ClickHouse는 `{dt:DateTime('Europe/Berlin')}`와 같은 서버 측 플레이스홀더에 선언된 시간대를 사용해 이를 해석하고, 없으면 설정된 `session_timezone`을 사용하며, 그마저 없으면 서버 시간대를 사용합니다. 시간대 인식 `datetime`은 플레이스홀더에 시간대가 선언되어 있으면 해당 시간대로 변환되고, 그렇지 않으면 연결 시 보고된 서버 시간대로 변환됩니다. `session_timezone` 설정이 보고된 서버 시간대와 다르면, 시간대 인식 값에서 의도한 시점을 유지하도록 플레이스홀더에 시간대를 선언하십시오.
이전 호스트 로컬 변환과의 임시 호환성을 위해 매개변수를 바인딩하기 전에 `common.set_setting("naive_datetime_binding", "legacy")`를 설정하십시오. 시점을 보존하려면 `datetime` 값을 매개변수로 전달하기 전에 의도한 `tzinfo`를 지정하십시오. `client.insert`를 통한 삽입은 기본적으로 naive `datetime` 값을 프로세스 로컬 시간대로 해석합니다. 컬럼 시간대의 wall time으로 해석하려면 전역 `naive_datetime_insert` 설정을 `"server"`로 지정하십시오. 컬럼에 시간대가 없으면 서버 시간대를 사용합니다. [시간대 정보가 없는 datetime 객체](/ko/integrations/language-clients/python/advanced-inserting#timezone-naive-datetime-objects)를 참조하십시오.
서버 측 `{value:DateTime64(precision)}` 플레이스홀더의 경우 선언된 유형이 `Array` 및 `Tuple` 힌트 내부를 포함해 초 미만 정밀도를 자동으로 유지합니다.
클라이언트 측 `%s` 바인딩에는 선언된 유형이 없습니다. 초 미만 정밀도로 렌더링해야 하는 경우 `datetime`을 `DT64Param`으로 감싸십시오:
```python theme={null}
from datetime import datetime
from clickhouse_connect.driver.binding import DT64Param
query = "SELECT toDateTime64(%s, 6)"
parameters = [DT64Param(datetime.now())]
client.query(query, parameters=parameters)
```
이전 버전과의 호환성을 위해, 딕셔너리 매개변수 이름이 `_64`로 끝나는 경우에도 쿼리에 정확히 그 접미사가 붙은 이름이 없으면 DateTime64 포맷팅을 요청합니다.
`datetime.time` 또는 `datetime.timedelta` 매개변수는 두 바인딩 스타일 모두에서, 그리고 `Array` 및 `Tuple` 값 내부에서 ClickHouse `Time` 및 `Time64` 컬럼용 `[-]HH:MM:SS[.ffffff]` 리터럴로 포맷됩니다. 클라이언트가 따옴표를 추가하므로 쿼리에서 플레이스홀더를 따옴표로 묶지 마십시오. `timedelta`는 음수일 수 있으며 24시간을 초과할 수 있습니다. pandas `Timedelta`는 나노초를 유지하며 `Time64(9)`에 대해 9자리 소수 부분으로 포맷됩니다. ClickHouse `Time`에는 시간대가 없으므로 시간대 인식 `time`의 시간대 정보는 무시됩니다.
### 설정 인수
주요 ClickHouse Connect Client의 "insert" 및 "select" 메서드는 모두 포함된 SQL 문에 대해 ClickHouse 서버 [사용자 설정](/ko/reference/settings/session-settings)을 전달할 수 있도록 선택적 `settings` 키워드 인수를 지원합니다. `settings` 인수는 딕셔너리여야 합니다. 각 항목은 ClickHouse 설정 이름과 해당 값으로 이루어져야 합니다. 값은 서버로 쿼리 매개변수로 전송될 때 문자열로 변환된다는 점에 유의하십시오.
클라이언트 수준 설정과 마찬가지로, ClickHouse Connect는 서버가 *readonly*=*1*로 표시한 설정을 관련 로그 메시지와 함께 모두 제외합니다. ClickHouse HTTP 인터페이스를 통한 쿼리에만 적용되는 설정은 항상 유효합니다. 이러한 설정은 `get_client` [API](#settings-argument)에서 설명합니다.
ClickHouse 설정 사용 예시:
```python theme={null}
settings = {
"merge_tree_min_rows_for_concurrent_read": 65535,
"session_id": "session_1234",
"use_skip_indexes": False,
}
client.query(
"SELECT event_type, sum(timeout) "
"FROM event_errors WHERE event_time > '2022-08-01'",
settings=settings,
)
```
## Client `command` 메서드
표 형식의 데이터셋을 반환하지 않는 SQL 문이나, 단일 원시 값 또는 단일 행을 반환하는 쿼리에는 `Client.command`를 사용합니다. 응답에 따라 문자열, 정수, 문자열 시퀀스 또는 `QuerySummary`를 반환합니다. 빈 결과 집합을 생성하는 읽기 작업은 빈 문자열을 반환합니다.
| 매개변수 | Type | Default | Description |
| ------------------- | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cmd | str | *Required* | 단일 값 또는 값으로 이루어진 단일 행을 반환하는 ClickHouse SQL 문입니다. |
| parameters | dict or sequence | *None* | [매개변수 설명](#parameters-argument)을 참조하십시오. |
| data | str or bytes | *None* | 명령과 함께 POST 본문으로 포함할 수 있는 선택적 데이터입니다. |
| settings | dict | *None* | [설정 설명](#settings-argument-1)을 참조하십시오. |
| use\_database | bool | True | 클라이언트 데이터베이스(클라이언트 생성 시 지정됨)를 사용합니다. False이면 명령은 연결된 사용자의 기본 ClickHouse 서버 데이터베이스를 사용합니다. |
| external\_data | ExternalData | *None* | 쿼리와 함께 사용할 파일 또는 바이너리 데이터가 포함된 `ExternalData` 객체입니다. [고급 쿼리(외부 데이터)](/ko/integrations/language-clients/python/advanced-querying#external-data)를 참조하십시오. |
| transport\_settings | dict | *None* | 이 요청에 포함할 HTTP 헤더의 선택적 딕셔너리입니다. 각 키-값 쌍은 HTTP 헤더로 추가됩니다(예: `{'X-Custom-Header': 'value'}`). 프록시 인증, 요청 추적 또는 중간 인프라에 필요한 헤더를 전달할 때 유용합니다. |
### 명령 예시
#### DDL 문
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Create a table. A successful DDL returns QuerySummary.
summary = client.command(
"CREATE TABLE test_command "
"(col_1 String, col_2 DateTime) "
"ENGINE MergeTree ORDER BY tuple()"
)
print(summary.query_id())
# Show table definition
result = client.command("SHOW CREATE TABLE test_command")
print(result)
# Output:
# CREATE TABLE default.test_command
# (
# `col_1` String,
# `col_2` DateTime
# )
# ENGINE = MergeTree
# ORDER BY tuple()
# Drop table
client.command("DROP TABLE test_command")
```
#### 단일 값을 반환하는 간단한 쿼리
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Single value result
count = client.command("SELECT count() FROM system.tables")
print(count)
# Server version
version = client.command("SELECT version()")
print(version)
```
#### 매개변수를 사용하는 명령
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# 클라이언트 측 매개변수 사용
table_name = "system"
result = client.command(
"SELECT count() FROM system.tables WHERE database = %(db)s",
parameters={"db": table_name}
)
# 서버 측 매개변수 사용
result = client.command(
"SELECT count() FROM system.tables WHERE database = {db:String}",
parameters={"db": "system"}
)
```
#### 설정이 포함된 명령
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# 특정 설정을 사용해 명령 실행
result = client.command(
"OPTIMIZE TABLE large_table FINAL",
settings={"optimize_throw_if_noop": 1}
)
```
## Client `query` 메서드
`Client.query`는 ClickHouse Native 형식의 테이블형 데이터셋을 가져와 `QueryResult`를 반환합니다. 결과 속성에 접근하는 시점에 전체 결과가 구체화됩니다. 메모리에 보관하지 않아야 하는 결과에는 스트리밍 메서드를 사용하세요.
| 매개변수 | 유형 | 기본값 | 설명 |
| -------------------- | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `query` | str | 필수 | 테이블형 결과를 반환하는 ClickHouse 쿼리이며, 대부분 `SELECT` 또는 `DESCRIBE`입니다. `context`에서 제공되는 경우 생략할 수 있습니다. |
| `parameters` | dict or sequence | `None` | [매개변수 인수](#parameters-argument)를 참조하세요. |
| `settings` | dict | `None` | [설정 인수](#settings-argument-1)를 참조하세요. |
| `query_formats` | dict | `None` | ClickHouse 유형별 읽기 포맷입니다. [Read formats](/ko/integrations/language-clients/python/advanced-querying#read-formats)을 참조하세요. |
| `column_formats` | dict | `None` | Nested type 포맷 매핑을 포함한 결과 컬럼별 읽기 포맷입니다. |
| `encoding` | str | `None` | String 컬럼 인코딩입니다. 기본값은 UTF-8입니다. |
| `use_none` | bool | `True` | SQL NULL에 대해 `None`을 반환합니다. `false`이면 해당 유형의 기본 NULL 값을 반환합니다. NumPy/Pandas 메서드는 성능 중심의 기본값을 선택합니다. |
| `column_oriented` | bool | `False` | 결과를 행이 아닌 컬럼 기준으로 반환합니다. |
| `use_numpy` | bool | `False` | 호환되는 결과 컬럼을 `QueryResult` 내부의 NumPy 배열로 읽어옵니다. 원하는 결과가 하나의 NumPy 매트릭스라면 `query_np`를 사용하는 것이 좋습니다. |
| `max_str_len` | int | `0` | `use_numpy`를 사용할 때 이 길이까지의 String 컬럼에 고정 폭 유니코드 dtype을 사용합니다. 0이면 object 배열을 사용합니다. |
| `context` | `QueryContext` | `None` | 재사용 가능한 쿼리 Context입니다. 메서드에 명시적으로 전달한 인수는 context 값을 재정의합니다. |
| `query_tz` | str or `tzinfo` | `None` | 모든 `DateTime` 및 `DateTime64` 결과 컬럼에 적용되는 시간대입니다. |
| `column_tzs` | dict | `None` | 컬럼별 시간대 매핑입니다. |
| `external_data` | `ExternalData` | `None` | 외부 파일 또는 바이너리 데이터입니다. [External data](/ko/integrations/language-clients/python/advanced-querying#external-data)를 참조하세요. |
| `transport_settings` | dict | `None` | 이 요청에 추가되는 HTTP 헤더입니다. |
| `tz_mode` | str | 클라이언트 기본값 | `"naive_utc"`, `"aware"`, 또는 `"schema"` 시간대 처리에 대한 쿼리별 재정의입니다. |
### 쿼리 예시
#### 기본 쿼리
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Simple SELECT query
result = client.query(
"SELECT number, toString(number) AS label FROM numbers(3)"
)
# Access results as rows
for row in result.result_rows:
print(row)
# Output:
# (0, '0')
# (1, '1')
# (2, '2')
# Access column names and types
print(result.column_names)
# Output: ('number', 'label')
print([col_type.name for col_type in result.column_types])
# Output: ['UInt64', 'String']
```
#### 쿼리 결과 조회하기
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
result = client.query("SELECT number, toString(number) AS str FROM system.numbers LIMIT 3")
# Row-oriented access (default)
print(result.result_rows)
# Output: [(0, '0'), (1, '1'), (2, '2')]
# Column-oriented access
print(result.result_columns)
# Output: [[0, 1, 2], ['0', '1', '2']]
# Named results (list of dictionaries)
for row_dict in result.named_results():
print(row_dict)
# Output:
# {'number': 0, 'str': '0'}
# {'number': 1, 'str': '1'}
# {'number': 2, 'str': '2'}
# First row as dictionary
print(result.first_item)
# Output: {'number': 0, 'str': '0'}
# First row as tuple
print(result.first_row)
# Output: (0, '0')
```
#### 클라이언트 측 매개변수를 사용한 쿼리
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# 딕셔너리 매개변수 사용 (printf 스타일)
query = "SELECT * FROM system.tables WHERE database = %(db)s AND name LIKE %(pattern)s"
parameters = {"db": "system", "pattern": "%query%"}
result = client.query(query, parameters=parameters)
# 튜플 매개변수 사용
query = "SELECT * FROM system.tables WHERE database = %s LIMIT %s"
parameters = ("system", 5)
result = client.query(query, parameters=parameters)
```
#### 서버 측 매개변수를 사용하는 쿼리
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# 서버 측 바인딩 (보안이 강화되고 SELECT 쿼리 성능이 향상됨)
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)
```
#### 설정을 지정한 쿼리
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# 쿼리와 함께 ClickHouse 설정을 지정합니다
result = client.query(
"SELECT sum(number) FROM numbers(1000000)",
settings={
"max_block_size": 100000,
"max_execution_time": 30
}
)
```
### `QueryResult` 객체
기본 `query` 메서드는 다음 공개 속성을 포함하는 `QueryResult` 객체를 반환합니다.
* `result_rows` -- 행 기준으로 구성된 결과 매트릭스입니다.
* `result_columns` -- 컬럼 기준으로 구성된 결과 매트릭스입니다.
* `result_set` -- 쿼리 방향에 따라 `result_rows` 또는 `result_columns`입니다.
* `column_names` -- 결과 컬럼명의 `Tuple`입니다.
* `column_types` -- `ClickHouseType` 객체의 `Tuple`입니다.
* `row_count` -- 구체화된 결과 행 수입니다.
* `query_id` -- 요청에 대해 보고되었거나 생성된 쿼리 ID입니다. 빈 문자열은 사용 가능한 값이 없었음을 의미합니다.
* `summary` -- `X-ClickHouse-Summary` 응답 헤더에서 디코딩된 딕셔너리입니다.
* `first_item` -- 딕셔너리 형식의 첫 번째 행이며, 결과가 비어 있으면 `None`입니다.
* `first_row` -- 시퀀스 형식의 첫 번째 행이며, 결과가 비어 있으면 `None`입니다.
* `column_block_stream`, `row_block_stream`, `rows_stream` -- 내부 스트림 컨텍스트입니다. 대신 해당 클라이언트의 스트리밍 메서드를 사용하십시오.
지원되는 `StreamContext` API는 [스트리밍 쿼리](/ko/integrations/language-clients/python/advanced-querying#streaming-queries)에서 확인하십시오.
## NumPy, Pandas 또는 Arrow로 쿼리 결과 처리하기
ClickHouse Connect는 NumPy, Pandas, Arrow 데이터 포맷용 전용 쿼리 메서드를 제공합니다. 예시, 스트리밍 지원, 고급 타입 처리 등 이러한 메서드의 사용법에 관한 자세한 내용은 [고급 쿼리(NumPy, Pandas 및 Arrow 쿼리)](/ko/integrations/language-clients/python/advanced-querying#numpy-pandas-and-arrow-queries)를 참조하십시오.
## 클라이언트 스트리밍 쿼리 메서드
대규모 결과 집합(result set)을 스트리밍하려면 ClickHouse Connect에서 여러 스트리밍 메서드를 제공합니다. 자세한 내용과 예시는 [고급 쿼리(Streaming Queries)](/ko/integrations/language-clients/python/advanced-querying#streaming-queries)를 참조하십시오.
## 클라이언트 `insert` 메서드
여러 레코드를 ClickHouse에 삽입하는 일반적인 경우에는 `Client.insert` 메서드를 사용합니다. 이 메서드는 다음 매개변수를 받습니다.
| Parameter | Type | Default | Description |
| -------------------- | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `table` | str | Required | 대상 테이블입니다. 데이터베이스를 포함한 이름도 사용할 수 있습니다. `context`에서 제공하는 경우 생략할 수 있습니다. |
| `data` | Sequence of Sequences | Required | 행 지향 또는 컬럼 지향 데이터 매트릭스입니다. 나중에 `InsertContext`를 통해 제공할 수도 있습니다. |
| `column_names` | str or Sequence\[str] | `"*"` | 순서가 지정된 컬럼입니다. `"*"`를 사용하면 삽입 가능한 모든 컬럼을 찾기 위해 메타데이터 쿼리를 실행합니다. |
| `database` | str or None | Client database | `table`에 데이터베이스가 지정되지 않은 경우의 대상 데이터베이스입니다. |
| `column_types` | Sequence\[`ClickHouseType`] | `None` | 명시적인 컬럼 타입입니다. 제공하면 메타데이터 쿼리를 실행하지 않아도 됩니다. |
| `column_type_names` | Sequence\[str] | `None` | 명시적인 ClickHouse 타입 이름입니다. `column_types` 대신 사용할 수 있습니다. |
| `column_oriented` | bool | `False` | `data`를 행이 아닌 컬럼으로 해석합니다. |
| `settings` | dict | `None` | [설정 인수](#settings-argument-1)를 참조하십시오. |
| `context` | `InsertContext` | `None` | 재사용 가능한 삽입 컨텍스트입니다. [InsertContexts](/ko/integrations/language-clients/python/advanced-inserting#insertcontexts)를 참조하십시오. |
| `transport_settings` | dict | `None` | 이 요청에 추가되는 HTTP 헤더입니다. |
이 메서드는 `QuerySummary`를 반환합니다. 이 객체의 `summary` 딕셔너리에는 서버가 보고한 값이 포함됩니다. `written_rows`는 편의 속성이며, `written_bytes()`와 `query_id()`는 해당 값을 반환합니다. 삽입이 실패하면 예외가 발생합니다.
Pandas DataFrame, PyArrow 테이블, Arrow 기반 DataFrame에서 작동하는 특수 삽입 메서드는 [고급 삽입(특수 삽입 메서드)](/ko/integrations/language-clients/python/advanced-inserting#specialized-insert-methods)를 참조하십시오.
NumPy 배열은 유효한 Sequence of Sequences이므로 기본 `insert` 메서드의 `data` 인수로 사용할 수 있으며, 별도의 특수 메서드는 필요하지 않습니다.
### 예시
아래 예시에서는 스키마(schema)가 `(id UInt32, name String, age UInt8)`인 기존 `users` 테이블(table)이 이미 있다고 가정합니다.
#### 기본적인 행 지향 삽입
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Row-oriented data: each inner list is a row
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
client.insert("users", data, column_names=["id", "name", "age"])
```
#### 컬럼 지향 방식 삽입
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Column-oriented data: each inner list is a column
data = [
[13, 79], # id column
["user_1", "user_2"], # name column
[25, 30], # age column
]
client.insert("users", data, column_names=["id", "name", "age"], column_oriented=True)
```
#### 명시적으로 컬럼 타입을 지정해 삽입
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
# Useful when you want to avoid a DESCRIBE query to the server
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
client.insert(
"users",
data,
column_names=["id", "name", "age"],
column_type_names=["UInt32", "String", "UInt8"],
)
```
#### 특정 데이터베이스에 삽입하기
```python theme={null}
import clickhouse_connect
client = clickhouse_connect.get_client()
data = [
[13, "user_1", 25],
[79, "user_2", 30],
]
# Insert into a table in a specific database
client.insert(
"users",
data,
column_names=["id", "name", "age"],
database="production",
)
```
## 파일 삽입
파일의 데이터를 ClickHouse 테이블에 직접 삽입하는 방법은 [고급 삽입(파일 삽입)](/ko/integrations/language-clients/python/advanced-inserting#file-inserts)을 참조하십시오.
## Raw API
유형 변환 없이 ClickHouse HTTP 인터페이스에 직접 액세스해야 하는 고급 사용 사례는 [고급 사용법(Raw API)](/ko/integrations/language-clients/python/advanced-usage#raw-api)을 참조하십시오.
## Python DB-API 2.0
`clickhouse_connect.dbapi` 모듈은 PEP 249의 연결 및 cursor 인터페이스를 구현합니다. 이 모듈은 API 수준 2.0, `threadsafety=2`, `paramstyle="pyformat"`를 선언합니다. 또한 PEP 249 유형 생성자인 `Date`, `Time`, `Timestamp`, `Binary`와 `DateFromTicks`, `TimeFromTicks`, `TimestampFromTicks` 함수를 제공합니다.
```python theme={null}
from clickhouse_connect import dbapi
connection = dbapi.connect(
host="localhost",
username="default",
password="password",
database="default",
)
cursor = connection.cursor()
try:
cursor.execute(
"SELECT name FROM system.tables "
"WHERE database = %(database)s ORDER BY name LIMIT 5",
{"database": "system"},
)
print(cursor.description)
print(cursor.fetchall())
finally:
cursor.close()
connection.close()
```
`Cursor.execute` 및 `Cursor.executemany`는 추가 `settings` 및 `query_formats` 키워드 인수를 받습니다. `settings`는 ClickHouse 설정을 전달합니다. `query_formats`는 SQL 문이 행을 반환할 때 `Client.query`와 동일한 매핑을 사용하여 ClickHouse 타입별 읽기 포맷을 적용합니다. `executemany`는 행 시퀀스가 구체화된 호환 가능한 `INSERT ... VALUES` SQL 문에 대해 드라이버의 네이티브 대량 삽입 경로를 사용합니다. `fetchone`, `fetchmany`, `fetchall`은 현재 구체화된 결과에서 데이터를 가져옵니다.
`Cursor.description`은 각 결과 컬럼 타입을 바탕으로 `null_ok`를 결정합니다. 널을 허용하지 않는 타입은 `False`를 보고하고, `Nullable` 래퍼, `Variant`, `Dynamic`을 포함한 널 허용 타입은 `True`를 보고합니다. `None`은 널 허용 여부를 알 수 없음을 의미합니다. 선행 주석을 무시하고 `SELECT` 또는 `WITH`로 시작하는 쿼리가 행이나 컬럼 메타데이터를 반환하지 않으면, cursor는 `description`을 채우기 위해 `LIMIT 0` 메타데이터 쿼리를 실행합니다. 해당 메타데이터 쿼리가 실패하면 `description`은 비어 있는 상태로 유지됩니다.
ClickHouse는 이 HTTP 인터페이스를 통해 전통적인 트랜잭션을 제공하지 않습니다. `Connection.commit()` 및 `Connection.rollback()`은 아무 작업도 수행하지 않습니다. 연결을 공유하는 경우에도 [session ID 동시성 규칙](/ko/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids)이 계속 적용됩니다.
## 유틸리티 클래스와 함수
다음 모듈은 클라이언트 애플리케이션에서 사용하는 추가 공개 도우미를 제공합니다.
설치된 패키지 버전은 문자열 `clickhouse_connect.__version__`으로 노출됩니다.
### 예외
DB-API 2.0 예외 계층을 포함한 사용자 정의 예외는 `clickhouse_connect.driver.exceptions`에 정의되어 있습니다. `DatabaseError`와 `OperationalError`는 ClickHouse 오류 코드가 담긴 숫자 `code` 속성과 `UNKNOWN_TABLE` 같은 기호 이름이 담긴 `name` 속성을 제공하므로, 애플리케이션은 메시지를 파싱하지 않고 `exc.code`를 기준으로 분기할 수 있습니다. `show_clickhouse_errors`가 비활성화되어 있어도 `code`는 설정되지만, `name`을 사용하려면 오류 세부 정보(`True` 또는 `"scrub"`)가 필요합니다. 전송 오류처럼 사용할 수 없는 경우에는 둘 다 `None`입니다. 최종 사용자에게 호스트 또는 서버 버전 정보 없이 SQL 오류를 표시해야 하는 경우 `show_clickhouse_errors="scrub"`를 사용하십시오. 이 설정은 스트림 도중 발생하는 `StreamFailureError` 메시지와 일반 전송 메시지도 제어합니다. 이 설정은 `str(exc)`에만 적용됩니다. 전송 오류는 여전히 `__cause__`로 연결되며, 트레이스백에는 원래 호스트, URL 또는 라이브러리 오류 텍스트가 포함될 수 있습니다.
### ClickHouse SQL 유틸리티
`clickhouse_connect.driver.binding` 모듈의 함수와 DT64Param 클래스는 ClickHouse SQL 쿼리를 올바르게 구성하고 이스케이프 처리하는 데 사용할 수 있습니다. 마찬가지로 `clickhouse_connect.driver.parser` 모듈의 함수는 ClickHouse 데이터 타입 이름을 파싱하는 데 사용할 수 있습니다.
## 멀티스레드, 멀티프로세스 및 비동기/이벤트 기반 사용 사례
멀티스레드, 멀티프로세스 및 비동기/이벤트 기반 애플리케이션에서 ClickHouse Connect를 사용하는 방법에 대한 자세한 내용은 [고급 사용법(멀티스레드, 멀티프로세스 및 비동기/이벤트 기반 사용 사례)](/ko/integrations/language-clients/python/advanced-usage#multithreaded-multiprocess-and-asyncevent-driven-use-cases)를 참조하십시오.
## AsyncClient
asyncio 환경에서 네이티브로 사용하는 방법은 [고급 사용법(AsyncClient)](/ko/integrations/language-clients/python/advanced-usage#asyncclient)를 참조하십시오.
## ClickHouse 세션 ID 관리
멀티스레드 또는 동시 처리 애플리케이션에서 ClickHouse 세션 ID를 관리하는 방법에 대한 자세한 내용은 [고급 사용법(ClickHouse 세션 ID 관리)](/ko/integrations/language-clients/python/advanced-usage#managing-clickhouse-session-ids)을 참조하십시오.
## HTTP 연결 풀 사용자 지정
대규모 멀티스레드 애플리케이션에서 HTTP 연결 풀을 사용자 지정하는 방법에 대한 자세한 내용은 [고급 사용법(HTTP 연결 풀 사용자 지정)](/ko/integrations/language-clients/python/advanced-usage#customizing-the-http-connection-pool)을 참조하십시오.