Skip to content

Geography functions

Geography functions are used to generate or perform operations on the value of the geography data type.

For descriptions of the geography data types, see Geography.

Descriptions

Function Return Type Description
ST_Point(longitude, latitude) GEOGRAPHY Creates the geography that contains a point.
ST_GeogFromText(wkt_string) GEOGRAPHY Returns the geography corresponding to the input WKT string.
ST_ASText(geography) STRING Returns the WKT string of the input geography.
ST_Centroid(geography) GEOGRAPHY Returns the centroid of the input geography in the form of the single point geography.
ST_ISValid(geography) BOOL Returns whether the input geography is valid.
ST_Intersects(geography_1, geography_2) BOOL Returns whether geography_1 and geography_2 have intersections.
ST_Covers(geography_1, geography_2) BOOL Returns whether geography_1 completely contains geography_2. If there is no point outside geography_1 in geography_2, return True.
ST_CoveredBy(geography_1, geography_2) BOOL Returns whether geography_2 completely contains geography_1.If there is no point outside geography_2 in geography_1, return True.
ST_DWithin(geography_1, geography_2, distance) BOOL If the distance between one point (at least) in geography_1 and one point in geography_2 is less than or equal to the distance specified by the distance parameter (measured by meters), return True.
ST_Distance(geography_1, geography_2) FLOAT Returns the smallest possible distance (measured by meters) between two non-empty geographies.
S2_CellIdFromPoint(point_geography) INT Returns the S2 Cell ID that covers the point geography.
S2_CoveringCellIds(geography) ARRAY<INT64> Returns an array of S2 Cell IDs that cover the input geography.

Examples

nebula> RETURN ST_ASText(ST_Point(1,1));
+--------------------------+
| ST_ASText(ST_Point(1,1)) |
+--------------------------+
| "POINT(1 1)"             |
+--------------------------+

nebula> RETURN ST_ASText(ST_GeogFromText("POINT(3 8)"));
+------------------------------------------+
| ST_ASText(ST_GeogFromText("POINT(3 8)")) |
+------------------------------------------+
| "POINT(3 8)"                             |
+------------------------------------------+

nebula> RETURN ST_ASTEXT(ST_Centroid(ST_GeogFromText("LineString(0 1,1 0)")));
+----------------------------------------------------------------+
| ST_ASTEXT(ST_Centroid(ST_GeogFromText("LineString(0 1,1 0)"))) |
+----------------------------------------------------------------+
| "POINT(0.5000380800773782 0.5000190382261059)"                 |
+----------------------------------------------------------------+

nebula> RETURN ST_ISValid(ST_GeogFromText("POINT(3 8)"));
+-------------------------------------------+
| ST_ISValid(ST_GeogFromText("POINT(3 8)")) |
+-------------------------------------------+
| true                                      |
+-------------------------------------------+

nebula> RETURN ST_Intersects(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)"));
+----------------------------------------------------------------------------------------------+
| ST_Intersects(ST_GeogFromText("LineString(0 1,1 0)"),ST_GeogFromText("LineString(0 0,1 1)")) |
+----------------------------------------------------------------------------------------------+
| true                                                                                         |
+----------------------------------------------------------------------------------------------+

nebula> RETURN ST_Covers(ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"),ST_Point(1,2));
+--------------------------------------------------------------------------------+
| ST_Covers(ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"),ST_Point(1,2)) |
+--------------------------------------------------------------------------------+
| true                                                                           |
+--------------------------------------------------------------------------------+

nebula> RETURN ST_CoveredBy(ST_Point(1,2),ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))"));
+-----------------------------------------------------------------------------------+
| ST_CoveredBy(ST_Point(1,2),ST_GeogFromText("POLYGON((0 0,10 0,10 10,0 10,0 0))")) |
+-----------------------------------------------------------------------------------+
| true                                                                              |
+-----------------------------------------------------------------------------------+

nebula> RETURN ST_dwithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000.0);
+---------------------------------------------------------------------------------------+
| ST_dwithin(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"),20000000000) |
+---------------------------------------------------------------------------------------+
| true                                                                                  |
+---------------------------------------------------------------------------------------+

nebula> RETURN ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)"));
+----------------------------------------------------------------------------+
| ST_Distance(ST_GeogFromText("Point(0 0)"),ST_GeogFromText("Point(10 10)")) |
+----------------------------------------------------------------------------+
| 1.5685230187677438e+06                                                     |
+----------------------------------------------------------------------------+

nebula> RETURN S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)"));
+---------------------------------------------------+
| S2_CellIdFromPoint(ST_GeogFromText("Point(1 1)")) |
+---------------------------------------------------+
| 1153277837650709461                               |
+---------------------------------------------------+

nebula> RETURN S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"));
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| S2_CoveringCellIds(ST_GeogFromText("POLYGON((0 1, 1 2, 2 3, 0 1))"))                                                                                                     |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| [1152391494368201343, 1153466862374223872, 1153554823304445952, 1153836298281156608, 1153959443583467520, 1154240918560178176, 1160503736791990272, 1160591697722212352] |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Last update: October 25, 2023