From bd304e8a13cc695a6ea67f17d8463a2b36cafa88 Mon Sep 17 00:00:00 2001 From: "James A. Gill" Date: Wed, 21 Aug 2019 16:08:32 -0400 Subject: [PATCH] Fix docs for geospatial functions Two functions had an incorrect return type (`Geometry` instead of `array(Geometry)`). Make formatting more consistent, and rearrange some paragraphs for clarity. --- .../src/main/sphinx/functions/geospatial.rst | 71 ++++++++++--------- 1 file changed, 36 insertions(+), 35 deletions(-) diff --git a/presto-docs/src/main/sphinx/functions/geospatial.rst b/presto-docs/src/main/sphinx/functions/geospatial.rst index b278ee5bcded..81fbb4ced313 100644 --- a/presto-docs/src/main/sphinx/functions/geospatial.rst +++ b/presto-docs/src/main/sphinx/functions/geospatial.rst @@ -21,35 +21,34 @@ Binary (WKB) form of spatial objects: * ``MULTIPOLYGON (((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1)), ((-1 -1, -1 -2, -2 -2, -2 -1, -1 -1)))`` * ``GEOMETRYCOLLECTION (POINT(2 3), LINESTRING (2 3, 3 4))`` -Use ST_GeometryFromText and ST_GeomFromBinary functions to create geometry -objects from WKT or WKB. In WKT/WKB, the coordinate order is ``(x, y)``. -For spherical/geospatial uses, this implies ``(longitude, latitude)`` instead -of ``(latitude, longitude)``. +Use ``ST_GeometryFromText`` and ``ST_GeomFromBinary`` functions to create +geometry objects from WKT or WKB. In WKT/WKB, the coordinate order is +``(x, y)``. For spherical/geospatial uses, this implies +``(longitude, latitude)`` instead of ``(latitude, longitude)``. -The SphericalGeography type provides native support for spatial features -represented on "geographic" coordinates (sometimes called "geodetic" -coordinates, or "lat/lon", or "lon/lat"). Geographic coordinates are spherical -coordinates expressed in angular units (degrees). - -The basis for the Geometry type is a plane. The shortest path between two +The basis for the ``Geometry`` type is a plane. The shortest path between two points on the plane is a straight line. That means calculations on geometries (areas, distances, lengths, intersections, etc) can be calculated using cartesian mathematics and straight line vectors. -The basis for the SphericalGeography type is a sphere. The shortest path +The ``SphericalGeography`` type provides native support for spatial features +represented on "geographic" coordinates (sometimes called "geodetic" +coordinates, or "lat/lon", or "lon/lat"). Geographic coordinates are spherical +coordinates expressed in angular units (degrees). + +The basis for the ``SphericalGeography`` type is a sphere. The shortest path between two points on the sphere is a great circle arc. That means that calculations on geographies (areas, distances, lengths, intersections, etc) must be calculated on the sphere, using more complicated mathematics. More accurate measurements that take the actual spheroidal shape of the world into account are not supported. -Values returned by the measurement functions ST_Distance and ST_Length are in -the unit of meters; values returned by ST_Area are in square meters. +For ``SphericalGeography`` objects, values returned by the measurement functions +``ST_Distance`` and ``ST_Length`` are in the unit of meters; values returned by +``ST_Area`` are in square meters. Use ``to_spherical_geography()`` function to convert a geometry object to -geography object. - -For example, +geography object. For example, ``ST_Distance(ST_Point(-71.0882, 42.3607), ST_Point(-74.1197, 40.6976))`` returns 3.4577 in the unit of the passed-in values on the euclidean plane, while @@ -116,7 +115,7 @@ Constructors of such geometries. For each point of the input geometry, it verifies that point.x is within [-180.0, 180.0] and point.y is within [-90.0, 90.0], and uses them as (longitude, latitude) degrees to construct the shape of the - SphericalGeography result. + ``SphericalGeography`` result. .. function:: to_geometry(SphericalGeography) -> Geometry @@ -241,7 +240,7 @@ Accessors Returns the area of a polygon or multi-polygon in square meters using a spherical model for Earth. -.. function:: ST_Centroid(Geometry) -> Geometry +.. function:: ST_Centroid(Geometry) -> Point Returns the point value that is the mathematical centroid of a geometry. @@ -334,34 +333,29 @@ Accessors .. function:: ST_XMax(Geometry) -> double - Returns X maxima of a bounding box of a geometry. + Returns the X maximum of the geometry's bounding box. .. function:: ST_YMax(Geometry) -> double - Returns Y maxima of a bounding box of a geometry. + Returns the Y maximum of the geometry's bounding box. .. function:: ST_XMin(Geometry) -> double - Returns X minima of a bounding box of a geometry. + Returns the X minimum of the geometry's bounding box. .. function:: ST_YMin(Geometry) -> double - Returns Y minima of a bounding box of a geometry. + Returns the Y minimum of the geometry's bounding box. .. function:: ST_StartPoint(Geometry) -> point Returns the first point of a LineString geometry as a Point. - This is a shortcut for ST_PointN(geometry, 1). - -.. function:: simplify_geometry(Geometry, double) -> Geometry - - Returns a "simplified" version of the input geometry using the Douglas-Peucker algorithm. - Will avoid creating derived geometries (polygons in particular) that are invalid. + This is a shortcut for ``ST_PointN(geometry, 1)``. .. function:: ST_EndPoint(Geometry) -> point Returns the last point of a LineString geometry as a Point. - This is a shortcut for ST_PointN(geometry, ST_NumPoints(geometry)). + This is a shortcut for ``ST_PointN(geometry, ST_NumPoints(geometry))``. .. function:: ST_X(Point) -> double @@ -371,7 +365,7 @@ Accessors Return the Y coordinate of the point. -.. function:: ST_InteriorRings(Geometry) -> Geometry +.. function:: ST_InteriorRings(Geometry) -> array(Geometry) Returns an array of all interior rings found in the input geometry, or an empty array if the polygon has no interior rings. Returns ``null`` if the input geometry @@ -380,12 +374,14 @@ Accessors .. function:: ST_NumGeometries(Geometry) -> bigint Returns the number of geometries in the collection. - If the geometry is a collection of geometries (e.g., GEOMETRYCOLLECTION or MULTI*), - returns the number of geometries, - for single geometries returns 1, - for empty geometries returns 0. + If the geometry is a collection of geometries (e.g., GEOMETRYCOLLECTION or + MULTI*), returns the number of geometries, for single geometries returns 1, + for empty geometries returns 0. Note that empty geometries inside of a + GEOMETRYCOLLECTION will count as a geometry; eg + ``ST_NumGeometries(ST_GeometryFromText('GEOMETRYCOLLECTION(MULTIPOINT EMPTY)'))`` + will evaluate to 1. -.. function:: ST_Geometries(Geometry) -> Geometry +.. function:: ST_Geometries(Geometry) -> array(Geometry) Returns an array of geometries in the specified collection. Returns a one-element array if the input geometry is not a multi-geometry. Returns ``null`` if input geometry is empty. @@ -399,6 +395,11 @@ Accessors Returns the cardinality of the collection of interior rings of a polygon. +.. function:: simplify_geometry(Geometry, double) -> Geometry + + Returns a "simplified" version of the input geometry using the Douglas-Peucker algorithm. + Will avoid creating derived geometries (polygons in particular) that are invalid. + .. function:: line_locate_point(LineString, Point) -> double Returns a float between 0 and 1 representing the location of the closest point on