Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

chDB 시작하기

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

환경 설정

먼저 가상 환경을 생성합니다:

python -m venv .venv
source .venv/bin/activate

이제 chDB를 설치합니다. 버전 2.0.3 이상인지 확인하세요:

pip install "chdb>=2.0.2"

이제 ipython을 설치하겠습니다:

pip install ipython

이 가이드의 나머지 부분에서 명령을 실행할 때는 ipython을 사용합니다. 다음을 실행하여 시작할 수 있습니다:

ipython

이 가이드에서는 Pandas와 Apache Arrow도 사용하므로, 해당 라이브러리도 함께 설치하세요:

pip install pandas pyarrow

S3의 JSON 파일 쿼리하기

이제 S3 버킷에 저장된 JSON 파일을 어떻게 쿼리하는지 살펴보겠습니다. YouTube dislikes 데이터셋에는 2021년까지 YouTube 동영상의 dislikes에 대한 40억 개 이상의 행이 포함되어 있습니다. 이 데이터셋에 포함된 JSON 파일 중 하나를 사용하겠습니다.

chdb를 가져옵니다:

import chdb

다음 쿼리를 사용하여 JSON 파일 하나의 구조를 확인할 수 있습니다:

chdb.query(
  """
  DESCRIBE s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )
  SETTINGS describe_compact_output=1
  """
)
"id","Nullable(String)"
"fetch_date","Nullable(String)"
"upload_date","Nullable(String)"
"title","Nullable(String)"
"uploader_id","Nullable(String)"
"uploader","Nullable(String)"
"uploader_sub_count","Nullable(Int64)"
"is_age_limit","Nullable(Bool)"
"view_count","Nullable(Int64)"
"like_count","Nullable(Int64)"
"dislike_count","Nullable(Int64)"
"is_crawlable","Nullable(Bool)"
"is_live_content","Nullable(Bool)"
"has_subtitles","Nullable(Bool)"
"is_ads_enabled","Nullable(Bool)"
"is_comments_enabled","Nullable(Bool)"
"description","Nullable(String)"
"rich_metadata","Array(Tuple(
    call Nullable(String),
    content Nullable(String),
    subtitle Nullable(String),
    title Nullable(String),
    url Nullable(String)))"
"super_titles","Array(Tuple(
    text Nullable(String),
    url Nullable(String)))"
"uploader_badges","Nullable(String)"
"video_badges","Nullable(String)"

해당 파일에 있는 행 수를 셀 수도 있습니다:

chdb.query(
  """
  SELECT count()
  FROM s3(
    's3://clickhouse-public-datasets/youtube/original/files/' ||
    'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
    'JSONLines'
  )"""
)
336432

이 파일에는 300,000개를 조금 넘는 레코드가 들어 있습니다.

chdb는 아직 쿼리 매개변수를 전달하는 기능을 지원하지 않지만, 경로를 추출해 f-String으로 전달할 수 있습니다.

path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'
chdb.query(
  f"""
  SELECT count()
  FROM s3('{path}','JSONLines')
  """
)

출력 형식 구성

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

