主要接口协议

1. HTTP/HTTPS 接口

基本用法

# 查询数据
curl -X POST 'http://localhost:8123/' \
  -H 'Content-Type: text/plain' \
  -d 'SELECT * FROM system.tables LIMIT 5'

# 插入数据
curl -X POST 'http://localhost:8123/?query=INSERT%20INTO%20test%20FORMAT%20CSV' \
  -H 'Content-Type: text/plain' \
  --data-binary @data.csv

支持的参数

  • query: SQL 查询语句
  • database: 默认数据库
  • user: 用户名
  • password: 密码
  • format: 输出格式（JSON、CSV、TabSeparated 等）
  • compress: 启用压缩
  • decompress: 启用解压缩

响应格式

  • 支持多种输出格式：JSON、CSV、TabSeparated、Parquet、Arrow 等
  • 可通过 FORMAT 子句或 format 参数指定

2. TCP 原生协议

连接建立

// C++ 客户端示例
#include <Client/Connection.h>

DB::Connection connection("localhost", 9000, "default", "user", "password");
connection.connect();

协议特点

  • 二进制协议，性能更高
  • 支持压缩传输
  • 支持异步查询
  • 支持查询进度回调

3. MySQL 协议兼容

连接方式

mysql -h localhost -P 9004 -u default -p

支持的功能

  • 基本的 SELECT、INSERT、UPDATE、DELETE 操作
  • 支持 MySQL 客户端工具
  • 兼容大部分 MySQL 驱动

限制

  • 不支持所有 MySQL 特性
  • 某些数据类型映射可能不完全一致

4. PostgreSQL 协议兼容

连接方式

psql -h localhost -p 9005 -U default -d default

支持的功能

  • 基本的 SQL 操作
  • 支持 PostgreSQL 客户端工具
  • 兼容 PostgreSQL 驱动

5. gRPC 接口

服务定义

service ClickHouse {
    rpc ExecuteQuery(QueryRequest) returns (stream QueryResponse);
    rpc ExecuteQueryWithStreamInput(stream QueryRequest) returns (stream QueryResponse);
}

使用场景

  • 高性能应用集成
  • 流式数据处理
  • 微服务架构

数据格式支持

输入格式

  • CSV: 逗号分隔值
  • TSV: 制表符分隔值
  • JSON: JSON 格式
  • JSONEachRow: 每行一个 JSON 对象
  • Parquet: Apache Parquet 格式
  • Arrow: Apache Arrow 格式
  • Avro: Apache Avro 格式
  • ORC: Apache ORC 格式
  • Native: ClickHouse 原生二进制格式

输出格式

  • TabSeparated: 制表符分隔（默认）
  • CSV: 逗号分隔值
  • JSON: JSON 格式
  • JSONCompact: 紧凑 JSON 格式
  • XML: XML 格式
  • HTML: HTML 表格格式
  • Vertical: 垂直格式（适合宽表）
  • Pretty: 美化的表格格式

认证与安全

用户认证

-- 创建用户
CREATE USER 'username' IDENTIFIED BY 'password';

-- 授权
GRANT SELECT ON database.* TO 'username';

-- 设置配额
CREATE QUOTA 'user_quota' FOR INTERVAL 1 HOUR MAX QUERIES 1000 TO 'username';

访问控制

  • 基于角色的访问控制 (RBAC)
  • 行级安全策略
  • 列级权限控制
  • IP 地址限制

SSL/TLS 支持

<!-- config.xml -->
<https_port>8443</https_port>
<tcp_port_secure>9440</tcp_port_secure>
<openSSL>
    <server>
        <certificateFile>/path/to/server.crt</certificateFile>
        <privateKeyFile>/path/to/server.key</privateKeyFile>
    </server>
</openSSL>

查询语言特性

DDL 操作

-- 创建数据库
CREATE DATABASE test_db;

-- 创建表
CREATE TABLE test_db.events (
    date Date,
    user_id UInt32,
    event_type String,
    value Float64
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(date)
ORDER BY (user_id, date);

-- 修改表结构
ALTER TABLE test_db.events ADD COLUMN new_field String;

DML 操作

-- 插入数据
INSERT INTO test_db.events VALUES 
    ('2023-01-01', 1001, 'click', 1.5),
    ('2023-01-01', 1002, 'view', 2.0);

-- 查询数据
SELECT 
    event_type,
    count() as cnt,
    avg(value) as avg_value
FROM test_db.events 
WHERE date >= '2023-01-01'
GROUP BY event_type
ORDER BY cnt DESC;

-- 更新数据（轻量级更新）
ALTER TABLE test_db.events UPDATE value = value * 2 WHERE event_type = 'click';

-- 删除数据
ALTER TABLE test_db.events DELETE WHERE date < '2023-01-01';

高级查询特性

-- 窗口函数
SELECT 
    user_id,
    event_type,
    value,
    row_number() OVER (PARTITION BY user_id ORDER BY date) as rn
FROM test_db.events;

-- 数组操作
SELECT 
    groupArray(event_type) as events,
    arrayJoin(events) as event
FROM test_db.events
GROUP BY user_id;

-- 近似查询
SELECT 
    uniq(user_id) as unique_users,
    quantile(0.95)(value) as p95_value
FROM test_db.events;

存储引擎

MergeTree 系列

-- 基础 MergeTree
CREATE TABLE basic_table (
    date Date,
    id UInt32,
    data String
) ENGINE = MergeTree()
PARTITION BY toYYYYMM(date)
ORDER BY id;

-- ReplicatedMergeTree（复制表）
CREATE TABLE replicated_table (
    date Date,
    id UInt32,
    data String
) ENGINE = ReplicatedMergeTree('/clickhouse/tables/shard1/replicated_table', 'replica1')
PARTITION BY toYYYYMM(date)
ORDER BY id;

-- SummingMergeTree（聚合表）
CREATE TABLE summing_table (
    date Date,
    key String,
    value UInt64
) ENGINE = SummingMergeTree()
PARTITION BY toYYYYMM(date)
ORDER BY (date, key);

特殊引擎

-- Memory 引擎（内存表）
CREATE TABLE memory_table (
    id UInt32,
    data String
) ENGINE = Memory();

-- Distributed 引擎（分布式表）
CREATE TABLE distributed_table (
    date Date,
    id UInt32,
    data String
) ENGINE = Distributed(cluster_name, database_name, table_name, rand());

-- MaterializedView（物化视图）
CREATE MATERIALIZED VIEW mv_table
ENGINE = SummingMergeTree()
PARTITION BY toYYYYMM(date)
ORDER BY (date, key)
AS SELECT 
    date,
    event_type as key,
    count() as value
FROM test_db.events
GROUP BY date, event_type;

集群配置

集群定义

<!-- config.xml -->
<remote_servers>
    <test_cluster>
        <shard>
            <replica>
                <host>node1</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node2</host>
                <port>9000</port>
            </replica>
        </shard>
        <shard>
            <replica>
                <host>node3</host>
                <port>9000</port>
            </replica>
            <replica>
                <host>node4</host>
                <port>9000</port>
            </replica>
        </shard>
    </test_cluster>
</remote_servers>

分布式查询

-- 查询分布式表
SELECT * FROM distributed_table WHERE date = '2023-01-01';

-- 跨集群查询
SELECT * FROM cluster('test_cluster', database.table) WHERE condition;

-- 集群函数
SELECT * FROM clusterAllReplicas('test_cluster', database.table);

监控与运维

系统表

-- 查看正在运行的查询
SELECT * FROM system.processes;

-- 查看表信息
SELECT * FROM system.tables WHERE database = 'test_db';

-- 查看集群状态
SELECT * FROM system.clusters;

-- 查看复制状态
SELECT * FROM system.replicas;

-- 查看分区信息
SELECT * FROM system.parts WHERE table = 'events';

性能监控

-- 查询统计
SELECT * FROM system.query_log WHERE type = 'QueryFinish' ORDER BY event_time DESC LIMIT 10;

-- 指标监控
SELECT * FROM system.metrics;
SELECT * FROM system.events;
SELECT * FROM system.asynchronous_metrics;

配置管理

<!-- config.xml 主要配置项 -->
<yandex>
    <logger>
        <level>information</level>
        <log>/var/log/clickhouse-server/clickhouse-server.log</log>
    </logger>
    
    <http_port>8123</http_port>
    <tcp_port>9000</tcp_port>
    
    <max_connections>4096</max_connections>
    <max_concurrent_queries>100</max_concurrent_queries>
    
    <path>/var/lib/clickhouse/</path>
    <tmp_path>/var/lib/clickhouse/tmp/</tmp_path>
    
    <users_config>users.xml</users_config>
</yandex>

最佳实践

表设计

  1. 选择合适的主键: 影响查询性能和存储效率
  2. 合理分区: 按时间或其他维度分区，便于数据管理
  3. 使用合适的数据类型: 选择最小的数据类型以节省存储空间
  4. 考虑压缩: 使用合适的压缩算法

查询优化

  1. 使用 PREWHERE: 在 WHERE 之前过滤数据
  2. **避免 SELECT ***: 只选择需要的列
  3. 合理使用索引: 创建跳数索引和布隆过滤器
  4. 批量操作: 避免频繁的小批量插入

运维建议

  1. 监控资源使用: CPU、内存、磁盘 I/O
  2. 定期备份: 使用 BACKUP/RESTORE 或文件系统快照
  3. 版本管理: 保持集群版本一致
  4. 容量规划: 预估数据增长和查询负载

这个接口详细说明文档涵盖了 ClickHouse 的主要接口协议、数据格式、认证安全、查询语言特性、存储引擎、集群配置、监控运维等方面的内容，为开发者和运维人员提供了全面的参考。