Skip to content

Consider reducing the amount of time spent on scan operations  #31

Closed

Description

@royvou

I really enjoy this library, easy to get started with and allows us to provide customized redis clients.

Challenge

What we have noticed in our instances with around 20k Keys (there are quite a few pages with tags).
The bottleneck seems excessive (or atleast several 10s of milliseconds) scan operations which take some time to resolve which is called each request due to the refreshtags API call.

Solution

I propose adding an opt-in tagReadMode: "on-demand" (default scan) option. With this option, it would look up only the tags attached to the cached entry and its route.

That would save Redis work on large databases while still being a single source of truth.

Activity

  1. leejpsd commented on Nov 19, 2026

    @leejpsd
    Owner

    Thanks for the report, and for the numbers. I reproduced it locally (Redis 7, redis@5, localhost):

    keys tag markers refreshTags() p50 MGET of 7 markers
    2.5k 500 4 ms <0.1 ms
    20.5k 500 18–35 ms <0.1 ms
    100k 500 166 ms <0.1 ms

    You're right about the cause, and it's a bit worse than "many tags": refreshTags() runs SCAN with a MATCH pattern over the namespace on every request, and Redis SCAN walks the whole keyspace regardless of the pattern. So the cost scales with total keys, not with the number of tags; with 500 markers it goes 4 → 18 → 166 ms as the keyspace grows from 2k to 100k. At 20k keys that's roughly 400 round trips per request (about 200 SCAN calls plus an MGET per chunk), which on a networked Redis easily lands in the tens of milliseconds you're seeing. Nothing avoids it today; tagPubSub speeds up propagation but keeps the scan as a safety net, and raising COUNT only halves it.

    Your proposal is the right shape, and it's how the rest of the code already works: getExpiration() does an MGET of just the tags it's given, and the singular cacheHandler reads an entry's tags on demand in get(). The plural handler is the odd one out.

    Plan:

    • tagReadMode: "on-demand" (opt-in first, default stays "scan"): refreshTags() stops scanning, get() does one MGET of the entry's own tags plus the route's soft tags and compares against entry.timestamp, same as the singular handler. One extra round trip per get, no per-request scan. tagPubSub keeps working with it.
    • The benchmark above goes into scripts/ so the numbers are reproducible, and the PR will include both modes at 20k keys.
    • If on-demand holds up, flip the default in the next minor.

    Two questions that would help decide the default: where does your Redis run (same host, ElastiCache, something else), and are you on redis or ioredis? I'll link the PR here.

  2. leejpsd commented on Nov 19, 2026

    @leejpsd
    Owner

    PR: #32. tagReadMode: "on-demand" as sketched above, plus the benchmark script and docs. Numbers from the script (local Redis 7, p50): scan refreshTags() 17–35 ms at 20k keys and 65–166 ms at 100k; on-demand get() including its MGET stays at 0.1 ms. One extra thing it fixes along the way: when a soft and a hard invalidation land in the same millisecond on two instances, the hard deadline now wins. I'll cut a release once CI is green.

  3. leejpsd commented on Nov 19, 2026

    @leejpsd
    Owner

    Released in 1.1.0.

    // cache-components.cjs
    module.exports = createCacheComponentsHandler({
      client: { type: "redis", url: process.env.REDIS_URL },
      tagReadMode: "on-demand",
    });

    The default is still "scan", so nothing changes until you set it. If you get a chance to run it on your 20k-key instances, the before/after of a cached page's p50/p95 (and where your Redis lives) would be good to have here before I decide about the default.

  4. royvou commented on Nov 19, 2026

    @royvou
    Author

    Thanks for the swift response Will try!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions