Skip to content

Document the minimum interval between Query Store size-based cleanups - #10496

Open
Rudi Bruchez (rudi-bruchez) wants to merge 1 commit into
MicrosoftDocs:livefrom
rudi-bruchez:fix/query-store-cleanup-min-period
Open

Rudi Bruchez (rudi-bruchez) wants to merge 1 commit into
MicrosoftDocs:livefrom
rudi-bruchez:fix/query-store-cleanup-min-period

Conversation

@rudi-bruchez

Copy link
Copy Markdown
Contributor

What's wrong

The SIZE_BASED_CLEANUP_MODE = AUTO paragraph says that size-based cleanup "is automatically activated when size on disk reaches 90% of MAX_STORAGE_SIZE_MB", and the MAX_STORAGE_SIZE_MB section says the cleanup "is also triggered" when the limit is breached. Neither says that a cleanup pass is followed by a minimum delay. When the store fills again within 15 minutes of a pass, cleanup does not run: Query Store stays in READ_ONLY (readonly_reason 65536) until 900 seconds have passed since the previous pass. Users who watch the store go read-only right after a cleanup have no way to tell from the page why it does not recover.

Evidence

SQL Server 2022 CU27-GDR (16.0.4305.5) and SQL Server 2025 CU10 (17.0.5035.5), Developer edition, Linux containers. Also seen on SQL Server 2019 CU32-GDR. Two fresh databases, MAX_STORAGE_SIZE_MB = 5, capture ALL, SIZE_BASED_CLEANUP_MODE = AUTO, DATA_FLUSH_INTERVAL_SECONDS 60 and 180, AUTO_CLOSE OFF.

-- Size-based cleanup minimum repeat period: repro
-- Two fresh databases, MAX_STORAGE_SIZE_MB = 5, capture ALL, flush 60 s and 180 s
CREATE DATABASE qs_cleanup_60;
CREATE DATABASE qs_cleanup_180;
GO
ALTER DATABASE qs_cleanup_60 SET QUERY_STORE = ON (OPERATION_MODE = READ_WRITE, QUERY_CAPTURE_MODE = ALL,
    MAX_STORAGE_SIZE_MB = 5, DATA_FLUSH_INTERVAL_SECONDS = 60, INTERVAL_LENGTH_MINUTES = 1, SIZE_BASED_CLEANUP_MODE = AUTO);
ALTER DATABASE qs_cleanup_180 SET QUERY_STORE = ON (OPERATION_MODE = READ_WRITE, QUERY_CAPTURE_MODE = ALL,
    MAX_STORAGE_SIZE_MB = 5, DATA_FLUSH_INTERVAL_SECONDS = 180, INTERVAL_LENGTH_MINUTES = 1, SIZE_BASED_CLEANUP_MODE = AUTO);
GO
CREATE EVENT SESSION qs_cleanup ON SERVER
    ADD EVENT qds.query_store_disk_size_over_limit,
    ADD EVENT qds.query_store_disk_size_below_limit,
    ADD EVENT qds.query_store_size_retention_cleanup_started,
    ADD EVENT qds.query_store_size_retention_cleanup_finished,
    ADD EVENT qds.query_store_size_retention_cleanup_skipped
    ADD TARGET package0.event_file (SET filename = N'qs_cleanup');
ALTER EVENT SESSION qs_cleanup ON SERVER STATE = START;
GO
WAITFOR DELAY '00:01:00';
GO

-- Load, run once per database with sqlcmd -v DB=qs_cleanup_60 then DB=qs_cleanup_180, in parallel
USE $(DB);
SET NOCOUNT ON;
DECLARE @end datetime2 = DATEADD(MINUTE, 22, SYSUTCDATETIME()), @i int = 0, @sql nvarchar(400);
WHILE SYSUTCDATETIME() < @end
BEGIN
    SET @i += 1;
    SET @sql = N'SELECT COUNT(*) FROM sys.objects WHERE object_id = ' + CAST(@i AS nvarchar(10)) + N' OPTION (MAXDOP 1);';
    EXEC (@sql);
    IF @i % 20 = 0 WAITFOR DELAY '00:00:01';
END;
SELECT @i AS queries_sent;

-- Read the events
SELECT CONVERT(char(8), CAST(x.timestamp_utc AS datetime2(0)), 108) AS utc, DB_NAME(d.v.value('(event/data[@name="database_id"]/value)[1]', 'int')) AS db,
       x.object_name,
       d.v.value('(event/data[@name="time_since_last_cleanup_seconds"]/value)[1]', 'bigint') AS since_last_s,
       d.v.value('(event/data[@name="min_repeat_period_seconds"]/value)[1]', 'bigint') AS min_repeat_s,
       d.v.value('(event/data[@name="deleted_query_count"]/value)[1]', 'bigint') AS deleted
FROM sys.fn_xe_file_target_read_file(N'qs_cleanup*.xel', NULL, NULL, NULL) AS x
CROSS APPLY (SELECT CAST(x.event_data AS xml)) AS d (v)
ORDER BY x.timestamp_utc;

Observed, identical on 2022 and 2025: the first pass runs at 11:59:10 UTC in both databases. The limit is breached again at 12:00:22. From then on, every size check raises query_store_size_retention_cleanup_skipped with min_repeat_period_seconds = 900 and time_since_last_cleanup_seconds growing (72, 131, ..., 851), and the store stays read-only. The next pass runs at 12:14:20 with a 60-second flush interval (900 s after the first), and at 12:16:20 with a 180-second flush interval (the first size check after 900 s).

Expected per the current text: a cleanup each time the limit is breached.

Change

Adds two sentences to the AUTO description of SIZE_BASED_CLEANUP_MODE in the SQL Server section: cleanup runs at most once every 15 minutes, and a store that reaches the limit again before then stays read-only until the next cleanup. The Azure SQL Database and Managed Instance sections carry the same paragraph; I didn't measure there, so I left them unchanged.

@prmerger-automator

Copy link
Copy Markdown
Contributor

Rudi Bruchez (@rudi-bruchez) : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit c6aada7:

✅ Validation status: passed

File Status Preview URL Details
docs/t-sql/statements/alter-database-transact-sql-set-options.md ✅Succeeded

For more details, please refer to the build report.

@v-dirichards

Copy link
Copy Markdown
Contributor

Umachandar Jayachandran (@uc-msft)

Can you review the proposed changes?

Important: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The documentation update clearly covers the SQL Server Query Store cleanup cooldown and the resulting read-only behavior, with no active review issues identified.

No open issues 🎉

What changed in this PR

Documents the minimum 15-minute interval between SQL Server Query Store size-based cleanup passes and explains why Query Store can remain read-only when the storage limit is reached again during that interval.

Changes:

  • Updates the SQL Server SIZE_BASED_CLEANUP_MODE = AUTO description.
  • Clarifies the read-only behavior until the next eligible cleanup.
File Description
docs/​t-sql/​statements/​alter-database-transact-sql-set-options.md Adds the size-based cleanup cooldown and read-only behavior to the SQL Server Query Store options documentation.

Review effort: Lite

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants