Skip to content

DuckDB Extension

Lindel

Encode coordinates, dates and lat/lon as Hilbert or Morton keys in DuckDB. Sort rows by a space-filling curve so multi-column range queries skip more data.

2,123,525
extension loads · last 90 days
On this page
Sample data for the examples

Each browser example starts with these sample tables; sample files are shared across examples on this page. Run this setup first when trying the examples in your own DuckDB session.

-- Fixtures for the lindel cookbook + technical-details + functions.json
-- examples. Small, deterministic, idempotent — re-running is a no-op.

-- A generic source table with every column the docs reach for: spatial
-- (lat, lon, alt), temporal (time as epoch seconds), and a categorical
-- id (symbol_id) for the Morton time-series example.
CREATE OR REPLACE TABLE source AS
SELECT
    (40 + (i % 10) * 0.1)::DOUBLE       AS lat,
    (-74 + (i % 10) * 0.1)::DOUBLE      AS lon,
    (100 + i)::INTEGER                  AS alt,
    (1700000000 + i * 60)::INTEGER      AS time,
    (i % 8)::INTEGER                    AS symbol_id
FROM range(0, 16) t(i);

-- Flight history fixture: same schema shape as the cookbook 4D example.
CREATE OR REPLACE TABLE flights AS
SELECT
    (30 + (i % 12))::INTEGER            AS lat,
    (-100 + (i % 12))::INTEGER          AS lon,
    (10000 + i * 100)::INTEGER          AS alt,
    (1700000000 + i * 60)::INTEGER      AS time
FROM range(0, 16) t(i);

-- 3D points fixture used by technical-details.
CREATE OR REPLACE TABLE points AS
SELECT
    (i % 8)::INTEGER                    AS x,
    ((i * 3) % 8)::INTEGER              AS y,
    ((i * 5) % 8)::INTEGER              AS z
FROM range(0, 16) t(i);

Arrange rows for queries across several dimensions

Lindel maps coordinates to one integer using a Hilbert or Morton space-filling curve. Sorting by that integer places nearby points close together in the stored row order.

Use it when writing Parquet or loading tables for queries that filter several dimensions, such as location and time. A curve ordering makes row-group statistics more selective, so readers skip more data. Lindel also quantizes latitude/longitude and other bounded values onto a grid, accepts dates, timestamps and decimals as coordinates, decodes keys by type, and turns a box into key ranges for key-only stores.

Example

Sort points by a Hilbert key

A fixed-size two-element array becomes one sortable integer. All six sample points are included.

Tested with DuckDB 2.0.0. Browser examples use Haybarn-Wasm 2.0.0-rc12.

SET allow_extension_repositories = 'allowed';
CREATE EXTENSION REPOSITORY IF NOT EXISTS query_farm
  WITH PREFIX 'https://duckdb-extensions.query.farm';
INSTALL lindel FROM query_farm;
LOAD lindel FROM query_farm;

SELECT x, y, hilbert_encode([x, y]::UINTEGER[2]) AS hilbert
FROM (VALUES (3, 5), (1, 1), (7, 0), (2, 6), (5, 3), (0, 4)) AS points(x, y)
ORDER BY hilbert;

Expected result

x y hilbert
1 1 2
7 0 21
5 3 28
2 6 50
3 5 52
0 4 58

The key provides an ordering, not a spatial index. Any benefit to Parquet range queries depends on how you write the file and filter it later.

Common tasks

Deep Dive

Technical Details

Reference

Extension Contents

Quick reference to all available functions and settings organized by category.

Hilbert
hilbert_decode() Object type: Scalar function Recover coordinates from a Hilbert curve key.
hilbert_decode_bounded() Object type: Scalar function Decode a key from hilbert_encode_bounded with the same bounds and bits into the centre of its grid cell, as a DOUBLE array.
hilbert_decode_latlon() Object type: Scalar function Decode a key from hilbert_encode_latlon with the same bits (default 32) into the centre of its grid cell, as STRUCT(lat DOUBLE, lon DOUBLE).
hilbert_encode() Object type: Scalar function Encode coordinates into one unsigned integer using the Hilbert curve.
hilbert_encode_bounded() Object type: Scalar function Scale each DOUBLE coordinate from [min, max] onto a grid of 2^bits cells and encode the cell with the Hilbert curve.
hilbert_encode_latlon() Object type: Scalar function Encode a latitude/longitude pair with the Hilbert curve over a grid of 2^bits cells per axis.
hilbert_ranges() Object type: Table function Table function returning the sorted, disjoint key ranges (lo, hi) of hilbert_encode that cover the box between min_point and max_point.
hilbert_ranges_bounded() Object type: Table function Table function returning the key ranges (lo, hi) of hilbert_encode_bounded, with the given bounds and bits, that cover the box between min_point and max_point.
Morton (Z-order)
morton_decode() Object type: Scalar function Recover coordinates from a Morton (Z-order) curve key.
morton_decode_bounded() Object type: Scalar function Decode a key from morton_encode_bounded with the same bounds and bits into the centre of its grid cell, as a DOUBLE array.
morton_decode_latlon() Object type: Scalar function Decode a key from morton_encode_latlon with the same bits (default 32) into the centre of its grid cell, as STRUCT(lat DOUBLE, lon DOUBLE).
morton_encode() Object type: Scalar function Encode coordinates into one unsigned integer by interleaving their bits (Morton / Z-order).
morton_encode_bounded() Object type: Scalar function Scale each DOUBLE coordinate from [min, max] onto a grid of 2^bits cells and encode the cell with the Morton (Z-order) curve.
morton_encode_latlon() Object type: Scalar function Encode a latitude/longitude pair with the Morton (Z-order) curve over a grid of 2^bits cells per axis.
morton_ranges() Object type: Table function Table function returning the sorted, disjoint key ranges (lo, hi) of morton_encode that cover the box between min_point and max_point.
morton_ranges_bounded() Object type: Table function Table function returning the key ranges (lo, hi) of morton_encode_bounded, with the given bounds and bits, that cover the box between min_point and max_point.

API Reference

Function Reference

Practical Examples

Cookbook

Real-world recipes and patterns for common use cases.

Platform Support

Compatibility

Extension availability may vary by platform and DuckDB version. Check below to ensure this extension supports your environment before installation.

Quick Facts

Release status Stable
Software License MIT
Pricing Free
Written In C++
Source Available Yes
View on GitHub
Usage
2,123,525
loads · last 90 days

Platforms

DuckDB 2.0.0

  • Linux x86_64aarch64
  • Linux (musl) Not available
  • macOS Apple Silicon
  • Windows x86_64x86_64 (MinGW)
  • WASM Not available
Compiled binary sizes
Platform Architecture Size
Linux x86_64 5.05 MB
Linux aarch64 4.38 MB
macOS Apple Silicon 2.99 MB
Windows x86_64 10.28 MB
Windows x86_64 (MinGW) 19.08 MB

Compressed download sizes for the release shown above.

DuckDB & Haybarn

Release calendar
  • DuckDB v2.0.0 Query.Farm repository Supported
  • Haybarn v1.5.6 Built-in community repository Supported

Browser examples use Haybarn-Wasm 2.0.0-rc12.

Checked .

Learn and explore

Tutorials and articles

Writing about Lindel: how it works, what changed, and why.

  • Lindel for DuckDB 2.0: curve keys that sort like your data

    Our Hilbert and Morton extension now keeps negative numbers, floats and dates in order, quantizes lat/lon onto a grid, and decomposes box queries into key ranges. Sorting 20 million points by a Hilbert key cut a Parquet box query from 200 row groups to 2. Joining on the key ranges never helped inside DuckDB.