Window compaction schedules tenant major compactions to occur within a specified time period, thereby reducing the impact on daily business operations. Each round of compaction uses a fixed target version and ends after the compaction and data consistency verification are completed.
The time window only determines when new compaction tasks can be added, not whether the current round ends. A single round of compaction can span multiple windows.
Furthermore, in an OceanBase AI Database cluster with cgroup enabled, OceanBase AI Database allows users to configure dedicated resource plans for window compaction. This allocates more CPU/IO resources to compaction tasks during the compaction window, enabling efficient use of idle time for data consolidation.
Limitations and considerations
Window-based major compaction is only available to primary user tenants. The system tenant, Meta tenant, and standby tenant cannot independently initiate it. Different user tenants can configure separate windows, each maintaining its own target and compaction status.
The target remains fixed for each round. When initiating a new round, the system generates a target version. This target is not replaced by cross-window requests, duplicate requests, or new business data until the current round is completed.
The compaction status does not end when a window closes. Once a round of major compaction starts, whether within or outside the window, it remains in the
COMPACTINGstate until completion, after which it changes toIDLE. Completion is determined by data consistency verification.Existing tasks are not canceled when a window ends. Tasks are scheduled based on available resources within the window. After the window ends, new window-based compaction tasks stop, and normal resource allocation resumes. Submitted tasks continue to execute, and queued tasks may begin execution outside the window, so resource consumption does not immediately return to zero.
Continuation across windows if a round is unfinished. If a round is not completed within a window, the original target continues when the next window is successfully triggered; no previously completed work needs to be redone. The system does not guarantee that a round of major compaction will be completed within one window.
No new target is added for early completion. If the old round resumed in the current window is completed as soon as it starts, or if the new round is completed midway through the window, the system will end the round and resume normal resource allocation, without automatically starting a second round using the remaining window time.
For example, if a window starts at
02:00every day and lasts for 6 hours: if the round is not completed on the first day, the original target continues on the second day; if it is completed by02:05on the second day, no new target is added for the remaining time of the window that day.Mutual exclusion with normal tenant compaction. The same tenant cannot perform both window-based major compaction and normal tenant compaction simultaneously. As long as either is not completed, the other cannot replace the current round; this restriction also applies when a window closes.
Business reads and writes follow the original rules. Business reads and writes can continue during compaction, and newly written data will not continuously raise the round's target. Operations such as indexing still follow the database's original rules; tables without data changes are not required to forcibly rewrite all data for the current round of compaction.
Resume from the original target after restart. After a node restarts with the original version, it will reread the current round's target and continue processing unfinished work, without generating a new target as a result. If recovery occurs outside the window, unfinished work still needs to wait for an active window.
Upgrade is allowed only after completing the current round. Upgrade is not allowed while the current round is incomplete; waiting outside the window also counts as incomplete. Closing a window, pausing compaction, or disabling the feature cannot replace completing the current round; other prerequisites for upgrade must still be met after completion.
Prerequisites
Before triggering compaction, ensure the global major compaction switch is enabled. The global major compaction switch is controlled by the cluster-level parameter enable_major_freeze, with a default value of
True, indicating the compaction switch is on.If the global major compaction switch is not enabled for the current cluster, refer to the following steps to enable it.
Log in to the
systenant of the cluster as therootuser.Check whether the global major compaction switch is enabled.
obclient(root@sys)[(none)]> SHOW PARAMETERS LIKE 'enable_major_freeze';If it shows as not enabled, execute the following statement to enable the compaction switch.
obclient(root@sys)[(none)]> ALTER SYSTEM SET enable_major_freeze='True';
To trigger window-based compaction, ensure the tenant-level parameter enable_window_compaction is set to
True.The specific procedure is as follows:
Log in to the user tenant of the cluster as the tenant administrator.
Check the value of the tenant-level parameter
enable_window_compaction.obclient> SHOW PARAMETERS LIKE 'enable_window_compaction';If the value is
False, execute the following statement to enable window compaction.obclient> ALTER SYSTEM SET enable_window_compaction = True;In the sys tenant, you can set this by specifying the tenant name, for example:
ALTER SYSTEM SET enable_window_compaction = True TENANT = tenant_name;.
Configure periodic triggering of window compaction
Similar to daily statistics collection, for each user tenant in the current version, a DAILY_MAINTENANCE_WINDOW task is registered with the scheduled tasks scheduler DBMS_SCHEDULER. You can flexibly define whether to enable or disable the window compaction task, its trigger time, and execution duration based on your business needs.
Enable the window compaction task
Triggering window compaction requires manual enabling of the window compaction task.
Log in to the user tenant of the cluster as the tenant administrator.
The connection example below is for reference only; connect to the database according to your actual environment.
obclient -h10.xx.xx.xx -P2883 -uroot@mysql_tenant#obdemo -p***** -ACall the
ENABLEsubprogram of theDBMS_SCHEDULERsystem package to enable window compaction.An example execution statement is as follows:
obclient> CALL DBMS_SCHEDULER.ENABLE('DAILY_MAINTENANCE_WINDOW');
After enabling the window compaction task, the default start time for window compaction is 02:00 AM, lasting for 6 hours, on a daily basis.
Modify the next start time for the window compaction task
After enabling the window compaction task, the default next start time for the window compaction task is 02:00 AM. You can configure the next start time for the window compaction task based on your business needs.
Note
Window compaction defaults to once a day. If you modify the next execution time, for example, to 01:00 AM, then window compaction will run at 01:00 AM every day thereafter, instead of 02:00 AM.
Log in to the user tenant of the cluster as the tenant administrator.
The connection example below is for reference only; connect to the database according to your actual environment.
obclient -h10.xx.xx.xx -P2883 -uroot@mysql_tenant#obdemo -p***** -ACall the
SET_ATTRIBUTEsubprogram of theDBMS_SCHEDULERsystem package to set the next start time for the window compaction task.The statement is as follows:
CALL DBMS_SCHEDULER.SET_ATTRIBUTE('DAILY_MAINTENANCE_WINDOW','NEXT_DATE', 'next_time');In the statement,
next_timespecifies the next start time for the window compaction task.Example:
For example, set the start time for the next window compaction to
2026-03-10 01:00:00.obclient(root@mysql001)[(none)]> CALL DBMS_SCHEDULER.SET_ATTRIBUTE('DAILY_MAINTENANCE_WINDOW', 'NEXT_DATE', '2026-03-10 01:00:00');
Configure the duration of a window compaction task
After enabling a window compaction task, its default execution duration is 6 hours. You can adjust this duration based on your business requirements.
Log in to the user tenant of the cluster as the tenant administrator.
The connection example below is for reference only; use the actual environment settings when connecting to the database.
obclient -h10.xx.xx.xx -P2883 -uroot@mysql_tenant#obdemo -p***** -ACall the
SET_ATTRIBUTEsubprogram of theDBMS_SCHEDULERsystem package to set the execution duration of the window compaction task.The statement is as follows:
CALL DBMS_SCHEDULER.SET_ATTRIBUTE('DAILY_MAINTENANCE_WINDOW', 'DURATION', duration);In the statement,
durationspecifies the execution duration of the window compaction task in seconds, with a valid range of 60 to 86400.Note
- Modifying the execution duration of the current task affects the task itself. For example, reducing the value of
durationwill cause the currently running window compaction task to end prematurely. - Since window compaction is scheduled daily, the value of
durationmust be less than 24 hours (86400).
For example, to set the duration of the window compaction task to 10 hours (36000 seconds), execute the following statement:
obclient> CALL DBMS_SCHEDULER.SET_ATTRIBUTE('DAILY_MAINTENANCE_WINDOW', 'DURATION', 36000);- Modifying the execution duration of the current task affects the task itself. For example, reducing the value of
Adjust the number of threads for window compaction
You can also adjust the number of threads for window compaction based on your business needs. During window compaction, if the thread_count parameter in the DBMS_DAILY_MAINTENANCE.SET_THREAD_COUNT subprogram is explicitly set to a non-zero value, the number of compaction threads is determined by thread_count. If thread_count is the default value 0, the system uses the larger of the adaptive value and compaction_low_thread_score.
Log in to the user tenant of the cluster as the tenant administrator.
The connection example below is for reference only; use the actual environment settings when connecting to the database.
obclient -h10.xx.xx.xx -P2883 -uroot@mysql_tenant#obdemo -p***** -ACall the
SET_THREAD_COUNTsubprogram of theDBMS_DAILY_MAINTENANCEsystem package to set the number of threads dedicated to window compaction.The statement is as follows:
DBMS_DAILY_MAINTENANCE.SET_THREAD_COUNT(thread_count);For example, to set the number of background compaction threads for window compaction at
COMPACTION_LOWto 8, execute the following statement:obclient> CALL DBMS_DAILY_MAINTENANCE.SET_THREAD_COUNT(8);
(Optional) Configure the resource management plan for window compaction
In a cluster with cgroup enabled, window compaction supports switching to a specific resource management plan during the compaction period. This provides more resources for the compaction task, enabling it to execute faster and cover a sufficient number of partitions, ensuring partition operation efficiency during business peak hours.
Log in to the user tenant of the cluster as a tenant administrator.
Call the
CREATE_CONSUMER_GROUPsubprogram in theDBMS_RESOURCE_MANAGERsystem package to create a dedicated resource group for window compaction.Note
The resource group name for window compaction,
INNER_DAILY_WINDOW_COMPACTION_LOW_GROUP, is fixed and cannot be changed arbitrarily.Example execution statement:
obclient> CALL DBMS_RESOURCE_MANAGER.CREATE_CONSUMER_GROUP( CONSUMER_GROUP => 'INNER_DAILY_WINDOW_COMPACTION_LOW_GROUP', COMMENT => 'consumer group for daily window maintenance job' );Call the
CREATE_PLANsubprogram in theDBMS_RESOURCE_MANAGERsystem package to create a dedicated resource plan for window compaction.Note
The resource management plan name for window compaction,
INNER_DAILY_WINDOW_PLAN, is fixed and cannot be changed arbitrarily.Example execution statement:
obclient> CALL DBMS_RESOURCE_MANAGER.CREATE_PLAN( PLAN => 'INNER_DAILY_WINDOW_PLAN', COMMENT => 'plan for daily window maintenance job' );Call the
CREATE_PLAN_DIRECTIVEsubprogram in theDBMS_RESOURCE_MANAGERsystem package to create the content of the resource management plan.Example execution statement:
obclient> CALL DBMS_RESOURCE_MANAGER.CREATE_PLAN_DIRECTIVE( PLAN => 'INNER_DAILY_WINDOW_PLAN', GROUP_OR_SUBPLAN => 'INNER_DAILY_WINDOW_COMPACTION_LOW_GROUP', COMMENT => 'directive for window compaction', MAX_IOPS => 100, MIN_IOPS => 30, WEIGHT_IOPS => 50, UTILIZATION_LIMIT => 100, MGMT_P1 => 70 );
After successful configuration, when a window compaction task starts, the system automatically switches the current resource management plan to the dedicated plan INNER_DAILY_WINDOW_PLAN and maps the resources of the current COMPACTION_LOW function threads (background compaction task threads) to the dedicated resource group INNER_DAILY_WINDOW_COMPACTION_LOW_GROUP.
Note
After configuring the resource management plan for window compaction, note the following during window compaction:
- You cannot delete the dedicated resource plan
INNER_DAILY_WINDOW_PLANor the dedicated resource groupINNER_DAILY_WINDOW_COMPACTION_LOW_GROUP. - You cannot modify all resource management plans under this tenant.
Manually trigger window compaction
After enabling a window compaction task, if it has not reached the specified execution time, you can manually trigger window compaction based on business needs.
Notice
- Only user tenants are allowed to manually trigger window compaction. The system tenant (
systenant) does not support manual triggering. - If there are unfinished major compactions for regular tenants, attempting to manually trigger window compaction will result in an error. You must wait for the regular tenant major compactions to complete before triggering.
- The execution duration of a manually triggered window compaction task is also controlled by the
durationparameter of the window compaction task (DAILY_MAINTENANCE_WINDOW) in theDBMS_SCHEDULER.SET_ATTRIBUTEsubprogram. For specific configuration details, see Configure the duration of a window compaction task.
Log in to the user tenant corresponding to the cluster as a tenant administrator.
The following is an example connection string. Adjust it according to your actual database configuration.
obclient -h10.xx.xx.xx -P2883 -uroot@mysql_tenant#obdemo -p***** -ACall the
TRIGGER_WINDOW_COMPACTION_PROCsubprogram of theDBMS_DAILY_MAINTENANCEsystem package to manually trigger a window compaction.The following is an example execution statement:
obclient> CALL DBMS_DAILY_MAINTENANCE.TRIGGER_WINDOW_COMPACTION_PROC();
Disable the window compaction task
If you do not want window compaction to be triggered, you can call the DISABLE subprogram of the DBMS_SCHEDULER system package to disable it.
Log in to the user tenant of the cluster as a tenant administrator.
The following is an example connection string. Adjust it according to your actual database configuration.
obclient -h10.xx.xx.xx -P2883 -uroot@mysql_tenant#obdemo -p***** -ACall the
DISABLEsubprogram of theDBMS_SCHEDULERsystem package to disable window compaction.The following is an example execution statement:
obclient> CALL DBMS_SCHEDULER.DISABLE('DAILY_MAINTENANCE_WINDOW');
After disabling the window compaction task, the system will no longer be able to trigger window compaction (including periodic window compaction and manual one-time triggering). Furthermore, if the value of the tenant-level parameter enable_window_compaction remains True, the system will neither trigger window compaction nor perform daily major compactions for the tenant. If you want to perform daily major compactions after disabling the window compaction task, set the value of the tenant-level parameter enable_window_compaction to False. For detailed steps on enabling daily major compactions, see Schedule daily tenant major compactions.
The relationship between the values of the parameter enable_window_compaction and the window compaction task DAILY_MAINTENANCE_WINDOW and the daily compaction behavior is as follows:
enable_window_compaction |
DAILY_MAINTENANCE_WINDOW |
Daily major compaction behavior |
|---|---|---|
| False | False(CALL DBMS_SCHEDULER.DISABLE('DAILY_MAINTENANCE_WINDOW');) |
Triggers daily tenant major compaction. After enable_window_compaction is set to False, no new window compaction tasks are added, but the current round of window compaction is not canceled. If the current round is not completed, a normal tenant major compaction cannot be initiated. Therefore, make sure that the current round of window compaction is complete before switching. |
| False | True(CALL DBMS_SCHEDULER.ENABLE('DAILY_MAINTENANCE_WINDOW');) |
Triggers daily tenant major compaction. After enable_window_compaction is set to False, no new window compaction tasks are added, but the current round of window compaction is not canceled. If the current round is not completed, a normal tenant major compaction cannot be initiated. Therefore, make sure that the current round of window compaction is complete before switching. |
| True | False (CALL DBMS_SCHEDULER.DISABLE('DAILY_MAINTENANCE_WINDOW');) |
No compaction is triggered, that is, neither window compaction nor daily tenant major compaction is triggered. |
| True | True(CALL DBMS_SCHEDULER.ENABLE('DAILY_MAINTENANCE_WINDOW');) |
Triggers window compaction. |
Status query
Run the following command to view the status of window compaction.
SELECT MODE, STATUS, GLOBAL_BROADCAST_SCN, LAST_SCN,
START_TIME, IS_SUSPENDED, IS_ERROR
FROM oceanbase.DBA_OB_MAJOR_COMPACTION;
Compaction mode:
MODE='WINDOW'indicates that the current or most recent round is window compaction.Major compaction version:
GLOBAL_BROADCAST_SCNis the target version for this round, andLAST_SCNis the most recently completed version.Window and Suspension:
START_TIMEis the start time of the recorded window, andIS_SUSPENDED='YES'indicates that it was explicitly suspended.Completion conditions: After the round is completed,
STATUS='IDLE',LAST_SCN=GLOBAL_BROADCAST_SCN, andIS_ERROR='NO'. When a new round is first initiated, the state of the previous round must not be mistaken for that of the current round.
FAQ
Q: If a manual trigger coincides with a daily task, will two rounds be initiated?
No. Both entry points use the same duplicate request check. A manual trigger starts a window from the point of call; if it overlaps with the subsequent daily task, the latter may be rejected as a duplicate request.
Q: Why does
START_TIMEchange when the target version remains the same?This is normal behavior for cross-window continuation.
START_TIMEis updated to the start time of the new window, but the target remains the version unfinished in the previous window. Do not mistake the time change for the start of a new round.Q: Will modifying the duration or next execution time affect the current major compaction?
Modifying
DURATIONaffects the current window: shortening it may close it early; extending it allows the task to continue or resume if it is within the new deadline and not yet finished. ModifyingNEXT_DATEonly adjusts the next trigger time, not the current target or window start. Configuration takes effect after a background refresh, which may have a slight delay.Q: If the window is set to 24 hours, will a new round always start?
No.
DURATION=86400allows the ongoing round to continue scheduling tasks until completion; it does not automatically generate a target upon completion. A new round still requires a subsequent valid trigger.Q: After disabling the daily task, can I still initiate manually?
No. The manual trigger also requires
DAILY_MAINTENANCE_WINDOWto be enabled. Disabling this task stops automatic triggering and also prevents manual triggering and the addition of new window compaction tasks.Q: Will the major compaction resume immediately when I turn on the switch again?
Not necessarily. It can only continue if the current round is not finished, the current time is still within the valid window, the daily task is enabled, and the compaction is not suspended. If the window has ended, a next valid trigger is required. The switch itself does not update the window start or generate a new target.
Q: Is closing a window the same as suspending a major compaction?
No. Normal window closure does not set
IS_SUSPENDEDtoYES. Explicit suspension prevents adding new compaction tasks but does not cancel the current round; after the suspension is lifted, the compaction is still subject to the time window, and the window does not automatically reopen.Q: Is it abnormal that the status is
COMPACTINGbut no tasks are currently running?Not necessarily. Outside the window, it may be waiting for the next window; inside the window, it may be waiting for resources, shared data to be ready, or background scanning.
COMPACTINGindicates that the current round is not finished, but it does not mean that tasks are always running. If no progress is made across multiple valid windows, it should not be simply treated as normal waiting.Q: After enabling window compaction, will regular daily major compactions still be executed?
When
enable_window_compaction=true, regular tenant major compactions are no longer automatically initiated based onmajor_freeze_duty_time, even if the daily window task is disabled. Regular tenant major compactions can still be explicitly initiated if the previous round is complete and original conditions permit.Q: Are compaction errors also part of the normal cross-window waiting?
No.
IS_ERROR='YES'indicates a compaction error, which cannot be treated as normal waiting or resolved by repeatedly re-initiating it. Please retain the error message and contact technical support.