> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 clickhouse-client 将数据插入到 ClickHouse Cloud

> 了解如何通过命令行使用 clickhouse-client，将本地 CSV 和 Parquet 文件中的数据插入到 ClickHouse Cloud 服务中。

<a href="/zh/get-started/quickstarts/home"><Badge size="lg" color="gray" icon="arrow-left">所有快速入门</Badge></a>

<div className="mt-2 flex flex-wrap gap-2">
  <Badge size="lg" color="blue">实时分析</Badge>
  <Badge size="lg" color="blue">数据仓储</Badge>
  <Badge size="lg" color="blue">可观测性</Badge>
  <Badge size="lg" color="blue">AI/ML</Badge>
  <Badge size="lg" color="orange">Cloud</Badge>
</div>

<div id="prerequisites">
  ## 前置条件
</div>

你还应完成以下快速入门：

* [创建你的第一个 Cloud 服务](/zh/get-started/quickstarts/create-your-first-service-on-cloud) - 你需要一个正在运行的 ClickHouse Cloud 服务，用于插入数据
* [获取你的 Cloud 连接详细信息](/zh/get-started/quickstarts/obtain-your-cloud-connection-details) - 你需要使用 hostname、用户名和密码进行连接

<div id="what-youll-build">
  ## 你将构建的内容
</div>

在本快速入门中，你将使用 **clickhouse-client** (官方的 ClickHouse 命令行客户端) ，将本地 CSV file 中的数据插入到 ClickHouse Cloud 服务中。
你将安装 clickhouse-client，准备一个样本数据集，连接到你的 Cloud 服务，创建一张表，并从本地机器插入数据。
完成后，你将了解如何使用 clickhouse-client 将本地文件加载到 ClickHouse Cloud；这一工作流适用于 CSV、Parquet、JSON 以及许多其他格式。

<Steps titleSize="h3">
  <Step>
    ### 安装 clickhouse-client

    `clickhouse-client` 是连接 ClickHouse 的官方 CLI，包含在 ClickHouse 二进制可执行文件中。

    使用通用安装程序进行安装：

    ```bash theme={null}
    curl https://clickhouse.com/ | sh
    ```

    这会将最新的 `clickhouse` 可执行文件下载到当前目录。验证安装是否成功：

    ```bash theme={null}
    ./clickhouse client --version
    ```

    你应该会看到显示 ClickHouse 版本号的输出，这表明 `clickhouse-client` 已可使用。
  </Step>

  <Step>
    ### 准备一个样例 CSV 文件

    创建一个小型样例 CSV 文件，以便本快速入门内容完整，可独立完成。请在终端中运行以下命令：

    ```bash theme={null}
    cat <<'EOF' > sample_data.csv
    timestamp,event_type,user_id,duration_ms,status
    2024-01-15 10:30:00,page_view,1001,120,success
    2024-01-15 10:31:15,click,1002,45,success
    2024-01-15 10:32:00,page_view,1003,200,success
    2024-01-15 10:33:30,purchase,1001,1500,success
    2024-01-15 10:34:00,click,1004,60,error
    2024-01-15 10:35:45,page_view,1002,95,success
    2024-01-15 10:36:10,purchase,1005,2200,success
    2024-01-15 10:37:00,click,1003,30,success
    2024-01-15 10:38:20,page_view,1004,150,error
    2024-01-15 10:39:00,purchase,1002,1800,success
    EOF
    ```
  </Step>

  <Step>
    ### 连接到你的 Cloud 服务

    以下命令假定你已按照[获取你的 Cloud 连接信息](/zh/get-started/quickstarts/obtain-your-cloud-connection-details)快速入门中的说明，将 `CLICKHOUSE_HOST`、`CLICKHOUSE_USER` 和 `CLICKHOUSE_PASSWORD` 导出为环境变量。如果还没有，你也可以直接替换为你自己的值。

    通过对你的 Cloud 服务运行一个简单查询来测试连通性：

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "SELECT 1"
    ```

    如果连接成功，终端会输出 `1`。如果出现连接错误，请检查你的服务是否已在 Cloud 控制台中启动，以及主机名和密码是否正确。

    <Note>
      端口 `9440` 是 ClickHouse Cloud 的安全原生协议端口。`--secure` 标志用于启用 TLS 加密。所有 Cloud 连接都必须使用这些设置。
    </Note>
  </Step>

  <Step>
    ### 创建目标表并插入数据

    首先，在您的 Cloud 服务中创建一个用于接收这些数据的表：

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "
        CREATE TABLE IF NOT EXISTS events (
          timestamp DateTime,
          event_type LowCardinality(String),
          user_id UInt32,
          duration_ms UInt32,
          status LowCardinality(String)
        )
        ENGINE = MergeTree
        ORDER BY (event_type, timestamp)
      "
    ```

    现在插入本地 CSV 文件中的数据。这是关键一步——`clickhouse-client` 会从 stdin 读取该文件，并将其流式发送到远程服务：

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "INSERT INTO events FORMAT CSVWithNames" < sample_data.csv
    ```

    `clickhouse-client` 会将 CSV 文件内容直接发送到你的 Cloud 服务。`CSVWithNames` 格式会告知 ClickHouse，第一行包含列名。
  </Step>

  <Step>
    ### 验证数据是否已插入

    查询您的 Cloud 服务，确认这些行已写入：

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "SELECT count() FROM events"
    ```

    你应该会看到 `10`，即示例 CSV 中的行数。

    预览数据：

    ```bash theme={null}
    ./clickhouse client \
      --host $CLICKHOUSE_HOST \
      --port 9440 \
      --user $CLICKHOUSE_USER \
      --password $CLICKHOUSE_PASSWORD \
      --secure \
      -q "SELECT * FROM events ORDER BY timestamp LIMIT 5"
    ```

    同样的工作流也适用于 Parquet、TSV、JSON、Avro、ORC 以及许多其他[支持的格式](/zh/reference/formats)——只需更改 `FORMAT` 子句，并将相应文件通过管道传入即可。
  </Step>
</Steps>

## 后续步骤

在本快速入门中，你安装了 `clickhouse-client`，将其连接到 ClickHouse Cloud 服务，并使用它将本地 CSV 文件中的数据流式传输到 Cloud。对于 Parquet、JSON 以及其他数十种格式，这种方法同样适用。

接下来请查看以下快速入门：

* [创建你的第一个 MergeTree 表](/zh/get-started/quickstarts/create-your-first-mergetree-table)

或者查阅参考文档，进一步了解：

* [clickhouse-client 参考](/zh/concepts/features/interfaces/cli)
* [支持的输入/输出格式](/zh/reference/formats)

<Frame caption="Check out the ClickHouse academy for on-demand and live training">
  <a href="https://learn.clickhouse.com/" target="_blank">
    <img src="https://mintcdn.com/private-7c7dfe99-fix-nav-issues/Y9kcWM6RbYppspJn/images/academy.png?fit=max&auto=format&n=Y9kcWM6RbYppspJn&q=85&s=d842bc871e006c08da3026a8a09e1d61" alt="ClickHouse Academy — Master ClickHouse with expert-designed training for every skill level" width="560" noZoom data-path="images/academy.png" />
  </a>
</Frame>

<div className="mt-8">
  <a href="/zh/get-started/quickstarts/home"><Badge size="lg" color="gray" icon="arrow-left">所有快速入门</Badge></a>
</div>