API Reference¶

This page lists everything public in polars-hash. One import registers the six namespaces on pl.Expr:

import polars_hash as plh

plh.col and plh.concat_str are typed wrappers around pl.col and pl.concat_str. They declare these namespaces. Refer to plh.col and pl.col.

`chash` — cryptographic¶

Each expression accepts Utf8 or Binary. Each one gives Utf8 in hexadecimal, unless the table shows a different type. Full page: chash.

Expression	Input	Output	Description
`chash.sha2_224()`	Utf8, Binary	Utf8	SHA-224 from the SHA-2 family.
`chash.sha2_256()`	Utf8, Binary	Utf8	SHA-256 from the SHA-2 family.
`chash.sha2_384()`	Utf8, Binary	Utf8	SHA-384 from the SHA-2 family.
`chash.sha2_512()`	Utf8, Binary	Utf8	SHA-512 from the SHA-2 family.
`chash.sha3_224()`	Utf8, Binary	Utf8	SHA3-224 from the SHA-3 family.
`chash.sha3_256()`	Utf8, Binary	Utf8	SHA3-256 from the SHA-3 family.
`chash.sha3_384()`	Utf8, Binary	Utf8	SHA3-384 from the SHA-3 family.
`chash.sha3_512()`	Utf8, Binary	Utf8	SHA3-512 from the SHA-3 family.
`chash.sha3_shake128(length)`	Utf8, Binary	Utf8	SHAKE128 extendable-output function. Gives `length` bytes.
`chash.blake3()`	Utf8, Binary	Utf8	BLAKE3 with 256-bit output.
`chash.hmac_sha256(key)`	Utf8, Binary	Utf8	Keyed HMAC-SHA256.
`chash.sha256()`	Utf8, Binary	Utf8	Deprecated. Alias of `sha2_256()`.

`nchash` — non-cryptographic¶

Full page: nchash.

Expression	Input	Output	Description
`nchash.wyhash()`	Utf8, Binary	UInt64	wyhash. The seed is always 0.
`nchash.xxhash32(seed)`	Utf8, Binary	UInt32	XXH32.
`nchash.xxhash64(seed)`	Utf8, Binary	UInt64	XXH64.
`nchash.xxh3_64(seed)`	Utf8, Binary	UInt64	XXH3 with 64-bit output.
`nchash.xxh3_128(seed)`	Utf8, Binary	UInt128 or Binary	XXH3 with 128-bit output.
`nchash.murmur32(seed)`	Utf8, Binary	UInt32	MurmurHash3, x86 32-bit variant.
`nchash.murmur128(seed)`	Utf8, Binary	UInt128 or Binary	MurmurHash3, x64 128-bit variant.
`nchash.farmhash32()`	Utf8, Binary	UInt32	FarmHash `fingerprint32`.
`nchash.farmhash64()`	Utf8, Binary	UInt64	FarmHash `fingerprint64`.
`nchash.cityhash32()`	Utf8, Binary	UInt32	CityHash `CityHash32`.
`nchash.cityhash64(seed)`	Utf8, Binary	UInt64	CityHash `CityHash64`, or `CityHash64WithSeed` when given a seed.
`nchash.cityhash128()`	Utf8, Binary	UInt128 or Binary	CityHash `CityHash128`.
`nchash.gxhash32(seed)`	Utf8, Binary	UInt32	GxHash with 32-bit output. Needs a CPU with AES instructions.
`nchash.gxhash64(seed)`	Utf8, Binary	UInt64	GxHash with 64-bit output. Needs a CPU with AES instructions.
`nchash.gxhash128(seed)`	Utf8, Binary	UInt128 or Binary	GxHash with 128-bit output. Needs a CPU with AES instructions.
`nchash.md5()`	Utf8, Binary	Utf8	MD5.
`nchash.sha1()`	Utf8, Binary	Utf8	SHA-1.

`geohash` — geohash¶

Full page: geohash.

Expression	Input	Output	Description
`geohash.from_coords(len)`	Struct	Utf8	Encodes `{latitude, longitude}` to a geohash of `len` characters. `len` is 1 to 12.
`geohash.to_coords()`	Utf8	Struct	Decodes a geohash to `{longitude, latitude}`.
`geohash.neighbors()`	Utf8	Struct	Gives the eight adjacent geohashes: `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw`.

`h3` — H3 index¶

Full page: h3.

Expression	Input	Output	Description
`h3.from_coords(len)`	Struct	Utf8	Encodes `{latitude, longitude}` to an H3 cell index at resolution `len`. `len` is 1 to 15.

`timehash` — time bucket¶

Full page: timehash.

Expression	Input	Output	Description
`timehash.from_datetime(precision, strict)`	Datetime, Date, epoch seconds	Utf8	Encodes an instant to the timehash of the window that holds it. `precision` is 1 to 32.
`timehash.to_datetime()`	Utf8	Datetime (UTC)	Decodes a timehash to the midpoint of its window.
`timehash.neighbors()`	Utf8	Struct	Gives the preceding and succeeding hash: `before`, `after`.

`uuidhash` — UUID v5¶

Full page: uuidhash.

Expression	Input	Output	Description
`uuidhash.uuid5(namespace)`	Utf8, Binary	Utf8	Makes a UUID v5 in a standard or a custom namespace.
`uuidhash.uuid5_concat(other, default)`	Utf8	Utf8	Concatenates two columns and makes a UUID v5 in the DNS namespace.

Rows — whole-row hashing¶

This is a function on plh. It is not an expression in a namespace. It hashes a full row, and a hash of the joined columns cannot do this. Full page: rows.

Function	Input	Output	Description
`plh.hash_rows(exprs, version)`	Any columns	Binary	Changes each row into bytes that no other row can make, for use with any hasher above.

Conventions¶

These rules apply to all the expressions above.

Elementwise. Each expression has is_elementwise=True. You can use it in select, in with_columns, in group_by(...).agg, and in streaming mode. Polars can also divide the data into chunks and change the order of operations.
Null values. A null input gives a null output. The expression does not hash a substitute value. hash_rows is the exception. A null is one of the values of a row, and therefore a row with a null also has a hash. The rules for the scalar arguments are different: length, key, namespace, default, len and precision must not be null, and neither may seed — except on cityhash64(), where seed=None is how you ask for the unseeded algorithm.
Output name. The output column has the same name as the input column. To keep both columns, use .alias(). hash_rows reads more than one column, and it keeps the name of the first, as the polars *_horizontal expressions do.
Object columns. Polars sends an Object column to a plugin as Binary, and it keeps no mark to identify the two. Therefore a hasher reads the eight bytes of the CPython pointer and not the value. These bytes change with each run. The digest is not repeatable, and two equal objects give two different digests. Change an Object column to a usual data type before you hash it. hash_rows rejects such a column.
Incorrect input type. The expression raises an error when the input type is not permitted. This occurs when Polars collects the data, not when you build the expression. All errors from the plugin become polars.exceptions.ComputeError in Python. The message starts with the plugin failed with message:.
Stability. The same input and the same arguments always give the same output. This does not change between polars-hash releases or Polars releases. The exception is GxHash, whose values hold within one major version of the algorithm. polars-hash pins that version, so only a release that says so can move them.

API Reference¶

chash — cryptographic¶

nchash — non-cryptographic¶

geohash — geohash¶

h3 — H3 index¶

timehash — time bucket¶

uuidhash — UUID v5¶