---
title: "ClickHouse Protocol Documentation"
---

# ClickHouse Protocol Documentation

:::caution[Planned: not in the current release]
ClickHouse protocol support for HeliosDB Full is planned. The current release opens no ClickHouse listener. Reach
the same data over the PostgreSQL listener or `POST /api/v1/query` today. This page
describes the planned interface.
:::

This directory contains consolidated documentation for HeliosDB's ClickHouse protocol support.

## Quick Start

Connect to HeliosDB using any ClickHouse client:

```python
from clickhouse_driver import Client

# Connect to HeliosDB (ClickHouse-compatible)
client = Client(
    host='localhost',
    port=9000,
    user='default',
    password='',
    database='default'
)

# Execute query
result = client.execute('SELECT count() FROM events')
print(f"Total events: {result[0][0]}")
```

## Contents

| File | Description |
|------|-------------|
| **README.md** | Overview and quick start (this file) |
| **CONFIGURATION.md** | Connection and protocol configuration |
| **COMPATIBILITY.md** | ClickHouse feature compatibility |
| **EXAMPLES.md** | Query and analytics examples |

## Feature Overview

### Protocol Support

| Feature | Result | Notes |
|---------|--------|-------|
| Native Protocol (TCP) | 100% | Port 9000 |
| HTTP Protocol | 100% | Port 8123 |
| Compression | Supported | LZ4, ZSTD |
| SSL/TLS | Supported | Secure connections |

### Table Engines

| Engine | Coverage | Notes |
|--------|----------|-------|
| MergeTree | 100% | Primary engine |
| ReplacingMergeTree | 100% | Upsert support |
| AggregatingMergeTree | 100% | Pre-aggregation |
| SummingMergeTree | 100% | Auto-summing |
| Distributed | 100% | Multi-node queries |

### Query Features

| Feature | Result | Notes |
|---------|--------|-------|
| PREWHERE | Supported | Early filtering |
| SAMPLE | Supported | Data sampling |
| FINAL | Supported | Deduplication |
| Materialized Views | Supported | Auto-aggregation |
| Window Functions | Supported | Analytics |

## Connection Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `host` | localhost | Server hostname |
| `port` | 9000 | Native protocol port |
| `http_port` | 8123 | HTTP protocol port |
| `user` | default | Username |
| `password` | - | Password |
| `database` | default | Database name |
| `compression` | lz4 | Compression type |

## Driver Compatibility

| Driver | Version | Result |
|--------|---------|--------|
| clickhouse-driver (Python) | 0.2+ | Full |
| clickhouse-go (Go) | 2.x | Full |
| @clickhouse/client (Node.js) | 0.2+ | Full |
| ClickHouse JDBC | 0.4+ | Full |

## Use Cases

- **Real-time Analytics**: Sub-second query response
- **Log Analysis**: Full-text search + aggregation
- **Time-Series**: Metrics and monitoring
- **OLAP Queries**: Complex aggregations
- **Data Lakes**: S3/GCS integration

## Performance Highlights

| Operation | Speed | Notes |
|-----------|-------|-------|
| count() | 11.7M rows/ms | 1B rows in 85ms |
| GROUP BY | 4.1M rows/ms | 100K groups |
| Bulk Insert | 1.5M rows/sec | 100K batches |

## Related Documentation

- **[CONFIGURATION.md](https://www.heliosdb.com/docs/full/reference/protocols/clickhouse/configuration/)** - Connection configuration
- **[COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/clickhouse/compatibility/)** - Feature compatibility
- **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/clickhouse/examples/)** - Usage examples
- **[Parent Directory](https://www.heliosdb.com/docs/full/reference/protocols/readme/)** - Protocol overview