Skip to content
Product
DBaaS
Service-Specific
ClickHouse
How-To
Tune the vector similarity index cache in Managed ClickHouse®

Tune the vector similarity index cache in Managed ClickHouse®

Tune the vector similarity index cache in Managed ClickHouse® to improve vector search performance for Hierarchical Navigable Small World (HNSW) indexes.

HNSW is a graph-based index that speeds up approximate nearest neighbor search on vector columns.

Managed ClickHouse uses a segmented least recently used (SLRU) cache to keep HNSW index data in memory during vector search queries.

If the cache evicts index data too often, ClickHouse reloads it from disk during queries, which can significantly increase query latency.

How the cache works

The size of the cache is set by server_settings.vector_similarity_index_cache_size, expressed as a fraction of the total server memory. It is the only vector cache setting you can change on Managed ClickHouse, and its default is 0.07, meaning 7% of the memory allocated to the ClickHouse server. Setting it to 0 disables the cache, and the maximum accepted value is 0.5.

The cache itself is an SLRU cache with two segments:

  • Protected segment: Stores frequently used index entries.
  • Probationary segment: Stores newly loaded or less frequently used index entries.

The share of the cache reserved for the protected segment is fixed by the platform at 0.5 through the read-only server setting vector_similarity_index_cache_size_ratio. You can read its value from system.server_settings, but you cannot change it.

ClickHouse stores HNSW indexes per table part, a chunk of table data on disk. To avoid repeated evictions, the protected segment must be large enough to hold the largest per-part HNSW index used by your queries.

Note

Table part structure affects cache behavior. A table with many smaller parts might cache more efficiently than one with a single large merged part because each smaller per-part HNSW index is more likely to fit within the protected segment.

Monitor part structure if you continue to see evictions after increasing the cache size.

Prerequisites

  • A Managed ClickHouse service running ClickHouse 25.8 or later.
  • A table with an HNSW vector similarity index and an active vector search workload.
  • A SQL client, such as the ClickHouse client, to run the monitoring queries.

Configure the cache size

Set the cache size as a fraction of the server memory, between 0 and 0.5:

echo '{"clickhouse-settings":{"server_settings":{"vector_similarity_index_cache_size":0.15}}}' | \
  exo x update-dbaas-service-clickhouse my-clickhouse -z ch-gva-2

Read the effective value back from the service:

SELECT name, value FROM system.server_settings
WHERE name LIKE '%vector_similarity%';

Caution

Vector search performance does not degrade gradually when the cache is too small. If the protected segment cannot hold the largest per-part HNSW index, ClickHouse evicts and reloads index entries repeatedly, causing a sharp increase in query latency.

The best value depends on:

  • The size of the HNSW indexes.
  • The number and size of table parts.
  • Query concurrency and access patterns.
  • Table merges that create larger parts over time.

As a rule of thumb, set the cache size so the protected SLRU segment, which is half of the cache, can hold the largest per-part HNSW index without eviction.

Monitor cache health

Use system.events to monitor vector similarity index cache activity:

SELECT
    event,
    value
FROM system.events
WHERE event LIKE '%VectorSimilarity%'
ORDER BY event;

Monitor VectorSimilarityIndexCacheWeightLost. If this value is greater than 0 during steady-state vector search queries, ClickHouse evicts vector index data. Increase server_settings.vector_similarity_index_cache_size and run the workload again.

Note

system.events omits counters that are still at zero, so an event that does not appear in the result has never fired. If VectorSimilarityIndexCacheWeightLost is absent, no eviction has occurred.

Note

Do not rely on hit rate alone to assess cache health. A high hit rate can coexist with evictions if ClickHouse reloads and reinserts indexes repeatedly. For stable vector search performance, keep VectorSimilarityIndexCacheWeightLost at 0 during steady-state queries.

Troubleshoot slow vector search queries

If vector search queries are slower than expected:

  1. Verify that the query uses the HNSW vector similarity index.
  2. Run the system.events query to monitor vector similarity index cache activity.
  3. Confirm whether VectorSimilarityIndexCacheWeightLost increases during steady-state queries.
  4. If evictions occur, increase server_settings.vector_similarity_index_cache_size.
  5. Monitor query latency and cache events again.

If evictions continue after increasing the cache size, the protected segment might still be too small for the largest per-part HNSW index. Review the table part structure.

Related pages

Last updated on
Enable reading and writing data across shards in Managed ClickHouse®