How can I use API to manage clusters on ClickHouse Cloud?
\nWe will use Terraform to configure our infra and ClickHouse Provider
\nSteps:
\n1). Create an API Key on Cloud.\nFollow the docs here - https://clickhouse.com/docs/cloud/manage/openapi
\nSave the creds locally.
\n2). Install Terraform using - https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli
\nYou can use Homebrew package manager if you're on Mac.
\n3). Create a directory anywhere you like:
\n4). Create 2 files: main.tf and secret.tfvars
Copy the following:
\nmain.tf file would be:
You can replace your own parameters like service name, region etc.. in the resources section above.
\nsecret.tfvars is where you'll put all the API Key related info that you downloaded earlier. The idea behind this file is that all your secret credentials will be hidden from the main config file.
It would be something like (replace these parameters):
\n5). Run terraform init from this directory
Expected output:
\n6). Run terraform apply -var-file=secret.tfvars command.
Something like:
\nType yes and hit enter
Side note: Notice it says password = (sensitive value) above.\nThis is because we set sensitive = true for the password in the main.tf file.
7). It will take a couple of mins to create the service but eventually it should come up like:
\n8). Check Cloud Console, you should be able to see the service created.
\n9). To clean up/destroy the service again, run terraform destroy -var-file=secret.tfvars
Something like:
\nType yes and hit enter
\n10).
\nAnd it should be gone from the Cloud Console.
\nMore details about the Cloud API can be found here - https://clickhouse.com/docs/cloud/manage/api/api-overview
Starting February 27, 2026, ClickHouse Cloud will begin collecting crash reports when server crashes occur. This is part of our commitment to improving service reliability for all our users.
\nCrash report collection helps us:
\nWhen a crash occurs, crash reports capture a snapshot of the server's state at that moment. We want to be transparent that this may include sensitive information that was in memory, such as:
\nWe take the security of this data seriously:
\nSome services are automatically excluded from crash report collection:
\nIf you'd prefer not to participate in crash report collection, you can easily opt out:
\nIn addition to the service setting, we also support configuring preferences for the organization. If the setting is disabled, i.e., opt out of the crash report collection, all existing and new services will be opted out automatically. If you set the preference to enabled i.e. opt in, you can selectively disable at the service level to override and opt out.
ClickHouse uses two independent concepts for organizing data within parts:
\nPart types determine how column data is organized within a data part.
\n| Type | Description | Best for |
|---|---|---|
| Wide | Each column is stored in separate file(s), each with its own marks file | Queries selecting a subset of columns |
| Compact | All columns are stored in a single file with a single marks file | Ingestion performance and queries needing all columns |
The part type is controlled by the following table settings:
\nmin_bytes_for_wide_part: Minimum bytes for a part to use Wide formatmin_rows_for_wide_part: Minimum rows for a part to use Wide formatIf either the number of bytes or rows in a data part is less than the corresponding setting value, the part is stored in Compact format; otherwise, it uses Wide format.
Compact parts:
\nWide parts:
\nCompact-to-wide merges are slower than wide-to-wide merges because ClickHouse uses vertical merge algorithms for compact-to-wide conversions, while using horizontal algorithms for compact-to-compact merges. If you want to force the use of wide parts regardless of size, you can set min_bytes_for_wide_part=0.
This can be useful in the following scenarios:
\nsystem.metric_log and system.text_log that are consuming excessive memory during mergesIt's worth noting that while setting this to 0 can improve certain performance characteristics, it may generate more GET requests to S3 storage due to the wide parts format.
\nColumn size statistics are not calculated for compact parts, which can affect monitoring and optimization efforts. When querying system.parts_columns, compact parts show 0 for column_data_compressed_bytes and column_data_uncompressed_bytes. For more information see \"Find counts and sizes of wide or compact parts\".
Storage formats determine how a part's files are physically stored on disk.
\n| Format | Description | Availability |
|---|---|---|
| Full | Each file is stored individually in the part directory | Open source and Cloud |
| Packed | All files are bundled into a single archive file | ClickHouse Cloud only |
In Full storage, each part consists of multiple separate files stored individually on disk. This is the default and only option in open source ClickHouse.
\nIn Packed storage, all part files are bundled into a single archive. This significantly reduces the number of file operations, which is critical for remote storage like S3 where each request has associated latency and cost.
\nBenefits of Packed storage:
\nIn ClickHouse Cloud, a part uses Packed storage if any of these conditions are true:
\nmin_bytes_for_full_part_storagemin_rows_for_full_part_storagemin_level_for_full_part_storageWhile the settings min_bytes_for_full_part_storage, min_rows_for_full_part_storage, and min_level_for_full_part_storage are defined in open source ClickHouse, they have no effect because the Packed storage implementation is only available in ClickHouse Cloud.
The min_level_for_full_part_storage setting can be used to optimize both performance and costs in ClickHouse Cloud environments, particularly for tables that receive continuous inserts.\nThe setting is available starting in ClickHouse version 25.10 and works in conjunction with min_level_for_wide_part to provide comprehensive control over part storage strategies.
Changing it from the default value (0) could be considered in the following use cases:
\nRecommended configuration:
\nSet min_level_for_full_part_storage = 2 for cloud deployments.\nThis ensures that:
Avoid this setting for tables that receive very large but infrequent writes where insufficient merges occur, as large initial writes may benefit from full part storage immediately.
These two concepts are orthogonal and you can have any combination, depending on if you are using ClickHouse Cloud or Open Source ClickHouse:
\n| Combination | Use case |
|---|---|
| Wide + Full | Large parts on local storage (default in open source) |
| Wide + Packed | Large parts on cloud storage |
| Compact + Full | Small parts on local storage |
| Compact + Packed | Small parts on cloud storage |
You can inspect the part type and part storage type of existing parts using the system.parts table:
You will see something like this:
\nThe following query can be used to count the number of parts by type:
\nAn example response is shown below:
\nRun the query below to query part size for wide and compact parts:
\nAn example response is shown below:
\nNote that columns sizes are not calculated in compact parts and they therefore show as 0 above.
Prerequisites:
\nopentelemetry_span_log system table is enabledIf you have not made any modifications to the opentelemetry_span_log section of config.xml you can skip this step.
Open your default ClickHouse config.xml file and find the following section:
Make sure that it is not commented out, or else you won't be able to see system.opentelemetry_span_log in the following steps.\nThis can also be the case if your ClickHouse server is not using the default configuration file.
Check your server logs for something like:
In standard installations this file is located at /etc/clickhouse-server/config.xml
With your ClickHouse server running, open ClickHouse client and enable trace collection using the following query:
You should now see the opentelemetry_span_log system table if you run:
Next run:
This sets the probability that the ClickHouse can start a trace for executed queries, where\n1 means that the trace is enabled for all executed queries.
Run the following dummy query, or the query you are interested in tracing:
Copy the query id:
Run the following query, substituting in the query ID you obtained in the previous step:
This will write the trace to a file named trace.json.\nBy default, this file is created in the current working directory from which you are running the clickhouse-client or clickhouse-local tool.
Use the hosted trace visualizer at https://trace-visualizer.clickhouse.com/.\nLoad the trace.json file from the previous step to visualize the trace.
We recommend Grafana for visualizing and exploring trace data using the official ClickHouse plugin.\nThe plugin has been enhanced to allow visualization of traces using the Trace Panel.\nThis is supported as both a visualization and as a component in Explore.
Follow the steps described in \"Using Grafana and ClickHouse for Observability\"\nto set up Grafana with the ClickHouse plugin.
From the Explore tab you can then run the following query, replacing the trace_id with your own:
Make sure to set Query type to Traces:
Click \"Run Query\" and inspect the trace diagram:
This guide assumes that the <path> parameter in your config.xml file is set to:
If you have configured a different data path, replace all instances of /var/lib/clickhouse in the below commands with the actual value of your <path> setting.
Copy the contents of the access folder which contains local users from the healthy replica:
/var/lib/clickhouse/store/.. which contains all the table DDLs.This command ensures that both the metadata files, and the symlink architecture are preserved in the backup.
backup.tar file to the faulty replica.To trigger automatic data synchronization from other replicas, create the following flag:
HAR files may contain session cookies or other sensitive data.\nOnly share them with authorized support personnel.
As a new user, ClickHouse can often seem like magic - every query is super fast,\neven on the largest datasets and most ambitious queries. Invariably though,\nreal-world usage tests even the limits of ClickHouse. Queries exceeding memory\ncan be the result of a number of causes. Most commonly, we see large joins or\naggregations on high cardinality fields. If performance is critical, and these\nqueries are required, we often recommend users simply scale up - something\nClickHouse Cloud does automatically and effortlessly to ensure your queries\nremain responsive. We appreciate, however, that in self-managed scenarios,\nthis is sometimes not trivial, and maybe optimal performance is not even required.\nUsers, in this case, have a few options.
\nFor memory-intensive aggregations or sorting scenarios, users can use the settings\nmax_bytes_before_external_group_by\nand max_bytes_before_external_sort respectively.\nThe former of which is discussed extensively here.
In summary, this ensures any aggregations can “spill” out to disk if a memory\nthreshold is exceeded. This will invariably impact query performance but will\nhelp ensure queries do not OOM. The latter sorting setting helps address similar\nissues with memory-intensive sorts. This can be particularly important in\ndistributed environments where a coordinating node receives sorted responses\nfrom child shards. In this case, the coordinating server can be asked to sort a\ndataset larger than its available memory. With max_bytes_before_external_sort,\nsorting can be allowed to spill over to disk. This setting is also helpful for\ncases where the user has an ORDER BY after a GROUP BY with a LIMIT,\nespecially in cases where the query is distributed.
For joins, users can select different JOIN algorithms, which can assist in\nlowering the required memory. By default, joins use the hash join, which offers\nthe most completeness with respect to features and often the best performance.\nThis algorithm loads the right-hand table of the JOIN into an in-memory hash\ntable, against which the left-hand table is then evaluated. To minimize memory,\nusers should thus place the smaller table on the right side. This approach still\nhas limitations in memory-bound cases, however. In these cases, partial_merge\njoin can be enabled via the join_algorithm\nsetting. This derivative of the sort-merge algorithm,\nfirst sorts the right table into blocks and creates a min-max index for them.\nIt then sorts parts of the left table by the join key and joins them over the\nright table. The min-max index is used to skip unneeded right table blocks.\nThis is less memory-intensive at the expense of performance. Taking this concept\nfurther, the full_sorting_merge algorithm allows a JOIN to be performed when\nthe right-hand side is very large and doesn't fit into memory and lookups are\nimpossible, e.g. a complex subquery. In this case, both the right and left side\nare sorted on disk if they do not fit in memory, allowing large tables to be\njoined.
Since 20.3, ClickHouse has supported an auto value for the join_algorithm setting.\nThis instructs ClickHouse to apply an adaptive join approach, where the hash-join\nalgorithm is preferred until memory limits are violated, at which point the\npartial_merge algorithm is attempted. Finally, concerning joins, we encourage\nreaders to be aware of the behavior of distributed joins and how to minimize\ntheir memory consumption. More information can be found here.
OPTIMIZE FINAL is a DDL command that physically and permanently reorganizes\nand optimizes data on disk. It physically merges data parts in MergeTree tables,\nperforming data deduplication in the process by removing duplicate rows from storage.
FINAL is a query-time modifier that provides deduplicated results without\nchanging the structure of the stored data. It works by performing merge logic at\nread-time. It is temporary, only affecting the current query result.
Users are often advised to avoid using OPTIMIZE FINAL, as it has a significant\nperformance overhead, however they should not confuse the two. It is often necessary\nto use FINAL to get back results without duplicates, especially when using table\nengines like ReplacingMergeTree which may contain duplicate rows which have not\nbeen replaced during the eventual, background merge process.
The table below summarises the key differences:
\n| Aspect | OPTIMIZE FINAL | FINAL |
|---|---|---|
| Type | DDL Command | Query Modifier |
| Effect | Permanent storage optimization | Temporary query-time deduplication |
| Performance | Impact\tHigh cost once, then faster queries | Lower individual cost, but repeated for each query |
| Data Modification | Yes - physically changes storage | No - read-only operation |
| Use Case | Periodic maintenance/optimization | Real-time deduplicated queries |
Use OPTIMIZE FINAL when:
Use FINAL when:
Both are valuable tools, but they serve different purposes in ClickHouse's deduplication strategy.
\n\nIn this knowledgebase article, we will walk you through how you can set up a\ncustom DNS alias for your ClickHouse Cloud instance through the use of a reverse\nproxy such as Nginx for ClickHouse native client.
\n
This step is not needed if you are using signed certificates.
Create a self-signed certificate with the domain name of your choice.\nIn this example we will use a domain name xyz-customdomain.com and\ncreate a certificate called MyCertificate.crt. Refer to \"Create SSL certificates\"\nfor further details.
Add the certificate to /etc/clickhouse-client/config.xml:
Add the following in your nginx.conf file:
Where isrgrootx1.pem is the root certificate for ClickHouse Cloud which you\ncan download here.
The following step is not needed if you are using your own domain controllers
Add the following to your /etc/hosts file on the Nginx server:
Where 10.X.Y.Z is the IP address of your specific Nginx box.
You are now ready to connect using your custom alias:
\n