ClickHouse 25.12 New Features Lab

---

A hands-on laboratory for learning and testing ClickHouse 25.12 new features. This directory focuses on verified and working features newly added in ClickHouse 25.12 (released 2025-12-18, the "Christmas Release" of 2025).

📋 Overview

ClickHouse 25.12 includes significant enhancements in security, machine learning, query optimization, and data lake integration. This release features 26 new features, 31 performance optimizations, and 129 bug fixes.

🎯 Key Features

1. HMAC Function - Hash-based Message Authentication Code for API security
2. Naive Bayes Classifier - Built-in machine learning for classification tasks
3. JOIN Order Optimization (DPSize) - Advanced algorithm for optimal query performance
4. Delta Lake Change Data Feed - CDC support for data lakes (requires additional setup)

🚀 Quick Start

Prerequisites

• macOS (with Docker Desktop)
• oss-docker environment setup

Setup and Run

# 1. Install and start ClickHouse 25.12
cd local/releases/25.12
./00-setup.sh

# 2. Run tests for each feature
./01-hmac-function.sh
./02-naive-bayes-classifier.sh
./03-join-optimization.sh

Manual Execution (SQL only)

To execute SQL files directly:

# Connect to ClickHouse client
cd ../../oss-docker
./client.sh 8123

# Execute SQL file
cd ../local/releases/25.12
source 01-hmac-function.sql

📚 Feature Details

1. HMAC Function (01-hmac-function)

New Feature: HMAC (Hash-based Message Authentication Code) function for secure message authentication

Test Content: - Basic HMAC with SHA-256, SHA-1, SHA-512 - Webhook signature generation and validation - API request authentication - Session token generation (JWT-like) - Data integrity verification - Replay attack prevention patterns

Execute:

./01-hmac-function.sh
# Or
cat 01-hmac-function.sql | docker exec -i clickhouse-25-12 clickhouse-client --multiline --multiquery

Key Learning Points: - HMAC(message, key, 'sha256') generates authentication codes - Used extensively in webhook validation (GitHub, Stripe, etc.) - Essential for API security and authentication - Prevents tampering and replay attacks - Supports multiple hash algorithms (sha1, sha256, sha512)

Use Cases: - Webhook signature validation - API authentication and authorization - Session token generation - Data integrity verification - Secure inter-service communication - OAuth and OpenID implementations - Audit trail protection

---

2. Naive Bayes Classifier (02-naive-bayes-classifier)

New Feature: Built-in support for Naive Bayes classification, a simple yet powerful probabilistic classifier

Test Content: - Email spam detection model - Customer churn prediction - Sentiment analysis - Product category classification - Feature probability analysis - Training data patterns

Execute:

./02-naive-bayes-classifier.sh

Key Learning Points: - Probabilistic classification based on Bayes' theorem - Works well with small training datasets - Binary features (0/1) for presence/absence - Calculate prior and conditional probabilities - Simple feature engineering approach - Interpretable results with probability scores

Use Cases: - Spam detection and email filtering - Sentiment analysis and opinion mining - Document categorization and tagging - Customer churn prediction - Product recommendation systems - Fraud detection - Medical diagnosis support - Content moderation

---

3. JOIN Order Optimization (03-join-optimization)

New Feature: DPSize algorithm for more exhaustive search of optimal JOIN order in multi-table queries

Test Content: - 2-table, 3-table, 4-table, and 5-table JOINs - Star schema query patterns - Complex JOIN conditions - LEFT JOIN optimization - EXPLAIN query analysis - Performance comparison scenarios

Execute:

./03-join-optimization.sh

Key Learning Points: - DPSize algorithm automatically optimizes JOIN order - Reduces query execution time and memory usage - Transparent to query writers - Handles complex multi-table JOINs efficiently - Works with star and snowflake schemas - Use EXPLAIN to understand execution plan

Use Cases: - Complex analytics queries with multiple tables - Star schema and snowflake schema queries - E-commerce product and order analytics - Multi-dimensional business intelligence - Data warehouse reporting - Dashboard and BI tool queries - Ad-hoc analytical queries

---

🔧 Management

ClickHouse Connection Info

• Web UI: http://localhost:8123/play
• HTTP API: http://localhost:8123
• TCP: localhost:9000
• User: default (no password)

Useful Commands

# Check ClickHouse status
cd ../../oss-docker
./status.sh

# Connect to CLI
./client.sh 8123

# View logs
docker logs clickhouse-25-12

# Stop
./stop.sh

# Complete removal
./stop.sh --cleanup

📂 File Structure

25.12/
├── README.md                        # This document
├── 00-setup.sh                      # ClickHouse 25.12 installation script
├── 01-hmac-function.sh              # HMAC function test execution
├── 01-hmac-function.sql             # HMAC function SQL
├── 02-naive-bayes-classifier.sh     # Naive Bayes classifier test execution
├── 02-naive-bayes-classifier.sql    # Naive Bayes classifier SQL
├── 03-join-optimization.sh          # JOIN optimization test execution
└── 03-join-optimization.sql         # JOIN optimization SQL

🎓 Learning Path

For Beginners

1. 00-setup.sh - Understand environment setup
2. 01-hmac-function - Learn API security fundamentals
3. 02-naive-bayes-classifier - Introduction to ML in databases

For Intermediate Users

1. 03-join-optimization - Query performance optimization
2. Combine HMAC with real API integrations
3. Build end-to-end ML pipelines with Naive Bayes

For Advanced Users

• Apply these features to production workloads
• Analyze query execution plans with EXPLAIN
• Performance benchmarking and comparison
• Integrate with external ML and API systems

🔍 Additional Resources

• Release Presentation: ClickHouse 25.12 Release Call
• ClickHouse Documentation: docs.clickhouse.com
• Release Notes: Changelog 2025
• Newsletter: December 2025 Newsletter
• Alexey's Favorites: Favorite Features 2025

📝 Notes

• Each script can be executed independently
• Read and modify SQL files directly to experiment
• Test data is generated within each SQL file
• Cleanup is commented out by default for inspection
• All features verified on ClickHouse 25.12.11.4

🆕 What's New in 25.12

• 26 new features including HMAC, improved text indexing, and Delta Lake CDC
• 31 performance optimizations with DPSize JOIN algorithm
• 129 bug fixes for stability and reliability
• Text Index Beta promotion from experimental status
• Advanced instrumentation for production debugging
• Object storage optimization with new storage format

🤝 Contributing

If you have improvements or additional examples for this lab: 1. Register an issue 2. Submit a Pull Request 3. Share feedback

📄 License

MIT — free to learn from and modify.

---

Happy Learning! 🎄

For questions or issues, please refer to the main clickhouse-hols README.

---

# 1. ClickHouse 25.12 설치 및 시작
cd local/releases/25.12
./00-setup.sh

# 2. 각 기능별 테스트 실행
./01-hmac-function.sh
./02-naive-bayes-classifier.sh
./03-join-optimization.sh

# ClickHouse 클라이언트 접속
cd ../../oss-docker
./client.sh 8123

# SQL 파일 실행
cd ../local/releases/25.12
source 01-hmac-function.sql

./01-hmac-function.sh
# 또는
cat 01-hmac-function.sql | docker exec -i clickhouse-25-12 clickhouse-client --multiline --multiquery

./02-naive-bayes-classifier.sh

./03-join-optimization.sh

# ClickHouse 상태 확인
cd ../../oss-docker
./status.sh

# CLI 접속
./client.sh 8123

# 로그 확인
docker logs clickhouse-25-12

# 중지
./stop.sh

# 완전 삭제
./stop.sh --cleanup

25.12/
├── README.md                        # 이 문서
├── 00-setup.sh                      # ClickHouse 25.12 설치 스크립트
├── 01-hmac-function.sh              # HMAC 함수 테스트 실행
├── 01-hmac-function.sql             # HMAC 함수 SQL
├── 02-naive-bayes-classifier.sh     # Naive Bayes 분류기 테스트 실행
├── 02-naive-bayes-classifier.sql    # Naive Bayes 분류기 SQL
├── 03-join-optimization.sh          # JOIN 최적화 테스트 실행
└── 03-join-optimization.sql         # JOIN 최적화 SQL