Hashed Indexes and Their Role in Shard-Key Distribution

Learning objectives

1. Hashing trades order for distribution

A hashed index stores the hash of a field value. Equal input values map to the same hash, so equality lookup can use the index. Natural range relationships are intentionally lost: lexically adjacent event IDs do not remain adjacent in hashed key space. That is why hashed sharding can spread monotonically increasing keys across shard-key ranges, but range predicates on the hashed field cannot use the hashed index as an ordered range access path.

2. Build a hashed index and inspect actual hash values

docker rm -f atlasmart-mongo-ch11-l4 2>/dev/null || truedocker volume rm atlasmart-mongo-ch11-l4-data 2>/dev/null || truedocker run -d --name atlasmart-mongo-ch11-l4 \  -p 127.0.0.1:27070:27017 \  -v atlasmart-mongo-ch11-l4-data:/data/db \  mongodb/mongodb-community-server:8.3.8-ubuntu2204-slimmongosh "mongodb://127.0.0.1:27070/atlasmart?directConnection=true" --quiet --eval \'printjson({server:db.version(),hello:db.hello().isWritablePrimary}); printjson(db.getSiblingDB("admin").runCommand({getParameter:1,featureCompatibilityVersion:1}))' 

const c=db.events_ch11_l4;c.drop();const docs=[];for(let i=1;i<=40;i++){ docs.push({_id:i,eventId:`evt-${String(i).padStart(3,"0")}`,tenantId:`tenant-${(i%5)+1}`,createdAt:new Date(1760000000000+i*60000),payload:`p-${i}`});}c.insertMany(docs);printjson(c.find({},{_id:0,eventId:1,tenantId:1,createdAt:1}).limit(8).toArray());

const c=db.events_ch11_l4;print(c.createIndex({eventId:"hashed"},{name:"idx_eventId_hashed"}));printjson(c.getIndexes());for(const v of ["evt-001","evt-002","evt-010","evt-020","evt-040"]){ printjson({value:v,hash:convertShardKeyToHashed(v)});}

3. Equality can use hashed access

const c=db.events_ch11_l4;const filter={eventId:"evt-020"};printjson(c.find(filter,{_id:0,eventId:1,tenantId:1}).hint("idx_eventId_hashed").explain("executionStats"));printjson(c.find(filter,{_id:0,eventId:1,tenantId:1}).hint("idx_eventId_hashed").toArray());

4. Deliberately wrong: expect a hashed range scan

The query “evt-010 through evt-019” is about natural string order. A hash is not monotonic with that string order. If range access is important, keep an ordinary ordered index or choose range-based shard-key design.

const c=db.events_ch11_l4;const filter={eventId:{$gte:"evt-010",$lt:"evt-020"}};printjson(c.find(filter,{_id:0,eventId:1}).explain("executionStats"));try{ printjson(c.find(filter,{_id:0,eventId:1}).hint("idx_eventId_hashed").explain("executionStats"));}catch(e){ printjson({name:e.name,code:e.code,message:e.message}); }

5. Hash values are not a standalone sharding simulation

convertShardKeyToHashed() uses the same hash function and lets us see that nearby input values do not produce nearby ordered values. But printing hashes on one process does not prove distribution across shards. Real distribution depends on sharded-cluster metadata, chunks/ranges, balancer activity, zones, and the shard key.

const values=[];for(let i=1;i<=200;i++) values.push(`evt-${i}`);const hashes=values.map(v=>({v,h:NumberLong(convertShardKeyToHashed(v))}));const ordered=hashes.slice().sort((a,b)=>a.h.toString().localeCompare(b.h.toString()));printjson({sample:hashes.slice(0,10),note:"Hashes are not in eventId lexical order; a sharded cluster uses hashed shard-key ranges, not this standalone array, to distribute chunks."});

6. Verification, cleanup, and production judgment

Verification checklist

• The index metadata uses "hashed" on eventId.
• convertShardKeyToHashed() returns deterministic 64-bit hash values.
• An equality lookup is explained against the hashed candidate.
• The range query is not described as a hashed range scan.
• No claim of multi-shard distribution is made from a standalone lab.
• The lesson distinguishes hashed index semantics from hashed sharding deployment.

Production judgment. Hashed shard keys can smooth writes for monotonic keys, but they weaken range locality and can make range-based operations scatter across shards. Choose high-cardinality fields, inspect common routing predicates, and test distribution under real sharded topology. A compound hashed index can contain one hashed term plus ordered terms, but added fields do not erase routing tradeoffs. Security and tenant isolation still require authorization; a hashed tenant key is not an access-control boundary. Lesson 5 closes the chapter by separating built-in self-managed text/geospatial indexes from the richer Search/Vector Search subsystem.

docker rm -f atlasmart-mongo-ch11-l4docker volume rm atlasmart-mongo-ch11-l4-data

Authoritative references

• MongoDB 8.3 release notes — Current 8.3 baseline and patch-sensitive behavior; re-check before reproduction.
• Index types — Current index-family overview and boundaries.
• Explain results — Planner and execution evidence used throughout this chapter.
• mongosh changelog — mongosh version used for chapter commands.
• Hashed indexes — Hashed index semantics and restrictions.
• Create a hashed index — Equality/distribution rationale and range-query limitation.
• convertShardKeyToHashed — mongosh helper for observing the actual hash transformation.