# 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](/product/dbaas/service-specific/clickhouse/how-to/connect-with-clickhouse-cli/), 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`:

```bash
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:

```sql
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:

```sql
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.
1. Run the `system.events` query to monitor vector similarity index cache activity.
1. Confirm whether `VectorSimilarityIndexCacheWeightLost` increases during steady-state
   queries.
1. If evictions occur, increase `server_settings.vector_similarity_index_cache_size`.
1. 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

- [Indexing and data processing in Managed ClickHouse®](/product/dbaas/service-specific/clickhouse/overview/indexing/)
- [Use query cache in Managed ClickHouse®](/product/dbaas/service-specific/clickhouse/how-to/clickhouse-query-cache/)
- [Fetch query statistics for Managed ClickHouse®](/product/dbaas/service-specific/clickhouse/how-to/fetch-query-statistics/)