Those internals are not part of Rust's stable API. They can change without breaking user code. The useful part is understanding the shape of the current design and the costs it creates.

1. Hashing is supplied, not hard-coded

HashMap<K, V, S> stores a hash builder S. Each operation asks it for a hasher, feeds the key through Hash, and uses the resulting integer to begin a lookup. The default RandomState is seeded per map, which makes deliberately constructed collision attacks harder.

The exact default hashing algorithm is deliberately not a contract. Code that needs a different speed or security trade-off can provide another BuildHasher, but every key already in a map must have been processed by the same builder.

2. Control bytes narrow the search

The table keeps key-value storage alongside a compact control byte for each bucket. A control byte records whether the bucket is full, empty, or deleted. For a full bucket it also keeps a short fingerprint derived from the hash.

The remaining hash bits choose the first group of buckets to inspect. The table compares the wanted fingerprint against a group of control bytes at once, using vector instructions where they are available. Only matching fingerprints become candidates for a full key comparison.

That separation matters. Most misses are rejected by metadata that is much smaller and denser than the keys themselves.

3. Collisions probe another group

This is open addressing: colliding entries live elsewhere in the same table, not in a linked structure hanging from one bucket. If the first group does not contain the key, the probe sequence moves to another group and continues.

A genuinely empty bucket ends an unsuccessful lookup. A deleted bucket cannot, because entries later in the probe sequence may still depend on that path. Deletion therefore leaves a tombstone until later maintenance can reclaim it.

4. Capacity leaves room for probing

The table grows before every bucket is occupied. The SwissTable-style layout keeps roughly one slot in eight available so lookups usually find an empty bucket quickly; the exact growth policy remains an implementation detail.

Growing allocates a larger raw table and redistributes the entries. If the approximate size is already known, with_capacity or reserve avoids repeating that work.

use std::collections::HashMap;

let mut counts: HashMap<String, u64> = HashMap::with_capacity(1_024);

for word in ["timeout", "retry", "timeout"] {
    *counts.entry(word.to_owned()).or_insert(0) += 1;
}

// String implements Borrow<str>, so this lookup allocates nothing.
assert_eq!(counts.get("timeout"), Some(&2));

5. Ownership shapes the public API

Insertion moves owned keys and values into the map. Lookup is more flexible: get can accept a borrowed form of the key when the stored key implements Borrow for it and both forms hash and compare the same way. A map keyed by String can therefore be queried with &str.

The entry API performs the lookup once and then exposes the occupied or vacant case. That is why counters and in-place updates use entry instead of a get-then-insert pair.

Conclusion

The useful model is a hash builder feeding an open-addressed table, with compact metadata filtering candidates before key comparison. Rust then layers ownership, borrowing, and entry on top so callers can use that table without giving up the language's usual guarantees.

Cache-aside is the default

Cache-aside keeps the database authoritative. A read checks Redis first, falls back to the source on a miss, and stores the result with an expiration. Writes usually invalidate the key so the next read repopulates it. Updating the cache directly can be appropriate, but it also makes ordering between two systems part of the correctness model.

func (s *Service) Product(ctx context.Context, id string) (Product, error) {
	key := "product:" + id

	cached, err := s.cache.Get(ctx, key).Bytes()
	if err == nil {
		var product Product
		if json.Unmarshal(cached, &product) == nil {
			return product, nil
		}
		slog.WarnContext(ctx, "invalid cached product", "key", key)
	} else if !errors.Is(err, redis.Nil) {
		slog.WarnContext(ctx, "redis read failed", "key", key, "error", err)
	}

	product, err := s.products.ByID(ctx, id)
	if err != nil {
		return Product{}, err
	}

	if encoded, err := json.Marshal(product); err == nil {
		if err := s.cache.Set(ctx, key, encoded, 10*time.Minute).Err(); err != nil {
			slog.WarnContext(ctx, "redis write failed", "key", key, "error", err)
		}
	}

	return product, nil
}

redis.Nil is the expected miss. Other Redis errors are observable, but they do not turn a successful source-of-truth read into an application failure. That trade-off only makes sense because this Redis instance is a disposable cache.

Stampedes

When a hot key expires, every concurrent reader misses at once and they all hit the database together. TTL jitter prevents related keys from expiring in lockstep. Request coalescing or a short distributed lock lets one caller recompute while the rest wait briefly. Systems that can tolerate bounded staleness can serve the previous value during that refresh instead.

The right mechanism depends on the cost of recomputation and the consequence of stale data. A lock is not automatically worth adding to every cached read.

Picking an eviction policy

For a Redis instance containing only reproducible cache entries, an allkeys-* policy lets Redis reclaim memory instead of rejecting writes. LRU is a sensible starting point when recent access predicts reuse; LFU can fit workloads where a stable hot set matters more.

If Redis contains data that cannot be regenerated, it is no longer merely a cache. noeviction turns memory pressure into a visible write failure rather than silently discarding that data, but the larger fix is to separate durable state from disposable cache entries and operate them with different policies.

Condition one: the index covers the query

Every column referenced — in SELECT, WHERE and ORDER BY — must be present in the index. INCLUDE adds payload columns without widening the search key:

CREATE INDEX idx_orders_customer
  ON orders (customer_id)
  INCLUDE (status, total_cents);

Condition two: the visibility map is current

The index holds no row visibility information, so Postgres consults the visibility map to learn whether a page is all-visible. Pages dirtied since the last vacuum are not, and those rows require a heap fetch anyway.

Reading the plan

EXPLAIN (ANALYZE, BUFFERS) reports Heap Fetches. Zero means the scan was genuinely index-only. A large number after a bulk load means the table has not been vacuumed — run VACUUM ANALYZE and measure again before touching the index.