> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# chDB 시작하기
> chDB는 ClickHouse 기반의 인프로세스 SQL OLAP Engine입니다
이 가이드에서는 chDB의 Python 버전을 사용해 시작하는 방법을 살펴봅니다.
먼저 S3의 JSON 파일에 쿼리한 다음, 해당 JSON 파일을 기반으로 chDB에 테이블을 만들고 데이터에 대해 몇 가지 쿼리를 수행합니다.
또한 Apache Arrow와 Pandas를 포함한 다양한 포맷으로 쿼리 결과를 반환하는 방법도 살펴보고, 마지막으로 Pandas DataFrame에 쿼리하는 방법을 알아봅니다.
## 준비
먼저 가상 환경을 생성합니다:
```bash theme={null}
python -m venv .venv
source .venv/bin/activate
```
이제 chDB를 설치합니다.
버전 2.0.3 이상이 설치되어 있는지 확인하십시오:
```bash theme={null}
pip install "chdb>=2.0.2"
```
이제 [ipython](https://ipython.org/)을 설치하겠습니다:
```bash theme={null}
pip install ipython
```
이 가이드의 나머지 부분에서는 명령 실행에 `ipython`을 사용하며, 다음을 실행해 시작할 수 있습니다:
```bash theme={null}
ipython
```
이 가이드에서는 Pandas와 Apache Arrow도 사용하므로 이 라이브러리들도 설치하겠습니다:
```bash theme={null}
pip install pandas pyarrow
```
## S3의 JSON 파일 쿼리하기
이제 S3 버킷에 저장된 JSON 파일을 쿼리하는 방법을 살펴보겠습니다.
[YouTube dislikes 데이터셋](/ko/get-started/sample-datasets/youtube-dislikes)에는 2021년까지 YouTube 동영상의 싫어요 데이터가 40억 행 이상 포함되어 있습니다.
이 데이터셋에 포함된 JSON 파일 중 하나를 사용하겠습니다.
chdb를 임포트합니다:
```python theme={null}
import chdb
```
다음과 같은 쿼리를 작성하여 JSON 파일 중 하나의 구조를 확인할 수 있습니다:
```python theme={null}
chdb.query(
"""
DESCRIBE s3(
's3://clickhouse-public-datasets/youtube/original/files/' ||
'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
'JSONLines'
)
SETTINGS describe_compact_output=1
"""
)
```
```text theme={null}
"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)"
```
해당 파일의 행 수도 셀 수 있습니다:
```python theme={null}
chdb.query(
"""
SELECT count()
FROM s3(
's3://clickhouse-public-datasets/youtube/original/files/' ||
'youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst',
'JSONLines'
)"""
)
```
```text theme={null}
336432
```
이 파일에는 300,000개가 약간 넘는 레코드가 들어 있습니다.
chdb는 아직 쿼리 매개변수를 전달하는 기능을 지원하지 않지만, 경로를 추출해 f-String으로 전달할 수 있습니다.
```python theme={null}
path = 's3://clickhouse-public-datasets/youtube/original/files/youtubedislikes_20211127161229_18654868.1637897329_vid.json.zst'
```
```python theme={null}
chdb.query(
f"""
SELECT count()
FROM s3('{path}','JSONLines')
"""
)
```
프로그램에서 정의한 변수에는 이렇게 해도 괜찮지만, 사용자 입력값에는 이렇게 하면 안 됩니다. 그렇지 않으면 쿼리가 SQL 인젝션에 취약해집니다.
## 출력 형식 설정
기본 출력 형식은 `CSV`이지만 `output_format` 매개변수로 변경할 수 있습니다.
chDB는 ClickHouse 데이터 포맷과 [자체 포맷 일부](/ko/products/chdb/reference/data-formats)를 지원하며, 여기에는 Pandas 데이터프레임을 반환하는 `DataFrame`도 포함됩니다:
```python theme={null}
result = chdb.query(
f"""
SELECT is_ads_enabled, count()
FROM s3('{path}','JSONLines')
GROUP BY ALL
""",
output_format="DataFrame"
)
print(type(result))
print(result)
```
```text theme={null}
is_ads_enabled count()
0 False 301125
1 True 35307
```
또는 Apache Arrow 테이블로 가져오려면:
```python theme={null}
result = chdb.query(
f"""
SELECT is_live_content, count()
FROM s3('{path}','JSONLines')
GROUP BY ALL
""",
output_format="ArrowTable"
)
print(type(result))
print(result)
```
```text theme={null}
pyarrow.Table
is_live_content: bool
count(): uint64 not null
----
is_live_content: [[false,true]]
count(): [[315746,20686]]
```
## JSON 파일에서 테이블 생성하기
다음으로, chDB에서 테이블을 생성하는 방법을 살펴보겠습니다.
이를 위해서는 다른 API를 사용해야 하므로, 먼저 해당 API를 import하겠습니다:
```python theme={null}
from chdb import session as chs
```
다음으로 세션을 초기화하겠습니다.
세션을 디스크에 유지하려면 디렉터리 이름을 지정해야 합니다.
비워 두면 데이터베이스는 메모리에만 존재하며 Python 프로세스를 종료하는 즉시 사라집니다.
```python theme={null}
sess = chs.Session("gettingStarted.chdb")
```
다음으로 데이터베이스를 생성하겠습니다:
```python theme={null}
sess.query("CREATE DATABASE IF NOT EXISTS youtube")
```
이제 `CREATE...EMPTY AS` 기법을 사용해 JSON 파일의 스키마를 기반으로 `dislikes` 테이블을 생성할 수 있습니다.
모든 컬럼 타입이 `Nullable`로 지정되지 않도록 [`schema_inference_make_columns_nullable`](/ko/reference/settings/formats#schema_inference_make_columns_nullable) 설정을 사용하겠습니다.
```python theme={null}
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` 절을 사용해 스키마를 살펴볼 수 있습니다:
```python theme={null}
sess.query(f"""
DESCRIBE youtube.dislikes
SETTINGS describe_compact_output=1
"""
)
```
```text theme={null}
"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"
```
다음으로, 해당 테이블에 데이터를 채워 넣어 보겠습니다:
```python theme={null}
sess.query(f"""
INSERT INTO youtube.dislikes
SELECT *
FROM s3('{path}','JSONLines')
SETTINGS schema_inference_make_columns_nullable=0
"""
)
```
`CREATE...AS` 기법을 사용하면 이 두 단계도 한 번에 수행할 수 있습니다.
이 기법을 사용해 다른 테이블을 만들어보겠습니다:
```python theme={null}
sess.query(f"""
CREATE TABLE youtube.dislikes2
ORDER BY fetch_date
AS
SELECT *
FROM s3('{path}','JSONLines')
SETTINGS schema_inference_make_columns_nullable=0
"""
)
```
## 테이블 쿼리하기
마지막으로, 테이블을 쿼리해 보겠습니다:
```sql theme={null}
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
```
```text theme={null}
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에 컬럼을 하나 더 추가한다고 가정해 보겠습니다.
다음과 같은 코드를 작성할 수 있습니다:
```python theme={null}
df["likeDislikeRatio"] = df["likeCount"] / df["dislikeCount"]
```
## Pandas 데이터프레임 쿼리하기
이후 chDB에서 해당 DataFrame을 쿼리할 수 있습니다:
```python theme={null}
chdb.query(
"""
SELECT uploader, likeDislikeRatio
FROM Python(df)
""",
output_format="DataFrame"
)
```
```text theme={null}
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 DataFrame 쿼리에 대한 자세한 내용은 [Pandas DataFrame 쿼리](/ko/products/chdb/guides/querying-pandas) 개발자 가이드에서 확인할 수 있습니다.
## 다음 단계
이 가이드를 통해 chDB를 전반적으로 이해하는 데 도움이 되었기를 바랍니다.
사용 방법을 더 자세히 알아보려면 다음 개발자 가이드를 참조하십시오.
* [Pandas DataFrame 쿼리하기](/ko/products/chdb/guides/querying-pandas)
* [Apache Arrow 쿼리하기](/ko/products/chdb/guides/querying-apache-arrow)
* [JupySQL에서 chDB 사용하기](/ko/products/chdb/guides/jupysql)
* [기존 clickhouse-local 데이터베이스와 함께 chDB 사용하기](/ko/products/chdb/guides/clickhouse-local)