All Products
Search

This Product

    PolarDB:ST_AsText

    Document Center

    PolarDB:ST_AsText

    Last Updated:Mar 28, 2026

    Converts a geographic grid object to GGER-encoded text or H3-encoded text, depending on the grid type.

    Syntax

    For GeomGrid (single grid):

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

    For GeomGrid (grid array):

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

    For H3Grid:

    text ST_AsText(h3grid grid)

    Parameters

    ParameterTypeDefaultDescription
    gridGeomGrid or H3Grid—The geographic grid object to convert.
    precisioninteger-1The output precision level. Valid values: 1 to 32. Set to -1 to use the storage precision of the grid.
    separatedboolfalseSpecifies whether to use split encoding. Applies to 3D GGER encoding.
    standardtext'GGER'The encoding specification. Supports GGER (GeoSpatial Grid Encoding Rule), developed by the Ministry of Natural Resources of the People's Republic of China.

    Description

    ST_AsText converts a geographic grid to text based on the specified layer, precision, and encoding specification.

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

    In split encoding, the height encoding represents the index value of the grid in the height dimension as a binary text code. Grids above the surface produce a height encoding prefixed with +. Grids below the surface produce a height encoding prefixed with -.

    Examples

    Default layer

    The following example converts a grid at the default precision (level 15, set when constructing the grid via ST_AsGrid).

    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

    The following example outputs the grid at precision level 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

    3D encoding

    The following example encodes a 3D point (with altitude) at precision level 20 using GGER.

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

    Output:

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

    Split encoding

    The following example uses split encoding (separated = true) to separate the horizontal and height components of the grid code. The height component is prefixed with + because the point is above the surface.

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

    Output:

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

    H3 encoding

    The following example converts an H3Grid object to its H3 text representation.

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

    Output:

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

    See also

    • ST_AsGrid — Convert a geometry to a GeomGrid object.

    • ST_As3DGrid — Convert a 3D geometry to a GeomGrid object.

    • ST_H3FromLatLng — Create an H3Grid object from a latitude/longitude pair.