keepcalculator

06 Numbers and Powers

Cache Keys: Data Identity vs Routine Name

Card No. 06·75758 · Updated · Standard formula, shown below

Cache keys should identify the data, not the routine name. When you cache a function’s result, the key must represent the inputs and the data version, not just which function produced it; using the routine name alone causes stale or incorrect data to be served when the function’s logic or underlying data changes.

Background: Why Caching Exists

Caching stores the result of an expensive operation so future requests can reuse it without recomputing. The cache key is the lookup value: given a key, the cache returns the stored result. If two different operations produce the same key, one result overwrites the other; if the same operation produces different keys, the cache misses and recomputes. The key’s design determines correctness, hit rate, and memory usage.

How Cache Keys Work

A cache key is typically a string or a hash of a string. When you call a function, you build a key from the arguments, then check the cache. If the key exists, return the cached value; otherwise run the function and store the result under that key.

The key must uniquely identify the data that the result depends on. For a function getUserProfile(userId), the key should include userId and a version of the profile schema. If you only use the routine name "getUserProfile", every user shares the same cache entry, and the first user’s profile is served to everyone.

Choosing the Right Key: Data Identity

Data identity means the key reflects everything that affects the result. For a pure function (same inputs always produce same output), the inputs are the identity. For a function that reads from a database, the key must include the query parameters and a version of the data model. For a function that depends on configuration, include the config version.

  • Function arguments: always include them, even if you think they are constant.
  • Data version: a schema version or a data source ID. When you change the database schema or the underlying dataset, old cached values become invalid.
  • Locale/currency: if the result is localized, include the locale and currency codes.
  • Permissions/tenant: if the result depends on the user’s role or tenant, include those.

Common Problems with Routine-Name Keys

Using the routine name alone (or as the only part of the key) causes several issues:

  • Cross-user data leakage: one user’s result is served to another.
  • Stale data after code updates: you change the function’s logic, but the cache still returns old results because the key hasn’t changed.
  • Cache poisoning: a malicious user can craft an input that produces a key colliding with another user’s, overwriting it.
  • Low hit rate: if you include too much (like a timestamp) the key changes every call, making the cache useless.

Practical Examples

Consider a function that returns the weather for a city:

function getWeather(city) {
  const key = `weather:${city}:v1`;
  // check cache, fetch from API if missing, store under key
}

The key includes the city and a version v1. When the weather API changes its data format, you bump the version to v2, invalidating all old entries. If you had used just "weather", every city would share one entry, and the first city’s weather would be served for all.

Another example: a function that calculates shipping cost based on weight and destination:

function shippingCost(weight, country) {
  const key = `ship:${weight}:${country}:v3`;
  // ...
}

Here the key includes the weight and country, and a version for the rate table.

Comparing Key Strategies

Different strategies balance simplicity and correctness:

  • Routine name only: simplest, but almost always wrong for multi-argument functions.
  • Routine name + arguments: good for pure functions, but misses data version changes.
  • Routine name + arguments + data version: recommended for most cases. The version can be a constant you bump manually or a hash of the underlying data.
  • Hash of the entire key: reduces memory and speeds up lookup, but you lose readability for debugging.

Costs and Trade-offs

Longer keys use more memory, but the cost is usually negligible compared to the cost of recomputing. The real cost is in maintenance: you must remember to bump the version when data changes. Some systems use automatic invalidation (e.g., Redis with key expiration), but that only helps if you set appropriate TTLs.

Another cost is key collision. If you hash a long string, collisions are rare but possible. Use a strong hash (e.g., SHA-256) and consider a namespace prefix to reduce collision risk.

Safety and Best Practices

  • Never trust user input directly in a key without sanitizing, as it could cause cache poisoning.
  • Use a version constant for the data schema, and update it whenever the data structure changes.
  • Set a TTL to avoid serving forever-stale data.
  • Monitor cache hit rate to ensure your keys are not too granular or too coarse.

Frequently Asked Questions

What if my function has no arguments?

If the function takes no arguments, the routine name alone might be sufficient, but only if the underlying data never changes. If the data can change (e.g., a config file), include a version or a last-modified timestamp.

Should I include the routine name at all?

Yes, as a namespace prefix. It prevents collisions with other functions that might use the same argument values. For example, user:123 and order:123 are different keys.

How do I invalidate a cache entry when data changes?

You can delete the specific key, or use a versioned key and bump the version. Some caches support tags or patterns to delete multiple keys at once, but that is implementation-specific.

What is the difference between a cache key and a cache tag?

A key is the unique identifier for a single entry. A tag is a label attached to multiple entries, allowing you to invalidate all entries with that tag at once. For example, tag all user-related entries with user:123 and delete them when the user updates.

Is it safe to use a hash of the key?

Yes, as long as the hash is collision-resistant (e.g., SHA-256) and you accept the tiny risk. Hashing reduces memory and speeds up lookup, but makes debugging harder because you cannot read the key directly.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →