clickhouse-local - ClickHouse Documentation

`clickhouse-local`과 ClickHouse를 언제 사용해야 하나요?

clickhouse-local은 전체 데이터베이스 서버를 설치하지 않고도 SQL을 사용해 로컬 및 원격 파일을 빠르게 처리해야 하는 개발자에게 적합한, 사용하기 쉬운 ClickHouse 버전입니다. clickhouse-local을 사용하면 개발자는 명령줄에서 직접 SQL 명령을 사용할 수 있으며(ClickHouse SQL 방언 사용), 전체 ClickHouse를 설치하지 않고도 ClickHouse 기능을 간단하고 효율적으로 활용할 수 있습니다. clickhouse-local의 주요 장점 중 하나는 clickhouse-client를 설치할 때 이미 함께 포함된다는 점입니다. 즉, 복잡한 설치 과정 없이도 clickhouse-local을 빠르게 시작할 수 있습니다. clickhouse-local은 개발, 테스트, 파일 처리 용도로는 매우 유용하지만, 최종 사용자나 애플리케이션에 서비스를 제공하는 용도로는 적합하지 않습니다. 이런 경우에는 오픈소스 ClickHouse를 사용하는 것이 좋습니다. ClickHouse는 대규모 분석 워크로드를 처리하도록 설계된 강력한 OLAP 데이터베이스입니다. 대규모 데이터셋에 대한 복잡한 쿼리를 빠르고 효율적으로 처리하므로, 고성능이 중요한 프로덕션 환경에 적합합니다. 또한 ClickHouse는 복제(replication), 세그먼트 분할(sharding), 고가용성(high availability)과 같은 다양한 기능을 제공하며, 이러한 기능은 대규모 데이터셋을 처리하도록 확장하고 애플리케이션을 서비스하는 데 필수적입니다. 더 큰 데이터셋을 처리하거나 최종 사용자 또는 애플리케이션에 서비스를 제공해야 한다면 clickhouse-local 대신 오픈소스 ClickHouse를 사용하는 것이 좋습니다. 아래 문서를 읽고 로컬 파일 쿼리 또는 S3의 Parquet 파일 읽기와 같은 clickhouse-local의 예시 사용 사례를 확인하십시오.

clickhouse-local 다운로드

clickhouse-local은 ClickHouse 서버와 clickhouse-client를 실행할 때 사용하는 것과 동일한 clickhouse 바이너리로 실행됩니다. 최신 버전을 가장 쉽게 다운로드하는 방법은 다음 명령을 사용하는 것입니다:

curl https://clickhouse.com/ | sh

방금 다운로드한 실행 파일(binary)로 다양한 ClickHouse 도구와 유틸리티를 실행할 수 있습니다. ClickHouse를 데이터베이스 서버로 실행하려면 Quick Start를 참조하십시오.

SQL을 사용해 파일의 데이터를 쿼리하기

clickhouse-local의 일반적인 용도 중 하나는 파일에 대해 애드혹 쿼리를 실행하는 것입니다. 즉, 데이터를 테이블에 삽입할 필요가 없습니다. clickhouse-local은 파일의 데이터를 임시 테이블로 스트리밍한 뒤 SQL을 실행할 수 있습니다. 파일이 clickhouse-local이 실행되는 동일한 머신에 있으면 로드할 파일만 지정하면 됩니다. 다음 reviews.tsv 파일에는 Amazon 제품 리뷰 샘플이 포함되어 있습니다:

./clickhouse local -q "SELECT * FROM 'reviews.tsv'"

이 명령은 다음 명령의 축약형입니다:

./clickhouse local -q "SELECT * FROM file('reviews.tsv')"

ClickHouse는 파일 이름 확장자를 보고 해당 파일이 탭으로 구분된 포맷을 사용한다는 것을 알 수 있습니다. 포맷을 명시적으로 지정해야 한다면 다양한 ClickHouse 입력 형식 중 하나를 추가하면 됩니다:

