ClickHouse On-Demand Compute

• Stateless query execution with on-demand compute
• A new CBO (cost-based optimizer)
• A new distributed query execution

​

When to use On-Demand 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.

​

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.

​

Using On-Demand Compute

​

Settings

​

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

​

Concurrent queries

SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 3, ...;
SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 3, ...;

SELECT ... SETTINGS make_distributed_plan = 1, distributed_plan_workers_num = 5, ...;

​

When the pool cannot satisfy the request

​

Monitoring

​

Number of allocated workers

SELECT
    ProfileEvents['StatelessWorkerRequested'],
    ProfileEvents['StatelessWorkerProvided']
FROM clusterAllReplicas(default, system.query_log)
WHERE query_id = '<YOUR_QUERY_ID>'
  AND type != 'QueryStart';

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

​

Pricing

​

Limitations

• 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

• 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

• 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

• 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

• 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.

​

FAQ