### Install H3 Extension from URL

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Use this command to install the H3 extension from a remote URL. Ensure DuckDB is started with the -unsigned option.

```sql
INSTALL h3 FROM 'https://pub-cc26a6fd5d8240078bd0c2e0623393a5.r2.dev';
LOAD h3;
```

--------------------------------

### Install and Load H3 Extension for DuckDB

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Use these SQL commands to install the H3 extension from the community repository and then load it into your DuckDB session.

```sql
INSTALL h3 FROM community;
LOAD h3;
```

--------------------------------

### Run DuckDB with Unsigned Option

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Start the DuckDB shell with the -unsigned flag to allow loading unsigned extensions.

```sh
duckdb -unsigned
```

--------------------------------

### Get All Resolution 0 Cells in DuckDB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_get_res0_cells` or `h3_get_res0_cells_string` to get all 122 base resolution cells as UBIGINT or VARCHAR lists.

```sql
SELECT h3_get_res0_cells();
-- Result: [576495936675512319, 576531121047601151, ... ] (122 cells)
```

```sql
SELECT h3_get_res0_cells_string();
-- Result: [8001fffffffffff, 8003fffffffffff, ... ]
```

```sql
-- Count
SELECT len(h3_get_res0_cells());
-- Result: 122
```

--------------------------------

### Get cells exactly at grid distance k from origin

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_grid_ring` for safe ring generation. The `_unsafe` variant may return NULL near pentagons.

```sql
SELECT h3_grid_ring('822d57fffffffff', 1);
-- Result: [822d77fffffffff, 822d0ffffffffff, 822c27fffffffff,
--          822c2ffffffffff, 822d5ffffffffff, 822d47fffffffff]
```

```sql
-- Pentagon case: safe version handles it, unsafe returns NULL
SELECT h3_grid_ring('8408001ffffffff', 1);     -- works (safe)
SELECT h3_grid_ring_unsafe('8408001ffffffff', 1); -- NULL (pentagon nearby)
```

```sql
-- Resolution 0 pentagon ring (5 cells)
SELECT h3_grid_ring('804dfffffffffff', 1);
-- Result: [805ffffffffffff, 8045fffffffffff, 802bfffffffffff,
--          803bfffffffffff, 8067fffffffffff]
```

--------------------------------

### Get Child Cells or Child Count

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_cell_to_children` to get a list of child cells at a finer resolution, or `h3_cell_to_children_size` for the count. Invalid resolutions return NULL. UNNEST can expand children into rows.

```sql
SELECT h3_cell_to_children('822d57fffffffff', 3);
-- Result: [832d50fffffffff, 832d51fffffffff, 832d52fffffffff, 832d53fffffffff,
--          832d54fffffffff, 832d55fffffffff, 832d56fffffffff]
```

```sql
SELECT h3_cell_to_children_size('822d57fffffffff', 3);  -- 7
SELECT h3_cell_to_children_size('822d57fffffffff', 4);  -- 49
```

```sql
-- Invalid resolution returns NULL
SELECT h3_cell_to_children('822d57fffffffff', 30);
-- Result: NULL
```

```sql
-- UNNEST children for row expansion
SELECT UNNEST(h3_cell_to_children('822d57fffffffff', 3)) AS child;
```

--------------------------------

### Get Cells and Distances within Grid Disk

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_grid_disk_distances` to get cells grouped by their distance ring from a central cell. The `_safe` variant correctly handles pentagons, while `_unsafe` may return NULL near them.

```sql
SELECT h3_grid_disk_distances('822d57fffffffff', 1);
-- Result: [[822d57fffffffff], [822d0ffffffffff, 822c27fffffffff, 822c2ffffffffff,
--           822d5ffffffffff, 822d47fffffffff, 822d77fffffffff]]
```

```sql
-- Pentagon-safe disk (use when cells may be near pentagons)
SELECT h3_grid_disk_distances_safe('8408001ffffffff', 2);
```

```sql
-- Unsafe returns NULL near pentagons
SELECT h3_grid_disk_unsafe('8408001ffffffff', 1);
-- Result: NULL
```

--------------------------------

### Get Pentagon Cells at a Resolution in DuckDB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_get_pentagons` or `h3_get_pentagons_string` to retrieve the 12 pentagon cells at a specified resolution. Invalid resolutions return NULL.

```sql
SELECT h3_get_pentagons(0);
-- Result: [576636674163867647, 576988517884755967, ...] (12 pentagons)
```

```sql
SELECT h3_get_pentagons_string(5);
-- Result: [85080003fffffff, 851c0003fffffff, ...] (12 pentagons)
```

```sql
SELECT h3_get_pentagons(-1);   -- NULL (invalid resolution)
```

```sql
SELECT h3_get_pentagons(16);   -- NULL (invalid resolution)
```

--------------------------------

### Get H3 Cell Boundary as WKT or WKB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Returns the hexagonal boundary of an H3 cell as Well-Known Text (WKT) or Well-Known Binary (WKB). Invalid cells return `NULL`.

```sql
SELECT h3_cell_to_boundary_wkt('822d57fffffffff');
-- Result: POLYGON ((38.777546 44.198571, 39.938746 42.736298, 42.150674 42.631271,
--                   43.258395 44.047542, 42.146575 45.539505, 39.897167 45.559577,
--                   38.777546 44.198571))

-- WKB binary output
SELECT h3_cell_to_boundary_wkb('822d57fffffffff');

-- Invalid cell returns NULL
SELECT h3_cell_to_boundary_wkt('zzz');
-- Result: NULL
```

--------------------------------

### Get Cell Vertex IDs in DuckDB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_cell_to_vertexes` to get all vertex IDs for a cell, or `h3_cell_to_vertex` for a specific vertex. Invalid inputs return NULL.

```sql
SELECT h3_cell_to_vertexes('823d6ffffffffff');
-- Result: [2222597fffffffff, 2523d47fffffffff, 2423d47fffffffff,
--          21224b7fffffffff, 20224b7fffffffff, 2322597fffffffff]
```

```sql
SELECT h3_cell_to_vertex('823d6ffffffffff', 0);
-- Result: 2222597fffffffff
```

```sql
-- Invalid vertex number returns NULL
SELECT h3_cell_to_vertex('823d6ffffffffff', -1);
-- Result: NULL
```

```sql
-- Invalid cell returns NULL
SELECT h3_cell_to_vertexes('fffffffffffffff');
-- Result: NULL
```

--------------------------------

### Get path cells between two H3 cells

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Returns a list of cells forming a path between two cells at the same resolution. Returns NULL if a path cannot be found, such as for invalid cells.

```sql
SELECT h3_grid_path_cells('86584e9afffffff', '8658412c7ffffff');
-- Result: [86584e9afffffff, 86584e91fffffff, 86584e907ffffff,
--          86584e92fffffff, 8658412d7ffffff, 8658412c7ffffff]
```

```sql
SELECT h3_grid_path_cells('86584e9afffffff', '0');
-- Result: NULL (invalid end cell)
```

--------------------------------

### Get Cells within Grid Distance K

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_grid_disk` to retrieve all cells within a specified grid distance `k` (inclusive) as a flat list. Negative `k` values return NULL. The `_unsafe` variant is faster but may return NULL near pentagons.

```sql
SELECT h3_grid_disk('822d57fffffffff', 1);
-- Result: [822d57fffffffff, 822d0ffffffffff, 822c27fffffffff, 822c2ffffffffff,
--          822d5ffffffffff, 822d47fffffffff, 822d77fffffffff]
```

```sql
-- Negative k returns NULL
SELECT h3_grid_disk('822d57fffffffff', -1);
-- Result: NULL
```

```sql
-- Flatten and count
SELECT count(*) FROM (SELECT UNNEST(h3_grid_disk('822d57fffffffff', 2)));
```

--------------------------------

### Sub-indexing: Cell to Parent Position and Inverse

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_cell_to_child_pos` to find a cell's 0-based index within its parent at a given resolution. `h3_child_pos_to_cell` performs the inverse operation. A round-trip example is provided.

```sql
SELECT h3_cell_to_child_pos('84af8b1ffffffff', 1);
-- Result: 70
```

```sql
SELECT h3_child_pos_to_cell(70::bigint, '81afbffffffffff', 4);
-- Result: 84af8b1ffffffff
```

```sql
-- Round-trip
SELECT h3_child_pos_to_cell(
    h3_cell_to_child_pos('84af8b1ffffffff', 1),
    h3_cell_to_parent('84af8b1ffffffff', 1),
    4
) = '84af8b1ffffffff';
-- Result: true
```

--------------------------------

### Get H3 directed edge boundary geometry

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Returns the boundary linestring of a directed edge as WKT or WKB. Returns NULL for invalid edges. Includes a check for edge validity.

```sql
SELECT h3_directed_edge_to_boundary_wkt('115283473fffffff');
-- Result: LINESTRING (-122.037735 37.420129, -122.090429 37.337556, -122.037735 37.420129)
```

```sql
SELECT h3_is_valid_directed_edge('115283473fffffff');
-- Result: true
```

```sql
SELECT h3_is_valid_directed_edge('2222597fffffffff');
-- Result: false (this is a vertex, not an edge)
```

--------------------------------

### Build H3 Extension from Source

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Commands to initialize submodules and build the release version of the H3 extension. Requires Git, CMake, and a C compiler.

```sh
git submodule update --init
GEN=ninja make release
```

--------------------------------

### Navigate H3 directed edges

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Get outgoing edge IDs from a cell using `h3_origin_to_directed_edges`. Get origin/destination cells from an edge ID using `h3_directed_edge_to_cells`. Invalid edges return NULL.

```sql
SELECT h3_origin_to_directed_edges('85283473fffffff');
-- Result: [115283473fffffff, 125283473fffffff, 135283473fffffff,
--          145283473fffffff, 155283473fffffff, 165283473fffffff]
```

```sql
SELECT h3_directed_edge_to_cells('165283473fffffff');
-- Result: [85283473fffffff, 85283447fffffff]
```

```sql
SELECT h3_get_directed_edge_origin('165283473fffffff');
-- Result: 85283473fffffff
```

```sql
SELECT h3_get_directed_edge_destination('165283473fffffff');
-- Result: 85283447fffffff
```

```sql
-- Invalid edge returns NULL
SELECT h3_directed_edge_to_cells('0');
-- Result: NULL
```

--------------------------------

### Fill Polygon with H3 Cells (Experimental Containment)

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Uses an experimental algorithm for polyfilling polygons with H3 cells, offering explicit control over containment modes. Returns an empty list for unknown modes.

```sql
SELECT h3_polygon_wkt_to_cells_experimental(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    5,
    'CONTAINMENT_CENTER'
);
```

```sql
SELECT h3_polygon_wkt_to_cells_experimental(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    5,
    'CONTAINMENT_OVERLAPPING'
);
```

```sql
SELECT h3_polygon_wkt_to_cells_experimental(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    6,
    'CONTAINMENT_FULL'
);
```

```sql
SELECT h3_polygon_wkt_to_cells_experimental_string(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    6,
    'overlap'
);
```

--------------------------------

### Load Local H3 Extension

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Load the H3 extension from a local build path. This command is used after compiling the extension from source.

```sql
load 'build/release/extension/h3/h3.duckdb_extension';
```

--------------------------------

### h3_polygon_wkt_to_cells_experimental

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Experimental polyfill algorithm with explicit containment mode. Modes: 'CONTAINMENT_CENTER'/'center', 'CONTAINMENT_FULL'/'full', 'CONTAINMENT_OVERLAPPING'/'overlap', 'CONTAINMENT_OVERLAPPING_BBOX'/'overlap_bbox'. Returns empty list for unknown modes.

```APIDOC
## `h3_polygon_wkt_to_cells_experimental(wkt, resolution, containment_mode)` — Polyfill with containment control

### Description
Experimental polyfill algorithm with explicit containment mode. Modes: `'CONTAINMENT_CENTER'`/`'center'`, `'CONTAINMENT_FULL'`/`'full'`, `'CONTAINMENT_OVERLAPPING'`/`'overlap'`, `'CONTAINMENT_OVERLAPPING_BBOX'`/`'overlap_bbox'`. Returns empty list for unknown modes.

### Parameters
#### Path Parameters
- **wkt** (string) - Required - The Well-Known Text representation of the polygon.
- **resolution** (integer) - Required - The H3 resolution at which to fill the polygon.
- **containment_mode** (string) - Required - The containment mode to use for filling.

### Request Example
```sql
-- Only cells whose centers are within the polygon
SELECT h3_polygon_wkt_to_cells_experimental(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    5, 'CONTAINMENT_CENTER'
);

-- All cells that overlap the polygon boundary or interior
SELECT h3_polygon_wkt_to_cells_experimental(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    5, 'CONTAINMENT_OVERLAPPING'
);

-- Full containment (cells entirely inside polygon)
SELECT h3_polygon_wkt_to_cells_experimental(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    6, 'CONTAINMENT_FULL'
);

-- String variant
SELECT h3_polygon_wkt_to_cells_experimental_string(
    'POLYGON ((-122.534 37.817, -122.534 37.705, -122.348 37.705, -122.348 37.817, -122.534 37.817))',
    6, 'overlap'
);
```

### Response
#### Success Response (200)
- **cells** (array of UBIGINT or array of VARCHAR) - A list of H3 cell IDs based on the specified containment mode.
```

--------------------------------

### Run H3 Extension Tests

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Execute the test suite for the H3 extension. This command is typically run after building the extension.

```sh
make test
```

--------------------------------

### Run Development Build of DuckDB

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Execute the DuckDB shell from a development build. The -unsigned option is required for loading local extensions.

```sh
./build/release/duckdb -unsigned
```

--------------------------------

### Get H3 Cell Resolution

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Returns the H3 resolution (0–15) of a given cell index. Accepts `UBIGINT`, `BIGINT`, or `VARCHAR`.

```sql
SELECT h3_get_resolution('822d57fffffffff');
-- Result: 2

SELECT h3_get_resolution(cast(586265647244115967 as ubigint));
-- Result: 2
```

--------------------------------

### Parallel Build with CMake

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Build the DuckDB release with parallel compilation enabled using CMAKE_BUILD_PARALLEL_LEVEL. Replace '4' with your CPU core count.

```sh
CMAKE_BUILD_PARALLEL_LEVEL=4 make duckdb_release release
```

--------------------------------

### Get Total Cell Count at Resolution in DuckDB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_get_num_cells` to retrieve the total number of H3 cells at a specified resolution. Invalid resolutions return NULL.

```sql
SELECT h3_get_num_cells(0);   -- 122
```

```sql
SELECT h3_get_num_cells(5);   -- 2016842
```

```sql
SELECT h3_get_num_cells(-1);  -- NULL (invalid)
```

--------------------------------

### h3_polygon_wkb_to_cells / h3_polygon_wkb_to_cells_experimental

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Same as the WKT variants but accepts WKB (Well-Known Binary) input. Useful when integrating with spatial extensions that output WKB geometries.

```APIDOC
## `h3_polygon_wkb_to_cells(wkb, resolution)` / `h3_polygon_wkb_to_cells_experimental(wkb, resolution, mode)` — Polyfill from WKB

### Description
Same as the WKT variants but accepts WKB (Well-Known Binary) input. Useful when integrating with spatial extensions that output WKB geometries.

### Parameters
#### Path Parameters
- **wkb** (binary) - Required - The Well-Known Binary representation of the polygon.
- **resolution** (integer) - Required - The H3 resolution at which to fill the polygon.
- **mode** (string) - Optional - The containment mode for the experimental variant.

### Request Example
```sql
-- Typical usage with spatial extension
SELECT h3_polygon_wkb_to_cells(ST_AsWKB(geom), 9) AS cells
FROM my_polygons_table;

-- Experimental WKB variant
SELECT h3_polygon_wkb_to_cells_experimental(wkb_col, 7, 'CONTAINMENT_OVERLAPPING') AS cells
FROM geometries;
```

### Response
#### Success Response (200)
- **cells** (array of UBIGINT or array of VARCHAR) - A list of H3 cell IDs that fall within the polygon.
```

--------------------------------

### Construct H3 Cell from Components

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Build an H3 cell using `h3_construct_cell` (with UBIGINT) or `h3_construct_cell_string` (with VARCHAR) from a base cell number and resolution digits. The resolution can be optionally specified and must match the digit list length. Returns NULL for invalid parameters.

```sql
SELECT h3_construct_cell(0, []);
-- Result: 576495936675512319

SELECT h3_construct_cell_string(0, []);
-- Result: 8001fffffffffff

SELECT h3_construct_cell_string(100, [1, 2, 3, 4, 5, 6, 1, 2, 3, 4, 5, 6, 1, 2, 3], 15);
-- Result: 8fc8539714e5c53

-- Invalid: digit count doesn't match resolution
SELECT h3_construct_cell(5, [1, 2], 1);
-- Result: NULL
```

--------------------------------

### h3_polygon_wkb_to_cells_experimental_string

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Converts a polygon represented in Well-Known Binary (WKB) format into a set of H3 cells using a new algorithm, returning the cell indices as VARCHAR.

```APIDOC
## h3_polygon_wkb_to_cells_experimental_string

### Description
Converts a polygon represented in Well-Known Binary (WKB) format into a set of H3 cells using a new algorithm, returning the cell indices as VARCHAR.

### Method
SQL Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT h3_polygon_wkb_to_cells_experimental_string(ST_GeomFromWKB(your_wkb_data))
```

### Response
#### Success Response (200)
- **cells** (ARRAY<VARCHAR>) - An array of H3 cell indices as strings.

#### Response Example
```json
{
  "cells": ["892901711711234567", "892901711711234568"]
}
```
```

--------------------------------

### Access H3 Cell Components

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Get the base cell number using `h3_get_base_cell_number`. Extract a specific resolution digit (1-15) using `h3_get_index_digit`; returns NULL for out-of-range digits.

```sql
SELECT h3_get_base_cell_number('85283473fffffff');
-- Result: 20

SELECT h3_get_index_digit('822d57fffffffff', 1);  -- 5
SELECT h3_get_index_digit('822d57fffffffff', 2);  -- 2
SELECT h3_get_index_digit('822d57fffffffff', 3);  -- 7
SELECT h3_get_index_digit('822d57fffffffff', -1); -- NULL (invalid)
SELECT h3_get_index_digit('822d57fffffffff', 20); -- NULL (out of range)
```

--------------------------------

### Fill Polygon with H3 Cells (WKB)

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Fills a polygon represented in Well-Known Binary (WKB) format with H3 cells. This is useful when integrating with spatial extensions that output WKB.

```sql
SELECT h3_polygon_wkb_to_cells(ST_AsWKB(geom), 9) AS cells
FROM my_polygons_table;
```

```sql
SELECT h3_polygon_wkb_to_cells_experimental(wkb_col, 7, 'CONTAINMENT_OVERLAPPING') AS cells
FROM geometries;
```

--------------------------------

### h3_polygon_wkb_to_cells_experimental

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Converts a polygon represented in Well-Known Binary (WKB) format into a set of H3 cells using a new algorithm.

```APIDOC
## h3_polygon_wkb_to_cells_experimental

### Description
Converts a polygon represented in Well-Known Binary (WKB) format into a set of H3 cells using a new algorithm.

### Method
SQL Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT h3_polygon_wkb_to_cells_experimental(ST_GeomFromWKB(your_wkb_data))
```

### Response
#### Success Response (200)
- **cells** (ARRAY<BIGINT>) - An array of H3 cell indices.

#### Response Example
```json
{
  "cells": [892901711711234567, 892901711711234568]
}
```
```

--------------------------------

### Convert H3 Index to/from String

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_string_to_h3` to convert a VARCHAR hex string to a UBIGINT H3 index, and `h3_h3_to_string` for the reverse. `h3_string_to_h3` returns NULL for malformed strings.

```sql
SELECT h3_string_to_h3('85283473fffffff');
-- Result: 599686042433355775 (UBIGINT)

SELECT h3_h3_to_string(599686042433355775::ubigint);
-- Result: 85283473fffffff

SELECT h3_string_to_h3(',,,,,');
-- Result: NULL

-- Round-trip
SELECT h3_h3_to_string(h3_string_to_h3('8928308280fffff'));
-- Result: 8928308280fffff
```

--------------------------------

### Get Center Child Cell

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Retrieve the single center descendant cell at a specified finer resolution using `h3_cell_to_center_child`. The target resolution must be finer than the input cell's resolution.

```sql
SELECT h3_cell_to_center_child('822d57fffffffff', 4);
-- Result: 842d501ffffffff
```

```sql
SELECT h3_cell_to_center_child(cast(586265647244115967 as ubigint), 4);
-- Result: 595272305332977663
```

```sql
-- Resolution must be finer than the cell's resolution
SELECT h3_cell_to_center_child('822d57fffffffff', 0);
-- Result: NULL
```

--------------------------------

### Fill Polygon with H3 Cells (WKT)

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Fills a WKT polygon with H3 cells at a specified resolution. Supports polygons with holes and offers a string variant for hex cell IDs. Returns an empty list for empty polygons.

```sql
SELECT h3_polygon_wkt_to_cells(
    'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
               -122.512 37.708, -122.525 37.784, -122.480 37.815,
               -122.409 37.813))',
    9
);
```

```sql
SELECT length(h3_polygon_wkt_to_cells(
    'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
               -122.512 37.708, -122.525 37.784, -122.480 37.815, -122.409 37.813),
              (-122.447 37.787, -122.459 37.766, -122.414 37.771))',
    9
));
```

```sql
SELECT h3_polygon_wkt_to_cells_string(
    'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
               -122.512 37.708, -122.525 37.784, -122.480 37.815, -122.409 37.813))',
    9
);
```

```sql
SELECT h3_polygon_wkt_to_cells('POLYGON EMPTY', 9);
```

--------------------------------

### Get Icosahedron Faces Intersected by H3 Cell

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Retrieve a list of icosahedron face IDs (0–19) that an H3 cell intersects using `h3_get_icosahedron_faces`. Returns NULL for invalid cells.

```sql
SELECT h3_get_icosahedron_faces('85283473fffffff');
-- Result: [7]

SELECT h3_get_icosahedron_faces('801dfffffffffff');
-- Result: [1, 6, 11, 7, 2]   -- spans 5 faces

SELECT h3_get_icosahedron_faces(18446744073709551615::ubigint);
-- Result: NULL (invalid cell)
```

--------------------------------

### h3_polygon_wkt_to_cells_experimental_string

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Converts a polygon represented in Well-Known Text (WKT) format into a set of H3 cells using a new algorithm, returning the cell indices as VARCHAR.

```APIDOC
## h3_polygon_wkt_to_cells_experimental_string

### Description
Converts a polygon represented in Well-Known Text (WKT) format into a set of H3 cells using a new algorithm, returning the cell indices as VARCHAR.

### Method
SQL Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT h3_polygon_wkt_to_cells_experimental_string(ST_GeomFromText('POLYGON((...))'))
```

### Response
#### Success Response (200)
- **cells** (ARRAY<VARCHAR>) - An array of H3 cell indices as strings.

#### Response Example
```json
{
  "cells": ["892901711711234567", "892901711711234568"]
}
```
```

--------------------------------

### Get Hexagon Area Measurements in DuckDB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_get_hexagon_area_avg` for average area at a resolution or `h3_cell_area` for a specific cell's area. Specify units as 'km^2' or 'm^2'. Invalid units return NULL.

```sql
SELECT h3_get_hexagon_area_avg(0, 'km^2');
-- Result: 4357449.416078383
```

```sql
SELECT h3_get_hexagon_area_avg(9, 'm^2');
-- Result: 105332.51355...
```

```sql
SELECT h3_cell_area('8928308280fffff', 'km^2');
-- Result: 0.1093981886464832
```

```sql
SELECT h3_cell_area('8928308280fffff', 'm^2');
-- Result: 109398.18864648319
```

```sql
-- Invalid unit returns NULL
SELECT h3_cell_area('8928308280fffff', 'km');
-- Result: NULL
```

--------------------------------

### h3_compact_cells / h3_uncompact_cells

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Manages cell sets by compaction and uncompaction. `h3_compact_cells` reduces a set to its minimal representation, while `h3_uncompact_cells` expands a set to a single target resolution.

```APIDOC
## `h3_compact_cells(cells)` / `h3_uncompact_cells(cells, resolution)` — Compaction

`h3_compact_cells` reduces a set of cells to the minimal mixed-resolution set (merging 7 children into their parent). `h3_uncompact_cells` expands a mixed-resolution set to a single target resolution.

### Parameters
#### Path Parameters
- **cells** (array of strings) - Required - An array of H3 cell indices.
- **resolution** (integer) - Required - The target resolution for uncompaction.

### Request Example
```sql
-- Compact 7 children into their parent
SELECT h3_compact_cells([
    '822d67fffffffff', '822d5ffffffffff', '822d4ffffffffff',
    '822d57fffffffff', '822d77fffffffff', '822d6ffffffffff', '822d47fffffffff'
]);

-- Expand parent back to resolution 2
SELECT h3_uncompact_cells(['812d7ffffffffff'], 2);
```

### Response
#### Success Response (200)
- **h3_compact_cells**: array of strings - The compacted set of H3 cell indices.
- **h3_uncompact_cells**: array of strings - The expanded set of H3 cell indices at the target resolution.

#### Response Example
```json
-- For h3_compact_cells:
["812d7ffffffffff"]
-- For h3_uncompact_cells:
["822d47fffffffff", "822d4ffffffffff", "822d57fffffffff", "822d5ffffffffff", "822d67fffffffff", "822d6ffffffffff", "822d77fffffffff"]
```

### Error Handling
- Invalid cell in array returns NULL.
- Empty array is valid.
```

--------------------------------

### Get Hexagon Edge Length Measurements in DuckDB

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_get_hexagon_edge_length_avg` for average edge length at a resolution or `h3_edge_length` for a specific edge. Specify units as 'km' or 'm'. Invalid units return NULL.

```sql
SELECT h3_get_hexagon_edge_length_avg(9, 'km');
```

```sql
SELECT h3_edge_length('115283473fffffff', 'km');
-- Result: 10.294736086198531
```

```sql
SELECT h3_edge_length('115283473fffffff', 'm');
-- Result: 10294.73608619853
```

```sql
-- Invalid unit returns NULL
SELECT h3_edge_length('115283473fffffff', 'km^2');
-- Result: NULL
```

--------------------------------

### h3_grid_disk / h3_grid_disk_distances

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Performs neighborhood traversal. `h3_grid_disk` returns all cells within a grid distance `k`, while `h3_grid_disk_distances` groups them by distance ring. Unsafe variants are faster but may return NULL near pentagons.

```APIDOC
## `h3_grid_disk(cell, k)` / `h3_grid_disk_distances(cell, k)` — Neighborhood traversal

`h3_grid_disk` returns all cells within grid distance `k` (inclusive) as a flat list. `h3_grid_disk_distances` returns a list-of-lists grouped by distance ring. Returns `NULL` for negative `k`. The `_unsafe` variant is faster but returns `NULL` near pentagons; `_safe` handles pentagons correctly.

### Parameters
#### Path Parameters
- **cell** (string) - Required - The H3 cell index.
- **k** (integer) - Required - The grid distance.

### Request Example
```sql
SELECT h3_grid_disk('822d57fffffffff', 1);
SELECT h3_grid_disk_distances('822d57fffffffff', 1);
SELECT h3_grid_disk_distances_safe('8408001ffffffff', 2);
SELECT h3_grid_disk_unsafe('8408001ffffffff', 1);
```

### Response
#### Success Response (200)
- **h3_grid_disk**: array of strings - A flat list of H3 cell indices within distance `k`.
- **h3_grid_disk_distances**: array of arrays of strings - A list of lists, where each inner list contains H3 cell indices at a specific distance ring.

#### Response Example
```json
-- For h3_grid_disk:
["822d57fffffffff", "822d0ffffffffff", "822c27fffffffff", "822c2ffffffffff", "822d5ffffffffff", "822d47fffffffff", "822d77fffffffff"]
-- For h3_grid_disk_distances:
[["822d57fffffffff"], ["822d0ffffffffff", "822c27fffffffff", "822c2ffffffffff", "822d5ffffffffff", "822d47fffffffff", "822d77fffffffff"]]
```

### Error Handling
- Returns `NULL` for negative `k`.
- `_unsafe` variants may return `NULL` near pentagons.
```

--------------------------------

### h3_polygon_wkb_to_cells_string

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Converts a polygon represented in Well-Known Binary (WKB) format into a set of H3 cells, returning the cell indices as VARCHAR.

```APIDOC
## h3_polygon_wkb_to_cells_string

### Description
Converts a polygon represented in Well-Known Binary (WKB) format into a set of H3 cells, returning the cell indices as VARCHAR.

### Method
SQL Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT h3_polygon_wkb_to_cells_string(ST_GeomFromWKB(your_wkb_data))
```

### Response
#### Success Response (200)
- **cells** (ARRAY<VARCHAR>) - An array of H3 cell indices as strings.

#### Response Example
```json
{
  "cells": ["892901711711234567", "892901711711234568"]
}
```
```

--------------------------------

### Reconstruct Polygon Geometry from H3 Cells (WKT/WKB)

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Converts a list of H3 cells back into a `MULTIPOLYGON` geometry in WKT or WKB format. Adjacent cells are merged into contiguous polygons, with holes handled appropriately. Supports both UBIGINT and string cell IDs.

```sql
SELECT h3_cells_to_multi_polygon_wkt([
    586265647244115967::ubigint, 586260699441790975::ubigint,
    586244756523188223::ubigint, 586245306279002111::ubigint,
    586266196999929855::ubigint, 586264547732488191::ubigint,
    586267846267371519::ubigint
]);
```

```sql
SELECT h3_cells_to_multi_polygon_wkt(
    h3_polygon_wkt_to_cells(
        'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
                   -122.512 37.708, -122.525 37.784, -122.480 37.815, -122.409 37.813))',
        9
    )
);
```

```sql
SELECT h3_cells_to_multi_polygon_wkt(
    ['8548ebb3fffffff', '8548eb8ffffffff', '8548ebbbfffffff',
     '8548eb97fffffff', '8548e94bfffffff', '8548eb83fffffff', '8548ebc3fffffff']
);
```

```sql
SELECT h3_cells_to_multi_polygon_wkt([]::ubigint[]);
```

--------------------------------

### Create H3 directed edges and check adjacency

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Create a directed edge between two adjacent cells using `h3_cells_to_directed_edge`. Check adjacency with `h3_are_neighbor_cells`. Supports both H3 string and integer representations.

```sql
SELECT h3_cells_to_directed_edge('85283473fffffff', '85283447fffffff');
-- Result: 165283473fffffff
```

```sql
SELECT h3_are_neighbor_cells('85283473fffffff', '85283447fffffff');
-- Result: true
```

```sql
SELECT h3_are_neighbor_cells('85283473fffffff', '85283443fffffff');
-- Result: false
```

```sql
-- Using integer API
SELECT h3_cells_to_directed_edge(599686042433355775::ubigint, 599686030622195711::ubigint);
-- Result: 1608492358964346879
```

--------------------------------

### h3_polygon_wkt_to_cells / h3_polygon_wkt_to_cells_string

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Fills a WKT polygon (with optional holes) with H3 cells at the given resolution. Returns a list of UBIGINT or VARCHAR cell IDs. Throws on malformed WKT.

```APIDOC
## `h3_polygon_wkt_to_cells(wkt, resolution)` / `h3_polygon_wkt_to_cells_string(wkt, resolution)` — Polyfill polygon with cells

### Description
Fills a WKT polygon (with optional holes) with H3 cells at the given resolution. Returns a list of `UBIGINT` or `VARCHAR` cell IDs. Throws on malformed WKT.

### Parameters
#### Path Parameters
- **wkt** (string) - Required - The Well-Known Text representation of the polygon.
- **resolution** (integer) - Required - The H3 resolution at which to fill the polygon.

### Request Example
```sql
-- Basic polyfill
SELECT h3_polygon_wkt_to_cells(
    'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
               -122.512 37.708, -122.525 37.784, -122.480 37.815,
               -122.409 37.813))',
    9
);

-- With a hole
SELECT length(h3_polygon_wkt_to_cells(
    'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
               -122.512 37.708, -122.525 37.784, -122.480 37.815, -122.409 37.813),
              (-122.447 37.787, -122.459 37.766, -122.414 37.771))',
    9
));

-- String variant
SELECT h3_polygon_wkt_to_cells_string(
    'POLYGON ((-122.409 37.813, -122.381 37.787, -122.354 37.720,
               -122.512 37.708, -122.525 37.784, -122.480 37.815, -122.409 37.813))',
    9
);

-- Empty polygon returns empty list
SELECT h3_polygon_wkt_to_cells('POLYGON EMPTY', 9);
```

### Response
#### Success Response (200)
- **cells** (array of UBIGINT or array of VARCHAR) - A list of H3 cell IDs that fall within the polygon.
```

--------------------------------

### h3_polygon_wkt_to_cells_experimental

Source: https://github.com/isaacbrodsky/h3-duckdb/blob/main/README.md

Converts a polygon represented in Well-Known Text (WKT) format into a set of H3 cells using a new algorithm.

```APIDOC
## h3_polygon_wkt_to_cells_experimental

### Description
Converts a polygon represented in Well-Known Text (WKT) format into a set of H3 cells using a new algorithm.

### Method
SQL Function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```sql
SELECT h3_polygon_wkt_to_cells_experimental(ST_GeomFromText('POLYGON((...))'))
```

### Response
#### Success Response (200)
- **cells** (ARRAY<BIGINT>) - An array of H3 cell indices.

#### Response Example
```json
{
  "cells": [892901711711234567, 892901711711234568]
}
```
```

--------------------------------

### h3_directed_edge_to_boundary_wkt / h3_directed_edge_to_boundary_wkb

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Returns the boundary linestring of a directed edge in WKT or WKB format. Returns NULL for invalid edges.

```APIDOC
## h3_directed_edge_to_boundary_wkt(edge) / h3_directed_edge_to_boundary_wkb(edge)

### Description
Returns the boundary linestring of a directed edge as WKT or WKB. Returns `NULL` for invalid edges.

### Parameters
#### Path Parameters
- **edge** (string) - Required - The directed edge ID.

### Request Example
```sql
SELECT h3_directed_edge_to_boundary_wkt('115283473fffffff');
```

### Response
#### Success Response (200)
- **boundary** (string) - The boundary linestring in WKT or WKB format.

### Response Example
```json
"LINESTRING (-122.037735 37.420129, -122.090429 37.337556, -122.037735 37.420129)"
```
```

--------------------------------

### h3_string_to_h3 / h3_h3_to_string

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Performs type conversion between H3 string representations (hexadecimal) and H3 `UBIGINT` cell indexes.

```APIDOC
## `h3_string_to_h3(str)` / `h3_h3_to_string(cell)` 

### Description
Converts between `VARCHAR` hex strings and `UBIGINT` cell indexes. `h3_string_to_h3` returns `NULL` for malformed strings.

### Method
SQL Function

### Parameters
#### Path Parameters
- **str** (string) - The H3 index as a hexadecimal string.
- **cell** (ubigint) - The H3 index as a `UBIGINT`.

### Request Example
```sql
SELECT h3_string_to_h3('85283473fffffff');
SELECT h3_h3_to_string(599686042433355775::ubigint);
```

### Response
#### Success Response (string or ubigint)
- `h3_string_to_h3` returns a `UBIGINT` H3 index or `NULL`.
- `h3_h3_to_string` returns a `VARCHAR` hex string H3 index.

### Response Example
```sql
-- Result: 599686042433355775 (UBIGINT)
-- Result: 85283473fffffff
-- Result: NULL
```
```

--------------------------------

### Compact and Uncompact H3 Cell Sets

Source: https://context7.com/isaacbrodsky/h3-duckdb/llms.txt

Use `h3_compact_cells` to reduce a set of cells to their minimal representation by merging children into parents. `h3_uncompact_cells` expands a set to a single target resolution. Invalid cells in input arrays return NULL.

```sql
-- Compact 7 children into their parent
SELECT h3_compact_cells([
    '822d67fffffffff', '822d5ffffffffff', '822d4ffffffffff',
    '822d57fffffffff', '822d77fffffffff', '822d6ffffffffff', '822d47fffffffff'
]);
-- Result: [812d7ffffffffff]
```

```sql
-- Expand parent back to resolution 2
SELECT h3_uncompact_cells(['812d7ffffffffff'], 2);
-- Result: [822d47fffffffff, 822d4ffffffffff, 822d57fffffffff, 822d5ffffffffff,
--          822d67fffffffff, 822d6ffffffffff, 822d77fffffffff]
```

```sql
-- Invalid cell in array returns NULL
SELECT h3_compact_cells(['X', '822d5ffffffffff']);
-- Result: NULL
```

```sql
-- Empty array is valid
SELECT h3_compact_cells([]);
-- Result: []
```

```sql
-- Practical: polyfill then compact
WITH cells AS (
    SELECT h3_polygon_wkt_to_cells(wkt, 7) AS polyfilled
    FROM (VALUES ('POLYGON ((-122.4 37.8, -122.3 37.7, -122.5 37.7, -122.4 37.8))')) t(wkt)
)
SELECT h3_compact_cells(polyfilled) FROM cells;
```