Skip to content

Introduce per-table cache of ColumnsDescription for parts to reduce memory usage#89352

Merged
azat merged 2 commits intoClickHouse:masterfrom
azat:columns-description-cache
Nov 18, 2025
Merged

Introduce per-table cache of ColumnsDescription for parts to reduce memory usage#89352
azat merged 2 commits intoClickHouse:masterfrom
azat:columns-description-cache

Conversation

@azat
Copy link
Copy Markdown
Member

@azat azat commented Nov 1, 2025

Changelog category (leave one):

  • Improvement

Changelog entry (a user-readable short description of the changes that goes into CHANGELOG.md):

Introduce a per-table cache of ColumnsDescription for parts, reducing memory usage when tables contain many parts and many columns.

Details

Each part currently stores its own ColumnsDescription (information about all columns). This includes not only full column metadata (including comments), but also IHints, which are used for correcting user input and are not trivial to decouple.

When a table has many columns, this structure becomes large, and storing a full copy for every part leads to significant memory consumption.

In one production setup, 12 GiB out of 73 GiB of memory was occupied by ColumnsDescription objects for 20 K parts with 6.5 M part columns.

As another example, even on an empty server with merges stopped, metric_log alone could cause the server to consume roughly 512 MiB over a few hours while doing almost nothing.

@clickhouse-gh
Copy link
Copy Markdown
Contributor

clickhouse-gh bot commented Nov 1, 2025

Workflow [PR], commit [e8f5478]

Summary:

job_name test_name status info comment
Stateless tests (arm_asan, targeted) failure
03279_database_backup_database_disk_engine FAIL cidb
03277_database_backup_database_file_engine FAIL cidb
BuzzHouse (amd_debug) failure
Buzzing result failure cidb

@clickhouse-gh clickhouse-gh bot added the pr-improvement Pull request with some product improvements label Nov 1, 2025
@azat azat force-pushed the columns-description-cache branch from 20f1eee to e83e721 Compare November 1, 2025 15:53
@azat azat marked this pull request as ready for review November 6, 2025 16:54
…emory usage

I've seen a setup where 7GiB (and this is jemalloc statistics w/o memory
fragmentation) out of 90 was used by the ColumnsDescription, and it is
only for 20K parts (but there are 6.5e6 parts columns).

Also I've seen that with stopped merges, due to metric_log, the server
may consume ~512MiB for a couple of hours with doing almost nothing.
@azat azat force-pushed the columns-description-cache branch from 5ee386b to a3473b8 Compare November 7, 2025 09:07
@davenger davenger self-assigned this Nov 17, 2025
@rschu1ze
Copy link
Copy Markdown
Member

I didn't read this PR in detail but based on the PR description, average readers won't understand how caching helps to reduce memory consumption. Are you saying that, previously the same ColumnDescription existed multiple times in memory, and now it exists once (in the cache) and we are somehow referencing it?

@azat
Copy link
Copy Markdown
Member Author

azat commented Nov 17, 2025

Are you saying that, previously the same ColumnDescription existed multiple times in memory, and now it exists once (in the cache) and we are somehow referencing it?

Yes

I didn't read this PR in detail but based on the PR description, average readers won't understand how caching helps to reduce memory consumption.

I've updated the description to make it cleaner.

@azat azat added this pull request to the merge queue Nov 18, 2025
@azat
Copy link
Copy Markdown
Member Author

azat commented Nov 18, 2025

I've rolled out to ci-logs, and the memory consumption reduced (though there is still more), and it is stable.

UPD: ColumnsDescriptionsCacheSize looks wrong

@azat azat removed this pull request from the merge queue due to a manual request Nov 18, 2025
@azat
Copy link
Copy Markdown
Member Author

azat commented Nov 18, 2025

UPD: ColumnsDescriptionsCacheSize looks wrong

It is actually correct, we should not have it too big, more or less the same size as number of tables, and it indeed looks similar

@azat azat added this pull request to the merge queue Nov 18, 2025
Merged via the queue into ClickHouse:master with commit b1234a4 Nov 18, 2025
129 of 132 checks passed
@azat azat deleted the columns-description-cache branch November 18, 2025 14:08
@robot-ch-test-poll2 robot-ch-test-poll2 added the pr-synced-to-cloud The PR is synced to the cloud repo label Nov 18, 2025
@alexey-milovidov alexey-milovidov added memory When memory usage is higher than expected and removed memory-footprint-reduction labels Jan 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

memory When memory usage is higher than expected pr-improvement Pull request with some product improvements pr-synced-to-cloud The PR is synced to the cloud repo

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants