When dedicated compute resources are insufficient for a burst workload, Hologres can route SQL queries to a shared serverless pool billed on a pay-as-you-go basis. This topic explains how the serverless resource quota is calculated and how to control how many compute units (CUs) each query can use.
Serverless resource quota
The serverless resource quota is the maximum number of CUs that all concurrently active SQL queries (in the EXECUTE state) on an instance can use at the same time. It is determined by the instance's dedicated CU count.
| Instance dedicated CUs | Serverless resource quota |
|---|---|
| Less than 32 CUs | Serverless computing is not supported. |
| 32 to less than 688 CUs | Default: 3x the instance's dedicated CUs (for example, 32 CUs gives a quota of 96 CUs). From v3.0.33: 5x, capped at 2,048 CUs. From v3.1.9: cap raised to 4,096 CUs. From v4.0.13: 10x, capped at 4,096 CUs. |
| 688 CUs or more | Capped at 2,048 CUs. From v3.1.9: cap raised to 4,096 CUs. |
The serverless resource pool in each zone is shared across all instances in that zone. Serverless computing is pay-as-you-go and resource availability is not guaranteed. If the instance quota is reached or the zone-level pool is exhausted, new queries enter a QUEUE state and wait until resources become available.
How resources are allocated to a query
Three factors determine how many CUs a single SQL query receives. The system uses the minimum of the three.
| Factor | Description | Default |
|---|---|---|
| Quota | The instance's serverless resource quota. | Determined by instance size (see table above). |
hg_experimental_serverless_computing_max_cores (Max Cores) | The CU ceiling for a single query. | 512 before v3.0.42 and v3.1.10; 1,024 from v3.0.42 and v3.1.10 onward. |
hg_experimental_serverless_computing_required_cores (Required Cores) | The estimated CUs for a query. When set to 0, the system estimates automatically. When set to a non-zero value, the actual allocation is max(required_cores, system_estimate x 0.5). | 0 (automatic estimation). |
Resources are allocated in increments of 15 CUs.
Example: An instance has a quota of 96 CUs. Max Cores is 32, and the system estimates the query needs 60 CUs. The query receives 32 CUs — the minimum of 96, 32, and 60.
How Max Cores differs from Required Cores
Both parameters limit the CUs allocated to a query, but they serve different purposes:
Max Cores sets a hard ceiling to prevent any single query from monopolizing serverless resources. Use it when you want to protect the resource pool from runaway queries.
Required Cores overrides the system's automatic estimate for a specific query. Use it only when automatic estimation is consistently wrong for a particular workload — and only after testing.
Set Max Cores
Max Cores sets the maximum CUs a single query can use from the serverless pool. Lower this value when large queries monopolize serverless resources and starve smaller concurrent queries.
Lowering Max Cores reduces the resources available to each query. Test the impact on query performance before applying this change in production.
-- Set the maximum CUs to allocate for a single serverless computing task. Default: 512.
SET hg_experimental_serverless_computing_max_cores = 512;
-- Reset to the default.
reset hg_experimental_serverless_computing_max_cores;Full example:
-- Route the query to the serverless pool.
SET hg_computing_resource = 'serverless';
-- Cap this query at 32 CUs.
SET hg_experimental_serverless_computing_max_cores = 32;
-- Run the query.
INSERT INTO sink_tbl SELECT * FROM source_tbl;
-- Reset both parameters.
reset hg_computing_resource;
reset hg_experimental_serverless_computing_max_cores;Set Required Cores
By default, the system automatically estimates the CUs a query needs based on its complexity. Set Required Cores only when the automatic estimate is consistently wrong for a specific query pattern — for example, when a query repeatedly under-uses or over-uses resources despite having the same logical complexity.
Setting Required Cores too low can cause out-of-memory (OOM) errors. Test thoroughly before using this parameter in production.
When you set a non-zero value, the actual allocation is max(required_cores, system_estimate x 0.5). This floor prevents the allocation from falling more than 50% below the system's own estimate.
-- Override the automatic estimate with a specific CU value.
SET hg_experimental_serverless_computing_required_cores = <value>;
-- Reset to automatic estimation.
reset hg_experimental_serverless_computing_required_cores;Full example:
-- Route the query to the serverless pool.
SET hg_computing_resource = 'serverless';
-- Request at least 96 CUs. Actual allocation: max(96, system_estimate x 0.5).
SET hg_experimental_serverless_computing_required_cores = 96;
-- Run the query.
INSERT INTO sink_tbl SELECT * FROM source_tbl;
-- Reset both parameters.
reset hg_computing_resource;
reset hg_experimental_serverless_computing_required_cores;Adjust the resource allocation ratio
If the system's automatic estimate is consistently off across multiple queries — not just one — adjust hg_experimental_serverless_computing_resource_allocation_ratio to scale the estimate globally. The default value is 4 (neutral).
| Value | Effect | Example (baseline estimate: 60 CUs) |
|---|---|---|
| Greater than 4 (for example, 8) | Scales up the estimate. | Adjusted to 120 CUs. |
| Less than 4 (for example, 2) | Scales down the estimate. | Adjusted to 30 CUs. |
Apply the parameter at the scope that fits your needs:
-- Apply at the SQL level (current session only).
SET hg_experimental_serverless_computing_resource_allocation_ratio = 4;
-- Apply at the user level.
ALTER USER "ROLE_NAME" IN DATABASE DB_NAME SET hg_experimental_serverless_computing_resource_allocation_ratio = 4;
-- Apply at the database level.
ALTER DATABASE DB_NAME SET hg_experimental_serverless_computing_resource_allocation_ratio = 4;