Aggregation binary hashing and hashed-index key separation
Parent: MongoDB Aggregation Pipeline · Published reference · snapshot 2026-10-29
↓ Facts as markdownall context files
Source-anchored research for Aggregation binary hashing and hashed-index key separation. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- Applications do not need to precompute hashes to use a hashed index: MongoDB computes the hashes when resolving indexed queries. (low confidence) [source]
- Hashed indexes automatically compute hashes when resolving queries; applications do not need to precompute a $hash digest. Use $toHashedIndexKey for aggregation-side index-hash calculation, or convertShardKeyToHashed() in the shell. (high confidence) [source]
Problems, failure modes and limitations
- $hash returns null for null, undefined, or missing input. For other inputs, a value that is neither a valid UTF-8 string nor BinData produces an error. (low confidence) [source]
- An algorithm value outside the accepted set produces a $hash error. (low confidence) [source]
- $hash raises an error for other input types or an unrecognized algorithm. A numeric or document value therefore needs an explicit application-defined representation before general-purpose hashing. (low confidence) [source]
- Percona lists $hash among the new expressions in its own Percona Server for MongoDB 8.3 Technical Preview announcement dated July 30, 2026. This supports distribution adoption, without independently verifying input/error behavior. (low confidence) [source]
Comparisons and alternatives
- $toHashedIndexKey does not apply collation to strings, even under a non-simple aggregation collation. A hashed index can hash a collation key instead, so its hash can differ from the expression result for the same data. (medium confidence) [source]
Facts and statements
- MongoDB documents $hash as new in 8.3; Percona also includes $hash among the aggregation expressions in its 8.3 technical preview. (medium confidence) (verified as of 2026-07-30) [source]
- $hash computes a BinData digest from a valid UTF-8 string or BinData; $hexHash is the corresponding hexadecimal-string form. (medium confidence) [source]
- The syntax is { $hash: { input: <expression>, algorithm: <string> } }; both fields are required, and input must resolve to a valid UTF-8 string or BinData, apart from the documented nullish cases. (low confidence) [source]
- For null or a missing input field, $hash returns null; $toHashedIndexKey instead hashes null and missing values to a Long. (medium confidence) [source]
- $toHashedIndexKey uses MongoDB hashed-index hashing and returns a fixed-size numeric hash, whereas $hash is a general-purpose binary-digest expression. The operators serve different output and key semantics. (high confidence) [source]
- Hashed-index numeric semantics can collapse distinct inputs: the documented example gives 2.3, 2.2, and 2.9 the same hash after truncation to a 64-bit integer. An index hash is therefore unsuitable as a lossless identity for the original numeric value. (low confidence) [source]
- Migration Verifier documents that its toHashedIndexKey comparison mode can miss an equal-valued Long-to-Double type change. Hash-and-length comparison therefore does not establish full BSON binary equivalence. (low confidence) [source]
- NoSQLBooster 11.1 documents a $.hash({ input: "$password", algorithm: "sha256" }) operator helper for MongoDB 8.3 aggregation; its announcement says the helper includes inline code-completion documentation. (low confidence) (verified as of 2026-09-30) [source]
- MongoDB introduced $hash in 8.3 as an aggregation expression that returns a BinData digest from a UTF-8 string or binary input. (high confidence) [source]
- $hash returns null for null, undefined, or missing input. For null or missing values, $toHashedIndexKey instead returns a Long hash value; replacing one operator with the other changes null semantics. (high confidence) [source]
Children
- No children recorded.