./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"

file 테이블 함수는 테이블을 생성하고, DESCRIBE를 사용해 추론된 스키마(schema)를 확인할 수 있습니다:

./clickhouse local -q "DESCRIBE file('reviews.tsv')"

파일 이름에서 글롭 패턴을 사용할 수 있습니다(글롭 치환 참조).예시:

./clickhouse local -q "SELECT * FROM 'reviews*.jsonl'"
./clickhouse local -q "SELECT * FROM 'review_?.csv'"
./clickhouse local -q "SELECT * FROM 'review_{1..3}.csv'"

marketplace    Nullable(String)
customer_id    Nullable(Int64)
review_id    Nullable(String)
product_id    Nullable(String)
product_parent    Nullable(Int64)
product_title    Nullable(String)
product_category    Nullable(String)
star_rating    Nullable(Int64)
helpful_votes    Nullable(Int64)
total_votes    Nullable(Int64)
vine    Nullable(String)
verified_purchase    Nullable(String)
review_headline    Nullable(String)
review_body    Nullable(String)
review_date    Nullable(Date)

평점이 가장 높은 상품을 찾아보겠습니다:

./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"

Monopoly Junior Board Game    5

AWS S3의 Parquet 파일에서 데이터 쿼리하기

S3에 파일이 있으면 clickhouse-local과 s3 테이블 함수를 사용해 해당 파일을 직접 쿼리할 수 있습니다(데이터를 ClickHouse 테이블에 삽입하지 않음). 공개 버킷에 영국에서 판매된 부동산의 주택 가격이 들어 있는 house_0.parquet 파일이 있습니다. 이 파일에 몇 개의 행이 있는지 살펴보겠습니다:

./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

파일에는 270만 행이 있습니다:

파일을 기반으로 ClickHouse가 추론한 스키마가 무엇인지 확인하는 것은 언제나 유용합니다:

./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

price    Nullable(Int64)
date    Nullable(UInt16)
postcode1    Nullable(String)
postcode2    Nullable(String)
type    Nullable(String)
is_new    Nullable(UInt8)
duration    Nullable(String)
addr1    Nullable(String)
addr2    Nullable(String)
street    Nullable(String)
locality    Nullable(String)
town    Nullable(String)
district    Nullable(String)
county    Nullable(String)

가장 비싼 지역이 어디인지 살펴보겠습니다:

./clickhouse local -q "
SELECT
    town,
    district,
    count() AS c,
    round(avg(price)) AS price,
    bar(price, 0, 5000000, 100)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')
GROUP BY
    town,
    district
HAVING c >= 100
ORDER BY price DESC
LIMIT 10"

LONDON    CITY OF LONDON    886    2271305    █████████████████████████████████████████████▍
LEATHERHEAD    ELMBRIDGE    206    1176680    ███████████████████████▌
LONDON    CITY OF WESTMINSTER    12577    1108221    ██████████████████████▏
LONDON    KENSINGTON AND CHELSEA    8728    1094496    █████████████████████▉
HYTHE    FOLKESTONE AND HYTHE    130    1023980    ████████████████████▍
CHALFONT ST GILES    CHILTERN    113    835754    ████████████████▋
AMERSHAM    BUCKINGHAMSHIRE    113    799596    ███████████████▉
VIRGINIA WATER    RUNNYMEDE    356    789301    ███████████████▊
BARNET    ENFIELD    282    740514    ██████████████▊
NORTHWOOD    THREE RIVERS    184    731609    ██████████████▋

파일을 ClickHouse에 삽입할 준비가 되면 ClickHouse 서버를 시작한 다음, file 및 s3 테이블 함수의 결과를 MergeTree 테이블에 삽입하세요. 자세한 내용은 Quick Start를 참조하십시오.

포맷 변환

clickhouse-local을 사용해 서로 다른 포맷 간에 데이터를 변환할 수 있습니다. 예시:

$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv

포맷은 파일 확장자를 기준으로 자동 감지됩니다:

$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv

간단히는 --copy 인수를 사용해 작성할 수 있습니다:

$ clickhouse-local --copy < data.json > data.csv

사용법

기본적으로 clickhouse-local은 동일한 호스트에서 실행 중인 ClickHouse 서버의 데이터에 접근할 수 있으며, 서버 구성에 의존하지 않습니다. 또한 --config-file 인수를 사용해 서버 구성을 로드할 수도 있습니다. 임시 데이터의 경우 기본적으로 고유한 임시 데이터 디렉터리가 생성됩니다. 기본 사용법(Linux):

$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

기본 사용법 (Mac):

$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

clickhouse-local은 WSL2를 통해 Windows에서도 지원됩니다.

인수:

-S, --structure — 입력 데이터의 테이블 구조입니다.
--input-format — 입력 형식이며, 기본값은 TSV입니다.
-F, --file — 데이터 경로이며, 기본값은 stdin입니다.
-q, --query — ;를 구분자로 사용해 실행할 쿼리입니다. --query는 여러 번 지정할 수 있습니다. 예: --query "SELECT 1" --query "SELECT 2". --queries-file과 동시에 사용할 수 없습니다.
--queries-file - 실행할 쿼리가 들어 있는 파일 경로입니다. --queries-file은 여러 번 지정할 수 있습니다. 예: --query queries1.sql --query queries2.sql. --query와 동시에 사용할 수 없습니다.
--multiquery, -n – 지정하면 세미콜론으로 구분된 여러 쿼리를 --query 옵션 뒤에 나열할 수 있습니다. 편의를 위해 --query를 생략하고 쿼리를 --multiquery 뒤에 직접 전달할 수도 있습니다.
-N, --table — 출력 데이터를 넣을 테이블 이름이며, 기본값은 table입니다.
-f, --format, --output-format — 출력 형식이며, 기본값은 TSV입니다.
-d, --database — 기본 데이터베이스이며, 기본값은 _local입니다.
--stacktrace — 예외 발생 시 디버그 출력을 덤프할지 여부입니다.
--echo [ <bool> ] — 실행 전에 각 쿼리를 출력합니다. 선택적 불리언 값을 받습니다. 대화형 모드에서는 기본적으로 활성화되고 batch mode에서는 비활성화됩니다. 참고: 이제 --echo는 선택적 값을 받으므로, 값 없이 사용한 --echo 바로 뒤에 위치 인수 쿼리를 두면 그 쿼리가 값으로 처리됩니다. 대신 --echo --query "...", --echo -q "...", --echo=false 또는 파이프로 전달된 stdin을 사용하십시오.
--echo-formatted [ <bool> ] — 출력되는 쿼리를 포맷합니다. 선택적 불리언 값을 받습니다. 대화형 모드에서는 기본적으로 활성화되고 batch mode에서는 비활성화됩니다.
--echo-query-id [ <bool> ] — 실행 전에 query_id를 출력합니다. 선택적 불리언 값을 받습니다. 대화형 모드에서는 기본적으로 활성화되고 batch mode에서는 비활성화됩니다.
--echo-query-separator <string> — 포맷된 출력 쿼리 앞에 이 구분자를 출력합니다(--echo-formatted 필요). 이렇게 하면 직접 입력한 쿼리와 다시 포맷되어 출력된 쿼리를 더 쉽게 구분할 수 있습니다. 기본값은 빈 문자열(비활성화)입니다.
--highlight, --hilite <bool> — 명령 프롬프트와 출력되는 쿼리의 구문 강조를 전환합니다. 기본적으로 활성화됩니다. 강조는 터미널에 출력할 때만 적용됩니다.
--hints <bool> — 커서가 입력 끝에 있을 때 가장 잘 일치하는 제안에 대해 입력 중 자동 완성 힌트(인라인 “ghost” 텍스트)를 표시합니다. 위/아래(또는 Ctrl-Up/Ctrl-Down)로 힌트를 탐색할 수 있으며, Tab 또는 Right로 인라인 힌트를 수락할 수 있습니다. Enter는 힌트가 명시적으로 선택된 경우에만 해당 힌트를 수락하고, 그렇지 않으면 쿼리를 실행합니다. Tab은 기존 완성 목록도 엽니다. --highlight가 필요하며(힌트에는 색상이 필요함), 제안 기능도 필요합니다(따라서 --disable_suggestion도 이를 비활성화합니다). 기본적으로 활성화됩니다.
--verbose — 쿼리 실행에 대한 자세한 정보를 표시합니다.
--logger.console — 콘솔에 로그를 기록합니다.
--logger.log — 로그 파일 이름입니다.
--logger.level — 로그 수준입니다.
--ignore-error — 쿼리가 실패해도 처리를 중단하지 않습니다.
-c, --config-file — ClickHouse 서버와 동일한 형식의 설정 파일 경로이며, 기본적으로 구성은 비어 있습니다.
--no-system-tables — system tables을 ATTACH하지 않습니다.
--help — clickhouse-local의 인수 참고입니다.
-V, --version — 버전 정보를 출력하고 종료합니다.

또한 --config-file 대신 더 자주 사용되는, 각 ClickHouse 구성 변수에 대응하는 인수도 있습니다。

명령어

LS 명령

clickhouse-local이 접근할 수 있는 현재 작업 디렉터리의 모든 파일을 나열합니다. 다음과 같이 interactive mode에서 실행할 수 있습니다:

Query

ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC

Response

┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

인수 -q를 사용해 쿼리로도 실행할 수 있습니다:

./clickhouse-local -q ls

Response

file1.csv
file2.json
file3.xml

CLEAR 명령

터미널 화면을 지웁니다(Linux의 clear 명령이나 많은 터미널에서의 Ctrl+L과 유사함). 이는 클라이언트 측 동작이며 SQL 엔진으로 전송되지 않습니다. clickhouse-local에서는 메타 명령이 대화형 모드와 -q 및 --queries-file 입력에서 인식됩니다(-q와 동일한 클라이언트 경로를 사용하며, ls와 같은 방식임). 따라서 clear만 단독으로 입력해도 UNKNOWN_IDENTIFIER 오류가 발생하지 않습니다. 원격 clickhouse-client --queries-file 동작은 변경되지 않습니다. 파일 내용은 SQL로만 실행되며(텍스트 수준 메타 명령은 없음), 메타 명령은 처리되지 않습니다. clickhouse-client에서는 대화형 모드에서만 인식됩니다. -q 또는 쿼리 파일과 함께 사용할 때 clear는 여전히 SQL로 해석되므로, 자동화에서는 오타가 조용히 아무 작업도 하지 않는 동작으로 바뀌지 않고 기존 오류 동작이 유지됩니다. 지원되는 형식: clear, CLEAR, /clear(끝의 선택적 ;는 무시됨). 표준 출력이 터미널이 아닌 경우(예: 출력을 파이프로 전달하는 경우) 메타 명령은 인식되면 허용되지만 제어 시퀀스를 출력하지 않습니다. clickhouse-local에서 -q를 사용할 때:

./clickhouse-local -q clear

예시

Query

$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Read 2 rows, 32.00 B in 0.000 sec., 5182 rows/sec., 80.97 KiB/sec.
1   2
3   4

이전 예시는 다음과 동일합니다:

Query

$ echo -e "1,2\n3,4" | clickhouse-local -n --query "
    CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin);
    SELECT a, b FROM table;
    DROP TABLE table;"
Read 2 rows, 32.00 B in 0.000 sec., 4987 rows/sec., 77.93 KiB/sec.
1   2
3   4

