Skip to content

chash — Cryptographic hash functions

Every example on this page starts here

import polars as pl
import polars_hash as plh

Cryptographic hash functions, on pl.Expr as .chash.

Every expression here accepts Utf8 or Binary and gives a lowercase hexadecimal string. A digest reads bytes, so the data type of the input does not change the result. A null input gives a null output.

sha2_256 

sha2_256() -> Expr

SHA-256 from the SHA-2 family.

Returns:

Type Description
Expr

Utf8 with 64 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha2_256()).item()
'35072c1ae546350e0bfa7ab11d49dc6f129e72ccd57ec7eb671225bbd197c8f1'

sha2_512 

sha2_512() -> Expr

SHA-512 from the SHA-2 family.

Returns:

Type Description
Expr

Utf8 with 128 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha2_512()).item()[:32]
'94f427efefa74c1230c3e93c35104dcb'

sha2_384 

sha2_384() -> Expr

SHA-384 from the SHA-2 family.

Returns:

Type Description
Expr

Utf8 with 96 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha2_384()).item()[:32]
'7f251a65acbe92af4c6a6d624c0860d9'

sha2_224 

sha2_224() -> Expr

SHA-224 from the SHA-2 family.

Returns:

Type Description
Expr

Utf8 with 56 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha2_224()).item()
'69c9392f54e5a0e0fff8945e9ed6475ef89236092a52b2005776912c'

sha3_256 

sha3_256() -> Expr

SHA3-256 from the SHA-3 family.

The digest has the size of sha2_256() and a different construction. The two expressions do not give the same value.

Returns:

Type Description
Expr

Utf8 with 64 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha3_256()).item()
'fed30406b832b6c457e1e3605016eadfe7b57074c050e16ce2321de734ab29f4'

sha3_512 

sha3_512() -> Expr

SHA3-512 from the SHA-3 family.

Returns:

Type Description
Expr

Utf8 with 128 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha3_512()).item()[:32]
'3d96f9b16a74980badc6aa05f8f102d7'

sha3_384 

sha3_384() -> Expr

SHA3-384 from the SHA-3 family.

Returns:

Type Description
Expr

Utf8 with 96 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha3_384()).item()[:32]
'd407e9fb45a350dce0d557f4d3d514f0'

sha3_224 

sha3_224() -> Expr

SHA3-224 from the SHA-3 (Keccak) family.

Returns:

Type Description
Expr

Utf8 with 56 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha3_224()).item()
'e24c066a49e260ba46a7b73d5d2374bfe86670be8ebbdf547bfce343'

sha3_shake128 

sha3_shake128(*, length: int) -> Expr

SHAKE128, the extendable-output function from the SHA-3 family.

Every other digest in this namespace has a fixed size. Here you set the size.

Parameters:

Name Type Description Default
length int

The digest size in bytes. The hexadecimal output has two characters for each byte. A length of 0 gives an empty string. A negative length raises ComputeError.

 required

Returns:

Type Description
Expr

Utf8 with 2 × length characters.
Note

A short output is the start of a longer output for the same input. If you cut a long digest to n bytes, you get the digest that length=n gives.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.sha3_shake128(length=10)).item()
'6b57b385e070e3534257'

blake3 

blake3() -> Expr

BLAKE3 with the default 256-bit output.

BLAKE3 is much faster than SHA-2. Use it for large quantities of data.

Returns:

Type Description
Expr

Utf8 with 64 characters.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.blake3()).item()
'9833e5324eb2400de814730f4e92810905351bc0451e10b75847210c1d7c37ed'

Each expression in this namespace also hashes the bytes of a Binary column:

>>> pl.select(pl.lit(b"my_bytes").chash.blake3()).item()
'4656d42e3468733c9316ef5d4e4488682fc41ad441644ca63cde6aced8378605'

hmac_sha256 

hmac_sha256(*, key: str) -> Expr

Keyed HMAC-SHA256 (RFC 2104).

The digest is a function of the input and the key. One input with two different keys gives two different digests.

Parameters:

Name Type Description Default
key str

The key. It can have any length, and an empty key is permitted. polars-hash expands the key one time for each expression, not one time for each row.

 required

Returns:

Type Description
Expr

Utf8 with 64 characters.
Warning

polars-hash writes key into the keyword arguments of the expression. The key therefore appears in the output of explain() and in each plan that you cache or write to a log.

Examples:

>>> df = pl.DataFrame({"foo": ["hello_world"]})
>>> df.select(plh.col("foo").chash.hmac_sha256(key="secret")).item()
'e0f5b5bb7264e77b340a55a694a6c9ca4edc035c394c703a0408f099563be1ca'