메인 콘텐츠로 건너뛰기
이 가이드에서는 chDB의 Python 버전을 사용해 빠르게 시작하는 방법을 설명합니다. 먼저 S3의 JSON 파일에 쿼리한 다음, 해당 JSON 파일을 기반으로 chDB에 테이블(table)을 생성하고 데이터에 대해 몇 가지 쿼리를 수행합니다. 또한 Apache Arrow와 Panda를 포함해 쿼리 결과를 다양한 포맷으로 반환하는 방법을 살펴보고, 마지막으로 Pandas 데이터프레임을 쿼리하는 방법을 알아봅니다.

환경 설정

먼저 가상 환경을 생성합니다:
이제 chDB를 설치합니다. 버전 2.0.3 이상인지 확인하세요:
이제 ipython을 설치하겠습니다:
이 가이드의 나머지 부분에서 명령을 실행할 때는 ipython을 사용합니다. 다음을 실행하여 시작할 수 있습니다:
이 가이드에서는 Pandas와 Apache Arrow도 사용하므로, 해당 라이브러리도 함께 설치하세요:

S3의 JSON 파일 쿼리하기

이제 S3 버킷에 저장된 JSON 파일을 어떻게 쿼리하는지 살펴보겠습니다. YouTube dislikes 데이터셋에는 2021년까지 YouTube 동영상의 dislikes에 대한 40억 개 이상의 행이 포함되어 있습니다. 이 데이터셋에 포함된 JSON 파일 중 하나를 사용하겠습니다. chdb를 가져옵니다:
다음 쿼리를 사용하여 JSON 파일 하나의 구조를 확인할 수 있습니다:
해당 파일에 있는 행 수를 셀 수도 있습니다:
이 파일에는 300,000개를 조금 넘는 레코드가 들어 있습니다. chdb는 아직 쿼리 매개변수를 전달하는 기능을 지원하지 않지만, 경로를 추출해 f-String으로 전달할 수 있습니다.
프로그램에서 정의한 변수에는 이렇게 해도 괜찮지만, 사용자가 제공한 입력값에는 이렇게 하면 안 됩니다. 그렇지 않으면 쿼리가 SQL 인젝션에 취약해집니다.

출력 형식 구성

기본 출력 형식은 CSV이지만, output_format 매개변수로 변경할 수 있습니다. chDB는 ClickHouse 데이터 포맷과 자체 포맷 일부를 지원하며, 여기에는 Pandas 데이터프레임을 반환하는 DataFrame도 포함됩니다:
또는 Apache Arrow 테이블을 다시 가져오려면:

JSON 파일에서 테이블 생성하기

다음으로 chDB에서 테이블을 생성하는 방법을 살펴보겠습니다. 이를 위해서는 다른 API를 사용해야 하므로, 먼저 해당 API를 import하겠습니다:
다음으로 세션을 초기화하겠습니다. 세션을 디스크에 유지하려면 디렉터리 이름을 지정해야 합니다. 비워 두면 세션은 임시 상태가 됩니다. chDB는 데이터를 디스크의 임시 디렉터리에 보관하고 세션이 종료되면 삭제하므로 데이터가 유지되지 않습니다.
chDB는 프로세스당 하나의 내장 엔진만 실행하므로 데이터베이스 디렉터리(경로)에는 몇 가지 규칙이 적용됩니다:
  • 경로당 하나의 프로세스: chDB 데이터 디렉터리는 한 번에 하나의 운영 체제 프로세스만 열 수 있습니다. 첫 번째 프로세스가 닫힐 때까지 동일한 경로를 열려는 두 번째 프로세스는 실패합니다.
  • 프로세스당 하나의 경로: 세션 또는 연결이 열려 있는 동안 다른 경로에 대한 세션이나 연결을 추가로 열면 실패합니다. 오류를 방지하려면 먼저 열려 있는 세션이나 연결을 닫으십시오. 동일한 경로의 여러 세션이나 연결은 함께 사용할 수 있습니다.
  • 동시성: 동일한 경로의 세션이나 연결은 쿼리를 동시에 실행할 수 있습니다.
  • 경로 없는 세션은 공유됩니다: 경로를 지정하지 않으면 세션은 프로세스 전체에서 공유되는 :memory: 데이터베이스를 사용하므로 빈 세션에서도 서로의 테이블을 볼 수 있으며, 임시 디렉터리는 마지막 세션이 닫힐 때만 제거됩니다.
다음으로 데이터베이스를 생성합니다:
이제 CREATE...EMPTY AS 기법을 사용해 JSON 파일의 스키마를 기반으로 dislikes 테이블을 생성할 수 있습니다. 모든 컬럼 타입이 Nullable로 지정되지 않도록 schema_inference_make_columns_nullable 설정을 사용합니다.
그런 다음 DESCRIBE 절을 사용해 스키마를 살펴볼 수 있습니다:
다음으로, 해당 테이블에 데이터를 입력해 보겠습니다:
CREATE...AS 기법을 사용하면 이 두 단계를 한 번에 처리할 수도 있습니다. 이 기법을 사용해 다른 테이블을 만들어 보겠습니다:

테이블 쿼리하기

마지막으로, 테이블에 쿼리를 실행해 보겠습니다:
예를 들어, 좋아요와 싫어요의 비율을 계산하기 위해 DataFrame에 컬럼을 하나 더 추가한다고 가정해 보겠습니다. 다음과 같은 코드를 작성할 수 있습니다.

Pandas 데이터프레임 쿼리하기

이제 chDB에서 해당 데이터프레임을 쿼리할 수 있습니다:
Pandas 데이터프레임을 쿼리하는 방법에 대한 자세한 내용은 Pandas 데이터프레임 쿼리 개발자 가이드에서 확인할 수 있습니다.

다음 단계

이 가이드를 통해 chDB를 전반적으로 이해하는 데 도움이 되었기를 바랍니다. 사용 방법을 더 자세히 알아보려면 다음 개발자 가이드를 참조하십시오: