ClickHouse HOLs
GitHub

Hands-on ClickHouse labsClickHouse 실습 랩

One directory per ClickHouse release, plus Cloud integrations, workload experiments and workshops. Every lab brings up what it needs, generates its own data, and can be run on its own.ClickHouse 릴리스마다 디렉토리 하나, 여기에 Cloud 연동·워크로드 실험·워크숍을 더했습니다. 각 랩은 필요한 환경을 스스로 띄우고 테스트 데이터를 생성하므로 독립적으로 실행됩니다.

21release labs릴리스 랩
25.1 → 26.9versions covered다루는 버전
76runnable SQL labs실행 가능한 SQL 랩

Release labs릴리스 랩

Each directory holds runnable SQL for that version's new features, with a bilingual guide.각 디렉토리에는 해당 버전 신기능의 실행 가능한 SQL과 영/한 가이드가 들어 있습니다.

Version버전Released출시일Labs랩Verified검증Features covered다루는 기능
26.9 2026-09-21 4 26.9.1.1629 LIMIT ... AFTER / UNTIL, keyValuePairs text index tokenizer, ZSTD(3) as the default codec, CREATE TOKEN + scoped GRANTSLIMIT ... AFTER / UNTIL, keyValuePairs 텍스트 인덱스 토크나이저, 기본 코덱 ZSTD(3), CREATE TOKEN + 범위 제한 GRANTS
26.8 2026-08-30 3 26.8.2.7 Pipe operators |>, GROUPS window frame mode, japanese / chinese / icu tokenizers파이프 연산자 |>, GROUPS 윈도우 프레임, japanese·chinese·icu 토크나이저
26.7 2026-07-22 3 26.7.1 EXPLAIN ANALYZE, AT TIME ZONE / AT LOCAL, groupFormat + -Tuple combinatorEXPLAIN ANALYZE, AT TIME ZONE / AT LOCAL, groupFormat + -Tuple 조합자
26.6 2026-06-25 3 26.6.2 Hypothetical indexes + EXPLAIN WHATIF, ADD ENUM VALUES, SQL compatibility (SOME/ALL, * LIKE, ESCAPE, date_part)가상 인덱스 + EXPLAIN WHATIF, ADD ENUM VALUES, SQL 호환성 (SOME/ALL, * LIKE, ESCAPE, date_part)
26.5 2026-05-21 3 26.5.1.882 filesystem() table function, bare function names + isPrime, tokenizeQuery / highlightQueryfilesystem() 테이블 함수, 베어 함수 이름 + isPrime, tokenizeQuery / highlightQuery
26.4 2026-04-30 3 26.4.3.37 NATURAL JOIN on VALUES, array functions, string/text functionsVALUES에 대한 NATURAL JOIN, 배열 함수, 문자열/텍스트 함수
26.3 2026-03-26 3 26.3.12.3 Materialized CTE, natural sort key, Unicode functions구체화 CTE, 자연 정렬 키, 유니코드 함수
26.2 2026-02-26 3 26.2.19.43 primes() function, XXH3-128 hash, system.tokenizersprimes() 함수, XXH3-128 해시, system.tokenizers
26.1 2026-01-29 3 26.1.12.23 reverseBySeparator, text index for arrays, Keeper HTTP APIreverseBySeparator, 배열 텍스트 인덱스, Keeper HTTP API
25.12 2025-12-18 3 25.12.11.4 HMAC function, Naive Bayes classifier, JOIN order optimization (DPSize)HMAC 함수, 나이브 베이즈 분류기, JOIN 순서 최적화 (DPSize)
25.11 2025-11-27 4 25.11.2.24 HAVING without GROUP BY, fractional LIMIT, Map aggregation, geometry functionsGROUP BY 없는 HAVING, 소수 LIMIT, Map 집계, 기하 함수
25.10 2025-10-30 5 25.10.7.6 QBit vector search, negative LIMIT/OFFSET, JOIN improvements, LIMIT BY ALL, auto statisticsQBit 벡터 검색, 음수 LIMIT/OFFSET, JOIN 개선, LIMIT BY ALL, 자동 통계
25.9 2025-09-25 4 25.9.7.56 Global join reordering, text index, streaming secondary indices, arrayExcept전역 조인 재정렬, 텍스트 인덱스, 스트리밍 보조 인덱스, arrayExcept
25.8 2025-08-28 6 25.8.28.1 New Parquet reader, hive partitioning, temp data on S3, UNION ALL _table, data lake features, MinIO신규 Parquet 리더, hive 파티셔닝, S3 임시 데이터, UNION ALL _table, 데이터 레이크, MinIO
25.7 2025-07-24 4 25.7.8.71 SQL UPDATE/DELETE, count() optimization, JOIN performance, bulk UPDATESQL UPDATE/DELETE, count() 최적화, JOIN 성능, 대량 UPDATE
25.6 2025-06-26 5 25.6.13.41 CoalescingMergeTree, Time/Time64 types, Bech32 encoding, lag/lead, consistent snapshotCoalescingMergeTree, Time/Time64 타입, Bech32 인코딩, lag/lead, 일관된 스냅샷
25.5 2025-05-22 5 25.5.11.15 Vector similarity index, Hive Metastore catalog, implicit table, new functions, geo types in Parquet벡터 유사도 인덱스, Hive Metastore 카탈로그, 암시적 테이블, 신규 함수, Parquet 지오 타입
25.4 2025-04-30 3 25.4.13.22 Array Levenshtein distance, sparseGrams, toInterval and editable database comments배열 Levenshtein 거리, sparseGrams, toInterval과 수정 가능한 DB 코멘트
25.3 2025-03-20 3 25.3.14.14 New functions (arraySymmetricDifference, keccak256), query condition cache, estimateCompressionRatio신규 함수(arraySymmetricDifference, keccak256), 쿼리 조건 캐시, estimateCompressionRatio
25.2 2025-03-07 3 25.2.2.39 Parquet Bloom filters, Backup database engine, stringCompare and the progress formatsParquet Bloom 필터, Backup 데이터베이스 엔진, stringCompare와 진행 포맷
25.1 2025-02-07 3 25.1.8.25 Automatic minmax indices, Merge tables unifying schemas as Variant, sequenceMatchEvents자동 minmax 인덱스, Merge 테이블의 Variant 스키마 통합, sequenceMatchEvents

Verified names the exact server build every lab in that directory was run against, end to end, with zero exceptions. Getting all nineteen there took fixing eleven of them: SQL referencing functions and settings that do not exist, arguments in the wrong order, aliases shadowing the column they aggregated. Re-run any of them with .github/scripts/verify_release_lab.sh <version>.검증은 해당 디렉토리의 모든 랩을 예외 0으로 끝까지 실행해 본 정확한 서버 빌드입니다. 19개 전부를 그 상태로 만드는 데 11개를 고쳐야 했습니다 — 존재하지 않는 함수·설정 참조, 뒤바뀐 인자 순서, 집계 대상 컬럼을 가리는 별칭 같은 문제였습니다. 직접 재현하려면 .github/scripts/verify_release_lab.sh <버전> 을 실행하세요.

Everything else그 외 실습

Cloud integrations, end-to-end use cases, focused workload experiments and multi-service workshops.Cloud 연동, 엔드투엔드 활용 사례, 집중 워크로드 실험, 다중 서비스 워크숍입니다.

🏠 Local Environments (`local/`)🏠 로컬 환경 (`local/`)

  • local/oss-docker

    ClickHouse OSS on Docker (macOS, Linux); set.sh <version> switches versions and every release lab builds on itDocker 기반 ClickHouse OSS (macOS·Linux). set.sh <버전>으로 버전을 전환하며, 모든 릴리스 랩이 이 환경을 사용

  • local/releases

    21 per-release feature labs, 25.1 → 26.9 — one directory per release, each with runnable SQL for that version's new features. All 21 have been executed against their own server build; the index records which릴리스별 기능 랩 21개, 25.1 → 26.9 — 릴리스마다 디렉토리 하나, 해당 버전 신기능의 실행 가능한 SQL 포함. 21개 모두 해당 서버 빌드에서 실제 실행 검증했으며, 빌드 번호는 인덱스에 표기

  • local/datalake-minio-catalog

    Local data lake: MinIO plus Iceberg / Nessie / Unity / Delta catalogs, with Jupyter notebooks로컬 데이터 레이크: MinIO + Iceberg / Nessie / Unity / Delta 카탈로그, Jupyter 노트북

  • local/kafka-mysql-table-engines

    Kafka and MySQL table engines, including materialized-view block-size testingKafka·MySQL 테이블 엔진, 구체화 뷰 블록 크기 테스트 포함

  • local/pg-analytics

    pg_lake + Polaris Iceberg ILM: can pg_clickhouse → ClickHouse read the Iceberg files pg_lake writes, and how it compares with pg_duckdb (TPC-H SF10)pg_lake + Polaris Iceberg ILM: pg_lake가 쓴 Iceberg 파일을 pg_clickhouse → ClickHouse로 읽을 수 있는지, pg_duckdb와 성능 비교 (TPC-H SF10)

  • local/mcp-server-clickhouse

    ClickHouse MCP server for LLM tool accessLLM 도구 접근용 ClickHouse MCP 서버

  • local/llm-mac-librechat-with-clickhouse

    LibreChat with a local LLM and the ClickHouse MCP server (macOS)로컬 LLM + ClickHouse MCP 서버와 LibreChat (macOS)

  • local/llm-linux-librechat-sole

    LibreChat standalone (Linux)LibreChat 단독 구성 (Linux)

☁️ ClickHouse Cloud (`chc/`)☁️ ClickHouse Cloud (`chc/`)

🧪 Use Cases (`usecase/`)🧪 활용 사례 (`usecase/`)

  • usecase/ads-analytics

    Ad performance analytics cube광고 성과 분석 큐브

  • usecase/customer360

    Customer 360 modellingCustomer 360 모델링

  • usecase/device-360

    Device360 PoC: Cloud performance validation at billions of rowsDevice360 PoC: 수십억 행 규모 Cloud 성능 검증

  • usecase/fulltext-search

    Bilingual (ko/en) full-text search over support tickets한/영 이중 언어 지원 티켓 전문 검색

  • usecase/korean-rag-tokenizers

    Korean keyword search for RAG: text-index tokenizers, a Kiwi morpheme column, hybrid retrieval (OSS 26.9)한국어 RAG 키워드 검색: text index 토크나이저, Kiwi 형태소 컬럼, 하이브리드 검색 (OSS 26.9)

  • usecase/langfuse-on-clickhouse

    Langfuse's ClickHouse tables without Langfuse: a v4 snapshot and the langfuse-hols trace, analytics and score SQL (OSS 26.8)Langfuse 없이 보는 Langfuse의 ClickHouse 테이블: v4 스냅샷과 langfuse-hols의 trace, 분석, 점수 SQL (OSS 26.8)

  • usecase/ch-geo-analytics

    Geospatial analytics with H3 indexingH3 인덱싱 기반 공간 분석

  • usecase/korea-geo

    Korean administrative boundaries with Superset한국 행정경계(시군구) + Superset

  • usecase/gnome-variants

    Genome variant analysis유전체 변이 분석

  • usecase/security-traffic-analysis

    Security traffic analysis platform보안 트래픽 분석 플랫폼

  • usecase/json-explode-confluent-clickpipes

    Real-time JSON explode: Confluent → ClickPipes → ClickHouse실시간 JSON explode: Confluent → ClickPipes → ClickHouse

  • usecase/mysql-prewhere

    PREWHERE behaviour over the MySQL protocolMySQL 프로토콜에서의 PREWHERE 동작

  • usecase/mysql-protocol-benchmark

    MySQL vs ClickHouse point-query performanceMySQL vs ClickHouse 포인트 쿼리 성능

  • usecase/timeseries-promql-oss

    TimeSeries table engine + querying it with PromQL (OSS 26.8; Cloud is Private Preview only — no Cloud lab yet)TimeSeries 테이블 엔진 + PromQL로 조회하기 (OSS 26.8; Cloud는 Private Preview 전용 — Cloud 실습은 아직 없음)

🔬 Workloads (`workload/`)🔬 워크로드 (`workload/`)

Getting started시작하기

git clone https://github.com/litkhai/clickhouse-hols.git
cd clickhouse-hols/local/releases/26.9
./00-setup.sh

Then run the numbered scripts in order. Every lab documents its own setup and teardown; nothing is global.이후 번호 순서대로 스크립트를 실행하세요. 각 랩이 자체 설정과 정리 방법을 문서화하며, 전역 설정은 없습니다.