# Setting the Blob Cache

The blob cache is a local cache of data from an unlimited storage database, also known as a "bottomless" database. Refer to [Local and Unlimited Database Storage Concepts](https://docs.singlestore.com/db/v9.1/manage-data/local-and-unlimited-database-storage-concepts.md) for information on unlimited storage databases.

## Blob Cache Size Engine Variables

The size of the blob cache is controlled by the following engine variables:

| Name                                                           | Description                                                                                                                                                               |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `maximum_blob_cache_size_mb`                                   | Specifies the maximum blob cache size per leaf node. This variable does not sync between nodes. This variable is updated when`maximum_blob_cache_size_percent`is changed. |
| `maximum_blob_cache_size_percent`                              | Sets the maximum percent of disk space that can be used by the blob cache.                                                                                                |
| `maximum_blob_cache_shrink_percent_under_default_spilling_max` | Controls the maximum amount of automatic shrinking of the blob cache.                                                                                                     |

Updates to the `maximum_blob_cache_size_mb` and `maximum_blob_cache_size_percent` engine variable function as follows:

* Changing `maximum_blob_cache_size_percent` changes the value of `maximum_blob_cache_size_mb` and changes the size of the blob cache.
* Changing `maximum_blob_cache_size_mb` changes the value of `maximum_blob_cache_size_mb` and the size of the blob cache but does not update `maximum_blob_cache_size_percent`.
* The `maximum_blob_cache_size_percent` engine variable can be "out of date" if you set `maximum_blob_cache_size_mb` after setting `maximum_blob_cache_size_percent`.
* On a restart, `maximum_blob_cache_size_percent` takes precedence, and sets `maximum_blob_cache_size_mb` to the corresponding value.

> **📝 Note**: SingleStore recommends using only one of the `maximum_blob_cache_size_mb` and `maximum_blob_cache_size_percent` engine variables at a time.

Details related to the blobs cached in the blob cache and events on those blobs are found in the information schema views [MV\_CACHED\_BLOBS](https://docs.singlestore.com/db/v9.1/reference/information-schema-reference/cluster-component/mv-cached-blobs.md) and [MV\_BLOB\_CACHE\_EVENTS](https://docs.singlestore.com/db/v9.1/reference/information-schema-reference/cluster-component/mv-blob-cache-events.md).

## Automatic Resizing of Blob Cache and Blob Cache Shrink Percent Engine Variable

When the disk on which the blob cache is mounted begins to fill, the blob cache automatically shrinks. Thus, anything that uses disk space – logs, trace logs, plancache, audit logs, and files outside the engine – can steal space from the blob cache.

The amount of blob cache shrinking is configurable and is controlled by the `maximum_blob_cache_shrink_percent_under_default_spilling_max` engine variable.

For example, if `maximum_blob_cache_shrink_percent_under_default_spilling_max` is set to `0.3`, the blob cache can shrink to 70% of the configured size of the blob cache. That is the blob cache can shrink to: `(maximum_blob_cache_size_mb* (1- 30%)`.

The `maximum_blob_cache_shrink_percent_under_default_spilling_max` engine variable only controls the maximum amount of blob cache shrinkage when `spilling_maximum_disk_percent` is equal to `-1`, which is the default value.  When `spilling_maximum_disk_percent` is set to a value other than `-1`, query spilling takes precedence and the engine may shrink the blob cache more than the percentage specified by `maximum_blob_cache_shrink_percent_under_default_spilling_max`.

Refer to [Engine Variables](https://docs.singlestore.com/db/v9.1/reference/configuration-reference/engine-variables.md) for details on the engine variables.

***

Modified at: January 14, 2026

Source: [/db/v9.1/manage-data/setting-the-blob-cache/](https://docs.singlestore.com/db/v9.1/manage-data/setting-the-blob-cache/)

(An index of the documentation is available at /llms.txt)