Lindel

What you can do with one query

Replace a multi-column ORDER BY with one space-filling-curve sort key. For nonnegative integer coordinates, compute the key and order by it:

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

Use that ordering when writing Parquet to group nearby coordinates. This can improve row-group pruning for queries that filter several dimensions. It does not guarantee that every nearby pair becomes adjacent or that every row group has tight bounds on every column.

Hilbert vs Morton

Both hilbert_encode and morton_encode take a fixed-size numeric array and return one unsigned integer.

• Hilbert follows a space-filling curve with no long jumps between consecutive positions on its integer grid. It is a useful starting point for locality-oriented sorting.
• Morton / Z-order interleaves the coordinate bits. Its simpler mapping has jumps at quadrant boundaries.

Compare the resulting file layout and encoding cost on your own data. Neither curve guarantees better pruning for every distribution or query.

Type coverage and output width

Both encoders support these element types and array sizes:

HUGEINT and UHUGEINT are not supported as input array element types. The result uses the smallest unsigned integer type that fits element bit width × number of dimensions, up to 128 bits:

Cast arrays explicitly: [10, 20] is a LIST; [10, 20]::UINTEGER[2] is a fixed-size ARRAY. Array elements cannot be NULL.

Choose coordinate units and precision deliberately. A degree of latitude, a meter of altitude, and a second of time are different measures; Lindel does not decide their relative importance for you. Keep the same transform when writing subsequent batches.

Decoding

hilbert_decode and morton_decode recover the component values using the matching curve. Three trailing arguments specify the number of dimensions, whether to return floats, and whether to return unsigned integers:

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

For signed integers, use false, false; for floating-point values, use true, false. Preserve the encoded key’s original SQL type: the decoder uses its width together with the dimension count to determine the component width. If you shifted or quantized coordinates before encoding, decoding returns those transformed coordinates.

Community build 6435106 rejects one-dimensional signed-integer decoding. The v1.5 source fix a92ec61 (extension version 2026100701) supports signed round-trips in one dimension and restores four-dimensional 8-bit decoding. Older installed community binaries may still have these limitations. Signed two-dimensional, unsigned one-dimensional, and floating-point one-dimensional round-trips work in the older build too.

Why ordering can help Parquet

Parquet stores per-row-group min/max statistics. For a query such as WHERE lat BETWEEN 40 AND 41 AND lon BETWEEN -74 AND -73, a reader can skip a row group if its statistics rule out either condition. Grouping points by a Hilbert or Morton key can make those ranges more selective across multiple columns.

The improvement depends on coordinate preparation, data distribution, row-group size, and query predicates. Measure scanned rows or bytes, query time, and file size against the existing layout. Sorting does not guarantee smaller files or a particular speedup.

This is a write-time ordering, not a runtime index. Use ORDER BY inside the query passed to COPY; for changing data, sort each rewritten file or batch. Queries still filter on the original columns.

Compared to alternatives

• ORDER BY a, b prioritizes a, then b within equal values of a. It can be a better fit when queries mostly filter the leading column. A curve order balances multiple coordinates in a different way.
• Partitioning by year or region separates data into files or directories. Curve sorting can complement partitioning by organizing rows inside each partition.
• A spatial index supports a different access pattern. Lindel computes keys; it does not create an index or automatically translate spatial predicates into encoded-key ranges.

What this is for

Lindel computes Hilbert and Morton sort keys from multi-dimensional numeric arrays. Ordering rows by one of these keys can group related coordinates when writing Parquet, helping readers use min/max statistics for multi-column predicates. The benefit depends on the data, coordinate transform, and row-group size.

Prepare latitude and longitude

For valid latitude in [-90, 90] and longitude in [-180, 180], shift both ranges above zero and quantize to six decimal places before casting to unsigned integers:

SELECT lat, lon, hilbert_encode([
  round((lat + 90) * 1e6),
  round((lon + 180) * 1e6)
]::UINTEGER[2]) AS hilbert
FROM source
ORDER BY hilbert;

The offsets matter: casting a negative coordinate directly to UINTEGER fails. The scale sets angular precision, not uniform distance in meters. Direct DOUBLE encoding is supported, but it uses floating-point bit patterns without normalizing numeric distance.

Write the sorted layout to Parquet

COPY (
  SELECT * FROM source
  ORDER BY hilbert_encode([
    round((lat + 90) * 1e6),
    round((lon + 180) * 1e6)
  ]::UINTEGER[2])
) TO 'spatial.parquet' (FORMAT PARQUET);

Query the original columns normally:

SELECT * FROM 'spatial.parquet'
WHERE lat BETWEEN 40 AND 41
  AND lon BETWEEN -74 AND -73;

A reader can skip a row group when its statistics cannot match the predicates. Curve sorting can improve that pruning; it does not guarantee tight bounds for every group or column. Benchmark with enough rows to produce multiple row groups.

Use up to four 32-bit dimensions

All components must share one array element type. Four UINTEGER coordinates produce a 128-bit UHUGEINT key:

SELECT hilbert_encode([10, 20, 30, 40]::UINTEGER[4]) AS hilbert;

For inputs with different units, choose a consistent scaling and offset for each dimension before encoding. Four DOUBLE dimensions are not supported: their combined width exceeds 128 bits.

Try Morton / Z-order

Use the same prepared coordinates with morton_encode:

SELECT lat, lon, morton_encode([
  round((lat + 90) * 1e6),
  round((lon + 180) * 1e6)
]::UINTEGER[2]) AS morton
FROM source
ORDER BY morton;

Morton interleaves bits and has a simpler mapping than Hilbert. Compare encoding time and the resulting query performance before choosing an ordering.

Decode unsigned, signed, or floating-point values

Use the same curve to decode, and match the dimension count and type flags:

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

SELECT hilbert_decode(
  hilbert_encode([-10, 20]::INTEGER[2]), 2, false, false
) AS signed_roundtrip;
-- [-10, 20]

SELECT morton_decode(
  morton_encode([-1.5, 2.25]::DOUBLE[2]), 2, true, false
) AS float_roundtrip;
-- [-1.5, 2.25]

Preserve the key’s original SQL type when storing or decoding it. The integer width and dimension count determine the decoded component width. Decoding recovers the values passed to the encoder; it does not undo any earlier quantization or offsets.

Community build 6435106 rejects one-dimensional signed-integer decoding. The v1.5 source fix a92ec61 (extension version 2026100701) supports signed round-trips in one dimension and restores four-dimensional 8-bit decoding. Older installed community binaries may still have these limitations.

Type coverage

The result is the smallest unsigned integer type that fits the combined bits, up to UHUGEINT. HUGEINT and UHUGEINT are not supported input element types. Use fixed-size arrays with explicit casts, and handle NULL coordinates before encoding.