Skip to main content
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

​
Parameters

​
Geometry
required
The input geometry. The function uses the midpoint of its envelope, not its centroid.
​
Double
required
The minimum X coordinate of the extent used to scale the midpoint.
​
Double
required
The minimum Y coordinate of the extent used to scale the midpoint.
​
Double
required
The maximum X coordinate of the extent used to scale the midpoint.
​
Double
required
The maximum Y coordinate of the extent used to scale the midpoint.
​
Integer
required
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: Level-2 Hilbert curve visiting a 4-by-4 grid in address order from 0 through 15 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: Five geometry envelopes and midpoints normalized onto a Hilbert grid, then sorted by addresses 0, 2, 4, 13, and 15 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:

​
Maximum address

The return type can represent the maximum level-16 address without becoming negative: