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: Accurately 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"),
... )
>>> 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.

⚠️ 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

Full list of functions¶

Plotting¶

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

import polars_h3 as pl_h3
import polars as pl

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

# or if you have a metric to plot

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

Development¶

It's recommended to use uv to manage the extension dependencies. If you modify rust code, you will need to run uv run maturin develop --uv to see changes. 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.