> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ST_HilbertDistance
Maps the midpoint of a geometry's envelope to an address along a Hilbert curve over a supplied extent. Use the result as a spatial sorting, clustering, or partitioning key. It is a one-dimensional curve address, not a geometric distance.
The envelope midpoint is scaled independently on each axis to the integer grid from `0` through `2^level - 1`. Coordinates outside the supplied extent are clipped to its nearest edge. A zero-width axis maps to grid coordinate zero. Z and M coordinates do not affect the result.
Use the same extent and level for geometries whose keys you want to compare. Different geometries whose envelope midpoints map to the same grid position receive the same key.
## Signatures
```sql theme={"system"}
ST_HilbertDistance(geometry: Geometry, xmin: Double, ymin: Double, xmax: Double, ymax: Double, level: Integer)
```
## Parameters
The input geometry. The function uses the midpoint of its envelope, not its centroid.
The minimum X coordinate of the extent used to scale the midpoint.
The minimum Y coordinate of the extent used to scale the midpoint.
The maximum X coordinate of the extent used to scale the midpoint.
The maximum Y coordinate of the extent used to scale the midpoint.
The curve level. Levels 1 through 16 provide increasingly fine ordering keys. For a non-empty geometry, a level at or below zero returns zero. A level above 16 raises an error.
## Return type
A non-negative Hilbert address. At level 16, the maximum value is `4294967295`.
If any argument is `NULL`, the result is `NULL`. An empty geometry raises an error because it has no envelope midpoint, including when the level is zero or negative.
## How addresses are assigned
At level 2, the extent becomes a 4-by-4 grid. The Hilbert curve visits every cell once and assigns addresses from 0 through 15 along that continuous path:
*Consecutive addresses share a grid edge, which is why sorting by the returned key tends to keep nearby records together. The key is an ordering address, not a geometric distance.*
For each input geometry, the function uses the midpoint of its envelope, normalizes that point into the supplied extent, and looks up the cell's Hilbert address. This example also shows how a midpoint outside the extent is clipped before lookup:
*Only the envelope midpoint determines the address. Different geometries with midpoints in the same grid cell receive the same value at that level.*
## Examples
### Envelope midpoint
The polygon's envelope midpoint is `(0.5, 0.5)`. Within the unit-square extent at level 2, it maps to address `2`:
```sql theme={"system"}
SELECT ST_HilbertDistance(
ST_GeomFromWKT('POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))'),
0.0, 0.0, 1.0, 1.0, 2
) AS hilbert_key;
```
```text theme={"system"}
2
```
### Maximum address
The return type can represent the maximum level-16 address without becoming negative:
```sql theme={"system"}
SELECT ST_HilbertDistance(
ST_GeomFromWKT('POINT (1 0)'),
0.0, 0.0, 1.0, 1.0, 16
) AS hilbert_key;
```
```text theme={"system"}
4294967295
```