Use ST_AsText to convert a geographic grid to text - PolarDB

Converts a geographic grid object (GeomGrid or H3Grid) to its text representation using a specified encoding standard.

To create a grid object from a geometry, use ST_AsGrid (2D), ST_As3DGrid (3D), or ST_H3FromLatLng (H3).

Syntax

text ST_AsText(geomgrid    grid
               integer     precision  DEFAULT -1,
               bool        separated  DEFAULT false,
               text        standard   DEFAULT 'GGER')

text[] ST_AsText(geomgrid[] grid
                 integer    precision  DEFAULT -1,
                 bool       separated  DEFAULT false,
                 text       standard   DEFAULT 'GGER')

text ST_AsText(h3grid grid)

Parameters

Parameter	Type	Default	Description
`grid`	GeomGrid or H3Grid	—	The geographic grid object to convert.
`precision`	integer	-1	The precision level for the output. Valid values: 1–32. The value `-1` uses the precision level of the input grid.
`separated`	bool	false	Specifies whether to use split encoding. Applicable to 3D GeoSpatial Grid Encoding Rule (GGER) grids.
`standard`	text	`'GGER'`	The encoding standard to apply. Currently supports `GGER`, developed by the Ministry of Natural Resources of the People's Republic of China.

How it works

ST_AsText encodes a geographic grid based on the specified precision level and encoding standard.

Precision behavior: If the specified precision is higher than the storage precision of the input grid, the output is not zero-padded.

Split encoding (3D GGER): When separated is set to true, the height encoding is returned as the binary text code for the grid's index value in the height dimension. The prefix indicates the grid's position relative to the surface:

+ — the grid is above the surface
- — the grid is below the surface

Examples

Default encoding

Encode a 2D grid using the default precision and GGER standard.

WITH g AS (
  SELECT unnest(ST_AsGrid(
    ST_geomfromtext('POINT(116.31522216796875 39.910277777777778)', 4490), 15)) AS grid
)
SELECT ST_AsText(grid) FROM g;

Output:

    st_astext
------------------
 G001310322230230

Specified precision level

Encode the same grid at a lower precision level by setting precision to 8.

WITH g AS (
  SELECT unnest(ST_AsGrid(
    ST_geomfromtext('POINT(116.31522216796875 39.910277777777778)', 4490), 15)) AS grid
)
SELECT ST_AsText(grid, 8) FROM g;

Output:

  st_astext
-------------
 G00131032

The output is shorter because the precision is reduced from 15 to 8. Missing digits are not padded with zeros.

3D encoding

Encode a 3D grid with an elevation of 1001.8 meters at precision level 20.

SELECT unnest(ST_AsText(ST_As3DGrid(
  'srid=4490;POINT(116.31522216796875 39.910277777777778 1001.8)'::geometry,
  20)));

Output:

         unnest
------------------------
 GZ00262064446046072072

Split encoding

Encode a 3D grid using split encoding (separated = true). The horizontal and height components are returned separately.

SELECT unnest(ST_AsText(ST_As3DGrid(
  'srid=4490;POINT(116.31522216796875 39.910277777777778 1001.8)'::geometry,
  20), -1, true));

Output:

             unnest
-------------------------------
 G00131032223023031031, +10010

The + prefix on 10010 indicates this grid is above the surface.

H3 encoding

Encode an H3Grid object to its H3 text index.

SELECT ST_AsText(ST_H3FromLatLng(20.5, 128.2, 8));

Output:

    st_astext
-----------------
 884a126689fffff

Related functions

[ST_AsGrid]() — Convert a geometry to a GeomGrid array
[ST_As3DGrid]() — Convert a 3D geometry to a GeomGrid array
[ST_H3FromLatLng]() — Create an H3Grid from a latitude/longitude coordinate