result = chdb.query(
  f"""
  SELECT is_ads_enabled, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="DataFrame"
)

print(type(result))
print(result)
<class 'pandas.core.frame.DataFrame'>
   is_ads_enabled  count()
0           False   301125
1            True    35307

또는 Apache Arrow 테이블을 다시 가져오려면:

result = chdb.query(
  f"""
  SELECT is_live_content, count()
  FROM s3('{path}','JSONLines')
  GROUP BY ALL
  """,
  output_format="ArrowTable"
)

print(type(result))
print(result)
<class 'pyarrow.lib.Table'>
pyarrow.Table
is_live_content: bool
count(): uint64 not null
----
is_live_content: [[false,true]]
count(): [[315746,20686]]

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

다음으로 chDB에서 테이블을 생성하는 방법을 살펴보겠습니다. 이를 위해서는 다른 API를 사용해야 하므로, 먼저 해당 API를 import하겠습니다:

from chdb import session as chs

다음으로 세션을 초기화하겠습니다. 세션을 디스크에 유지하려면 디렉터리 이름을 지정해야 합니다. 비워 두면 세션은 임시 상태가 됩니다. chDB는 데이터를 디스크의 임시 디렉터리에 보관하고 세션이 종료되면 삭제하므로 데이터가 유지되지 않습니다.

sess = chs.Session("gettingStarted.chdb")

다음으로 데이터베이스를 생성합니다:

sess.query("CREATE DATABASE IF NOT EXISTS youtube")

이제 CREATE...EMPTY AS 기법을 사용해 JSON 파일의 스키마를 기반으로 dislikes 테이블을 생성할 수 있습니다. 모든 컬럼 타입이 Nullable로 지정되지 않도록 schema_inference_make_columns_nullable 설정을 사용합니다.

sess.query(f"""
  CREATE TABLE youtube.dislikes
  ORDER BY fetch_date 
  EMPTY AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

그런 다음 DESCRIBE 절을 사용해 스키마를 살펴볼 수 있습니다:

sess.query(f"""
   DESCRIBE youtube.dislikes
   SETTINGS describe_compact_output=1
   """
)
"id","String"
"fetch_date","String"
"upload_date","String"
"title","String"
"uploader_id","String"
"uploader","String"
"uploader_sub_count","Int64"
"is_age_limit","Bool"
"view_count","Int64"
"like_count","Int64"
"dislike_count","Int64"
"is_crawlable","Bool"
"is_live_content","Bool"
"has_subtitles","Bool"
"is_ads_enabled","Bool"
"is_comments_enabled","Bool"
"description","String"
"rich_metadata","Array(Tuple(
    call String,
    content String,
    subtitle String,
    title String,
    url String))"
"super_titles","Array(Tuple(
    text String,
    url String))"
"uploader_badges","String"
"video_badges","String"

다음으로, 해당 테이블에 데이터를 입력해 보겠습니다:

sess.query(f"""
  INSERT INTO youtube.dislikes
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

CREATE...AS 기법을 사용하면 이 두 단계를 한 번에 처리할 수도 있습니다. 이 기법을 사용해 다른 테이블을 만들어 보겠습니다:

sess.query(f"""
  CREATE TABLE youtube.dislikes2
  ORDER BY fetch_date 
  AS 
  SELECT * 
  FROM s3('{path}','JSONLines')
  SETTINGS schema_inference_make_columns_nullable=0
  """
)

테이블 쿼리하기

마지막으로, 테이블에 쿼리를 실행해 보겠습니다:

df = sess.query("""
  SELECT uploader, sum(view_count) AS viewCount, sum(like_count) AS likeCount, sum(dislike_count) AS dislikeCount
  FROM youtube.dislikes
  GROUP BY ALL
  ORDER BY viewCount DESC
  LIMIT 10
  """,
  "DataFrame"
)
df
                             uploader  viewCount  likeCount  dislikeCount
0                             Jeremih  139066569     812602         37842
1                     TheKillersMusic  109313116     529361         11931
2  LetsGoMartin- Canciones Infantiles  104747788     236615        141467
3                    Xiaoying Cuisine   54458335    1031525         37049
4                                Adri   47404537     279033         36583
5                  Diana and Roma IND   43829341     182334        148740
6                      ChuChuTV Tamil   39244854     244614        213772
7                            Cheez-It   35342270        108            27
8                            Anime Uz   33375618    1270673         60013
9                    RC Cars OFF Road   31952962     101503         49489

예를 들어, 좋아요와 싫어요의 비율을 계산하기 위해 DataFrame에 컬럼을 하나 더 추가한다고 가정해 보겠습니다. 다음과 같은 코드를 작성할 수 있습니다.

df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]

Pandas 데이터프레임 쿼리하기

이제 chDB에서 해당 데이터프레임을 쿼리할 수 있습니다:

chdb.query(
  """
  SELECT uploader, likeDislikeRatio
  FROM Python(df)
  """,
  output_format="DataFrame"
)
                             uploader  likeDislikeRatio
0                             Jeremih         21.473548
1                     TheKillersMusic         44.368536
2  LetsGoMartin- Canciones Infantiles          1.672581
3                    Xiaoying Cuisine         27.842182
4                                Adri          7.627395
5                  Diana and Roma IND          1.225857
6                      ChuChuTV Tamil          1.144275
7                            Cheez-It          4.000000
8                            Anime Uz         21.173296
9                    RC Cars OFF Road          2.051021

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

다음 단계

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

Navigation