Skip to main content

Manage Warmup Jobs

A VeloDB Cloud cluster keeps hot data in a local cache and reads the rest from remote storage. A warmup job preloads data into a cluster's cache so the first requests do not need to fill the cache from remote storage.

Warm up a cluster when you want to:

  • Prepare a new or resumed cluster before it takes production traffic.
  • Refill the cache after scaling in compute, when cached data beyond the new capacity is evicted.
  • Keep a standby cluster's cache aligned with a busy cluster so it can take over quickly.

Cache warmup is available since version 4.1.8. The Warmup Jobs console entry appears only for warehouses with the supported core versions.

Create a warmup job​

Create a warmup job with SQL, not from the VeloDB Cloud console. Run the WARM UP COMPUTE GROUP statement in the SQL Editor or another SQL client. In the SQL statement, a cluster is named as a compute group.

Warm the destination cluster using another cluster's hotspot statistics. This selects hot data for the destination to load from shared storage, subject to its cache capacity. It does not copy the source cache byte for byte. Both clusters must belong to the same warehouse.

WARM UP COMPUTE GROUP <destination_cluster> WITH COMPUTE GROUP <source_cluster>;

Or warm specific tables and partitions, when you know which datasets the next queries will read.

WARM UP COMPUTE GROUP <destination_cluster> WITH
    TABLE <table_name>
    AND TABLE <table_name> PARTITION <partition_name>;

The statement returns a job ID. Use it to monitor and manage the job in the VeloDB Cloud console or with SQL. For the full syntax, see WARM UP.

Warm up materialized view caches​

Clusters in the same warehouse share materialized view (MV) definitions and stored data, but each cluster has its own local cache. Warmup preloads stored data. It does not create or refresh an MV, synchronize query results, or guarantee that the optimizer rewrites a query to use an MV.

Choose the warmup target according to the MV type:

MV typeHow to warm its cache
Synchronous MVSpecify its base table with WITH TABLE. Warmup includes the table's visible synchronous MVs. Do not use the synchronous MV name as a separate table name.
Asynchronous MVSpecify the MV itself with WITH TABLE <mv_name>. Warming only its base tables does not include the asynchronous MV. Complete its refresh before warming the new data.

Cluster-to-cluster warmup can select data for either MV type when it appears in the source cluster's hotspot statistics. It does not guarantee that every MV is selected. Use WITH TABLE when you need to target a particular asynchronous MV or a base table and its synchronous MVs.

For ongoing warmup based on the source cluster's hotspots, create a periodic job. For example, replace the cluster names below to repeat warmup every 600 seconds:

WARM UP COMPUTE GROUP destination_cluster WITH COMPUTE GROUP source_cluster
PROPERTIES ("sync_mode" = "periodic", "sync_interval_sec" = "600");

Each run uses the available hotspot statistics and destination cache capacity. It does not refresh MVs or guarantee that every MV refresh is immediately cached. A periodic job remains active between runs. To stop it, run CANCEL WARM UP JOB WHERE id = <job_id> with the returned job ID.

Example: prepare an asynchronous MV on another cluster​

