Tuning parameter reference for GeminiStateBackend - Realtime Compute for Apache Flink

GeminiStateBackend uses adaptive tuning to adjust most parameters automatically. In most cases, you only need to set the basic configurations below. For specific performance issues, use the targeted configuration groups in this topic.

Symptom	Configuration group
Memory usage too high or performance degradation	Memory configurations
Local disk space exhausted	Compute-storage separation configurations
Join operator performance bottleneck	Key-value separation configurations

For an overview of GeminiStateBackend and how to apply configurations, see Introduction to the enterprise-level state backend and Set State-related parameters.

Basic configurations

Parameter	Description	Data type	Default value	Notes
`table.exec.state.ttl`	The time-to-live (TTL) for the state of an SQL job. Mutually exclusive with `state.backend.gemini.ttl.ms` — use one or the other.	Long	Ververica Runtime (VVR) 4.0.12 and later: 1.5 days (129600000 ms). Earlier versions: none (state never expires).	Unit: milliseconds. Set a short value to limit state growth.
`state.backend.gemini.ttl.ms`	The TTL for the state of a DataStream or Python job. Mutually exclusive with `table.exec.state.ttl` — use one or the other.	Long	None	Unit: milliseconds. Set a short value to limit state growth.
`state.backend.gemini.savepoint.external-sort.local-storage.enabled`	Whether to store temporary data generated during standard snapshots on the local disk instead of a distributed file system (DFS).	Boolean	`false`	Supported in VVR 4.0 and later. Set to `true` only if local disk usage is below 30% — this reduces DFS interaction and speeds up snapshot creation.

Memory configurations

All memory configuration parameters require VVR 4.0 or later. Keep the default values unless you are actively troubleshooting a specific memory issue.

The standard Flink checkpoint and state backend configurations also apply to GeminiStateBackend. See Checkpoints and state backends.

Parameter	Description	Data type	Default value	Notes
`state.backend.gemini.memory.managed`	Whether GeminiStateBackend automatically allocates memory based on the managed memory. Set to `false` only when you need to control WriteBuffer and off-heap memory sizes separately.	Boolean	`true` (VVR 4.0.12 and later); `false` (earlier versions)	When `true`, the system calculates memory per backend based on managed memory and task slots. When `false`, memory = `state.backend.gemini.total.writebuffer.size` + `state.backend.gemini.offheap.size`. Keep the default value.
`state.backend.gemini.total.writebuffer.size`	The total memory allocated to WriteBuffer. Takes effect only when `state.backend.gemini.memory.managed` is `false`.	String	128 MB	Requires a unit suffix: B, KB, MB, or GB (case-insensitive; a space between number and unit is allowed).
`state.backend.gemini.offheap.size`	The off-heap memory size for GeminiStateBackend, excluding the memory used by WriteBuffer. Takes effect only when `state.backend.gemini.memory.managed` is `false`.	String	None	Requires a unit suffix: B, KB, MB, or GB (case-insensitive; a space between number and unit is allowed). Not configured by default.

Compute-storage separation configurations

All compute-storage separation parameters require VVR 4.0.11 or later.

When Object Storage Service (OSS) is the DFS, the OSS client SDK writes the entire file to local disk before uploading. As a result, compute-storage separation is not effective during savepoint creation — a single state backend generates one large uncompressed local file. To reduce state size per node in this scenario, increase the job concurrency instead.

Parameter	Description	Data type	Default value	Notes
`state.backend.gemini.file.cache.type`	The compute-storage separation mode.	String	`INFINITE` (VVR 4.0.11); `LIMITED` (VVR 4.0.12 and later)	Valid values (case-sensitive): `INFINITE` — state data is stored locally only; `LIMITED` — state data is stored locally first, then spills to a DFS when the local disk limit is reached. Set to `LIMITED` and configure `state.backend.gemini.file.cache.preserved-space` if local disk space is insufficient.
`state.backend.gemini.file.cache.preserved-space`	The minimum free disk space reserved for state data on a single TaskManager. When free space drops below this value, GeminiStateBackend spills state data to the DFS.	String	2 GB	Requires a unit suffix: B, KB, MB, or GB (case-insensitive; a space between number and unit is allowed).

Key-value separation configurations

All key-value separation parameters require VVR 4.0.12 or later. In VVR 6.0.1 and later, keep the default value — the engine handles separation automatically based on operator characteristics.

Parameter	Description	Data type	Default value	Notes
`state.backend.gemini.kv.separate.mode`	The key-value separation mode.	String	`DISABLE` (VVR 4.0.12–4.0.x); `SPECIFIED_TABLE_ENABLE` (VVR 6.0.1 and later)	Valid values (case-sensitive): `DISABLE` — disabled; `GLOBAL_ENABLE` — enabled for all operators; `SPECIFIED_TABLE_ENABLE` — the engine automatically enables or disables separation based on operator characteristics (VVR 6.0.1 and later). In VVR 4.0.x, set to `GLOBAL_ENABLE` if a join job has a low join success rate and large value sizes. Estimate the join success rate from the ratio of Records Received to Records Sent at the join node. In VVR 6.0.1 and later, keep the default value.
`state.backend.gemini.kv.separate.value.size.threshold`	The value size threshold, in bytes, that triggers key-value separation when key-value separation is enabled. Records at or above this size have their key and value stored separately.	Integer	200	Recommended range: 150–1000. A higher join success rate allows a larger value. In VVR 6.0.1 and later with adaptive tuning enabled, the engine adjusts this parameter automatically — no explicit configuration needed.

Adaptive tuning configurations

All adaptive tuning parameters require VVR 4.0.12 or later. The default ACTIVE mode handles parameter adjustment automatically. Keep the default values in most cases.

Parameter	Description	Data type	Default value	Notes
`state.backend.gemini.auto-tune.mode`	The adaptive tuning mode.	String	`ACTIVE`	Valid values (case-insensitive): `DISABLED` — disabled; `MONITORING` — monitors status and logs tuning suggestions without making changes; `ACTIVE` (default) — monitors and auto-adjusts parameters not explicitly set in `flink-conf.yaml`; `FORCEFUL` — monitors, auto-adjusts, and overwrites Gemini-related parameters set in `flink-conf.yaml`. Keep the default value.
`state.backend.gemini.auto-tune.burst.start.x`	The start time of a high-throughput window in which GeminiStateBackend switches to a transactions-per-second (TPS)-first policy. `x` is any number. Each `start.x` pairs with a corresponding `end.x`.	String	None	Value format: `yyyy-MM-dd HH:mm:ss`. The end time must be later than the start time. Multiple windows can be defined using different values of `x`. The TPS-first policy trades CPU and memory efficiency for higher throughput. Leave unconfigured unless peak throughput is the priority during a specific time window.
`state.backend.gemini.auto-tune.burst.end.x`	The end time of the high-throughput window that corresponds to `state.backend.gemini.auto-tune.burst.start.x`.	String	None	Value format: `yyyy-MM-dd HH:mm:ss`. Must be later than the corresponding `start.x` value.