> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Contains one row per entry currently stored in the deserialized columns cache. The cache keeps previously read and deserialized columns of `MergeTree` data parts in memory, so repeated reads of the same row range do not pay for decompression and deserialization again.

# system.columns_cache

<h2 id="description">
  Description
</h2>

Contains one row per entry currently stored in the deserialized columns cache. The cache keeps previously read and deserialized columns of `MergeTree` data parts in memory, so repeated reads of the same row range do not pay for decompression and deserialization again.

Each entry corresponds to a contiguous range of granules `[row_begin, row_end)` of a single column of a single data part, within a fixed stripe of the part of about 65536 rows. Reads are served from the cache granule by granule, and the stripes are the same for every read of the part, so the entries do not depend on how a query splits the part into mark ranges: a read that touches only some granules of a stripe caches those, and adjacent ranges written by different reads are merged.

The cache identifies entries by table UUID, so it is only active for tables in databases that assign UUIDs, such as `Atomic`, `Replicated`, and `Shared` (the default database engine in ClickHouse Cloud). Tables in legacy `Ordinary` databases have no UUID and are silently excluded from the cache. Only wide parts participate in the cache; compact parts are silently excluded.

The cache is controlled by the server settings `columns_cache_size` (by default `columns_cache_size_to_ram_ratio` of the memory available to the server) and `columns_cache_size_ratio`, and by the query-level settings `use_columns_cache`, `enable_reads_from_columns_cache`, `enable_writes_to_columns_cache`, `columns_cache_max_estimated_bytes_to_write_to_cache`, and `columns_cache_max_bytes_to_write_to_cache`. It can be dropped manually with [`SYSTEM DROP COLUMNS CACHE`](/docs/reference/statements/system).

The rows are filtered by access rights: an entry is visible only to a user who may see both its table and its column, that is holds `SHOW TABLES` on the table and `SHOW COLUMNS` on the column. A grant of `SHOW COLUMNS` on `*.*` does not bypass a revoke on an individual table or column, because this table exposes operational data (part names, row ranges and cached sizes) and not only schema. Entries of a table that no longer exists carry no name to check, so they are visible only to a user holding `SHOW COLUMNS` globally.

<h2 id="columns">
  Columns
</h2>

* `database` ([String](/docs/reference/data-types/string)) — Database name of the table the part belongs to.
* `table` ([String](/docs/reference/data-types/string)) — Table name.
* `table_uuid` ([UUID](/docs/reference/data-types/uuid)) — UUID of the table. Stable across renames.
* `part` ([String](/docs/reference/data-types/string)) — Name of the data part.
* `column` ([String](/docs/reference/data-types/string)) — Name of the column.
* `row_begin` ([UInt64](/docs/reference/data-types/int-uint)) — Starting row index of the cached range (inclusive).
* `row_end` ([UInt64](/docs/reference/data-types/int-uint)) — Ending row index of the cached range (exclusive).
* `rows` ([UInt64](/docs/reference/data-types/int-uint)) — Number of rows in the cached range (`row_end - row_begin`).
* `bytes` ([UInt64](/docs/reference/data-types/int-uint)) — Memory the entry retains, in bytes: the allocated size of the cached column plus a small per-entry overhead. This is the quantity the cache is bounded by, so the sum of this column over all entries stays within `columns_cache_size`. It can be larger than the logical size of the rows, because a column keeps the capacity it was allocated with.

<h2 id="examples">
  Examples
</h2>

Total memory consumed by cached columns, per table:

```sql theme={null}
SELECT
    database,
    table,
    formatReadableSize(sum(bytes)) AS size,
    sum(rows) AS rows,
    count() AS entries
FROM system.columns_cache
GROUP BY database, table
ORDER BY sum(bytes) DESC
```

Largest individual cache entries:

```sql theme={null}
SELECT database, table, part, column, row_begin, row_end, rows, formatReadableSize(bytes) AS size
FROM system.columns_cache
ORDER BY bytes DESC
LIMIT 10
```

<h2 id="see-also">
  See also
</h2>

* [SYSTEM DROP COLUMNS CACHE](/docs/reference/statements/system) — The statement which drops every entry of the columns cache.