Lindel

What you can do with one query

Replace a multi-column ORDER BY with one locality-preserving sort key. Compute the key and order by it — rows that were close in (x, y, z) come back adjacent:

SELECT x, y, z, hilbert_encode([x, y, z]::INTEGER[3]) AS hilbert
FROM points
ORDER BY hilbert;

Wrap that ordering in COPY (...) TO 'points.parquet' (FORMAT PARQUET) and Parquet block-skipping starts working on every dimension at once. A later query like WHERE x BETWEEN ... AND y BETWEEN ... AND z BETWEEN ... skips whole row groups whose stats don’t overlap any of the three predicates — instead of skipping only on the first sort column. The same trick compresses the file better, because adjacent rows have adjacent coordinates and Parquet’s RLE / dictionary / delta encodings find more runs.

Hilbert vs Morton — pick one

Both hilbert_encode and morton_encode take an array of unsigned integers and return one sortable integer. They differ in how locality-preserving the ordering is:

• Hilbert curve — neighbours along the curve are always neighbours in N-D. Tighter row-group bounds, slightly more CPU to compute. The geometry indexing systems S2 (Google) and H3 (Uber) use Hilbert-style ordering for the same reason. Default choice.
• Morton / Z-order curve — bit-interleave the dimensions. Trivially cheap, occasional long jumps at quadrant boundaries. The Bing Maps Tile System uses Morton-style quadkeys; Delta Lake’s original ZORDER BY was Morton before it moved to Hilbert-based liquid clustering.

When in doubt: Hilbert. Pick Morton when encoding throughput dominates and you can tolerate slightly looser row-group bounding boxes.

Type coverage and output width

Both encoders are polymorphic over UTINYINT through UHUGEINT. The output type is the smallest unsigned integer that fits bit-width × number of dimensions:

Pre-scale your inputs so the precision you care about lands in the high bits of each dimension — those are the bits that drive locality. For latitude/longitude in degrees, multiply by 1e6 (~10 cm resolution worldwide) and cast to UINTEGER. For epoch milliseconds in time-series, the value is already a sensibly-scaled unsigned integer.

Decoding

hilbert_decode and morton_decode recover the original array. Three trailing arguments tell DuckDB how to reconstruct the values, since they aren’t carried in the encoded integer:

SELECT hilbert_decode(
  hilbert_encode([5, 8]::UINTEGER[2]),  -- the encoded value
  2,      -- num_elements
  false,  -- return_float
  true    -- return_unsigned
);
-- [5, 8]

Useful for sanity-checking transforms and for storing the encoded value as an indexable single-column key while still being able to read back the components on demand.

Why this works on Parquet

Parquet stores per-row-group min/max statistics for every column. A predicate like WHERE lat BETWEEN 40 AND 41 lets the reader skip any row group whose lat range doesn’t overlap. With single-column sorting, that skipping works for one column at a time — the file is sorted by lat, so lon is scattered across row groups. With Hilbert / Morton sorting, every input column gets tight per-row-group bounds, so multi-column predicates each contribute to skipping.

Performance gains depend on data shape and query mix. For multi-column range queries against multi-million-row Parquet files, expect order-of-magnitude reductions in scanned bytes when the filter selectivity is high — the same regime the Delta Lake liquid clustering work targets.

Compared to alternatives

• ORDER BY a, b — sorts on a first, then b within a. Great for a-only or (a, b)-prefix queries; useless if you filter on b alone. Lindel gives every input column meaningful per-row-group bounds.
• Multiple Parquet files partitioned by category — works for low-cardinality keys (year, region). Falls apart on continuous dimensions. Lindel sorts continuous dimensions inside one file.
• GeoHash / quadkey strings — same idea (locality-preserving 1-D key), but as strings. Lindel returns native unsigned integers, which compare and store more cheaply and round-trip back to the original components.

What this is for

When a query filters on multiple columns at once — lat AND lon, time AND symbol_id, (altitude, lat, lon, time) — sorting Parquet by any single column doesn’t help much. Sorting by both needs a 1D ordering that keeps multi-dimensional neighbors together. That’s a space-filling curve like Hilbert or Morton.

Use Lindel as the ORDER BY when writing Parquet. The result: row groups have tight bounding boxes in every input dimension, so DuckDB / Athena / Trino / Spark / Snowflake can skip whole row groups whose stats don’t match the predicate.

This is the same optimization Databricks calls “Z-Order” (Morton) and now defaults to “Liquid Clustering” (Hilbert).

Hilbert-order rows

Compute one Hilbert key per row and ORDER BY it — points close in (lat, lon) stay adjacent in the result:

SELECT lat, lon, hilbert_encode([lat, lon]::DOUBLE[2]) AS hilbert
FROM source
ORDER BY hilbert;

To persist that layout, wrap the same ordering in a write — COPY (SELECT * FROM source ORDER BY hilbert_encode([lat, lon]::DOUBLE[2])) TO 'spatial.parquet' (FORMAT PARQUET). Rows close in (lat, lon) end up close in the file, so bounding-box queries (WHERE lat BETWEEN ... AND lon BETWEEN ...) skip irrelevant row groups.

For 4D — say flight history (lat, lon, alt, time) — pass all four dimensions to the encoder:

SELECT lat, lon, alt, time, hilbert_encode([lat, lon, alt, time]::INTEGER[4]) AS hilbert
FROM flights
ORDER BY hilbert;

Morton (Z-order) — faster, slightly weaker

Same recipe, swap the function:

SELECT time, symbol_id, morton_encode([time, symbol_id]::INTEGER[2]) AS morton
FROM source
ORDER BY morton;

When in doubt: Hilbert. Pick Morton only when encoding throughput is the bottleneck and you can tolerate slightly larger row-group bounding boxes.

Decode for sanity-checking

SELECT hilbert_decode(
  hilbert_encode([10, 20]::INTEGER[2]),
  /* num_elements   */ 2,
  /* return_float   */ false,
  /* return_unsigned */ true
) AS roundtrip;
-- [10, 20]

Type coverage

Both encoders accept:

• Any signed or unsigned integer (TINYINT through HUGEINT).
• FLOAT or DOUBLE.

Output type is the smallest unsigned integer that fits the bit width × number of dimensions. For [INTEGER, INTEGER] (32×2 = 64 bits) you get UBIGINT; for [DOUBLE, DOUBLE] (64×2 = 128 bits) you get UHUGEINT.

Why this works

Parquet stores per-row-group min/max statistics. A predicate like WHERE lat BETWEEN 40 AND 41 lets the reader skip any row group whose lat range doesn’t overlap. With single-column sorting that works for one column at a time. With Hilbert/Morton sorting, every input column gets tight per-row-group bounds, so multi-column predicates each contribute to skipping.

Performance gains depend on the data and query pattern. The Delta Lake / Databricks blog posts linked in the README report 5–100× speedups for multi-column range queries; in DuckDB you’ll see similar with the right data.