How to Control Cache Behavior in ParadeDB in PostgreSQL

Galaxy Glossary

How do I change ParadeDB cache behavior in PostgreSQL?

CACHE BEHAVIOR in ParadeDB lets you fine-tune how vector-search results are cached, trading speed for freshness.

Welcome to the Galaxy, Guardian!
You'll be receiving a confirmation email

Follow us on twitter :)

Oops! Something went wrong while submitting the form.

Description

Example H2

Example H3

What does CACHE BEHAVIOR do in ParadeDB?

ParadeDB’s CACHE BEHAVIOR setting tells the extension whether to store vector-search results in shared memory, keep them for a period, or bypass the cache entirely. Tuning it speeds up repeated semantic searches while avoiding stale reads.

When should I enable or disable caching?

Enable AUTO for dashboards or APIs that repeat similar queries. Use DISABLED for data that changes each request, like real-time inventory. Choose MANUAL when you want explicit control through TRUNCATE CACHE statements.

How do I set cache behavior for a specific index?

Pass the index name and policy (AUTO, MANUAL, DISABLED) to paradedb_cache_behavior(). Optional EXPIRY decides how long entries live. Each index can have its own policy.

Can I change the expiry time later?

Yes—re-run paradedb_cache_behavior() with a new EXPIRY. Existing cached items adopt the new limit instantly, so no restart is needed.

Does caching survive a PostgreSQL restart?

No. ParadeDB keeps cache pages in shared memory, which is cleared after a restart. Re-run heavy queries once to warm the cache.

Best practice: monitor hit ratio

Create a Prometheus scrape on paradedb_cache_stats() and alert when hit_ratio < 0.7. Adjust behavior or expiry to reach optimal levels.

Best practice: keep EXPIRY short on mutable data

Ten-minute expiry balances speed and accuracy for rapidly updating tables like Orders and OrderItems. Longer periods risk showing outdated totals.

Why How to Control Cache Behavior in ParadeDB in PostgreSQL is important

How to Control Cache Behavior in ParadeDB in PostgreSQL Example Usage


-- Speed up product search results for 15 min
SELECT paradedb_cache_behavior(
    'products_name_vec_idx',
    'AUTO',
    interval '15 minutes'
);

-- Disable caching on Orders index to ensure real-time totals
SELECT paradedb_cache_behavior('orders_vec_idx', 'DISABLED');

How to Control Cache Behavior in ParadeDB in PostgreSQL Syntax


SELECT paradedb_cache_behavior(
    index_name    TEXT,      -- e.g. 'products_vec_idx'
    policy        TEXT,      -- 'AUTO' | 'MANUAL' | 'DISABLED'
    expiry        INTERVAL   -- optional, e.g. '15 minutes'
);

-- Common policies
-- AUTO      ParadeDB invalidates automatically on writes and reuses hits.
-- MANUAL    Developer controls eviction with TRUNCATE CACHE;
-- DISABLED  Skip cache entirely.

Common Mistakes

Setting AUTO on highly volatile tables. ParadeDB will still cache, causing frequent invalidations and wasted memory. Fix by choosing DISABLED or a short EXPIRY.
Forgetting to quote index names with camelCase. PostgreSQL folds to lowercase, so "ProductsVecIdx" becomes productsvecidx. Fix by using lower-case indexes or double quotes.