ClickHouse On-Demand Compute

Add compute for ClickHouse Cloud workloads without resizing your primary service. Private preview support is limited to select queries.

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.

Join the 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. 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 (cost-based optimizer)
• A new distributed query execution

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

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:

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:

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

SELECT
    ProfileEvents['StatelessWorkerRequested'],
    ProfileEvents['StatelessWorkerProvided']
FROM clusterAllReplicas(default, system.query_log)
WHERE query_id = '<YOUR_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.

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. We will enable more region based on demand.

Pricing

During private preview, On-Demand Compute is free, with a usage cap (see 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

Is On-Demand Compute open source?

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.

Do I need a specific version to join the private preview?

Yes. The version used during the private preview will be a custom build. Additional upgrades may be required during the preview.

What will pricing look like?

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.

Can I use this for production?

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.

How is this different from autoscaling my service?

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.

Where can I ask questions?

Ask your account team; they will introduce you to the product manager for On-Demand Compute.

Where can I report bugs?

Open a support ticket (severity 3) or report it to the product manager. Include query_id, your service ID and the full exception.

Can another ClickHouse Cloud service reach the workers running my query?

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.

Is a worker reused by another service after my query finishes?

No. When a lease ends, the worker is destroyed and replaced with a fresh one rather than passed on to the next service.

Is this available in ClickHouse BYOC or ClickHouse Private?

No. The private preview is not available in ClickHouse BYOC or ClickHouse Private.