Returns an array of geomgrid objects identifying the geographic grid cells that intersect with a given geometry.
Syntax
geomgrid[] ST_AsGrid(geometry geom, integer precision, bool degenerated default false);Parameters
| Parameter | Type | Description |
|---|---|---|
geom | geometry | The geometry to query. |
precision | integer | The precision level of the grid cells. Valid values: 1 to 32. A higher value produces finer-grained grid cells. |
degenerated | bool | Specifies whether to return a degenerated grid. Default: false. See Usage notes for when to use each mode. |
Description
The input geometry must use the CGC2000 spatial reference system (Spatial Reference System Identifier (SRID) = 4490). If the geometry uses a different spatial reference system, ST_Transform is called automatically to convert its coordinates to CGC2000 before processing.
The function returns an array of geographic grid cells that intersect with the geometry. The following figure shows examples of grid intersections for a point, a line, and a polygon.
Usage notes
Standard grid vs. degenerated grid
The degenerated parameter controls how grid cells along the boundary of the geometry are handled:
Standard grid (
degenerated=false, default): Returns all grid cells whose boundaries intersect the geometry, including partial-overlap cells at the edges. This produces a larger result set and is suitable for use cases that require complete coverage, such as spatial indexing.Degenerated grid (
degenerated=true): Collapses boundary cells into their parent cells, returning a smaller, more compact result set. Use this when you need a coarser approximation and a reduced number of grid identifiers.
The following figure compares the two modes:
For example, querying a polygon at precision 15 returns 28 grid cells with the standard grid and 13 cells with the degenerated grid.
Examples
All examples wrap ST_AsGrid in ST_AsText to display the grid identifiers as text.
Example 1: Point geometry
Query the grid cell at precision 15 that contains a single point in Beijing.
SELECT ST_AsText(ST_AsGrid(
ST_GeomFromText('POINT(116.31522216796875 39.910277777777778)', 4490), 15));Result:
st_astext
--------------------
{G001310322230230}Example 2: LineString geometry
Query the grid cells at precision 18 that intersect a line segment in northeastern China.
SELECT ST_AsText(ST_AsGrid(
ST_GeomFromText('LINESTRING(122.48077 51.72814,122.47416 51.73714)', 4490), 18));Result:
st_astext
--------------------------------------------------------------------------------
{G001331032213300011,G001331032213300013,G001331032213122320,G001331032213122322,
G001331032213300100,G001331032213122303,G001331032213122321,G001331032213122312}Example 3: Polygon geometry — standard grid
Query the grid cells at precision 15 that intersect a polygon, using the default standard grid mode. This returns all cells that overlap the polygon boundary, including partial-overlap cells.
SELECT ST_AsText(ST_AsGrid(
ST_GeomFromText('POLYGON((-0.08077 -0.02814, 0.0482 -0.03, 0.07426 0.03724, -0.08077 -0.02814))', 4490), 15));Result (28 cells):
st_astext
--------------------------------------------------------------------------------
{G000000000000000,G000000000000001,G000000000000003,G000000000000010,G000000000000011,
G000000000000012,G000000000000013,G000000000000031,G000000000000102,G000000000000120,
G100000000000000,G200000000000000,G200000000000001,G200000000000002,G200000000000003,
G200000000000010,G200000000000011,G200000000000012,G200000000000013,G300000000000000,
G300000000000001,G300000000000002,G300000000000003,G300000000000010,G300000000000011,
G300000000000012,G300000000000013,G300000000000102}Example 4: Polygon geometry — degenerated grid
Query the same polygon using the degenerated grid mode (degenerated=true). Boundary cells are collapsed into parent cells, reducing the result from 28 to 13 cells.
SELECT ST_AsText(ST_AsGrid(
ST_GeomFromText('POLYGON((-0.08077 -0.02814, 0.0482 -0.03, 0.07426 0.03724, -0.08077 -0.02814))', 4490), 15, true));Result (13 cells):
st_astext
--------------------------------------------------------------------------------
{G000000000000000,G000000000000001,G000000000000003,G00000000000001,G000000000000031,
G000000000000102,G000000000000120,G100000000000000,G20000000000000,G200000000000001,
G30000000000000,G30000000000001,G300000000000102}What's next
ST_As3DGrid: Returns three-dimensional grid cells that intersect with a 3D geometry.ST_AsH3Grid: Returns H3 hexagonal grid cells that intersect with a geometry.