;
};
On-Demand Compute is in private preview. It is not covered by ClickHouse Cloud SLOs or SLAs, and known and unknown limitations may apply. See [Limitations](#limitations).
[Join the waitlist](https://clickhouse.com/cloud/on-demand-compute-waitlist).
On-Demand Compute is a ClickHouse Cloud capability that gives your cloud service service (a tenant) additional and instant capacity for supported workloads, without requiring you to resize or provision another service. It runs this work on ClickHouse workers outside your service's own compute. Workers come from a managed pool shared across tenants in the same region, but each worker is assigned to only one tenant at a time.
During the private preview, On-Demand Compute only supports `SELECT` queries. You opt a query in using query/session/user level settings, and ClickHouse assigns workers from the pool to execute it through your existing service and endpoint.
This differs from [compute-compute separation](/docs/products/cloud/features/infrastructure/warehouses). A warehouse provides dedicated, long-lived compute through multiple services that share data. On-Demand Compute provides temporary workers from a shared pool through your existing service.
On-demand compute leverage brand new capabilities:
* Stateless query execution with on-demand compute
* A new [CBO](https://github.com/ClickHouse/ClickHouse/pull/86353) (cost-based optimizer)
* A new [distributed query execution](https://clickhouse.com/blog/multi-stage-distributed-query-execution-clickhouse-cloud)
When to use On-Demand Compute
During the private preview, use On-Demand Compute for eligible, compute-intensive `SELECT` queries that you want to run outside the primary service's compute:
* **Ad hoc and analytical queries:** Run compute-intensive `SELECT` queries on additional workers.
* **Non-critical read workloads:** Move selected reads off the primary service.
* **Data lake queries:** Query supported Apache Iceberg, Delta Lake, or `SharedMergeTree` data on additional workers.
* **Temporary additional compute:** Request workers for eligible queries without resizing the primary service.
The private preview supports `SELECT` queries only. Workers do not execute `INSERT` queries, DDL, mutations, or background operations.
How it works
1. You send an eligible `SELECT` query to your ClickHouse Cloud service requesting a specific number of workers. Your endpoint, authentication, and RBAC configuration do not change
2. Your cluster will then connect to the pool and request the specified number of workers
3. The workers will be leased for a duration of at least 60 seconds if the query last for longer, the lease will be automatically renewed
4. The workers receive the query and execute it
5. The response is then sent back to your client
6. The workers are wiped.
During the private preview, each worker has `8 vCPUs` and `32 GiB` of memory. Use `distributed_plan_workers_num` to specify how many workers the query requests.
Using On-Demand Compute
Settings
Use these settings to start using on-demand compute:
| Setting | Required value | Purpose |
| ------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `make_distributed_plan` | Yes | Enables the experimental distributed query plan. Required for On-Demand Compute. |
| `distributed_plan_workers_num` | Yes | Number of workers to lease for this query. If this is `0` (the default), the query runs on your service, not on the worker pool. |
| `enable_parallel_replicas` | Yes (set to `0`) | Parallel replicas are incompatible with the distributed plan. |
During the preview, set the settings at the query level, or create a separate user with different settings. That makes it obvious which statements use On-Demand Compute, and it avoids inheriting Cloud default profiles that enable parallel replicas.
Example
```sql theme={null}
SELECT
sum(l_extendedprice * l_discount) AS revenue
FROM lineitem
WHERE
l_shipdate >= DATE '1994-01-01'
AND l_shipdate < DATE '1994-01-01' + INTERVAL 1 YEAR
AND l_discount BETWEEN 0.06 - 0.01 AND 0.06 + 0.01
AND l_quantity < 24
SETTINGS
make_distributed_plan = 1,
distributed_plan_workers_num = 5,
enable_parallel_replicas = 0
```
This query requests five workers. The number of workers ClickHouse provides depends on the private-preview limit and available pool capacity.
Concurrent queries
Concurrent queries from the same ClickHouse Cloud service can share assigned workers. ClickHouse requests additional workers only when a query asks for more workers than are already assigned to the service.
For example, if two concurrent queries each request three workers, they can share the same three workers. If another query requests five workers, ClickHouse can use the three assigned workers and request two more from the pool.
See the example below:
```sql theme={null}
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 3, ...;
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 3, ...;
```
They share the same three workers.
If a third concurrent query asks for five workers:
```sql theme={null}
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 5, ...;
```
That query runs on the existing three workers plus two newly leased workers.
When the pool cannot satisfy the request
Worker availability is best effort during the private preview. If fewer workers are available than requested, the query runs with the workers ClickHouse can assign. For example, a request for five workers may run with three.
If no worker can be leased, the query fails.
Retry the query. If this persists, contact your ClickHouse account team — the preview pool may be exhausted or mis-scaled.
Monitoring
Use `system.query_log` on your service to know how many workers were allocated to your query.
Number of allocated workers
```sql theme={null}
SELECT
ProfileEvents['StatelessWorkerRequested'],
ProfileEvents['StatelessWorkerProvided']
FROM clusterAllReplicas(default, system.query_log)
WHERE query_id = ''
AND type != 'QueryStart';
```
Set `log_comment = 'on-demand'` (or a workload name) on On-Demand queries so you can filter them without parsing `Settings`.
```sql theme={null}
SELECT
sum(l_extendedprice * l_discount) AS revenue
FROM lineitem
WHERE
l_shipdate >= DATE '1994-01-01'
AND l_shipdate < DATE '1994-01-01' + INTERVAL 1 YEAR
AND l_discount BETWEEN 0.06 - 0.01 AND 0.06 + 0.01
AND l_quantity < 24
SETTINGS
make_distributed_plan = 1,
distributed_plan_workers_num = 5,
enable_parallel_replicas = 0,
log_comment = 'on-demand-private-preview'
```
Available regions
On-Demand Compute is regional: workers run in the same region as your service.
| Cloud | Region | Notes |
| ----- | --------- | ----- |
| AWS | us-east-1 | |
| AWS | eu-west-1 | |
If your region is missing, request it on the [waitlist](https://clickhouse.com/cloud/on-demand-compute-waitlist). We will enable more region based on demand.
Pricing
During private preview, On-Demand Compute is free, with a usage cap (see [Limitations](#limitations)). Ask your ClickHouse account team if you need the cap raised.
Pricing will be introduced when the preview ends. Preview participants will be notified before the feature is promoted to beta and before any charges start.
The intended model is the same as ClickHouse Cloud compute: pay for compute you use (leased worker time), not for data scanned or rows read.
Limitations
The following limitations apply during the private preview. Other limitations may apply. Report unexpected behavior to ClickHouse Support or your account team.
* **`SELECT` queries only.** Workers do not execute `INSERT` queries, mutations, DDL, or background operations.
* **Supported format.** The private preview supports Apache Iceberg, Delta Lake, and `SharedMergeTree`.
* **Parallel replicas.** Parallel replicas must be disabled.
* **Worker size.** Each worker has `8 vCPUs` and `32 GiB` of memory.
* **Worker limit.** Each query can request up to five workers during the private preview.
* **Pool capacity.** Worker availability is best effort. A query may receive fewer workers than requested. If no workers are available, the query fails.
* **Performance.** Performance varies by query. Worker assignment, distributed planning, and the transfer of plan stages can add latency. Some query shapes may perform worse than execution on the primary service (your typical sub-second queries will probably perform better in your cluster)
* **Query compatibility.** The distributed planner cannot execute every query plan remotely. Unsupported queries may return a `SUPPORT_IS_DISABLED` exception.
Roadmap
On-Demand Compute is a foundation. Work in flight or next:
* Close known limitations (`SUPPORT_IS_DISABLED` gaps)
* Pools of different worker sizes
* Stabilize query performance compared to stateful execution
* Background merge support
* Pricing
* Worker-pool autoscaler calibration
* Built-in observability
* Dedicated permissions for On-Demand Compute
* Data Lake workload expansion (write, compaction, etc...)
Security
Workers come from a pre-warm pool that is shared across services in the same region, so there is one non-negotiable rule: a worker serves one service at a time, and it is never handed from one service to another.
Nothing about how you reach ClickHouse changes. Clients still connect to your service endpoint with your existing authentication, and your service is the only thing that talks to workers on your behalf. Workers have no customer-facing endpoint.
* **One service per worker:** A worker is leased to a single service for the duration of that lease. It is never shared by two services at the same time.
* **No reuse between services:** When a lease ends, the worker is destroyed and replaced with a fresh one. A worker is never reassigned to a different service.
* **No persistent data:** Workers keep no persistent storage, and they do not survive the end of a lease.
* **Same region as your service:** Workers run in the same region as the service that leases them, following strict data residency rules.
* **Your existing access controls still apply:** IP access lists and private endpoints govern your service endpoint exactly as before. On-Demand Compute adds no endpoint for you to configure or protect.
* **Your existing authentication and RBAC:** Queries run under the same user and privileges as any other query on your service. Workers carry no separate identity or permission model.
Network isolation
While a worker is leased to your service, the platform permits network traffic between that worker and your service, and blocks everything else. The restriction is applied at the network layer rather than in the query engine, so it does not depend on the query, its settings, or the plan the optimizer produces.
* **Only your service can reach your workers.** The path exists for the worker's current lease, and for that one service.
* **Unassigned workers are unreachable.** A worker waiting in the pool has no network path to or from any service until it is leased.
* **Workers leased to different services cannot reach each other.** Workers within a single lease exchange plan stages and intermediate results between themselves. Workers in different leases stay isolated from one another, even though they share a pool.
* **The path is removed with the worker.** Ending a lease destroys the worker, which removes the only thing traffic was permitted to reach.
* **The request path stays narrow.** Your service reaches the worker assignment service to lease and renew workers. That path carries no query data and is limited to the assignment API.
Internal authentication & authorization
Network isolation governs what can reach a worker. Authentication governs what a caller is allowed to do once it gets there, and the two are enforced independently: a caller has to satisfy both.
Every connection between your service, the worker assignment service, and workers is authenticated. Nothing is trusted, all credentials are minted by the platform and handed out per lease.
* **One credential per worker:** When workers are leased to your service, the platform issues an unique signed token for each one. Each token works only for that one worker, and only for your service.
* **Short-lived and tied to the lease:** Tokens expire with the lease that produced them. Renewing a lease issues fresh ones, and once a lease is over its tokens no longer authenticate anything.
* **Verified against the platform:** A worker validates the token it is presented against the platform's identity service, rather than trusting anything supplied in the request.
| Connection | What is authenticated |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Your service → worker assignment service | Your service's platform identity, which determines the leases it may act on. |
| Your service → a worker leased to it | A signed token scoped to that one worker, for the life of the lease. |
| Worker → worker within one lease | Each worker's own platform identity, plus a check that the caller still holds a live lease on the receiving worker. |
These credentials are internal to how ClickHouse Cloud executes your query. They are never exposed to your clients, and they are unrelated to how you authenticate to ClickHouse: clients continue to connect with your existing credentials, and query privileges are still governed by your service's RBAC.
FAQ
No. It is a ClickHouse Cloud architecture: ClickHouse server (distributed plan), data plane (worker pool and leases), and control plane. The experimental `make_distributed_plan` setting and the CBO exist in ClickHouse OSS, but the shared worker pool and stateless execution is Cloud-only.
Yes. The version used during the private preview will be a custom build. Additional upgrades may be required during the preview.
We don't have a public pricing to share for the moment. But the feature is free to use during the private preview. That said, the pricing philosophy will be the same as ClickHouse Cloud: charge for compute used, not for data scanned or rows read. Exact rates will be published before pricing is rolled out.
You can run real workloads, but this is a private preview: there are known and unknown limitations, and there is no SLO/SLA for worker-pool availability.
Autoscaling changes the compute assigned to your primary service. During the private preview, On-Demand Compute gives eligible `SELECT` queries temporary access to workers from a managed pool without changing the size of the primary service. Autoscaling manages ongoing service capacity, while On-Demand Compute provides temporary compute for specific workloads.
Ask your account team; they will introduce you to the product manager for On-Demand Compute.
Open a support ticket (severity 3) or report it to the product manager. Include `query_id`, your service ID and the full exception.
No. While a worker is leased to your service, the platform permits traffic between that worker and your service only, and blocks it for every other service. Unassigned workers and workers leased to another service have no network path to yours. See [Network isolation](#network-isolation).
No. When a lease ends, the worker is destroyed and replaced with a fresh one rather than passed on to the next service.
No. The private preview is not available in ClickHouse BYOC or ClickHouse Private.