This is a Polars extension that adds support for the H3 discrete global grid system, so you can index points and geometries to hexagons directly in Polars. All credits goes to the h3o for doing the heavy lifting.

Highlights

• 🚀 Blazing Fast: Built entirely in Rust, offering vectorized, multi-core H3 operations within Polars. Ideal for high-performance data processing.

  • 25X faster than h3-py
  • 5X faster than H3 DuckDB (See notebook for more details)

• 🌍 H3 Feature Parity: Comprehensive support for H3 functions, covering almost everything the standard H3 library provides, excluding geometric functions.

• 📋 Fully Tested & Used in Production: Thoroughly tested against the standard H3 library.

• 🔍 Data Type Agnostic: Supports string and integer H3 indexes natively, eliminating format conversion hassles.

Get started

You can get started by installing it with pip (or uv):

pip install polars-h3

You can use the extension as a drop-in replacement for the standard H3 functions.

import polars_h3 as plh3
import polars as pl

df = (
    pl.DataFrame(
        {
            "lat": [37.7749],
            "long": [-122.4194],
        }
    )
    .with_columns(
        plh3.latlng_to_cell(
            "lat",
            "long",
            resolution=7,
            return_dtype=pl.Utf8,
        ).alias("h3_cell")
    )
)

print(df)

shape: (1, 3)
┌─────────┬───────────┬─────────────────┐
│ lat     ┆ long      ┆ h3_cell         │
│ ---     ┆ ---       ┆ ---             │
│ f64     ┆ f64       ┆ str             │
╞═════════╪═══════════╪═════════════════╡
│ 37.7749 ┆ -122.4194 ┆ 872830828ffffff │
└─────────┴───────────┴─────────────────┘

Check out the quickstart notebook for more examples.

🌟 You can also find the advanced notebooks here.

Implemented functions

This extension implements most of the H3 API. The full list of functions is below - you can find full docs here.

⚠️ Performance Note: When possible, prefer using pl.UInt64 for H3 indices instead of the pl.Utf8 representation. String representations require casting operations which impact performance. Working directly with the native 64-bit integer format provides better computational efficiency.

We are unable to support the functions that work with geometries.

Full list of functions

✅ = Supported 🚧 = Pending 🛑 = Not supported

Plotting

The library also comes with helper functions to plot hexes on a Folium map.

import polars_h3 as plh3
import polars as pl

hex_map = plh3.graphing.plot_hex_outlines(df, "h3_cell")
display(hex_map)

# or if you have a metric to plot

hex_map = plh3.graphing.plot_hex_fills(df, "h3_cell", "metric_col")
display(hex_map)

Development

It's recommended to use uv to manage the extension's python dependencies. If you modify rust code, you will need to run uv run maturin develop --uv to see changes.

You can run test suite with uv run pytest. You can also run the docs locally with uv run mkdocs serve.

Benchmarking

If you're looking to benchmark the performance of the extension, build the release version with maturin develop --release --uv and then run uv run -m benchmarks.engine (assuming you have the benchmark dependencies installed). Benchmarking with the development version will lead to misleading results.

# 1 – (build) compile the optimized Rust extension
uv run maturin develop --release --uv

# 2 – (run) execute the benchmark CLI
uv run h3-bench \
  --libraries plh3 duckdb h3_py \   # which back-ends to test (or “all”)
  --functions latlng_to_cell cell_to_parent \  # which functions to time (or “all”)
  --iterations 3 \                  # repetitions per test
  --fast-factor 4 \                 # divide default row-counts to speed things up
  --output results.json             # optional: dump raw results