ClickHouse Cloud 快速入门

要快速轻松地开始使用 ClickHouse，最简单快捷的方式是在 ClickHouse Cloud 中创建新服务。本快速入门指南将通过三个简单步骤帮助您完成设置。

创建 ClickHouse 服务

要在 ClickHouse Cloud 中创建免费的 ClickHouse 服务，只需按以下步骤注册：

在注册页面创建账户
您可以选择使用电子邮件注册，或通过 Google SSO、Microsoft SSO、AWS Marketplace、Google Cloud 或 Microsoft Azure 注册
如果您使用电子邮件和密码注册，请务必在 24 小时内通过邮件中收到的链接验证电子邮件地址
使用刚创建的用户名和密码登录

登录后，ClickHouse Cloud 会启动引导向导，指导您创建新的 ClickHouse 服务。选择部署服务的区域，并为新服务命名：

默认情况下，新组织会使用 Scale 层级，并创建 3 个副本，每个副本配备 4 个 vCPU 和 16 GiB RAM。Scale 层级默认启用垂直自动扩缩容。之后您可以在“套餐”页面更改组织层级。

如有需要，可通过指定副本扩缩容的最小和最大规格来自定义服务资源。准备就绪后，选择 Create service。

恭喜！您的 ClickHouse Cloud 服务现已启动并运行，引导流程已完成。请继续阅读，了解如何开始摄取和查询数据。

连接 ClickHouse

有两种方式可连接到 ClickHouse：

使用我们的网页版 SQL 控制台
通过您的应用连接

使用 SQL 控制台连接

为了快速上手，ClickHouse 提供了网页版 SQL 控制台。完成引导设置后，您将自动跳转到该控制台。

新建一个查询选项卡，然后输入一个简单的查询，以验证连接是否正常：

SHOW databases

您应能在列表中看到 4 个数据库，以及您可能添加的其他数据库。

至此，您已可开始使用新的 ClickHouse 服务！

连接您的应用

在导航菜单中点击“连接”按钮。随即会打开一个模态窗口，其中提供服务凭据以及一组说明，指导您如何通过接口或语言客户端进行连接。

如果找不到您所用的语言客户端，请查看我们的集成列表。

添加数据

有了数据，ClickHouse 才能发挥威力！添加数据的方式有很多，其中大部分都可以在“数据源”页面中找到，该页面可通过导航菜单进入。

您可以通过以下方法上传数据：

设置 ClickPipe，开始从 S3、Postgres、Kafka、GCS 等数据源摄取数据
使用 SQL 控制台
使用 ClickHouse 客户端
上传文件 - 支持 JSON、CSV 和 TSV 格式
通过文件 URL 上传数据

ClickPipes

ClickPipes 是一个托管式集成平台，只需点击几下即可从各种数据源摄取数据。ClickPipes 专为要求最为苛刻的工作负载而设计，其稳健且可扩展的架构可确保稳定的性能与可靠性。ClickPipes 既可满足长期的流式数据需求，也可用于一次性的数据加载任务。

使用 SQL 控制台添加数据

与大多数数据库管理系统一样，ClickHouse 在逻辑上将表组织到数据库中。使用 CREATE DATABASE 命令即可在 ClickHouse 中创建新数据库：

CREATE DATABASE IF NOT EXISTS helloworld

运行以下命令，在 helloworld 数据库中创建一个名为 my_first_table 的表：

CREATE TABLE helloworld.my_first_table
(
    user_id UInt32,
    message String,
    timestamp DateTime,
    metric Float32
)
ENGINE = MergeTree()
PRIMARY KEY (user_id, timestamp)

在上面的示例中，my_first_table 是一个包含四列的 MergeTree 表：

user_id：32 位无符号整数 (UInt32)
message：String 数据类型，可替代其他数据库系统中的 VARCHAR、BLOB、CLOB 等类型
timestamp：DateTime 值，表示某一时刻
metric：32 位浮点数 (Float32)

主键简介

在继续之前，务必先了解主键在 ClickHouse 中的工作原理 (主键的实现方式可能会出乎你的意料！) ：

ClickHouse 中的主键对于表中的每一行而言并不唯一

ClickHouse 表的主键决定了数据写入磁盘时的排序方式。每 8,192 行或 10MB 数据 (即所谓的索引粒度) 会在主键索引文件中生成一个条目。这种粒度机制构建出一个可以轻松放入内存的稀疏索引，而每个粒度对应 SELECT 查询执行期间所处理的最小一段列数据。

