> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $hash (aggregation expression)

## Definition

**New in version 8.3**

Generates and returns a binary hash value ([`BinData`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary)) from a UTF-8 string or binary data. Use `$hash` in an aggregation pipeline to compute binary hashes for storage, verification, or comparison. To get a hexadecimal string instead of binary data, use [`$hexHash`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/hexhash.md#mongodb-expression-exp.-hexHash)

## Syntax

`$hash` has the following syntax:

```javascript
{
   $hash: {
      input: <expression>,
      algorithm: <string>
   }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `input` | [Expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) | Required. The value to calculate the hash for. Must resolve to a valid UTF-8 string or [`BinData`.](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary) |
| `algorithm` | String | Required. The hashing algorithm. Accepted values: `"md5"`; `"sha256"`; `"xxh64"` |

## Behavior

| `input` Value | Result | Notes |
| --- | --- | --- |
| UTF-8 string | [`BinData`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary) | Input must be a valid UTF-8 string. |
| [`BinData`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary) | [`BinData`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary) | |
| `null`, undefined, or missing field | `null` | |

If `input` resolves to `null` or undefined, or refers to a missing field, `$hash` returns `null`.

If `input` resolves to a type other than a UTF-8 string or [`BinData`](https://www.mongodb.com/docs/manual/reference/mongodb-extended-json.md#mongodb-bsontype-Binary), `$hash` returns an error.

If `algorithm` is not one of the accepted values, `$hash` returns an error.

**Important:**

MD5 is not a cryptographically secure algorithm and is not suitable for security-sensitive applications. If you are hashing sensitive data, use `"sha256"` instead.

MD5 is also disabled in FIPS mode. If your deployment runs with FIPS mode enabled, use `"sha256"` or `"xxh64"` instead.

## Examples

The following examples use a collection named `files` with these documents:

```javascript
db.files.insertMany( [
   { _id: 1, filename: "report.pdf" },
   { _id: 2, filename: "archive.zip" }
] )

```

### Hash a Field Value

The following example computes the SHA-256 hash of the `filename` field for each document:

```javascript
db.files.aggregate( [
   {
      $project: {
         filename: 1,
         hash: {
            $hash: {
               input: "$filename",
               algorithm: "sha256"
            }
         }
      }
   }
] )

```

**Output:**

```javascript
[
  {
    _id: 1,
    filename: 'report.pdf',
    hash: Binary.createFromBase64('ZGbkUKFrd7hlxYKda2xW2fiSlWR1ZC2+uczENA/gGxU=', 0)
  },
  {
    _id: 2,
    filename: 'archive.zip',
    hash: Binary.createFromBase64('jsO6p+AcJW/43CrXux9Tpmq+hHLmCKPmqJjcARAsmVA=', 0)
  }
]

```

### Hash a Literal String

The following example hashes a literal string value:

```javascript
db.aggregate( [
   { $documents: [ { val: "hello" } ] },
   {
      $project: {
         _id: 0,
         hash: {
            $hash: {
               input: "$val",
               algorithm: "xxh64"
            }
         }
      }
   }
] )

```

**Output:**

```javascript
[
  {
    hash: Binary.createFromBase64('JseCfYifbaM=', 0)
  }
]

```

### Hash BinData

The following example computes the SHA-256 hash of a binary data field:

```javascript
db.binaries.insertMany( [
   { _id: 1, data: new BinData(0, "aGVsbG8=") }
] )

```

```javascript
db.binaries.aggregate( [
   {
      $project: {
         hash: {
            $hash: {
               input: "$data",
               algorithm: "sha256"
            }
         }
      }
   }
] )

```

**Output:**

```javascript
[
  {
    _id: 1,
    hash: Binary.createFromBase64('LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=', 0)
  }
]

```

### Null or Missing Input

If `input` is `null` or refers to a missing field, `$hash` returns `null`:

```javascript
db.aggregate( [
   {
      $documents: [
         { val: null },
         {}
      ]
   },
   {
      $project: {
         hash: {
            $hash: {
               input: "$val",
               algorithm: "sha256"
            }
         }
      }
   }
] )

```

**Output:**

```javascript
[
  {
    hash: null
  },
  {
    hash: null
  }
]

```

## Learn More

- [`$hexHash`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/hexhash.md#mongodb-expression-exp.-hexHash)

- [`$toHashedIndexKey`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tohashedindexkey.md#mongodb-expression-exp.-toHashedIndexKey)

- [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert)