반환값
지정된 형식으로 쿼리 결과를 반환합니다.
발생 예외
예시
chDB 엔진을 사용해 SQL 쿼리를 실행합니다. 내장 ClickHouse 엔진을 사용해 SQL 문을 실행하는 핵심 쿼리 함수입니다. 다양한 출력 형식을 지원하며, 임시 데이터베이스 또는 파일 기반 데이터베이스에서 사용할 수 있습니다. 구문
반환값
지정된 형식으로 쿼리 결과를 반환합니다.
발생 예외
예시
쿼리 결과를 PyArrow Table로 변환합니다. 효율적인 열 지향 데이터 처리를 위해 chDB 쿼리 결과를 PyArrow Table 형식으로 변환합니다. 결과가 비어 있으면 빈 테이블을 반환합니다. 구문
반환값
예외
예시
쿼리 결과를 pandas DataFrame으로 변환합니다. 먼저 PyArrow Table로 변환한 뒤, 성능 향상을 위해 멀티스레딩을 사용해 pandas DataFrame으로 변환합니다. 구문
반환값
예외
예시
기본 포맷
쿼리 매개변수 사용 시
쿼리 매개변수 처리
쿼리 매개변수는 시작 시 인수로 ClickHouse 엔진에 전달됩니다.
특수 매개변수 처리:
전체 매개변수 목록은
clickhouse local --help --verbose를 참고하십시오.
반환값
발생 가능한 예외
하나의 프로세스는 하나의 데이터베이스 경로에 바인딩된 내장 엔진 하나를 실행합니다. 동일한 경로에 대한 여러 연결은 공존하며 동시에 쿼리를 실행할 수 있습니다. 연결이 하나라도 열려 있는 상태에서 다른 경로를 열면
RuntimeError가 발생합니다. 먼저 열려 있는 연결을 닫으십시오.Connection- 데이터베이스 연결 클래스Cursor- DB-API 2.0 작업용 데이터베이스 커서
Exception
chDB 관련 오류를 위한 기본 예외 클래스입니다.
이 예외는 chDB 쿼리 실행에 실패하거나
오류가 발생할 때 발생합니다. 표준 Python Exception 클래스를 상속하며,
기반 ClickHouse engine의 오류 정보를 제공합니다.
기반 클래스:
object
Session은 쿼리 상태를 유지합니다.
path가 None이면 세션은 프로세스 전체에서 공유하는 임시(:memory:) 데이터베이스를 사용하므로, 경로가 없는 모든 세션은 서로의 테이블을 볼 수 있습니다. 이러한 세션이나 연결이 모두 닫힌 후에만 해당 임시 디렉터리가 삭제됩니다.
또한 path를 전달해 해당 경로에 데이터베이스를 생성하고 데이터를 유지할 수도 있습니다.
연결 문자열을 사용해 경로와 기타 매개변수를 전달할 수도 있습니다.
연결 문자열 인자 처리“file:test.db?param1=value1¶m2=value2”와 같이 쿼리 매개변수를 포함하는 연결 문자열의 경우,
“param1=value1”은 시작 인자로 ClickHouse 엔진에 전달됩니다.자세한 내용은
clickhouse local –help –verbose를 참조하십시오.몇 가지 특수 인자 처리:- “mode=ro”는 clickhouse에서 “–readonly=1”로 처리됩니다 (읽기 전용 모드)
중요
- 동일한 데이터베이스 경로를 공유하는 경우 여러 세션이 공존할 수 있습니다.
- 다른 데이터베이스 경로를 사용하려면 먼저 열려 있는 세션을 닫으십시오.
예외를 처리하며 세션 리소스를 정리합니다. 이 메서드는 정리 과정에서 발생할 수 있는 예외를 무시하면서 세션을 닫으려고 시도합니다. 오류 처리 상황에서 특히 유용하며, 세션 상태와 관계없이 정리가 반드시 수행되어야 할 때도 유용합니다. 구문
이 메서드는 예외를 발생시키지 않으므로
finally 블록이나 소멸자에서 안전하게 호출할 수 있습니다.close()- 오류를 전파하면서 세션을 명시적으로 종료할 때 사용합니다
세션을 종료하고 리소스를 정리합니다. 이 메서드는 내부 connection을 닫고 전역 session 상태를 재설정합니다. 이 메서드를 호출한 후에는 session이 더 이상 유효하지 않으므로 추가 쿼리에 사용할 수 없습니다. 구문
이 메서드는 세션을 컨텍스트 관리자(context manager)로 사용하거나
세션 객체가 소멸될 때 자동으로 호출됩니다.
SQL 쿼리를 실행하고 결과를 반환합니다. 이 메서드는 세션의 데이터베이스에서 SQL 쿼리를 실행하고 지정된 형식으로 결과를 반환합니다. 또한 다양한 출력 형식을 지원하며, 쿼리 간에 세션 상태를 유지합니다. 구문
반환값
지정된 형식으로 쿼리 결과를 반환합니다.
정확한 반환 유형은
fmt 매개변수에 따라 달라집니다.
- 문자열 포맷(CSV, JSON 등)은 str을 반환합니다
- 바이너리 형식(Arrow, Parquet)은 bytes를 반환합니다
“Debug” 포맷은 지원되지 않으며 경고와 함께 자동으로
“CSV”로 변환됩니다.
디버깅할 때는 대신 연결 문자열 매개변수를 사용하십시오.
send_query()- 스트리밍 쿼리 실행에 사용됩니다sql- 이 메서드의 별칭입니다
SQL 쿼리를 실행하고 스트리밍 결과 이터레이터를 반환합니다. 이 메서드는 세션의 데이터베이스에서 SQL 쿼리를 실행하고, 모든 내용을 한 번에 메모리에 로드하지 않고도 결과를 순회할 수 있는 스트리밍 결과 객체를 반환합니다. 이는 특히 큰 결과 집합에 유용합니다. 구문
반환
발생 가능한 예외
“Debug” 포맷은 지원되지 않으며 경고와 함께 자동으로 “CSV”로 변환됩니다. 디버깅하려면 대신 연결 문자열 매개변수를 사용하십시오.
query()- 비스트리밍 쿼리 실행용chdb.state.sqlitelike.StreamingResult- 스트리밍 결과 이터레이터
SQL 쿼리를 실행하고 결과를 반환합니다. 이 메서드는 세션의 데이터베이스에서 SQL 쿼리를 실행하고, 지정된 포맷으로 결과를 반환합니다. 또한 다양한 출력 형식을 지원하며, 쿼리 간 세션 상태를 유지합니다. 구문
반환값
지정한 형식으로 쿼리 결과를 반환합니다.
정확한 반환 유형은
fmt 매개변수에 따라 달라집니다:
- 문자열 포맷(CSV, JSON 등)은 str을 반환합니다
- 바이너리 형식(Arrow, Parquet)은 bytes를 반환합니다
“Debug” 포맷은 지원되지 않으며, 경고와 함께 자동으로 “CSV”로 변환됩니다.
디버깅에는 대신 연결 문자열 매개변수를 사용하십시오.
send_query()- 스트리밍 쿼리 실행에 사용sql- 이 메서드의 별칭
기본 포맷
지원되는 연결 문자열 포맷:
쿼리 매개변수 포함
쿼리 매개변수 처리
쿼리 매개변수는 시작 인수로 ClickHouse 엔진에 전달됩니다.
특수 매개변수 처리:
전체 매개변수 목록은
clickhouse local --help --verbose를 참조하십시오.
반환값
발생 예외
하나의 프로세스에서는 하나의 데이터베이스 경로에 바인딩된 내장 엔진 하나가 실행됩니다. 동일한 경로에 대한 여러 연결은 공존할 수 있으며 동시에 쿼리를 실행할 수 있습니다. 연결이 하나라도 열려 있는 동안 다른 경로를 열면
RuntimeError가 발생하므로, 먼저 열려 있는 연결을 닫으십시오.Connection- 데이터베이스 연결 클래스Cursor- DB-API 2.0 작업을 위한 데이터베이스 커서”
object
구문
연결을 닫고 리소스를 정리합니다. 이 메서드는 데이터베이스(database) 연결을 닫고, 활성 커서를 포함한 관련 리소스를 모두 정리합니다. 이 메서드를 호출한 후에는 연결이 더 이상 유효하지 않아 이후 작업에 사용할 수 없습니다. 구문
이 메서드는 멱등적이므로 여러 번 호출해도 안전합니다.
쿼리를 실행하기 위한 Cursor 객체를 생성합니다. 이 메서드는 쿼리 실행과 결과 조회를 위한 표준 DB-API 2.0 인터페이스를 제공하는 데이터베이스 커서를 생성합니다. 커서를 사용하면 쿼리 실행과 결과 조회를 세밀하게 제어할 수 있습니다. 구문
새 커서를 생성하면 이 connection에 연결된 기존 커서가 대체됩니다. connection당
하나의 커서만 지원됩니다.
Cursor- 데이터베이스 커서 구현체
SQL 쿼리를 실행하고 전체 결과를 반환합니다. 이 메서드는 SQL 쿼리를 동기적으로 실행하고 전체 결과를 반환합니다. 다양한 출력 형식을 지원하며 출력 형식별 후처리를 자동으로 적용합니다. 구문
반환값
예외
예시
send_query()- 스트리밍 쿼리 실행에 사용됩니다
SQL 쿼리를 실행하고 스트리밍 결과 이터레이터를 반환합니다. 이 메서드는 SQL 쿼리를 실행하고 StreamingResult 객체를 반환합니다. 이 객체를 사용하면 모든 데이터를 한 번에 메모리에 로드하지 않고도 결과를 순회할 수 있습니다. 대규모 결과 집합을 처리할 때 적합합니다. 구문
반환값
예외
반환된 StreamingResult에서는 “Arrow” 형식에서만
record_batch() 메서드를 지원합니다.query()- 비스트리밍 쿼리 실행용StreamingResult- 스트리밍 결과 이터레이터
기반 클래스:
object
대용량 쿼리 결과를 처리하기 위한 스트리밍 결과 반복자입니다.
이 클래스는 전체 결과 집합을 메모리에 로드하지 않고
쿼리 결과를 스트리밍할 수 있는 반복자 인터페이스를 제공합니다. 다양한 출력 형식을
지원하며, 수동으로 결과를 가져오는 메서드와 PyArrow RecordBatch 스트리밍 메서드도 제공합니다.
스트리밍 결과의 다음 청크를 가져옵니다. 이 메서드는 스트리밍 쿼리 결과에서 다음으로 사용 가능한 데이터 청크를 가져옵니다. 반환되는 데이터의 포맷은 스트리밍 쿼리를 시작할 때 지정한 포맷에 따라 달라집니다. 구문
예시
스트리밍 쿼리를 취소하고 리소스를 정리합니다. 이 메서드는 진행 중인 스트리밍 쿼리를 취소하고 관련 리소스를 해제합니다. 스트림이 끝나기 전에 결과 처리를 중단하려는 경우 호출해야 합니다. 구문
스트리밍 결과를 닫고 리소스를 정리합니다.
cancel()의 별칭입니다. 스트리밍 결과 이터레이터를 닫고
관련 리소스를 해제합니다.
구문
효율적인 배치 처리를 위해 PyArrow RecordBatchReader를 생성합니다. 이 메서드는 Arrow 형식의 쿼리 결과를 효율적으로 순회할 수 있는 PyArrow RecordBatchReader를 생성합니다. PyArrow를 사용할 때 대규모 결과 집합을 처리하는 가장 효율적인 방법입니다. 구문
반환
이 메서드는 스트리밍 쿼리가
format="Arrow"로 시작된 경우에만 사용할 수
있습니다. 다른 포맷에서 사용하면 오류가 발생합니다.StreamingResult는 Python의 반복자 프로토콜을 지원하므로 for 루프에서 직접 사용할 수 있습니다:
StreamingResult는 자동 리소스 정리를 위해 컨텍스트 매니저 프로토콜을 지원합니다:
상속:
object
커서를 닫고 리소스를 정리합니다. 이 메서드는 커서를 닫고 관련 리소스를 모두 정리합니다. 이 메서드를 호출하면 커서는 더 이상 유효하지 않아 이후 작업에 사용할 수 없습니다. 구문
이 메서드는 멱등성을 가지므로 여러 번 호출해도 안전합니다.
connection이 닫히면 커서도 자동으로 닫힙니다.
마지막으로 실행된 쿼리의 컬럼 이름 목록을 반환합니다. 이 메서드는 가장 최근에 실행한 SELECT 쿼리의 컬럼 이름을 반환합니다. 이름은 결과 집합에 나타나는 순서대로 반환됩니다. 구문
예시
column_types()- 컬럼 타입 정보를 조회합니다description- DB-API 2.0 컬럼 설명 정보
마지막으로 실행된 쿼리의 컬럼 타입 목록을 반환합니다. 이 메서드는 가장 최근에 실행된 SELECT 쿼리의 ClickHouse 컬럼 타입 이름을 반환합니다. 타입은 결과 집합에 표시된 순서와 동일한 순서로 반환됩니다. 구문
예시
column_names()- 컬럼 이름 정보를 확인합니다description- DB-API 2.0 컬럼 설명
보류 중인 트랜잭션을 커밋합니다. 이 메서드는 보류 중인 모든 데이터베이스(Database) 트랜잭션을 커밋합니다. ClickHouse에서는 대부분의 작업이 자동으로 커밋되지만, 이 메서드는 DB-API 2.0 호환성을 위해 제공됩니다.
ClickHouse는 일반적으로 작업을 자동으로 커밋하므로, 명시적으로 커밋할
필요는 거의 없습니다. 이 메서드는 표준
DB-API 2.0 워크플로와의 호환성을 위해 제공됩니다.
DB-API 2.0 사양에 따라 컬럼 설명을 반환합니다. 이 속성은 마지막으로 실행한 SELECT 쿼리의 결과 집합(result set)에 있는 각 컬럼을 설명하는 7개 항목으로 이루어진 튜플 목록을 반환합니다. 각 튜플에는 다음이 포함됩니다: (name, type_code, display_size, internal_size, precision, scale, null_ok) 현재는 name과 type_code만 제공되며, 나머지 필드는 None으로 설정됩니다. 반환값
이는 cursor.description에 대한 DB-API 2.0 사양을 따릅니다.
이 구현에서는 처음 두 요소(name 및 type_code)에만
의미 있는 데이터가 포함됩니다.
column_names()- 컬럼 이름만 반환합니다column_types()- 컬럼 타입만 반환합니다
SQL 쿼리를 실행하고 결과를 가져올 수 있도록 준비합니다. 이 메서드는 SQL 쿼리를 실행한 뒤 fetch 메서드를 사용해 결과를 조회할 수 있도록 준비합니다. 결과 데이터의 구문 분석과 ClickHouse 데이터 타입에 대한 자동 타입 변환도 처리합니다. 구문
예외
이 메서드는
cursor.execute()에 대한 DB-API 2.0 사양을 따릅니다.
실행 후에는 fetchone(), fetchmany(), fetchall()을 사용하여
결과를 가져오십시오.이 메서드는 ClickHouse 데이터 타입을 적절한
Python 타입으로 자동 변환합니다:
- Int/UInt 타입 → int
- Float 타입 → float
- String/FixedString → str
- DateTime → datetime.datetime
- Date → datetime.date
- Bool → bool
fetchone()- 행 1개 가져오기fetchmany()- 여러 행 가져오기fetchall()- 남은 모든 행 가져오기
쿼리 결과에 남아 있는 모든 행을 가져옵니다. 이 메서드는 현재 커서 위치를 기준으로 현재 쿼리 결과 집합에 남아 있는 모든 행을 조회합니다. 반환값은 적절한 Python 유형 변환이 적용된 행 튜플들의 튜플입니다. 구문
예시
fetchone()- 단일 행 조회fetchmany()- 여러 행을 배치로 조회
쿼리 결과에서 여러 행을 가져옵니다. 이 메서드는 현재 쿼리 결과 집합에서 최대
size개의 행을 가져옵니다. 반환값은 행 튜플로 이루어진 튜플이며, 각 행에는 적절한 Python 유형으로 변환된 컬럼 값이 포함됩니다.
구문
반환값
이 메서드는 DB-API 2.0 사양을 따릅니다. 결과 집합이 소진되면
‘size’보다 적은 수의 행을 반환합니다.
fetchone()- 단일 행 조회fetchall()- 남아 있는 모든 행 조회
쿼리 결과에서 다음 행을 가져옵니다. 이 메서드는 현재 쿼리 결과 집합에서 다음으로 사용 가능한 행을 가져옵니다. 반환값은 적절한 Python 유형 변환이 적용된 컬럼 값들을 포함하는 튜플입니다. 구문
이 메서드는 DB-API 2.0 사양을 따릅니다. 컬럼 값은
ClickHouse 컬럼 타입에 따라 적절한 Python 타입으로
자동 변환됩니다.
fetchmany()- 여러 행 조회fetchall()- 남은 모든 행 조회
쿼리 결과를 PyArrow Table로 변환합니다. 이 함수는 chdb 쿼리 결과를 PyArrow Table 포맷으로 변환하여 열 지향 데이터에 효율적으로 접근할 수 있게 하고, 다른 데이터 처리 라이브러리와도 원활하게 상호 운용할 수 있도록 합니다. 구문
반환값
예외 발생
이 함수를 사용하려면 pyarrow와 pandas가 모두 설치되어 있어야 합니다.
다음 명령으로 설치하십시오:
pip install pyarrow pandas쿼리 결과를 Pandas DataFrame으로 변환합니다. 이 함수는 chdb 쿼리 결과를 먼저 PyArrow Table로 변환한 뒤 DataFrame으로 변환하여 Pandas API를 통한 편리한 데이터 분석 기능을 제공합니다. 구문
반환값:
예외
이 함수는 대규모 데이터셋에서 성능을 높이기 위해 Arrow를 Pandas로 변환할 때
멀티스레딩을 사용합니다.
to_arrowTable()- PyArrow Table 포맷으로 변환할 때 사용합니다.
- Connections: 연결 문자열(connection string)을 사용한 데이터베이스 연결 관리
- Cursors: 쿼리 실행 및 결과 가져오기
- Type System: DB-API 2.0을 준수하는 유형 상수 및 컨버터
- Error Handling: 표준 데이터베이스 예외 계층 구조
- Thread Safety: 수준 1의 스레드 안전성(스레드는 모듈을 공유할 수 있지만 연결은 공유할 수 없음)
Database API (DBAPI) 2.0 인터페이스는 다음과 같은 핵심 함수를 구현합니다: 새 데이터베이스 연결을 초기화합니다. 구문
발생 예외
클라이언트 버전 정보를 반환합니다. MySQLdb와의 호환성을 위해 chDB 클라이언트 버전을 문자열로 반환합니다. 구문
x를 바이너리 형식으로 반환합니다. 이 함수는 DB-API 2.0 사양에 따라 바이너리 데이터베이스 필드에서 사용할 수 있도록 입력을
bytes 유형으로 변환합니다.
구문
반환값
기반 클래스:
object
chDB 데이터베이스용 DB-API 2.0 호환 연결입니다.
이 클래스는 chDB 데이터베이스에 연결하고 상호 작용할 수 있는 표준 DB-API 인터페이스를 제공합니다. 임시 데이터베이스와 파일 기반 데이터베이스를 모두 지원합니다.
이 연결은 내부의 chDB 엔진을 관리하며, 쿼리 실행, 트랜잭션 관리(ClickHouse에서는 no-op), 커서 생성용 메서드를 제공합니다.
변수
예시
ClickHouse는 일반적인 트랜잭션을 지원하지 않으므로, commit() 및 rollback()
작업은 실제로 아무 동작도 하지 않지만 DB-API 컴플라이언스를 위해 제공됩니다.
데이터베이스 연결을 닫습니다. 내부 chDB 연결을 닫고 이 연결을 닫힌 상태로 표시합니다. 이후 이 연결에서 작업을 수행하면 오류가 발생합니다. 구문
현재 트랜잭션을 커밋합니다. 구문
이는 chDB/ClickHouse에서 전통적인 트랜잭션을 지원하지 않으므로 no-op입니다.
DB-API 2.0 컴플라이언스를 위해 제공됩니다.
쿼리 실행에 사용할 새 커서를 생성합니다. 구문
반환값
예외 발생
예시
값을 SQL 쿼리에 안전하게 포함할 수 있도록 이스케이프 처리합니다. 구문
반환값
예시
SQL 쿼리에서 사용할 문자열 값을 이스케이프합니다. 구문
반환값
연결(connection)이 열려 있는지 확인합니다. 반환값
SQL 쿼리를 직접 실행하고 원시 결과를 반환합니다. 이 메서드는 cursor 인터페이스를 거치지 않고 쿼리를 직접 실행합니다. 표준 DB-API 사용 시에는
cursor() 메서드를 사용하는 것이 좋습니다.
구문
반환값
예외 발생
예시
마지막 쿼리 응답을 반환합니다. 반환값
이 속성은
query()를 직접 호출할 때마다 업데이트됩니다.
커서를 통해 실행된 쿼리는 반영되지 않습니다.현재 트랜잭션을 롤백합니다. 구문
chDB/ClickHouse는 전통적인 트랜잭션을 지원하지 않으므로 이는 no-op입니다. DB-API 2.0 컴플라이언스를 위해 제공됩니다.
기반:
object
쿼리를 실행하고 결과를 가져오는 DB-API 2.0 커서입니다.
이 커서는 SQL 문을 실행하고 쿼리 결과를 관리하며,
결과 집합을 탐색하는 메서드를 제공합니다. 매개변수 바인딩, 일괄 작업을 지원하고,
DB-API 2.0 사양을 따릅니다.
Cursor 인스턴스를 직접 생성하지 마십시오. 대신 Connection.cursor()를 사용하십시오.
예시
전체 사양의 자세한 내용은 DB-API 2.0 Cursor Objects를
참조하십시오.
저장 프로시저를 실행합니다(임시로 제공되는 구현). 구문
반환값
chDB/ClickHouse는 전통적인 의미의 저장 프로시저를 지원하지 않습니다.
이 메서드는 DB-API 2.0 컴플라이언스를 위해 제공되지만 실제로는
아무 작업도 수행하지 않습니다. 모든 SQL 작업에는 execute()를 사용하십시오.
커서를 닫고 관련 리소스를 해제합니다. 닫은 후에는 커서를 더 이상 사용할 수 없으며, 어떤 작업을 수행해도 예외가 발생합니다. 커서를 닫으면 남아 있는 데이터를 모두 소진하고 내부 커서를 해제합니다. 구문
선택적으로 매개변수를 바인딩하여 SQL 쿼리를 실행합니다. 이 메서드는 선택적으로 매개변수를 치환하여 단일 SQL 문을 실행합니다. 유연성을 위해 여러 매개변수 플레이스홀더 스타일을 지원합니다. 구문
반환값
매개변수 스타일
예시
서로 다른 매개변수 집합으로 쿼리를 여러 번 실행합니다. 이 메서드는 동일한 SQL 쿼리를 서로 다른 매개변수 값으로 반복해 효율적으로 실행합니다. 특히 대량 INSERT 작업에 유용합니다. 구문
반환값
예시
이 메서드는 여러 행을 INSERT하거나 UPDATE하는 작업에서
쿼리 실행 과정을 최적화해 성능을 높입니다.
쿼리 결과에 남아 있는 모든 행을 가져옵니다. 구문
발생 가능한 예외
예시
쿼리 결과에서 여러 행을 가져옵니다. 구문
반환값
예외 발생
예시
쿼리 결과에서 다음 행을 반환합니다. 구문
예외 발생
예시
executemany()이 생성하는 최대 문 길이입니다.
기본값은 1024000입니다.
데이터베이스로 전송될 정확한 쿼리 문자열을 반환합니다. 이 메서드는 매개변수 치환이 적용된 최종 SQL 쿼리를 보여주므로, 디버깅 및 로깅에 유용합니다. 구문
반환값
예시
이 메서드는 Psycopg에서 사용하는 DB-API 2.0에 대한 확장을 따릅니다.
다음 결과 세트로 이동합니다(지원되지 않음). 구문
chDB/ClickHouse는 단일 쿼리에서 여러 결과 집합을 지원하지 않습니다.
이 메서드는 DB-API 2.0 컴플라이언스를 위해 제공되지만, 항상 None을 반환합니다.
매개변수 입력 크기를 설정합니다(no-op 구현). 구문
이 메서드는 아무 작업도 수행하지 않지만, DB-API 2.0 사양상 필요합니다.
chDB는 내부적으로 매개변수 크기 지정을 자동으로 처리합니다.
출력 컬럼 크기를 설정합니다(아무 동작도 하지 않는 구현). 구문
이 메서드는 아무 작업도 수행하지 않지만, DB-API 2.0 사양상 필요합니다.
chDB가 출력 크기를 내부적으로 자동으로 처리합니다.
chdb 데이터베이스 작업에서 사용하는 예외 클래스입니다. 이 모듈은 Python Database API Specification v2.0을 따르며, chdb에서 발생하는 데이터베이스 관련 오류를 처리하기 위한 전체 예외 클래스 계층 구조를 제공합니다. 예외 계층 구조는 다음과 같습니다:
이러한 예외 클래스는 Python DB API 2.0 사양을 준수하며,
다양한 데이터베이스 작업에서 일관된 오류 처리를 제공합니다.
- Python Database API Specification v2.0
chdb.dbapi.connections- 데이터베이스 연결 관리chdb.dbapi.cursors- 데이터베이스 커서 작업
기반 클래스:
DatabaseError
처리된 데이터의 문제로 인해 발생하는 오류에 대해 발생하는 예외입니다.
이 예외는 처리 중인 데이터에 문제가 있어 데이터베이스 작업이 실패할 때 발생합니다. 예를 들면 다음과 같습니다:
- 0으로 나누기 연산
- 범위를 벗어난 숫자 값
- 잘못된 날짜/시간 값
- 문자열 잘림 오류
- 유형 변환 실패
- 컬럼 유형에 맞지 않는 잘못된 데이터 포맷
예시
기반 클래스:
Error
데이터베이스와 관련된 오류가 발생할 때 반환되는 예외입니다.
이 클래스는 모든 데이터베이스 관련 오류의 기본 클래스입니다. 데이터베이스 작업 중 발생하는 오류 중에서, 인터페이스 자체가 아니라 데이터베이스 자체와 관련된 모든 오류를 포괄합니다.
일반적인 사례는 다음과 같습니다:
- SQL 실행 오류
- 데이터베이스 연결 문제
- 트랜잭션 관련 문제
- 데이터베이스별 제약 조건 위반
이 클래스는
DataError, OperationalError 등 더 구체적인 데이터베이스 오류 유형의 상위 클래스 역할을 합니다.기반 클래스:
StandardError
Warning을 제외한 모든 오류 예외의 기본 클래스입니다.
이는 경고를 제외한 chdb의 모든 오류 예외를 위한 기본 클래스입니다.
작업이 성공적으로 완료되지 못하게 하는 모든 데이터베이스 오류 조건의
상위 클래스로 사용됩니다.
이 예외 계층 구조는 Python DB API 2.0 명세를 따릅니다.
Warning- 작업 완료를 방해하지 않는 비치명적 경고는 이를 참조하십시오.
DatabaseError
데이터베이스의 관계형 무결성이 손상될 때 발생하는 예외입니다.
이 예외는 데이터베이스 작업이 무결성 제약을 위반할 때 발생하며,
다음과 같은 경우가 포함됩니다:
- 외래 키 제약 위반
- 기본 키(primary key) 또는 고유 제약 조건(unique constraint) 위반(중복 키)
- CHECK 제약 위반
- NOT NULL 제약 위반
- 참조 무결성 위반
예시
기반 클래스:
Error
이 예외는 데이터베이스 자체가 아니라 데이터베이스 인터페이스와 관련된 오류가 있을 때 발생합니다.
다음과 같이 데이터베이스 인터페이스 구현에 문제가 있을 때 이 예외가 발생합니다.
- 잘못된 연결 매개변수
- API 오용(닫힌 연결에서 메서드를 호출하는 경우)
- 인터페이스 수준의 프로토콜 오류
- 모듈 import 또는 초기화 실패
이러한 오류는 일반적으로 프로그래밍 오류 또는 구성 문제이며,
클라이언트 코드나 구성을 수정하면 해결할 수 있습니다.
기반 클래스:
DatabaseError
데이터베이스에서 내부 오류가 발생했을 때 발생하는 예외입니다.
이 예외는 데이터베이스 시스템에서 애플리케이션이 원인이 아닌 내부
오류가 발생했을 때 발생합니다. 예를 들면 다음과 같습니다.
- 잘못된 커서 상태(커서가 더 이상 유효하지 않음)
- 트랜잭션 상태 불일치(트랜잭션 동기화가 맞지 않음)
- 데이터베이스 손상 문제
- 내부 데이터 구조 손상
- 시스템 수준의 데이터베이스 오류
이러한 오류는 일반적으로 애플리케이션이 제어할 수 있는 범위를 벗어나며,
데이터베이스를 재시작하거나 복구 작업이 필요할 수 있습니다.
기반 클래스:
DatabaseError
메서드 또는 데이터베이스 API를 지원하지 않을 때 발생하는 예외입니다.
애플리케이션이 현재 데이터베이스 구성이나 버전에서 지원하지 않는 데이터베이스
기능 또는 API 메서드를 사용하려고 할 때 이 예외가 발생합니다. 예시는 다음과 같습니다:
- 트랜잭션을 지원하지 않는 연결에서
rollback()을 요청하는 경우 - 데이터베이스 버전에서 지원하지 않는 고급 SQL 기능을 사용하는 경우
- 현재 드라이버에서 구현되지 않은 메서드를 호출하는 경우
- 비활성화된 데이터베이스 기능을 사용하려는 경우
예시
이러한 오류를 방지하려면 데이터베이스 문서와 드라이버 지원 기능을 확인하십시오.
가능하면 적절한 폴백을 고려하십시오.
기반:
DatabaseError
데이터베이스 운영과 관련된 오류가 발생할 때 발생하는 예외입니다.
이 예외는 데이터베이스를 운영하는 중 발생하며, 반드시 프로그래머가 제어할 수 있는 것은 아닌 오류에 대해 발생합니다. 예시는 다음과 같습니다:
- 데이터베이스와의 연결이 예기치 않게 끊어진 경우
- 데이터베이스 서버를 찾을 수 없거나 연결할 수 없는 경우
- 트랜잭션 처리 실패
- 처리 중 메모리 할당 오류
- 디스크 공간 또는 리소스 고갈
- 데이터베이스 서버 내부 오류
- 인증 또는 권한 부여 실패
이러한 오류는 일반적으로 일시적이며, 작업을 다시 시도하거나
시스템 수준의 문제를 해결하면 해소될 수 있습니다.
기반:
DatabaseError
데이터베이스 작업에서 프로그래밍 오류가 발생할 때 이 예외가 발생합니다.
이 예외는 애플리케이션이 데이터베이스를 사용하는 과정에서 프로그래밍 오류가 있을 때 발생하며, 다음과 같은 경우를 포함합니다:
- 테이블 또는 컬럼을 찾을 수 없음
- 생성 시 테이블 또는 인덱스가 이미 존재함
- SQL 문의 구문 오류
- prepared 문에 지정된 매개변수 수가 잘못됨
- 잘못된 SQL 작업(예: 존재하지 않는 객체에 대한 DROP)
- 데이터베이스 API 메서드를 잘못 사용함
예시
기반 클래스:
Exception
chdb 작업과 관련된 예외입니다.
이 클래스는 모든 chdb 관련 예외의 기본 클래스입니다. Python의 내장 Exception 클래스를 상속하며, 데이터베이스 작업용 예외 계층 구조의 최상위 클래스 역할을 합니다.
이 예외 클래스는 데이터베이스 예외 처리를 위한 Python DB API 2.0 사양을 따릅니다.
기반:
StandardError
삽입 중 데이터 잘림과 같은 중요한 경고가 발생했을 때 발생하는 예외입니다.
이 예외는 데이터베이스 작업이 완료되었지만 애플리케이션에서
주의해야 할 중요한 경고가 함께 발생한 경우에 발생합니다.
일반적인 예는 다음과 같습니다.
- 삽입 중 데이터 잘림
- 숫자 변환 시 정밀도 손실
- 문자 집합 변환 경고
이는 경고 예외에 관한 Python DB API 2.0 사양을 따릅니다.
encoding 또는
errors가 지정되면, 객체는 데이터 버퍼를 제공해야 하며
이 버퍼는 지정된 인코딩과 오류 처리기(error handler)를 사용해 디코딩됩니다.
그렇지 않으면 object._\_str_\_()의 결과(정의된 경우) 또는
repr(object)를 반환합니다.
encoding의 기본값은 ‘utf-8’입니다.errors의 기본값은 ‘strict’입니다.
DB-API 2.0 유형 비교를 위한 확장 frozenset입니다. 이 클래스는 DB-API 2.0의 유형 비교 의미 체계를 지원하도록 frozenset을 확장한 것입니다. 개별 항목을 집합과 비교할 때 등호 및 부등호 연산자를 모두 사용할 수 있어 유형을 유연하게 확인할 수 있습니다. 이 객체는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며,
field_type이 단일 유형 값일 때 “field_type == STRING”과 같은 비교를 가능하게 합니다.
예시
DB-API 2.0 유형 비교를 위한 확장된 frozenset입니다. 이 클래스는 DB-API 2.0 유형 비교 의미 체계를 지원하도록 frozenset을 확장합니다. 이를 통해 개별 항목을 집합과 비교할 때 동등 및 부등 연산자를 모두 사용하여 유연하게 유형을 검사할 수 있습니다. 이는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며, field_type이 단일 유형 값일 때 “field_type == STRING”과 같은 비교를 가능하게 합니다. 예시
DB-API 2.0 유형 비교를 위한 확장 frozenset입니다. 이 클래스는 DB-API 2.0의 유형 비교 의미 체계를 지원하도록 frozenset을 확장합니다. 이를 통해 개별 항목을 집합과 비교할 때 equality 및 inequality 연산자를 모두 사용해 유연하게 유형을 검사할 수 있습니다. 이는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며,
field_type == STRING과 같은 비교를 가능하게 합니다. 여기서 field_type은 단일 유형 값입니다.
예시
DB-API 2.0 유형 비교를 위한 확장 frozenset입니다. 이 클래스는 DB-API 2.0의 유형 비교 의미 체계를 지원하도록 frozenset을 확장한 것입니다. 개별 항목을 집합과 비교할 때 동등 및 부등 연산자를 모두 사용할 수 있어 유형을 더 유연하게 확인할 수 있습니다. 이는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며, field_type이 단일 유형 값일 때 “field_type == STRING”과 같은 비교를 가능하게 합니다. 예시
DB-API 2.0 유형 비교를 위한 확장된 frozenset입니다. 이 클래스는 DB-API 2.0의 유형 비교 의미 체계를 지원하도록 frozenset을 확장합니다. 개별 항목을 동등 및 부등 연산자를 사용해 집합과 비교할 수 있으므로 유연한 유형 검사가 가능합니다. 이는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며, field_type이 단일 유형 값일 때 “field_type == STRING”과 같은 비교를 가능하게 합니다. 예시
DB-API 2.0 유형 비교를 위해 확장된 frozenset입니다. 이 클래스는 DB-API 2.0 유형 비교 시맨틱을 지원하도록 frozenset을 확장합니다. 개별 항목을 집합과 비교할 때 동등 연산자와 부등 연산자를 모두 사용할 수 있어 유연한 유형 확인이 가능합니다. 이는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며,
field_type이 단일 유형 값일 때 “field_type == STRING”과 같은 비교를 가능하게 합니다.
예시
DB-API 2.0의 유형 비교를 위해 확장된 frozenset입니다. 이 클래스는 DB-API 2.0의 유형 비교 의미 체계를 지원하도록 frozenset을 확장한 것입니다. 이를 통해 개별 항목을 집합과 비교할 때 동등 및 부등 연산자를 모두 사용해 유연하게 유형을 확인할 수 있습니다. 이는 STRING, BINARY, NUMBER 등의 유형 상수에 사용되며, field_type이 단일 유형 값일 때 “field_type == STRING”과 같은 비교를 가능하게 합니다. 예시
- 연결 관리: 작업이 끝나면 항상 연결과 커서를 닫으십시오
- Context 관리자: 자동으로 정리되도록
with문을 사용하십시오 - 배치 처리: 큰 결과 집합에는
fetchmany()를 사용하십시오 - 오류 처리: 데이터베이스 작업은 try-except 블록으로 감싸십시오
- 매개변수 바인딩: 가능하면 매개변수화된 쿼리를 사용하십시오
- 메모리 관리: 매우 큰 데이터셋에는
fetchall()사용을 피하십시오
- chDB의 DB-API 2.0 인터페이스는 대부분의 Python 데이터베이스 도구와 호환됩니다
- 이 인터페이스는 수준 1 스레드 안전성을 제공합니다(스레드는 모듈을 공유할 수 있지만 연결은 공유할 수 없습니다)
- connection string은 chDB 세션과 동일한 매개변수를 지원합니다
- 모든 표준 DB-API 2.0 예외를 지원합니다
NULL이 \N으로 표시되고 문자열 및 날짜 값에는 CSV 따옴표 처리가 적용됩니다.
Python 함수를 chDB SQL 함수로 등록합니다.
구문
각 타입 매개변수(
arg_types 원소 및 return_type)에는 다음을 사용할 수 있습니다.
ChdbType상수:INT64,STRING,FLOAT64등- ClickHouse 타입 문자열:
"Int64","String","DateTime64(6)","DateTime('UTC')"등 - Python 타입:
int,float,str,bool,bytes,datetime.date,datetime.datetime— 자동 타입 매핑에 따라 매핑됩니다.
drop_function을 호출하십시오.
예시
이전에 등록된 Python UDF를 제거합니다. 함수가 등록되어 있지 않으면 아무 작업도 수행하지 않으므로, 조건과 관계없이 안전하게 호출할 수 있습니다. 구문
Python 함수를 chDB SQL 함수로 등록하는 데 사용되는 데코레이터입니다. 등록한 함수는 일반 Python 함수처럼 계속 호출할 수 있으며, 동시에
__name__을 통해 SQL 쿼리에서도 사용할 수 있습니다.
구문
name 및 func를 제외하면 create_function과 동일합니다.
예시
chdb.sqltypes에서 타입을 import합니다:
타입은 여러 방법으로 지정할 수 있습니다:
on_null 매개변수로 NULL 값을 처리하는 방식을 지정합니다.
on_error 매개변수로 예외 처리 방식을 제어합니다.
UDF는 시간대를 인식하는
Date, Date32, DateTime, DateTime64 타입을 완벽하게 지원합니다.
- 입력 ClickHouse
DateTime/DateTime64값은 시간대 정보가 포함된 Pythondatetime객체로 변환됩니다 - 출력 Python
datetime객체는 ClickHouse로 반환될 때 시간대 정보를 유지합니다 chdb.sqltypes의DATETIME64타입은 기본적으로 스케일 6(마이크로초)을 사용하며,DateTime64(6)과 동일합니다
chDB Python UDF(사용자 정의 함수)용 데코레이터입니다. 구문
참고
- 함수는 stateless해야 합니다. UDAF는 지원되지 않으며 UDF만 지원됩니다.
- 기본 반환 타입은 String입니다. 반환 타입은 ClickHouse 데이터 타입 중 하나여야 합니다.
- 함수는 String 타입의 인수를 받아야 합니다. 모든 인수는 문자열입니다.
- 함수는 입력 각 줄에 대해 호출됩니다.
- 함수는 순수 Python 함수여야 합니다. 함수 내부에서 사용하는 모든 모듈은 import해야 합니다.
- 사용되는 Python 인터프리터는 스크립트를 실행할 때 사용하는 인터프리터와 동일합니다.
UDF 구성과 실행형 스크립트 파일을 생성합니다. 이 함수는 chDB에서 사용자 정의 함수(UDF)에 필요한 다음 파일을 생성합니다:
- 입력 데이터를 처리하는 Python 실행형 스크립트
- ClickHouse에 UDF를 등록하는 XML 설정 파일
이 함수는 일반적으로 @chdb_udf 데코레이터에서 호출되므로, 사용자가 직접
호출해서는 안 됩니다.
chDB용 유틸리티 함수와 도우미입니다. 이 모듈에는 chDB 작업에 사용하는 다양한 유틸리티 함수가 포함되어 있으며, 데이터 타입 추론, 데이터 변환 도우미, 디버깅 유틸리티 등을 제공합니다.
딕셔너리 목록을 컬럼형 포맷으로 변환합니다. 이 함수는 딕셔너리 목록을 받아 각 키가 하나의 컬럼에 대응하고 각 값이 해당 컬럼 값의 목록인 딕셔너리로 변환합니다. 딕셔너리에서 누락된 값은 None으로 표현됩니다. 구문
반환값
예시
중첩된 딕셔너리를 평탄화합니다. 이 함수는 중첩된 딕셔너리를 받아 구분자를 사용해 중첩된 키를 이어 붙여 평탄화합니다. 딕셔너리 목록은 JSON 문자열로 직렬화됩니다. 구문
반환값
예시
값 목록에 가장 적합한 데이터 타입을 추론합니다. 이 함수는 값 목록을 살펴보고, 목록의 모든 값을 표현할 수 있는 가장 적절한 데이터 타입을 결정합니다. 정수, 부호 없는 정수, Decimal, float 타입을 고려하며, 값을 어떤 숫자 타입으로도 표현할 수 없거나 모든 값이 None이면 기본적으로 “string”을 사용합니다. 구문
반환값
- 목록의 모든 값이 None이면 함수는 “string”을 반환합니다.
- 목록에 문자열 값이 하나라도 있으면 함수는 즉시 “string”을 반환합니다.
- 이 함수는 숫자 값이 범위와 정밀도에 따라 정수, Decimal 또는 float로 표현될 수 있다고 가정합니다.
열 지향 데이터 구조에서 각 컬럼의 데이터 타입을 추론합니다. 이 함수는 각 컬럼의 값을 분석하고, 데이터 샘플을 바탕으로 각 컬럼에 가장 적합한 데이터 타입을 추론합니다. 구문
반환값
기반 클래스:
ABC
주어진 컬럼에서 지정된 수의 행을 읽고 객체 목록을 반환합니다. 각 객체는 하나의 컬럼에 대한 값 시퀀스입니다.
반환값
기반 클래스:
ABC
블록에서 최종 데이터를 조합해 반환합니다. 하위 클래스에서 반드시 구현해야 합니다.
데이터 컬럼들을 블록에 저장합니다. 하위 클래스에서 반드시 구현해야 합니다.
기반 클래스:
Exception
chDB 관련 오류를 위한 기본 예외 클래스입니다.
이 예외는 chDB 쿼리 실행이 실패하거나
오류가 발생했을 때 발생합니다. 표준 Python Exception 클래스를 상속하며
하위 ClickHouse 엔진의 오류 정보를 제공합니다.
예외 메시지에는 일반적으로 ClickHouse의 자세한 오류 정보가 포함되며,
여기에는 구문 오류, 유형 불일치, 누락된
테이블/컬럼, 기타 쿼리 실행 문제가 포함됩니다.
변수
예시
이 예외는 내부 ClickHouse engine이 오류를 보고하면 chdb.query() 및 관련
함수에서 자동으로 발생합니다.
애플리케이션에서 적절한 오류 처리를 수행할 수 있도록, 실패할 가능성이 있는
쿼리를 처리할 때는 이 예외를 포착해야 합니다.
- encoding의 기본값은 ‘utf-8’입니다.
- errors의 기본값은 ‘strict’입니다.
encoding 또는
errors가 지정되면, 객체는 지정된 인코딩과 오류 handler를 사용해
디코딩할 데이터 버퍼를 제공해야 합니다.
그렇지 않으면 object._str_()의 결과(정의된 경우)
또는 repr(object)를 반환합니다.
encoding의 기본값은 ‘utf-8’입니다.errors의 기본값은 ‘strict’입니다.