Use two running clusters in the same warehouse. Replace source_cluster and destination_cluster with their names, and <database_name> with an existing database. Use a SQL account that can create and refresh an MV, create and query the example table, and run warmup on the selected clusters. Use unused names for the example objects.

  1. Select the source cluster and database, then create a table and an asynchronous MV:

    USE @source_cluster;
    USE <database_name>;

    CREATE TABLE warmup_sales (
        region VARCHAR(20),
        amount BIGINT
    )
    DUPLICATE KEY(region)
    DISTRIBUTED BY HASH(region) BUCKETS 1;

    INSERT INTO warmup_sales VALUES ('east', 100), ('east', 200), ('west', 50);

    CREATE MATERIALIZED VIEW warmup_sales_mv
    BUILD DEFERRED REFRESH AUTO ON MANUAL
    DISTRIBUTED BY HASH(region) BUCKETS 1
    AS SELECT region, SUM(amount) AS total_amount
    FROM warmup_sales
    GROUP BY region;

    REFRESH MATERIALIZED VIEW warmup_sales_mv COMPLETE;

  2. Check the refresh task. Wait until its Status is SUCCESS before continuing. If it fails, inspect ErrorMsg and resolve the error.

    SELECT * FROM tasks("type" = "mv")
    WHERE MvDatabaseName = '<database_name>' AND MvName = 'warmup_sales_mv'
    ORDER BY CreateTime DESC;

  3. Read the MV on the source cluster, then submit a cluster-to-cluster warmup job:

    SELECT * FROM warmup_sales_mv ORDER BY region;

    WARM UP COMPUTE GROUP destination_cluster
    WITH COMPUTE GROUP source_cluster;

    This is a one-time warmup job by default. Hotspot statistics are collected asynchronously, so a query immediately followed by warmup might not select the MV yet. To target the MV directly without waiting for hotspot collection, use this statement instead:

    WARM UP COMPUTE GROUP destination_cluster WITH TABLE warmup_sales_mv;

  4. Replace <job_id> with the ID returned by the warmup statement. Wait for FINISHED. If the job is CANCELLED, inspect its error before continuing.

    SHOW WARM UP JOB WHERE id = <job_id>;

  5. Switch to the destination cluster and query the same MV:

    USE @destination_cluster;
    SELECT * FROM warmup_sales_mv ORDER BY region;

    The result contains east, 300 and west, 50. This verifies access to the shared MV data. Correct query results alone do not prove a cache hit, because a query can also read from shared storage. Use the query profile's local and remote I/O statistics to check cache use. A completed warmup job does not guarantee that data stays cached after eviction or subsequent MV refreshes.

  6. When you finish, remove the example objects:

    DROP MATERIALIZED VIEW warmup_sales_mv;
    DROP TABLE warmup_sales;

Warmup consumes cluster resources and cache capacity. Reuse existing clusters for this example where possible. Stop or delete any clusters created only for testing when you finish.

Monitor a warmup job​

  1. Log in to the VeloDB Cloud console.
  2. In the upper-left corner, select the warehouse that contains the job.
  3. In the left navigation pane, under Compute, click Warmup Jobs.
  4. Use Search by ID to find a job, or filter jobs by Type, Sync Mode, or Status.
  5. Click a Job ID to open the job details.

A warmup job reports the following:

FieldMeaning
StatusPENDING, RUNNING, FINISHED, or CANCELLED.
TypeCLUSTER when warming from another cluster, and TABLE when warming specific tables or partitions.
Finished / total batchesHow many data batches are warmed out of the total. Use this to gauge progress.
Create time / finish timeWhen the job started and, once complete, when it finished.
ErrorThe failure reason when a job does not finish.

The equivalent SQL statement is SHOW WARM UP JOB.

Cancel a warmup job​

To stop a running job, find it on the Warmup Jobs page and use Actions to cancel it. Its status changes from RUNNING to CANCELLED. Data already warmed remains in the cache. The equivalent SQL statement is CANCEL WARM UP JOB WHERE id = <id>.

Alert on warmup jobs​

When you warm a destination cluster from a source cluster, VeloDB Cloud can keep the destination cache in sync with the source over time. Two metrics track that sync and can be used as a Warmup alert target. Both are available since v4.1.8 on the v4.x line and v26.0.5 on the v26.x line.

MetricUnitWhat it tracks
Warmup Job Trigger GapmsThe interval between warmup runs. A growing gap means warmup is scheduling behind.
Warmup Job Pending SizebytesThe source-minus-destination data size over the last 5 minutes. A growing value means the destination cache is falling behind the source.

Create a warmup alert from the job's own page, not from the Alerts page: open the job on the Warmup Jobs page, then click Create Alert. For the full alerting workflow, including the other target types and notification channels, see Alerts.

Warmup runs on the SQL layer. Create a warmup job with WARM UP COMPUTE GROUP, then look it up and cancel it from the VeloDB Cloud console or with SQL.

On This Page