> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ADBC 드라이버로 사용하는 chDB

> Arrow Database Connectivity(ADBC)를 통해 chDB를 사용하는 방법

export const ExperimentalBadge = () => {
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#experimental-features" className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            실험 기능
        </a>;
};

<ExperimentalBadge />

<Warning>
  ADBC 드라이버는 실험적 기능입니다. 동작 및 옵션은 릴리스마다 변경될 수 있습니다.
</Warning>

[ADBC](https://arrow.apache.org/adbc/)는 애플리케이션과 데이터베이스 간에 Arrow 데이터를 이동하기 위한 공급업체 중립적 API입니다. chDB ADBC 드라이버는 ADBC Driver Foundry를 통해 배포되며, 모든 ADBC 드라이버 관리자에서 로드할 수 있습니다.

결과는 행별 변환 없이 Arrow 레코드 배치 형태로 경계를 넘습니다. 애플리케이션은 Python 또는 ADBC 드라이버 관리자를 지원하는 다른 언어에서 동일한 드라이버를 사용할 수 있습니다.

<div id="installation">
  ## 설치
</div>

[`dbc`](https://docs.columnar.tech/dbc/)를 사용하여 ADBC Driver Foundry에서 드라이버를 설치합니다:

```bash theme={null}
dbc install chdb
```

chDB용으로 처음 게시된 `dbc` 패키지는 버전 26.7.0입니다. 사용 가능한 버전을 확인하려면 다음을 실행하십시오:

```bash theme={null}
dbc search -v chdb
```

설치된 드라이버는 ADBC 드라이버 관리자에서 `chdb`라는 이름으로 불러올 수 있습니다.

x86-64 및 arm64 아키텍처에서 Linux와 macOS를 지원합니다.

<div id="connecting-from-python">
  ## Python에서 연결하기
</div>

Python ADBC 드라이버 관리자를 설치합니다:

```bash theme={null}
pip install adbc-driver-manager pyarrow
```

그런 다음 이름을 지정해 `dbc`로 설치한 chDB 드라이버를 로드합니다:

```python theme={null}
from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(3)")
        print(cur.fetch_arrow_table())
```

| `uri`                   | 데이터베이스                      |
| ----------------------- | --------------------------- |
| `chdb://`               | 인메모리                        |
| `chdb:///absolute/path` | 지정된 디렉터리에 디스크 기반으로 영구 저장됩니다 |

<div id="connection-lifecycle">
  ## 연결 수명 주기
</div>

chDB는 연결이 열려 있는 동안 각 프로세스에서 하나의 내장 엔진을 실행합니다. 다음 규칙을 유의하십시오.

* 프로세스에서 동시에 열려 있는 모든 ADBC 연결은 동일한 스토리지 경로를 가리켜야 합니다.
* 동일한 경로에 여러 연결을 사용할 수 있으며, 서로 다른 스레드에서 동시에 사용하는 연결도 지원됩니다. 동시 쿼리를 실행할 때는 하나의 연결에서 여러 작업을 동시에 실행하지 말고 각 worker에 별도의 연결을 제공하십시오.
* 마지막 연결을 닫으면 내장 엔진이 종료됩니다. 이후 연결하면 다른 스토리지 경로로도 엔진을 다시 시작할 수 있지만, 반복적으로 종료하고 시작하면 시간과 메모리가 소모됩니다. 반복 작업 시에는 최소 하나의 연결을 열어 두십시오.
* 특정 온디스크 디렉터리는 한 번에 하나의 운영 체제 프로세스만 열 수 있습니다. 각 프로세스에 별도의 디렉터리를 할당하거나 인메모리 데이터베이스를 사용하십시오.

<div id="using-python-chdb-package">
  ### Python chDB 패키지에서 ADBC 사용하기
</div>

`dbc` 패키지는 독립형 네이티브 ADBC 드라이버를 설치합니다. 이 드라이버는 Python `chdb` 패키지가 로드하는 네이티브 라이브러리와 별개입니다.

하나의 Python 프로세스에서 `dbc`로 로드한 ADBC 연결과 일반 `chdb` 연결은 인메모리 테이블이나 엔진 상태를 공유하지 않습니다. 특정 데이터베이스 경로에는 한 번에 ADBC 드라이버 또는 Python `chdb` API 중 하나만 사용하고, 동일한 온디스크 경로에 둘 다 열어 두지 마십시오. 두 API 간에 데이터를 이동하려면 다른 쪽을 열기 전에 한쪽의 모든 연결을 닫거나 Arrow 또는 파일을 통해 데이터를 명시적으로 전달하십시오.

<div id="implemented-functionality">
  ## 구현된 기능
</div>

`Not yet`은 향후 추가될 수 있는 ADBC 드라이버 기능을 의미합니다. `Not applicable`은 현재 chDB 또는 ClickHouse 실행 모델에 해당하지 않는 기능을 의미합니다.

<div id="database">
  ### 데이터베이스
</div>

| 함수                                     | 상태  | 참고                             |
| -------------------------------------- | --- | ------------------------------ |
| `AdbcDatabaseNew` / `Init` / `Release` | 지원됨 |                                |
| `AdbcDatabaseSetOption`                | 지원됨 | `uri`, `path` 및 `chdb.*` 엔진 옵션 |

<div id="connection">
  ### 연결
</div>

| 함수                                       | 상태         | 참고                                                   |
| ---------------------------------------- | ---------- | ---------------------------------------------------- |
| `AdbcConnectionNew` / `Init` / `Release` | 지원됨        |                                                      |
| `AdbcConnectionGetInfo`                  | 지원됨        |                                                      |
| `AdbcConnectionGetObjects`               | 지원됨        | 모든 깊이                                                |
| `AdbcConnectionGetTableSchema`           | 지원됨        |                                                      |
| `AdbcConnectionGetTableTypes`            | 지원됨        |                                                      |
| `AdbcConnectionGetOption`                | 지원됨        | 현재 `db_schema`를 포함합니다                                |
| `AdbcConnectionSetOption`                | 부분 지원      | 자동 커밋은 활성화된 상태를 유지해야 하며, `db_schema` 변경은 지원되지 않습니다   |
| `AdbcConnectionCommit` / `Rollback`      | 해당 없음      | ClickHouse SQL 문은 자동 커밋되며, 커밋하거나 롤백할 일반적인 트랜잭션은 없습니다 |
| `AdbcConnectionGetStatistics`            | 아직 지원되지 않음 | 테이블 통계는 드라이버를 통해 제공되지 않습니다                           |
| `AdbcConnectionReadPartition`            | 해당 없음      | 드라이버는 분산된 결과 파티션을 생성하지 않습니다                          |
| `AdbcConnectionCancel`                   | 아직 지원되지 않음 | chDB 쿼리 취소 기능은 아직 ADBC를 통해 제공되지 않습니다                 |

<div id="statement">
  ### SQL 문
</div>

| 함수                                 | 상태         | 참고 사항                                        |
| ---------------------------------- | ---------- | -------------------------------------------- |
| `AdbcStatementNew` / `Release`     | 지원됨        |                                              |
| `AdbcStatementSetSqlQuery`         | 지원됨        | ClickHouse SQL                               |
| `AdbcStatementPrepare`             | 지원됨        |                                              |
| `AdbcStatementBind` / `BindStream` | 지원됨        | 위치 기반 `?` 매개변수                               |
| `AdbcStatementGetParameterSchema`  | 지원됨        |                                              |
| `AdbcStatementExecuteQuery`        | 지원됨        | Arrow 레코드 배치를 스트리밍합니다                        |
| `AdbcStatementSetOption`           | 지원됨        | 대량 수집, 아래 참조                                 |
| `AdbcStatementExecuteSchema`       | 아직 지원되지 않음 | 현재 결과 스키마는 실행 후 사용할 수 있습니다                   |
| `AdbcStatementExecutePartitions`   | 해당 없음      | 결과는 프로세스 내 Arrow 스트림으로 반환됩니다                 |
| `AdbcStatementSetSubstraitPlan`    | 해당 없음      | chDB는 Substrait 계획이 아닌 ClickHouse SQL을 사용합니다 |
| `AdbcStatementCancel`              | 아직 지원되지 않음 | chDB 쿼리 취소는 아직 ADBC를 통해 제공되지 않습니다            |

대량 수집은 기본 데이터베이스 또는 지정한 데이터베이스에 `create`, `append`, `create_append`, `replace` 모드를 지원합니다.

<div id="clickhouse-sql-and-type-behavior">
  ## ClickHouse SQL 및 타입 동작
</div>

chDB는 ClickHouse SQL 및 해당 타입 시스템을 사용합니다. ADBC를 통해 chDB에 액세스할 때도 다음 ClickHouse 의미 체계가 적용됩니다.

* 컬럼은 `Nullable(...)`로 선언하지 않는 한 널을 허용하지 않습니다. 일반 `String` 컬럼에 바인딩된 타입이 지정된 NULL은 NULL이 아닌 빈 문자열로 저장됩니다.
* ClickHouse 식별자 인용 방식을 사용하십시오. 예시에서는 백틱을 사용합니다.
* ClickHouse 데이터베이스는 ADBC `db_schema`에 매핑됩니다. 그 상위에는 카탈로그 계층이 없으므로 카탈로그 범위 작업은 적용할 수 없습니다.
* `Decimal`은 음수 scale을 허용하지 않으며, `Date32`는 1900-01-01부터 2299-12-31까지의 날짜를 지원합니다.
* 시간대가 없는 `DateTime64`는 엔진 시간대로 해석됩니다.
* 현재 ClickHouse Arrow 출력은 `Time` 타입을 표현하지 않으므로 ADBC를 통해 다시 읽을 수 없습니다.

일부 Arrow 타입은 값을 보존하지만, 다시 읽을 때는 다른 Arrow 타입으로 처리됩니다.

| Arrow 타입                                | 저장 형식            | 다시 읽는 형식            |
| --------------------------------------- | ---------------- | ------------------- |
| `binary`, `large_binary`, `binary_view` | `String`         | `string`            |
| `fixed_size_binary` (새 테이블로 대량 수집)      | `FixedString(n)` | `fixed_size_binary` |
| `large_string`, `string_view`           | `String`         | `string`            |
| `float16`                               | `Float32`        | `float`             |
| `time32` / `time64` / `timestamp`       | `DateTime64(n)`  | `timestamp`         |

바이너리 데이터는 `String`으로 저장되며 UTF-8로 다시 읽힙니다. 따라서 유효한 UTF-8이 아닌 페이로드는 `binary` 값으로 왕복 처리할 수 없습니다.

<div id="examples">
  ## 예시
</div>

<div id="bulk-ingestion">
  ### Arrow를 사용한 대량 수집
</div>

```python theme={null}
import pyarrow as pa
from adbc_driver_manager import dbapi

table = pa.table({"id": [1, 2, 3], "name": ["a", "b", "c"]})

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.adbc_ingest("events", table, mode="create")
        cur.execute("SELECT count() FROM events")
        print(cur.fetchone())
```

<div id="parameters">
  ### 매개변수
</div>

```python theme={null}
from adbc_driver_manager import dbapi

with dbapi.connect(
    driver="chdb",
    db_kwargs={"uri": "chdb://"},
    autocommit=True,
) as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT number FROM numbers(10) WHERE number > ?", (7,))
        print(cur.fetch_arrow_table())
```

<div id="c-example">
  ### C
</div>

`dbc install chdb` 실행 후 C Driver Manager는 이름으로 드라이버를 확인할 수 있습니다:

```c theme={null}
#include <arrow-adbc/adbc.h>
#include <arrow-adbc/adbc_driver_manager.h>

struct AdbcDatabase database = {0};
struct AdbcError error = {0};

AdbcDatabaseNew(&database, &error);
AdbcDatabaseSetOption(&database, "driver", "chdb", &error);
AdbcDatabaseSetOption(&database, "uri", "chdb://", &error);
AdbcDatabaseInit(&database, &error);
```

<div id="verification">
  ## 드라이버 검증 방식
</div>

chDB ADBC release build는 Linux x86-64 및 arm64, macOS x86-64 및 arm64 환경에서 네이티브 드라이버를 대상으로 두 가지 외부 테스트 모음을 실행합니다.

* C 계약을 확인하는 Apache Arrow ADBC 적합성 테스트 모음
* SQL 수준의 동작, 유형 왕복, 메타데이터 및 대량 수집을 확인하는 ADBC Driver Foundry 검증 테스트 모음

이 페이지의 지원 표는 이러한 실행 결과를 기반으로 합니다. 테스트 모음은 [chdb-core 리포지토리](https://github.com/chdb-io/chdb-core/tree/main/programs/local/adbc/validation)에 있습니다.