Set a Baseline CFU for a Flink SQL Statement

The Baseline CFU is a minimum scaling target for a single statement, measured in CFUs. After you set it, Autopilot keeps the statement at or above the Baseline CFU, so the statement holds enough capacity to keep latency predictable.

For the concept and when to use it, see Baseline CFU.

You manage the Baseline CFU on the statement itself: in Confluent Cloud Console from the statement’s detail page, or through the statement’s spec.scaling object with the Flink SQL REST API. Both act on the same statement; no separate API exists.

Note

Baseline CFU is a Limited Availability feature in Confluent Cloud. During the Limited Availability phase, it applies only to Flink statements, not to materialized tables, and you manage it in Confluent Cloud Console or with the Flink SQL REST API. Terraform and the Confluent CLI aren’t supported.

Warning

If Confluent previously configured a scaling floor for a statement, a Baseline CFU can interfere with that configuration. If that applies to your statement, contact Confluent Support before you set a Baseline CFU. For more information, see Get Help with Confluent Cloud for Apache Flink.

This guide covers the following tasks:

Manage the Baseline CFU in the Console
Prerequisites
Set up your shell
Get the current Baseline CFU
Set the Baseline CFU
Set the Baseline CFU at submit time
Change the Baseline CFU
Remove the Baseline CFU

For the behavior to expect after you change the value, see Baseline CFU behavior.

Manage the Baseline CFU in the Console

Open the statement’s detail page: in Confluent Cloud Console, go to your environment, click Flink, click Statements, and click the statement.

Set or change the Baseline CFU. In the Activity Trends section, on the Statement CFU chart, click Set baseline CFU, or Update baseline CFU if a value is already set. Enter a value and click Set. The dialog shows the Compute pool max CFU; the Baseline CFU can’t exceed it.
Remove the Baseline CFU. Click More, click Remove baseline CFU, and confirm. The statement is then free to scale down again.

The statement summary shows the current Baseline CFU, and the Statement CFU chart plots it as a line. If the statement runs below the Baseline CFU, for example when the compute pool is at capacity, the Console shows a warning.

Prerequisites

You need the following to manage the Baseline CFU with the REST API.

Item	Example	How to get it
Organization ID	`b0b21724-4586-4a07-b787-d0bb5aacbf87`	Confluent Cloud Console, or `confluent organization list`
Environment ID	`env-z3y2x1`	`confluent environment list`
Cloud provider	`gcp`	`confluent flink region list`
Cloud region	`europe-west1`	`confluent flink region list`
Statement name	`fa-sm-1e74151aca0e`	`confluent flink statement list`
API key and secret	N/A	Generate an API Key for Access in Confluent Cloud for Apache Flink

Authenticate with an API key whose principal can access Flink in the target environment. For more information about generating a key, see Generate an API Key for Access in Confluent Cloud for Apache Flink.

Set up your shell

Export the values from the prerequisites, and build the statement URL.

export FLINK_API_KEY="<flink-api-key>"
export FLINK_API_SECRET="<flink-api-secret>"
export ORG_ID="<organization-id>"
export ENV_ID="<environment-id>"
export CLOUD_PROVIDER="gcp"
export CLOUD_REGION="europe-west1"
export STATEMENT_NAME="<statement-name>"

export STMT_URL="https://flink.${CLOUD_REGION}.${CLOUD_PROVIDER}.confluent.cloud/sql/v1/organizations/${ORG_ID}/environments/${ENV_ID}/statements/${STATEMENT_NAME}"

The host is region-scoped, not api.confluent.cloud. With Flink private networking, the host has a private segment, for example, https://flink.${CLOUD_REGION}.${CLOUD_PROVIDER}.private.confluent.cloud.

Note

Examples throughout this guide pass -u "$FLINK_API_KEY:$FLINK_API_SECRET", which lets curl build the Authorization header for you. This is equivalent to the pre-encoded Authorization: Basic header shown in Basic authentication with API keys. OAuth also works and is the documented preference for production. For more information, see OAuth authentication.

Get the current Baseline CFU

With the shell ready, read the statement to see the current floor. Inspect spec.scaling.baseline_cfu in the response. A value of null, or an absent scaling object, means that no floor is set.

curl -sS "${STMT_URL}" \
  -u "$FLINK_API_KEY:$FLINK_API_SECRET" \
  -H 'Accept: application/json'

Set the Baseline CFU

Add a scaling object with a baseline_cfu value by sending a JSON Patch request. The following example sets a floor of 5 CFUs.

curl -sS -X PATCH "${STMT_URL}" \
  -u "$FLINK_API_KEY:$FLINK_API_SECRET" \
  -H 'Content-Type: application/json-patch+json' \
  -d '[{"op":"add","path":"/spec/scaling","value":{"baseline_cfu":5}}]'

The response is the updated statement. Read back spec.scaling.baseline_cfu to confirm the change.

Set the Baseline CFU at submit time

You can include scaling in the request that creates the statement because it’s part of spec. For the full submit request, see Submit a statement.

{
  "name": "my-statement",
  "organization_id": "b0b21724-4586-4a07-b787-d0bb5aacbf87",
  "environment_id": "env-z3y2x1",
  "spec": {
    "statement": "INSERT INTO sink SELECT * FROM source;",
    "compute_pool_id": "lfcp-8m03rm",
    "principal": "sa-23kgz4",
    "stopped": false,
    "scaling": { "baseline_cfu": 2 }
  }
}

Change the Baseline CFU

Replace the value when a floor is already set.

curl -sS -X PATCH "${STMT_URL}" \
  -u "$FLINK_API_KEY:$FLINK_API_SECRET" \
  -H 'Content-Type: application/json-patch+json' \
  -d '[{"op":"replace","path":"/spec/scaling/baseline_cfu","value":4}]'

Remove the Baseline CFU

Remove the scaling object to clear the floor. The statement is then free to scale down again.

curl -sS -X PATCH "${STMT_URL}" \
  -u "$FLINK_API_KEY:$FLINK_API_SECRET" \
  -H 'Content-Type: application/json-patch+json' \
  -d '[{"op":"remove","path":"/spec/scaling"}]'

Baseline CFU behavior

A change can take up to 10 minutes to take effect. Statement CFU metrics and the statement details in Confluent Cloud Console report the updated CFUs after the statement reaches them.
Autopilot keeps the statement at or above the Baseline CFU. Autopilot picks the smallest uniform CFU value at or above the Baseline CFU, so a statement often settles higher, and it scales up freely above the value. The Baseline CFU is a best-effort lower bound, not a guarantee. If the compute pool can’t supply the capacity, the request still succeeds and the statement runs below the Baseline CFU. The reason appears on the statement’s Operational logs tab.
Changes are dynamic but can cause a brief pause. You don’t need to stop or resume the statement, but changing the value triggers a rescale that pauses processing while capacity changes. The pause is longer for statements with large state or user-defined functions (UDFs).
Billing follows the Baseline CFU. A statement with a Baseline CFU of 5 is billed for at least 5 CFUs even when it’s idle. Usage above the Baseline CFU is billed on top. For more information, see Billing on Confluent Cloud for Apache Flink.
The Baseline CFU is a non-negative integer, capped by the compute pool. Keep it at or below the compute pool’s maximum CFUs (max_cfu): the pool caps the capacity the statement can reach, so a higher Baseline CFU can’t be satisfied.
Unset is not the same as 0. An unset Baseline CFU means no floor. Treat the two as distinct states.
A Baseline CFU applies only to statements, not to a materialized table.