ADBC 드라이버로 사용하는 chDB

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

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

dbc를 사용하여 ADBC Driver Foundry에서 드라이버를 설치합니다:

dbc install chdb

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

dbc search -v chdb

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

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

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

pip install adbc-driver-manager pyarrow

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

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())

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

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

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

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

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

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

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 타입으로 처리됩니다.

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

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())

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())

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

#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);

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

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

이 페이지의 지원 표는 이러한 실행 결과를 기반으로 합니다. 테스트 모음은 chdb-core 리포지토리에 있습니다.