stdin 또는 --file 인수를 반드시 사용할 필요는 없으며, file 테이블 함수를 사용해 파일을 원하는 만큼 열 수 있습니다:

Query

$ echo 1 | tee 1.tsv
1

$ echo 2 | tee 2.tsv
2

$ clickhouse-local --query "
    select * from file('1.tsv', TSV, 'a int') t1
    cross join file('2.tsv', TSV, 'b int') t2"
1    2

이제 각 Unix 사용자별로 memory 사용자를 출력해 보겠습니다:

Query

$ ps aux | tail -n +2 | awk '{ printf("%s\t%s\n", $1, $4) }' \
    | clickhouse-local --structure "user String, mem Float64" \
        --query "SELECT user, round(sum(mem), 2) as memTotal
            FROM table GROUP BY user ORDER BY memTotal DESC FORMAT Pretty"

Response

Read 186 rows, 4.15 KiB in 0.035 sec., 5302 rows/sec., 118.34 KiB/sec.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...

Starting TCP and HTTP Listeners

clickhouse-local은 TCP(네이티브 프로토콜) 및 HTTP 연결을 받을 수 있는 경량 서버로 전환할 수 있습니다. 이는 실행 중인 clickhouse-local 인스턴스의 데이터베이스와 테이블에 다른 ClickHouse 도구나 애플리케이션이 접근할 수 있도록 하려는 경우에 유용합니다. 각 들어오는 연결에는 자체 세션이 할당된다는 점에 유의하십시오. 따라서 대화형 clickhouse-local 세션의 임시 테이블과 세션 수준 설정은 외부 연결에서 볼 수 없습니다. 리스너를 열려면 SYSTEM START LISTEN을 사용하고, 닫으려면 SYSTEM STOP LISTEN을 사용하십시오:

clickhouse-local \
    --listen_host 127.0.0.1 \
    --tcp_port 9000 \
    --http_port 8123 \
    --query "
        SYSTEM START LISTEN TCP;
        SYSTEM START LISTEN HTTP;
        SELECT * FROM url('http://127.0.0.1:8123/?query=SELECT+42', LineAsString);
        SYSTEM STOP LISTEN TCP;
        SYSTEM STOP LISTEN HTTP;
    "

--listen_host, --tcp_port, --http_port 옵션은 바인드 주소와 포트를 설정합니다. 기본 포트는 TCP의 경우 9000, HTTP의 경우 8123입니다.

보안기본적으로 clickhouse-local은 임시 사용자 설정으로 실행되므로, 열리는 모든 리스너는 인증 없이 열립니다. users_config 설정이 사용자 지정 users.xml을 가리키도록 지정하여(예: --config-file 사용) 사용자와 액세스 제어(access control)를 명시적으로 구성한 경우가 아니라면 루프백 주소(127.0.0.1 또는 ::1)에 바인딩하십시오. 인증 없이 비루프백 주소에서 수신하면, 선택한 포트에 접근할 수 있는 누구에게나 로컬 인스턴스의 데이터가 노출됩니다.

​clickhouse-local과 ClickHouse를 언제 사용해야 하나요?

​clickhouse-local 다운로드

​SQL을 사용해 파일의 데이터를 쿼리하기

​AWS S3의 Parquet 파일에서 데이터 쿼리하기

​포맷 변환

​사용법

​명령어

​LS 명령

​CLEAR 명령

​예시

​Starting TCP and HTTP Listeners

​관련 콘텐츠

`clickhouse-local`과 ClickHouse를 언제 사용해야 하나요?

clickhouse-local 다운로드

SQL을 사용해 파일의 데이터를 쿼리하기

AWS S3의 Parquet 파일에서 데이터 쿼리하기

포맷 변환

사용법

명령어

LS 명령

CLEAR 명령

예시

Starting TCP and HTTP Listeners

관련 콘텐츠