主键可通过 PRIMARY KEY 参数定义。如果建表时未指定 PRIMARY KEY，则主键即为 ORDER BY 子句中指定的元组。如果同时指定了 PRIMARY KEY 和 ORDER BY，则主键必须是排序顺序的子集。

主键同时也是排序键，即元组 (user_id, timestamp)。因此，每个列文件中存储的数据会先按 user_id 排序，再按 timestamp 排序。

如需深入了解 ClickHouse 的核心概念，请参阅 "核心概念"。

向表中插入数据

在 ClickHouse 中，你可以使用熟悉的 INSERT INTO TABLE 命令，但务必了解：每次向 MergeTree 表插入数据，都会在存储中创建一个分片。

即使是简单的示例，我们也一次插入多行：

INSERT INTO helloworld.my_first_table (user_id, message, timestamp, metric) VALUES
    (101, 'Hello, ClickHouse!',                                 now(),       -1.0    ),
    (102, 'Insert a lot of rows per batch',                     yesterday(), 1.41421 ),
    (102, 'Sort your data based on your commonly-used queries', today(),     2.718   ),
    (101, 'Granules are the smallest chunks of data read',      now() + 5,   3.14159 )

下面验证是否生效：

SELECT * FROM helloworld.my_first_table

使用 ClickHouse 命令行客户端添加数据

你也可以使用名为 clickhouse client 的命令行工具连接到你的 ClickHouse Cloud 服务。点击左侧菜单中的 Connect，即可查看相关连接信息。在弹出的对话框中，从下拉列表选择 Native：

安装 ClickHouse。
运行以下命令，并将其中的主机名、用户名和密码替换为您的相应信息：

./clickhouse client --host HOSTNAME.REGION.CSP.clickhouse.cloud \
--secure --port 9440 \
--user default \
--password <password>

如果看到笑脸提示符，就说明你可以开始执行查询了！

:)

运行以下查询进行试用：

SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp

请注意，返回的响应采用了清晰美观的表格格式：

┌─user_id─┬─message────────────────────────────────────────────┬───────────timestamp─┬──metric─┐
│     102 │ Insert a lot of rows per batch                     │ 2022-03-21 00:00:00 │ 1.41421 │
│     102 │ Sort your data based on your commonly-used queries │ 2022-03-22 00:00:00 │   2.718 │
│     101 │ Hello, ClickHouse!                                 │ 2022-03-22 14:04:09 │      -1 │
│     101 │ Granules are the smallest chunks of data read      │ 2022-03-22 14:04:14 │ 3.14159 │
└─────────┴────────────────────────────────────────────────────┴─────────────────────┴─────────┘

4 rows in set. Elapsed: 0.008 sec.

添加 FORMAT 子句，以指定 ClickHouse 支持的众多输出格式之一：

SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp
FORMAT TabSeparated

在上述查询中，输出以制表符分隔的形式返回：

Query id: 3604df1c-acfd-4117-9c56-f86c69721121

102 Insert a lot of rows per batch      2022-03-21 00:00:00     1.41421
102 Sort your data based on your commonly-used queries  2022-03-22 00:00:00     2.718
101 Hello, ClickHouse!  2022-03-22 14:04:09     -1
101 Granules are the smallest chunks of data read       2022-03-22 14:04:14     3.14159

4 rows in set. Elapsed: 0.005 sec.

要退出 clickhouse client，请输入 exit 命令：

exit

上传文件

刚上手数据库时，一个常见的任务是把已有文件中的数据插入进来。我们在线提供了一份可供插入的样本数据，它代表点击流数据 —— 其中包含用户 ID、被访问的 URL 以及事件的时间戳。

假设有一个名为 data.csv 的 CSV 文件，其内容如下：

data.csvbash

102,This is data in a file,2022-02-22 10:43:28,123.45
101,It is comma-separated,2022-02-23 00:00:00,456.78
103,Use FORMAT to specify the format,2022-02-21 10:43:30,678.90

使用以下命令将数据插入 my_first_table：

./clickhouse client --host HOSTNAME.REGION.CSP.clickhouse.cloud \
--secure --port 9440 \
--user default \
--password <password> \
--query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv

