sha256

Use the `sha256()` function to compute the SHA-256 (Secure Hash Algorithm 256) hash of an input string, producing a unique 64-character hexadecimal fingerprint.

## Syntax

```sql
sha256 ("<input_string>")
```

## Parameters

| Name | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------ |
| `input_string` | string | Yes | The string value to be hashed. |

## Returns

The `sha256()` function returns the SHA-256 hash value as a string.

## Usage notes

* The function creates a unique, fixed-length digital fingerprint of the input, commonly employed for data integrity verification or for one-way transformation of sensitive data.
* SHA-256 is a one-way cryptographic hash function, meaning it is computationally infeasible to reverse the hashing process to obtain the original string from its hash.
* The function strictly requires a single string input.

## Examples

### Example 1: Hashing a basic literal string

**Goal**: Compute the SHA-256 hash of a simple literal string.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter hashed_literal = sha256("Hello XQL!")
| fields event_id, hashed_literal
| limit 3
```

**Explanation**: This query adds a new field, `hashed_literal`, containing the SHA-256 hash of the string "Hello XQL!" for each record.

**Output**:

| EVENT\_ID | HASHED\_LITERAL |
| --------- | ---------------------------------------------------------------- |
| 101 | 7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069 |
| 102 | 7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069 |
| 103 | 7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069 |

### Example 2: Hashing an existing string field

**Goal**: Hash the values from an existing string field in the dataset.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter hashed_description = sha256(event_description)
| fields event_id, event_description, hashed_description
| limit 3
```

**Explanation**: The query creates `hashed_description` by applying the `sha256()` function to the `event_description` field for each record.

**Output**:

| EVENT\_ID | EVENT\_DESCRIPTION | HASHED\_DESCRIPTION |
| --------- | ------------------------------ | ---------------------------------------------------------------- |
| 101 | User login successful | f7d9e4a3b0c3e7f2d1a9b8c7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7 |
| 102 | File access attempt | be2254e015ee6b158055c56c2e28a506a77d3b5b112d7c04192b45129c7b960d |
| 103 | Network connection established | 24b74f0c43666f272a85e13b06385a8677c7c3c5b9e0f3c5d6e2e5c8a3d1b7f2 |

### Example 3: Hashing a string derived from a non-string field

**Goal**: Convert a numeric field to a string and then hash it.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter event_id_string = to_string(event_id)
| alter hashed_id = sha256(event_id_string)
| fields event_id, event_id_string, hashed_id
| limit 3
```

**Explanation**: The `event_id` is first converted to a string using `to_string()`, and then `sha256()` hashes this string representation.

**Output**:

| EVENT\_ID | EVENT\_ID\_STRING | HASHED\_ID |
| --------- | ----------------- | ---------------------------------------------------------------- |
| 101 | 101 | d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35 |
| 102 | 102 | f86dd052d9482d8c9735d55b5d1222416b0451a541315b8813a484196ddc8160 |
| 103 | 103 | 9e0416a9a0899f2c3d1c9f4d7629b3c4f9a0d2f0c7e5b6a7d8f9e0c1b2a3d4e5 |

### Example 4: Hashing an empty string

**Goal**: Demonstrate the result of hashing an empty string.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter hashed_empty_string = sha256("")
| fields event_id, hashed_empty_string
| limit 3
```

**Explanation**: Hashing an empty string consistently results in the well-known SHA-256 hash for an empty string.

**Output**:

| EVENT\_ID | HASHED\_EMPTY\_STRING |
| --------- | ---------------------------------------------------------------- |
| 101 | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
| 102 | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
| 103 | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |

### Example 5: Handling NULL input

**Goal**: Demonstrate behavior when the input to the hash function is NULL.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter hashed_null_field = sha256(dst_domain)
| fields event_id, dst_domain, hashed_null_field
| limit 5
```

**Explanation**: When the input to `sha256()` is `NULL` (as seen in event 105), the function consistently returns `NULL` for the output field.

**Output**:

| EVENT\_ID | DST\_DOMAIN | HASHED\_NULL\_FIELD |
| --------- | ----------------- | ---------------------------------------------------------------- |
| 101 | ec2.amazonaws.com | 7f2f11181827457c134012019c4d93e5482329239d57a4141d63e9f425c2763b |
| 102 | sts.amazonaws.com | fdf15a896d92008779b1248039601d0f5e3e2b2a1a0c9b8d7e6f5d4c3b2a1a0d |
| 103 | www.google.com | 121f66cb71158f964092b3a1a36173a728b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3 |
| 104 | dropbox.com | 84b7a137e0c4573130d740a6b47c0b6b23a9b8c7e6d5c4b3a2f1e0d9c8b7a6f5 |
| 105 | NULL | NULL |

## Related articles

* **Stages**: [`alter`](../stages/alter)
* **Functions**: [`md5`](md5), [`sha1`](sha1), [`sha512`](sha512), [`to_string`](to_string)