> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse Cloud quick start > Quick start guide for ClickHouse Cloud This page covers provisioning a ClickHouse Cloud service, connecting to it, and loading data, all from the command line with the [ClickHouse CLI](/products/cloud/features/cli) (`clickhousectl`). Commands are non-interactive; `clickhousectl` emits JSON with `--json`.

Prerequisites

Install the ClickHouse CLI: ```bash theme={null} curl https://clickhouse.com/cli | sh ``` You also need `jq`. You need a ClickHouse Cloud account. If you don't have one yet, `clickhousectl cloud auth signup` opens the sign-up page in your browser. Write operations (create, delete) require [API key authentication](/products/cloud/features/admin-features/api/openapi); OAuth login is read-only: ```bash theme={null} clickhousectl cloud auth login --api-key --api-secret ``` Alternatively, set the `CLICKHOUSE_CLOUD_API_KEY` and `CLICKHOUSE_CLOUD_API_SECRET` environment variables. Verify with `clickhousectl cloud auth status`; expect an entry with scope `read/write`.

Create a ClickHouse service

Create the service and save the response; the password for the `default` user is shown only once: ```bash theme={null} clickhousectl cloud service create \ --name quickstart-ch \ --region us-east-1 \ --json > ch.json ``` The response includes the service ID, endpoints, and the generated password (trimmed here; the full response also contains scaling settings, the IP access list, and tags): ```json theme={null} { "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 } } ``` Extract what the rest of this guide needs: ```bash theme={null} 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) ``` If the password is lost, generate a new one with `clickhousectl cloud service reset-password "$CH_ID"`. Services created with `clickhousectl` default to an IP access list that allows all (`0.0.0.0/0`). To restrict access, pass `--ip-allow` when creating the service; see ["Setting IP filters"](/products/cloud/guides/security/connectivity/setting-ip-filters).

Wait for the service to provision

Provisioning takes about a minute. Poll until the state is `running`: ```bash theme={null} while [ "$(clickhousectl cloud service get "$CH_ID" --json | jq -r .state)" != "running" ]; do sleep 15 done ```

Run SQL with the Query API

`clickhousectl cloud service query` runs SQL over HTTP — no local `clickhouse` binary or service password required. The first call provisions a Query API endpoint and a service-scoped API key automatically: ```bash theme={null} clickhousectl cloud service query --id "$CH_ID" --query "SHOW databases" ``` ```text theme={null} Provisioning Query API endpoint + key for service 'quickstart-ch'... {"name":"INFORMATION_SCHEMA"} {"name":"default"} {"name":"information_schema"} {"name":"system"} ``` Piped output defaults to `JSONEachRow`; pass `--format PrettyCompact` for table-formatted output instead.

Create a database and table

```bash theme={null} 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)" ``` Both commands print `OK`. Insert a few rows: ```bash theme={null} 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)" ``` Verify it worked: ```bash theme={null} clickhousectl cloud service query --id "$CH_ID" \ --query "SELECT * FROM helloworld.my_first_table ORDER BY timestamp" ``` ```text theme={null} {"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} ``` The timestamps depend on when you ran the insert, so yours will differ.

Load a CSV file

Suppose the following text is in a CSV file named `data.csv`: ```text title="data.csv" theme={null} 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` reads the data from stdin, so pipe the query and the file together: ```bash theme={null} printf 'INSERT INTO helloworld.my_first_table FORMAT CSV\n' | cat - data.csv \ | clickhousectl cloud service query --id "$CH_ID" ``` Verify the new rows landed: ```bash theme={null} clickhousectl cloud service query --id "$CH_ID" \ --query "SELECT count() FROM helloworld.my_first_table" ``` ```text theme={null} {"count()":7} ```

Connect with clickhouse client

You can also connect over the native protocol with [**clickhouse client**](/concepts/features/interfaces/client). The ClickHouse CLI manages the `clickhouse` binary for you, so you don't need a separate client install: ```bash theme={null} clickhousectl local use latest ``` This installs the latest `clickhouse` binary and symlinks it to `~/.local/bin/clickhouse`, so the plain `clickhouse` command is available globally on your `PATH`. Then connect using the hostname and password from the create response. With `--query`, the result is printed and the client exits; without it you get the interactive prompt (`:)`), which you leave with `exit`: ```bash theme={null} 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" ``` ```text theme={null} 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 ``` The same command form uploads files: ```bash theme={null} clickhouse client --host "$CH_HOST" --secure --port 9440 \ --user default --password "$CH_PASSWORD" \ --query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv ```

Cleanup

Deleting a service removes all of its data permanently. `--force` stops a running service first: ```bash theme={null} clickhousectl cloud service delete "$CH_ID" --force ``` To keep the data but stop paying for compute, idle the service with `clickhousectl cloud service stop "$CH_ID"` instead.