请注意，从 SQL 控制台查询时，表中现在会显示新行：

后续步骤

教程将指导您向表中插入 200 万行数据，并编写一些分析查询
我们提供了示例数据集列表，其中包含插入这些数据集的说明
观看我们时长 12 分钟的 ClickHouse 入门视频
如果您的数据来自外部源，请查看我们的集成指南集合，了解如何连接消息队列、数据库、管道等
如果您使用 UI/BI 可视化工具，请查看将 UI 连接到 ClickHouse 的用户指南
关于主键的用户指南涵盖了您需要了解的主键相关知识及其定义方法

您可以自行按此流程操作，将其编写成脚本，或交给 AI 智能体处理。若要使用控制台版本，请切换到 Cloud UI 视图。

本页介绍如何通过 ClickHouse 命令行客户端 (clickhousectl) 在命令行中预配 ClickHouse Cloud 服务、连接到服务并加载数据。命令以非交互方式运行；使用 --json 时，clickhousectl 将输出 JSON。

前置条件

安装 ClickHouse 命令行客户端：

curl https://clickhouse.com/cli | sh

您还需要安装 jq。

您需要拥有 ClickHouse Cloud 账户。如果尚未注册，运行 clickhousectl cloud auth signup 会在浏览器中打开注册页面。

写操作 (创建、删除) 需要使用 API 密钥进行身份验证；OAuth 登录仅支持只读操作：

clickhousectl cloud auth login --api-key <YOUR_KEY> --api-secret <YOUR_SECRET>

或者，设置 CLICKHOUSE_CLOUD_API_KEY 和 CLICKHOUSE_CLOUD_API_SECRET 环境变量。使用 clickhousectl cloud auth status 进行验证；预期会显示一条 scope 为 read/write 的条目。

创建 ClickHouse 服务

创建服务并保存响应内容；default 用户的密码仅会显示一次：

clickhousectl cloud service create \
  --name quickstart-ch \
  --region us-east-1 \
  --json > ch.json

响应中包含服务 ID、端点和生成的密码 (此处已省略部分内容；完整响应还包含扩缩容设置、IP 访问列表和标签) ：

{
  "password": "dK7mPq2x_-TzrL9vNw0s",
  "service": {
    "id": "4f7b92f3-4163-403a-b538-b9bc6e2e8f66",
    "name": "quickstart-ch",
    "provider": "aws",
    "region": "us-east-1",
    "state": "provisioning",
    "endpoints": [
      {
        "host": "quickstart-abc123.us-east-1.aws.clickhouse.cloud",
        "port": 9440,
        "protocol": "nativesecure"
      },
      {
        "host": "quickstart-abc123.us-east-1.aws.clickhouse.cloud",
        "port": 8443,
        "protocol": "https"
      }
    ],
    "numReplicas": 3,
    "minReplicaMemoryGb": 16.0,
    "maxReplicaMemoryGb": 120.0
  }
}

提取本指南后续内容所需的文件：

CH_ID=$(jq -r .service.id ch.json)
CH_PASSWORD=$(jq -r .password ch.json)
CH_HOST=$(jq -r '.service.endpoints[] | select(.protocol=="nativesecure") | .host' ch.json)

如果忘记密码，请使用 clickhousectl cloud service reset-password "$CH_ID" 生成新密码。

使用 clickhousectl 创建的服务默认使用允许所有 IP 地址 (0.0.0.0/0) 访问的 IP 访问列表。要限制访问，请在创建服务时传入 --ip-allow；请参阅"设置 IP 过滤器"。

等待服务预配完成

预配过程约需一分钟。持续轮询，直到状态变为 running：

while [ "$(clickhousectl cloud service get "$CH_ID" --json | jq -r .state)" != "running" ]; do
  sleep 15
done

使用 Query API 执行 SQL

clickhousectl cloud service query 通过 HTTP 执行 SQL，无需本地 clickhouse 二进制文件或服务密码。首次调用时会自动创建 Query API 端点和服务范围的 API 密钥：

clickhousectl cloud service query --id "$CH_ID" --query "SHOW databases"

Provisioning Query API endpoint + key for service 'quickstart-ch'...
{"name":"INFORMATION_SCHEMA"}
{"name":"default"}
{"name":"information_schema"}
{"name":"system"}

管道输出默认采用 JSONEachRow；如需表格格式的输出，请传入 --format PrettyCompact。

