Skip to content
DuckDB Extensions All extensions Lindel

Hilbert functions in the Lindel DuckDB extension

Function category

Hilbert

2 functions

Hilbert-curve encoding — best locality preservation. Slightly slower to compute than Morton but produces tighter row groups when used as ORDER BY in Parquet, leading to better predicate skipping at query time.

hilbert_decode

Scalar function Hilbert
Signature
hilbert_decode( encoded_value: <numeric>, num_elements: UTINYINT, return_float: BOOLEAN, return_unsigned: BOOLEAN ) → ANY[ANY]
Arguments (Positional)
Argument encoded_value Type <numeric>
5 concrete types
UBIGINTUHUGEINTUINTEGERUSMALLINTUTINYINT
Mode Positional Description
Argument num_elements Type UTINYINT Mode Positional Description
Argument return_float Type BOOLEAN Mode Positional Description
Argument return_unsigned Type BOOLEAN Mode Positional Description
Description

Recover component values from a Hilbert-encoded key. Supply the original dimension count; use (return_float, return_unsigned) = (false, true) for unsigned integers, (false, false) for signed integers, or (true, false) for floats. Preserve the encoded key’s SQL type. Community build 6435106 rejects one-dimensional signed-integer decoding; v1.5 source commit a92ec61 (extension version 2026100701) fixes it. Older community binaries may still be affected.

1 Round-trip an encoded integer back to its components (num_elements, return_float, return_unsigned) 
SELECT hilbert_decode(hilbert_encode([10, 20]::UINTEGER[2]), 2, false, true) AS roundtrip;
2 Round-trip signed integer coordinates with return_unsigned = false 
SELECT hilbert_decode(hilbert_encode([-10, 20]::INTEGER[2]), 2, false, false) AS roundtrip;
3 Round-trip floating-point values with return_float = true 
SELECT hilbert_decode(hilbert_encode([-1.5, 2.25]::DOUBLE[2]), 2, true, false) AS roundtrip;
Related functions

hilbert_encode

Scalar function Hilbert
Signature
hilbert_encode(values: ANY[ANY]) → ANY
Arguments (Positional)
Argument values Type ANY[ANY] Mode Positional Description
Description

Encode a fixed-size numeric array into an unsigned integer using the Hilbert curve. Accepts 8–64-bit signed and unsigned integers, FLOAT, and DOUBLE, with at most 128 combined input bits. Signed and floating-point values are encoded by their bit patterns; shift and quantize coordinates first when numeric locality matters.

1 Order nonnegative integer coordinates by their Hilbert key 
SELECT x, y, hilbert_encode([x, y]::UINTEGER[2]) AS hilbert
FROM (VALUES (1, 1), (1, 2), (2, 1), (6, 7), (7, 6)) AS t(x, y)
ORDER BY hilbert;
Related functions