创建数据库和表

clickhousectl cloud service query --id "$CH_ID" \
  --query "CREATE DATABASE IF NOT EXISTS helloworld"

clickhousectl cloud service query --id "$CH_ID" \
  --query "CREATE TABLE helloworld.my_first_table (
    user_id UInt32,
    message String,
    timestamp DateTime,
    metric Float32
  ) ENGINE = MergeTree()
  PRIMARY KEY (user_id, timestamp)"

两条命令都会输出 OK。插入几行数据：

clickhousectl cloud service query --id "$CH_ID" \
  --query "INSERT INTO helloworld.my_first_table (user_id, message, timestamp, metric) VALUES
    (101, 'Hello, ClickHouse!', now(), -1.0),
    (102, 'Insert a lot of rows per batch', yesterday(), 1.41421),
    (102, 'Sort your data based on your commonly-used queries', today(), 2.718),
    (101, 'Granules are the smallest chunks of data read', now() + 5, 3.14159)"

验证是否成功：

clickhousectl cloud service query --id "$CH_ID" \
  --query "SELECT * FROM helloworld.my_first_table ORDER BY timestamp"

{"user_id":102,"message":"Insert a lot of rows per batch","timestamp":"2026-08-26 00:00:00","metric":1.41421}
{"user_id":102,"message":"Sort your data based on your commonly-used queries","timestamp":"2026-08-27 00:00:00","metric":2.718}
{"user_id":101,"message":"Hello, ClickHouse!","timestamp":"2026-08-27 10:41:28","metric":-1}
{"user_id":101,"message":"Granules are the smallest chunks of data read","timestamp":"2026-08-27 10:41:33","metric":3.14159}

时间戳取决于您执行 insert 的时间，因此会有所不同。

加载 CSV 文件

假设名为 data.csv 的 CSV 文件包含以下文本：

data.csvtext

102,This is data in a file,2022-02-22 10:43:28,123.45
101,It is comma-separated,2022-02-23 00:00:00,456.78
103,Use FORMAT to specify the format,2022-02-21 10:43:30,678.90

INSERT ... FORMAT 会从 stdin 读取数据，因此请将查询和文件通过管道传递：

printf 'INSERT INTO helloworld.my_first_table FORMAT CSV\n' | cat - data.csv \
  | clickhousectl cloud service query --id "$CH_ID"

验证新行是否已写入：

clickhousectl cloud service query --id "$CH_ID" \
  --query "SELECT count() FROM helloworld.my_first_table"

{"count()":7}

使用 clickhouse client 连接

您也可以通过原生协议使用 clickhouse client 进行连接。ClickHouse 命令行客户端会为您管理 clickhouse 二进制文件，因此无需另行安装客户端：

clickhousectl local use latest

这会安装最新的 clickhouse 二进制文件，并创建指向 ~/.local/bin/clickhouse 的符号链接，使 clickhouse 命令可通过 PATH 在全局使用。

然后，使用创建响应中的主机名和密码进行连接。使用 --query 时，客户端会打印结果后退出；不使用时，则会进入交互式提示符 (:))，可通过 exit 退出：

clickhouse client --host "$CH_HOST" --secure --port 9440 \
  --user default --password "$CH_PASSWORD" \
  --query "SELECT * FROM helloworld.my_first_table ORDER BY timestamp FORMAT TabSeparated"

102	Insert a lot of rows per batch	2026-08-26 00:00:00	1.41421
102	Sort your data based on your commonly-used queries	2026-08-27 00:00:00	2.718
101	Hello, ClickHouse!	2026-08-27 10:41:28	-1
101	Granules are the smallest chunks of data read	2026-08-27 10:41:33	3.14159
103	Use FORMAT to specify the format	2022-02-21 10:43:30	678.9
102	This is data in a file	2022-02-22 10:43:28	123.45
101	It is comma-separated	2022-02-23 00:00:00	456.78

同样的命令格式可用于上传文件：

clickhouse client --host "$CH_HOST" --secure --port 9440 \
  --user default --password "$CH_PASSWORD" \
  --query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv

清理

删除服务会永久删除其所有数据。--force 会先停止正在运行的服务：

clickhousectl cloud service delete "$CH_ID" --force

若要保留数据但不再为计算资源付费，请改用 clickhousectl cloud service stop "$CH_ID" 停止服务。