diff --git a/docs/functions.md b/docs/functions.md index 8a0d860f..2b24a7f3 100644 --- a/docs/functions.md +++ b/docs/functions.md @@ -5,125 +5,126 @@ | Function | Summary | | --- | --- | -| [ST_Area](#st_area) | Returns the area of a geometry. | -| [ST_Area_Spheroid](#st_area_spheroid) | Returns the area of a geometry in meters, using an ellipsoidal model of the earth | -| [ST_AsGeoJSON](#st_asgeojson) | Returns the geometry as a GeoJSON fragment | -| [ST_AsHEXWKB](#st_ashexwkb) | Returns the geometry as a HEXWKB string | -| [ST_AsText](#st_astext) | Returns the geometry as a WKT string | -| [ST_AsWKB](#st_aswkb) | Returns the geometry as a WKB blob | -| [ST_Boundary](#st_boundary) | Returns the "boundary" of a geometry | -| [ST_Buffer](#st_buffer) | Returns a buffer around the input geometry at the target distance | -| [ST_Centroid](#st_centroid) | Calculates the centroid of a geometry | -| [ST_Collect](#st_collect) | Collects geometries into a collection geometry | -| [ST_CollectionExtract](#st_collectionextract) | Extracts a sub-geometry from a collection geometry | -| [ST_Contains](#st_contains) | Returns true if geom1 contains geom2. | -| [ST_ContainsProperly](#st_containsproperly) | Returns true if geom1 "properly contains" geom2 | -| [ST_ConvexHull](#st_convexhull) | Returns the convex hull enclosing the geometry | -| [ST_CoveredBy](#st_coveredby) | Returns true if geom1 is "covered" by geom2 | -| [ST_Covers](#st_covers) | Returns if geom1 "covers" geom2 | -| [ST_Crosses](#st_crosses) | Returns true if geom1 "crosses" geom2 | -| [ST_DWithin](#st_dwithin) | Returns if two geometries are within a target distance of each-other | -| [ST_DWithin_Spheroid](#st_dwithin_spheroid) | Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface | -| [ST_Difference](#st_difference) | Returns the "difference" between two geometries | -| [ST_Dimension](#st_dimension) | Returns the dimension of a geometry. | -| [ST_Disjoint](#st_disjoint) | Returns if two geometries are disjoint | -| [ST_Distance](#st_distance) | Returns the distance between two geometries. | -| [ST_Distance_Sphere](#st_distance_sphere) | Returns the haversine distance between two geometries. | -| [ST_Distance_Spheroid](#st_distance_spheroid) | Returns the distance between two geometries in meters using a ellipsoidal model of the earths surface | -| [ST_Dump](#st_dump) | Dumps a geometry into a set of sub-geometries and their "path" in the original geometry. | -| [ST_EndPoint](#st_endpoint) | Returns the end point of a line. | -| [ST_Envelope](#st_envelope) | Returns the minimum bounding box for the input geometry as a polygon geometry. | -| [ST_Equals](#st_equals) | Compares two geometries for equality | -| [ST_Extent](#st_extent) | Returns the minimal bounding box enclosing the input geometry | -| [ST_ExteriorRing](#st_exteriorring) | Returns the exterior ring (shell) of a polygon geometry. | -| [ST_FlipCoordinates](#st_flipcoordinates) | Returns a new geometry with the coordinates of the input geometry "flipped" so that x = y and y = x. | -| [ST_Force2D](#st_force2d) | Forces the vertices of a geometry to have X and Y components | -| [ST_Force3DM](#st_force3dm) | Forces the vertices of a geometry to have X, Y and M components | -| [ST_Force3DZ](#st_force3dz) | Forces the vertices of a geometry to have X, Y and Z components | -| [ST_Force4D](#st_force4d) | Forces the vertices of a geometry to have X, Y, Z and M components | -| [ST_GeomFromGeoJSON](#st_geomfromgeojson) | Deserializes a GEOMETRY from a GeoJSON fragment. | -| [ST_GeomFromHEXEWKB](#st_geomfromhexewkb) | Deserialize a GEOMETRY from a HEXEWKB encoded string | -| [ST_GeomFromHEXWKB](#st_geomfromhexwkb) | Creates a GEOMETRY from a HEXWKB string | -| [ST_GeomFromText](#st_geomfromtext) | Deserializes a GEOMETRY from a WKT string, optionally ignoring invalid geometries | -| [ST_GeomFromWKB](#st_geomfromwkb) | Deserializes a GEOMETRY from a WKB encoded blob | -| [ST_GeometryType](#st_geometrytype) | Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type. | -| [ST_HasM](#st_hasm) | Check if the input geometry has M values. | -| [ST_HasZ](#st_hasz) | Check if the input geometry has Z values. | -| [ST_Hilbert](#st_hilbert) | Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box | -| [ST_Intersection](#st_intersection) | Returns the "intersection" of geom1 and geom2 | -| [ST_Intersects](#st_intersects) | Returns true if two geometries intersects | -| [ST_Intersects_Extent](#st_intersects_extent) | Returns true if the extent of two geometries intersects | -| [ST_IsClosed](#st_isclosed) | Returns true if a geometry is "closed" | -| [ST_IsEmpty](#st_isempty) | Returns true if the geometry is "empty" | -| [ST_IsRing](#st_isring) | Returns true if the input line geometry is a ring (both ST_IsClosed and ST_IsSimple). | -| [ST_IsSimple](#st_issimple) | Returns true if the input geometry is "simple" | -| [ST_IsValid](#st_isvalid) | Returns true if the geometry is topologically "valid" | -| [ST_Length](#st_length) | Returns the length of the input line geometry | -| [ST_Length_Spheroid](#st_length_spheroid) | Returns the length of the input geometry in meters, using a ellipsoidal model of the earth | -| [ST_LineMerge](#st_linemerge) | "Merges" the input line geometry, optionally taking direction into account. | -| [ST_M](#st_m) | Returns the M value of a point geometry, or NULL if not a point or empty | -| [ST_MMax](#st_mmax) | Returns the maximum M value of a geometry | -| [ST_MMin](#st_mmin) | Returns the minimum M value of a geometry | -| [ST_MakeEnvelope](#st_makeenvelope) | Returns a minimal bounding box polygon enclosing the input geometry | -| [ST_MakeLine](#st_makeline) | Creates a LINESTRING geometry from a pair or list of input points | -| [ST_MakePolygon](#st_makepolygon) | Creates a polygon from a shell geometry and an optional set of holes | -| [ST_MakeValid](#st_makevalid) | Attempts to make an invalid geometry valid without removing any vertices | -| [ST_NGeometries](#st_ngeometries) | Returns the number of component geometries in a collection geometry | -| [ST_NInteriorRings](#st_ninteriorrings) | Returns the number if interior rings of a polygon | -| [ST_NPoints](#st_npoints) | Returns the number of vertices within a geometry | -| [ST_Normalize](#st_normalize) | Returns a "normalized" version of the input geometry. | -| [ST_NumGeometries](#st_numgeometries) | Returns the number of component geometries in a collection geometry | -| [ST_NumInteriorRings](#st_numinteriorrings) | Returns the number if interior rings of a polygon | -| [ST_NumPoints](#st_numpoints) | Returns the number of vertices within a geometry | -| [ST_Overlaps](#st_overlaps) | Returns true if geom1 "overlaps" geom2 | -| [ST_Perimeter](#st_perimeter) | Returns the length of the perimeter of the geometry | -| [ST_Perimeter_Spheroid](#st_perimeter_spheroid) | Returns the length of the perimeter in meters using an ellipsoidal model of the earths surface | -| [ST_Point](#st_point) | Creates a GEOMETRY point | -| [ST_Point2D](#st_point2d) | Creates a POINT_2D | -| [ST_Point3D](#st_point3d) | Creates a POINT_3D | -| [ST_Point4D](#st_point4d) | Creates a POINT_4D | -| [ST_PointN](#st_pointn) | Returns the n'th vertex from the input geometry as a point geometry | -| [ST_PointOnSurface](#st_pointonsurface) | Returns a point that is guaranteed to be on the surface of the input geometry. Sometimes a useful alternative to ST_Centroid. | -| [ST_Points](#st_points) | Collects all the vertices in the geometry into a multipoint | -| [ST_QuadKey](#st_quadkey) | Computes a quadkey from a given lon/lat point. | -| [ST_ReducePrecision](#st_reduceprecision) | Returns the geometry with all vertices reduced to the target precision | -| [ST_RemoveRepeatedPoints](#st_removerepeatedpoints) | Returns a new geometry with repeated points removed, optionally within a target distance of eachother. | -| [ST_Reverse](#st_reverse) | Returns a new version of the input geometry with the order of its vertices reversed | -| [ST_ShortestLine](#st_shortestline) | Returns the line between the two closest points between geom1 and geom2 | -| [ST_Simplify](#st_simplify) | Simplifies the input geometry by collapsing edges smaller than 'distance' | -| [ST_SimplifyPreserveTopology](#st_simplifypreservetopology) | Returns a simplified geometry but avoids creating invalid topologies | -| [ST_StartPoint](#st_startpoint) | Returns the first point of a line geometry | -| [ST_Touches](#st_touches) | Returns true if geom1 "touches" geom2 | -| [ST_Transform](#st_transform) | Transforms a geometry between two coordinate systems | -| [ST_Union](#st_union) | Returns the union of two geometries. | -| [ST_Within](#st_within) | Returns true if geom1 is "within" geom2 | -| [ST_X](#st_x) | Returns the X value of a point geometry, or NULL if not a point or empty | -| [ST_XMax](#st_xmax) | Returns the maximum X value of a geometry | -| [ST_XMin](#st_xmin) | Returns the minimum X value of a geometry | -| [ST_Y](#st_y) | Returns the Y value of a point geometry, or NULL if not a point or empty | -| [ST_YMax](#st_ymax) | Returns the maximum Y value of a geometry | -| [ST_YMin](#st_ymin) | Returns the minimum Y value of a geometry | -| [ST_Z](#st_z) | Returns the Z value of a point geometry, or NULL if not a point or empty | -| [ST_ZMFlag](#st_zmflag) | Returns a flag indicating the presence of Z and M values in the input geometry. | -| [ST_ZMax](#st_zmax) | Returns the maximum Z value of a geometry | -| [ST_ZMin](#st_zmin) | Returns the minimum Z value of a geometry | +| [`ST_Area`](#st_area) | Compute the area of a geometry. | +| [`ST_Area_Spheroid`](#st_area_spheroid) | Returns the area of a geometry in meters, using an ellipsoidal model of the earth | +| [`ST_AsGeoJSON`](#st_asgeojson) | Returns the geometry as a GeoJSON fragment | +| [`ST_AsHEXWKB`](#st_ashexwkb) | Returns the geometry as a HEXWKB string | +| [`ST_AsSVG`](#st_assvg) | Convert the geometry into a SVG fragment or path | +| [`ST_AsText`](#st_astext) | Returns the geometry as a WKT string | +| [`ST_AsWKB`](#st_aswkb) | Returns the geometry as a WKB blob | +| [`ST_Boundary`](#st_boundary) | Returns the "boundary" of a geometry | +| [`ST_Buffer`](#st_buffer) | Returns a buffer around the input geometry at the target distance | +| [`ST_Centroid`](#st_centroid) | Calculates the centroid of a geometry | +| [`ST_Collect`](#st_collect) | Collects a list of geometries into a collection geometry. | +| [`ST_CollectionExtract`](#st_collectionextract) | Extracts a sub-geometry from a collection geometry | +| [`ST_Contains`](#st_contains) | Returns true if geom1 contains geom2. | +| [`ST_ContainsProperly`](#st_containsproperly) | Returns true if geom1 "properly contains" geom2 | +| [`ST_ConvexHull`](#st_convexhull) | Returns the convex hull enclosing the geometry | +| [`ST_CoveredBy`](#st_coveredby) | Returns true if geom1 is "covered" by geom2 | +| [`ST_Covers`](#st_covers) | Returns if geom1 "covers" geom2 | +| [`ST_Crosses`](#st_crosses) | Returns true if geom1 "crosses" geom2 | +| [`ST_DWithin`](#st_dwithin) | Returns if two geometries are within a target distance of each-other | +| [`ST_DWithin_Spheroid`](#st_dwithin_spheroid) | Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface | +| [`ST_Difference`](#st_difference) | Returns the "difference" between two geometries | +| [`ST_Dimension`](#st_dimension) | Returns the dimension of a geometry. | +| [`ST_Disjoint`](#st_disjoint) | Returns if two geometries are disjoint | +| [`ST_Distance`](#st_distance) | Returns the distance between two geometries. | +| [`ST_Distance_Sphere`](#st_distance_sphere) | Returns the haversine distance between two geometries. | +| [`ST_Distance_Spheroid`](#st_distance_spheroid) | Returns the distance between two geometries in meters using a ellipsoidal model of the earths surface | +| [`ST_Dump`](#st_dump) | Dumps a geometry into a list of sub-geometries and their "path" in the original geometry. | +| [`ST_EndPoint`](#st_endpoint) | Returns the last point of a line. | +| [`ST_Envelope`](#st_envelope) | Returns the minimum bounding box for the input geometry as a polygon geometry. | +| [`ST_Equals`](#st_equals) | Compares two geometries for equality | +| [`ST_Extent`](#st_extent) | Returns the minimal bounding box enclosing the input geometry | +| [`ST_ExteriorRing`](#st_exteriorring) | Returns the exterior ring (shell) of a polygon geometry. | +| [`ST_FlipCoordinates`](#st_flipcoordinates) | Returns a new geometry with the coordinates of the input geometry "flipped" so that x = y and y = x. | +| [`ST_Force2D`](#st_force2d) | Forces the vertices of a geometry to have X and Y components | +| [`ST_Force3DM`](#st_force3dm) | Forces the vertices of a geometry to have X, Y and M components | +| [`ST_Force3DZ`](#st_force3dz) | Forces the vertices of a geometry to have X, Y and Z components | +| [`ST_Force4D`](#st_force4d) | Forces the vertices of a geometry to have X, Y, Z and M components | +| [`ST_GeomFromGeoJSON`](#st_geomfromgeojson) | Deserializes a GEOMETRY from a GeoJSON fragment. | +| [`ST_GeomFromHEXEWKB`](#st_geomfromhexewkb) | Deserialize a GEOMETRY from a HEXEWKB encoded string | +| [`ST_GeomFromHEXWKB`](#st_geomfromhexwkb) | Creates a GEOMETRY from a HEXWKB string | +| [`ST_GeomFromText`](#st_geomfromtext) | Deserializes a GEOMETRY from a WKT string, optionally ignoring invalid geometries | +| [`ST_GeomFromWKB`](#st_geomfromwkb) | Deserializes a GEOMETRY from a WKB encoded blob | +| [`ST_GeometryType`](#st_geometrytype) | Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type. | +| [`ST_HasM`](#st_hasm) | Check if the input geometry has M values. | +| [`ST_HasZ`](#st_hasz) | Check if the input geometry has Z values. | +| [`ST_Hilbert`](#st_hilbert) | Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box. | +| [`ST_Intersection`](#st_intersection) | Returns the "intersection" of geom1 and geom2 | +| [`ST_Intersects`](#st_intersects) | Returns true if two geometries intersects | +| [`ST_Intersects_Extent`](#st_intersects_extent) | Returns true if the extent of two geometries intersects | +| [`ST_IsClosed`](#st_isclosed) | Returns true if a geometry is "closed" | +| [`ST_IsEmpty`](#st_isempty) | Returns true if the geometry is "empty" | +| [`ST_IsRing`](#st_isring) | Returns true if the input line geometry is a ring (both ST_IsClosed and ST_IsSimple). | +| [`ST_IsSimple`](#st_issimple) | Returns true if the input geometry is "simple" | +| [`ST_IsValid`](#st_isvalid) | Returns true if the geometry is topologically "valid" | +| [`ST_Length`](#st_length) | Returns the length of the input line geometry | +| [`ST_Length_Spheroid`](#st_length_spheroid) | Returns the length of the input geometry in meters, using a ellipsoidal model of the earth | +| [`ST_LineMerge`](#st_linemerge) | "Merges" the input line geometry, optionally taking direction into account. | +| [`ST_M`](#st_m) | Returns the M value of a point geometry, or NULL if not a point or empty | +| [`ST_MMax`](#st_mmax) | Returns the maximum M value of a geometry | +| [`ST_MMin`](#st_mmin) | Returns the minimum M value of a geometry | +| [`ST_MakeEnvelope`](#st_makeenvelope) | Returns a minimal bounding box polygon enclosing the input geometry | +| [`ST_MakeLine`](#st_makeline) | Creates a LINESTRING geometry from a pair or list of input points | +| [`ST_MakePolygon`](#st_makepolygon) | Creates a polygon from a shell geometry and an optional set of holes | +| [`ST_MakeValid`](#st_makevalid) | Attempts to make an invalid geometry valid without removing any vertices | +| [`ST_NGeometries`](#st_ngeometries) | Returns the number of component geometries in a collection geometry. | +| [`ST_NInteriorRings`](#st_ninteriorrings) | Returns the number if interior rings of a polygon | +| [`ST_NPoints`](#st_npoints) | Returns the number of vertices within a geometry | +| [`ST_Normalize`](#st_normalize) | Returns a "normalized" version of the input geometry. | +| [`ST_NumGeometries`](#st_numgeometries) | Returns the number of component geometries in a collection geometry. | +| [`ST_NumInteriorRings`](#st_numinteriorrings) | Returns the number if interior rings of a polygon | +| [`ST_NumPoints`](#st_numpoints) | Returns the number of vertices within a geometry | +| [`ST_Overlaps`](#st_overlaps) | Returns true if geom1 "overlaps" geom2 | +| [`ST_Perimeter`](#st_perimeter) | Returns the length of the perimeter of the geometry | +| [`ST_Perimeter_Spheroid`](#st_perimeter_spheroid) | Returns the length of the perimeter in meters using an ellipsoidal model of the earths surface | +| [`ST_Point`](#st_point) | Creates a GEOMETRY point | +| [`ST_Point2D`](#st_point2d) | Creates a POINT_2D | +| [`ST_Point3D`](#st_point3d) | Creates a POINT_3D | +| [`ST_Point4D`](#st_point4d) | Creates a POINT_4D | +| [`ST_PointN`](#st_pointn) | Returns the n'th vertex from the input geometry as a point geometry | +| [`ST_PointOnSurface`](#st_pointonsurface) | Returns a point that is guaranteed to be on the surface of the input geometry. Sometimes a useful alternative to ST_Centroid. | +| [`ST_Points`](#st_points) | Collects all the vertices in the geometry into a multipoint | +| [`ST_QuadKey`](#st_quadkey) | Compute the [quadkey](https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) for a given lon/lat point at a given level. | +| [`ST_ReducePrecision`](#st_reduceprecision) | Returns the geometry with all vertices reduced to the target precision | +| [`ST_RemoveRepeatedPoints`](#st_removerepeatedpoints) | Returns a new geometry with repeated points removed, optionally within a target distance of eachother. | +| [`ST_Reverse`](#st_reverse) | Returns a new version of the input geometry with the order of its vertices reversed | +| [`ST_ShortestLine`](#st_shortestline) | Returns the line between the two closest points between geom1 and geom2 | +| [`ST_Simplify`](#st_simplify) | Simplifies the input geometry by collapsing edges smaller than 'distance' | +| [`ST_SimplifyPreserveTopology`](#st_simplifypreservetopology) | Returns a simplified geometry but avoids creating invalid topologies | +| [`ST_StartPoint`](#st_startpoint) | Returns the first point of a line geometry | +| [`ST_Touches`](#st_touches) | Returns true if geom1 "touches" geom2 | +| [`ST_Transform`](#st_transform) | Transforms a geometry between two coordinate systems | +| [`ST_Union`](#st_union) | Returns the union of two geometries. | +| [`ST_Within`](#st_within) | Returns true if geom1 is "within" geom2 | +| [`ST_X`](#st_x) | Returns the X value of a point geometry, or NULL if not a point or empty | +| [`ST_XMax`](#st_xmax) | Returns the maximum X value of a geometry | +| [`ST_XMin`](#st_xmin) | Returns the minimum X value of a geometry | +| [`ST_Y`](#st_y) | Returns the Y value of a point geometry, or NULL if not a point or empty | +| [`ST_YMax`](#st_ymax) | Returns the maximum Y value of a geometry | +| [`ST_YMin`](#st_ymin) | Returns the minimum Y value of a geometry | +| [`ST_Z`](#st_z) | Returns the Z value of a point geometry, or NULL if not a point or empty | +| [`ST_ZMFlag`](#st_zmflag) | Returns a flag indicating the presence of Z and M values in the input geometry. | +| [`ST_ZMax`](#st_zmax) | Returns the maximum Z value of a geometry | +| [`ST_ZMin`](#st_zmin) | Returns the minimum Z value of a geometry | **[Aggregate Functions](#aggregate-functions)** | Function | Summary | | --- | --- | -| [ST_Envelope_Agg](#st_envelope_agg) | Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries | -| [ST_Intersection_Agg](#st_intersection_agg) | Computes the intersection of a set of geometries | -| [ST_Union_Agg](#st_union_agg) | Computes the union of a set of input geometries | +| [`ST_Envelope_Agg`](#st_envelope_agg) | Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries | +| [`ST_Intersection_Agg`](#st_intersection_agg) | Computes the intersection of a set of geometries | +| [`ST_Union_Agg`](#st_union_agg) | Computes the union of a set of input geometries | **[Table Functions](#table-functions)** | Function | Summary | | --- | --- | -| [ST_Drivers](#st_drivers) | Returns the list of supported GDAL drivers and file formats | -| [ST_Read](#st_read) | Read and import a variety of geospatial file formats using the GDAL library. | -| [ST_ReadOSM](#st_readosm) | The ST_ReadOsm() table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` | -| [ST_Read_Meta](#st_read_meta) | Read and the metadata from a variety of geospatial file formats using the GDAL library. | +| [`ST_Drivers`](#st_drivers) | Returns the list of supported GDAL drivers and file formats | +| [`ST_Read`](#st_read) | Read and import a variety of geospatial file formats using the GDAL library. | +| [`ST_ReadOSM`](#st_readosm) | The `ST_ReadOsm()` table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` | +| [`ST_Read_Meta`](#st_read_meta) | Read and the metadata from a variety of geospatial file formats using the GDAL library. | ---- @@ -131,9 +132,8 @@ ### ST_Area -_Returns the area of a geometry._ -#### Signature +#### Signatures ```sql DOUBLE ST_Area (col0 POINT_2D) @@ -145,27 +145,26 @@ DOUBLE ST_Area (col0 BOX_2D) #### Description -Returns the area of a geometry. - Compute the area of a geometry. Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + The area is in the same units as the spatial reference system of the geometry. -The `POINT_2D` and `LINESTRING_2D` variants of this function always return `0.0` but are included for completeness. +The `POINT_2D` and `LINESTRING_2D` overloads of this function always return `0.0` but are included for completeness. #### Example ```sql select ST_Area('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); + -- 1.0 ``` - +---- ### ST_Area_Spheroid -_Returns the area of a geometry in meters, using an ellipsoidal model of the earth_ -#### Signature +#### Signatures ```sql DOUBLE ST_Area_Spheroid (col0 POLYGON_2D) @@ -180,11 +179,10 @@ The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/ Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. - +---- ### ST_AsGeoJSON -_Returns the geometry as a GeoJSON fragment_ #### Signature @@ -197,6 +195,7 @@ JSON ST_AsGeoJSON (col0 GEOMETRY) Returns the geometry as a GeoJSON fragment This does not return a complete GeoJSON document, only the geometry fragment. To construct a complete GeoJSON document or feature, look into using the DuckDB JSON extension in conjunction with this function. + This function supports geometries with Z values, but not M values. #### Example @@ -204,13 +203,23 @@ This does not return a complete GeoJSON document, only the geometry fragment. To select ST_AsGeoJSON('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); ---- {"type":"Polygon","coordinates":[[[0.0,0.0],[0.0,1.0],[1.0,1.0],[1.0,0.0],[0.0,0.0]]]} -``` +-- Convert a geometry into a full GeoJSON feature (requires the JSON extension to be loaded) +SELECT CAST({ + type: 'Feature', + geometry: ST_AsGeoJSON(ST_Point(1,2)), + properties: { + name: 'my_point' + } +} AS JSON); +---- +{"type":"Feature","geometry":{"type":"Point","coordinates":[1.0,2.0]},"properties":{"name":"my_point"}} +``` +---- ### ST_AsHEXWKB -_Returns the geometry as a HEXWKB string_ #### Signature @@ -226,15 +235,46 @@ Returns the geometry as a HEXWKB string ```sql SELECT ST_AsHexWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +---- +01030000000100000005000000000000000000000000000... +``` + +---- + +### ST_AsSVG + + +#### Signature + +```sql +VARCHAR ST_AsSVG (col0 GEOMETRY, col1 BOOLEAN, col2 INTEGER) ``` +#### Description + +Convert the geometry into a SVG fragment or path + +Convert the geometry into a SVG fragment or path + The SVG fragment is returned as a string. The fragment is a path element that can be used in an SVG document. + The second boolean argument specifies whether the path should be relative or absolute. + The third argument specifies the maximum number of digits to use for the coordinates. + Points are formatted as cx/cy using absolute coordinates or x/y using relative coordinates. + +#### Example + +```sql +SELECT ST_AsSVG('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY, false, 15); +---- +M 0 0 L 0 -1 1 -1 1 0 Z +``` + +---- ### ST_AsText -_Returns the geometry as a WKT string_ -#### Signature +#### Signatures ```sql VARCHAR ST_AsText (col0 POINT_2D) @@ -251,14 +291,15 @@ Returns the geometry as a WKT string #### Example ```sql -SELECT ST_AsText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +SELECT ST_AsText(ST_MakeEnvelope(0,0,1,1)); +---- +POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0)) ``` - +---- ### ST_AsWKB -_Returns the geometry as a WKB blob_ #### Signature @@ -273,14 +314,15 @@ Returns the geometry as a WKB blob #### Example ```sql -SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY)::BLOB; +---- +\x01\x03\x00\x00\x00\x01\x00\x00\x00\x05... ``` - +---- ### ST_Boundary -_Returns the "boundary" of a geometry_ #### Signature @@ -292,13 +334,12 @@ GEOMETRY ST_Boundary (col0 GEOMETRY) Returns the "boundary" of a geometry - +---- ### ST_Buffer -_Returns a buffer around the input geometry at the target distance_ -#### Signature +#### Signatures ```sql GEOMETRY ST_Buffer (col0 GEOMETRY, col1 DOUBLE) @@ -320,23 +361,23 @@ Returns a buffer around the input geometry at the target distance `cap_style` must be one of "CAP_ROUND", "CAP_FLAT", "CAP_SQUARE". This parameter is case-insensitive. -`mite_limit` only applies when `join_style` is "JOIN_MITRE". It is the ratio of the distance from the corner to the miter point to the corner radius. The default value is 1.0. +`mitre_limit` only applies when `join_style` is "JOIN_MITRE". It is the ratio of the distance from the corner to the mitre point to the corner radius. The default value is 1.0. This is a planar operation and will not take into account the curvature of the earth. - +---- ### ST_Centroid -_Calculates the centroid of a geometry_ -#### Signature +#### Signatures ```sql POINT_2D ST_Centroid (col0 POINT_2D) POINT_2D ST_Centroid (col0 LINESTRING_2D) POINT_2D ST_Centroid (col0 POLYGON_2D) POINT_2D ST_Centroid (col0 BOX_2D) +POINT_2D ST_Centroid (col0 BOX_2DF) GEOMETRY ST_Centroid (col0 GEOMETRY) ``` @@ -352,11 +393,10 @@ select st_centroid('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); POINT(0.5 0.5) ``` - +---- ### ST_Collect -_Collects geometries into a collection geometry_ #### Signature @@ -366,8 +406,6 @@ GEOMETRY ST_Collect (col0 GEOMETRY[]) #### Description -Collects geometries into a collection geometry - Collects a list of geometries into a collection geometry. - If all geometries are `POINT`'s, a `MULTIPOINT` is returned. - If all geometries are `LINESTRING`'s, a `MULTILINESTRING` is returned. @@ -410,13 +448,12 @@ SELECT ST_Collect(list(geom)) FROM points; MULTIPOINT (1 2, 3 4) ``` - +---- ### ST_CollectionExtract -_Extracts a sub-geometry from a collection geometry_ -#### Signature +#### Signatures ```sql GEOMETRY ST_CollectionExtract (col0 GEOMETRY) @@ -434,13 +471,12 @@ select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1); -- POINT(1 2) ``` - +---- ### ST_Contains -_Returns true if geom1 contains geom2._ -#### Signature +#### Signatures ```sql BOOLEAN ST_Contains (col0 POLYGON_2D, col1 POINT_2D) @@ -459,11 +495,10 @@ select st_contains('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry, 'POINT(0.5 0. true ``` - +---- ### ST_ContainsProperly -_Returns true if geom1 "properly contains" geom2_ #### Signature @@ -475,11 +510,10 @@ BOOLEAN ST_ContainsProperly (col0 GEOMETRY, col1 GEOMETRY) Returns true if geom1 "properly contains" geom2 - +---- ### ST_ConvexHull -_Returns the convex hull enclosing the geometry_ #### Signature @@ -491,11 +525,10 @@ GEOMETRY ST_ConvexHull (col0 GEOMETRY) Returns the convex hull enclosing the geometry - +---- ### ST_CoveredBy -_Returns true if geom1 is "covered" by geom2_ #### Signature @@ -507,11 +540,10 @@ BOOLEAN ST_CoveredBy (col0 GEOMETRY, col1 GEOMETRY) Returns true if geom1 is "covered" by geom2 - +---- ### ST_Covers -_Returns if geom1 "covers" geom2_ #### Signature @@ -523,11 +555,10 @@ BOOLEAN ST_Covers (col0 GEOMETRY, col1 GEOMETRY) Returns if geom1 "covers" geom2 - +---- ### ST_Crosses -_Returns true if geom1 "crosses" geom2_ #### Signature @@ -539,11 +570,10 @@ BOOLEAN ST_Crosses (col0 GEOMETRY, col1 GEOMETRY) Returns true if geom1 "crosses" geom2 - +---- ### ST_DWithin -_Returns if two geometries are within a target distance of each-other_ #### Signature @@ -555,11 +585,10 @@ BOOLEAN ST_DWithin (col0 GEOMETRY, col1 GEOMETRY, col2 DOUBLE) Returns if two geometries are within a target distance of each-other - +---- ### ST_DWithin_Spheroid -_Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface_ #### Signature @@ -571,11 +600,12 @@ DOUBLE ST_DWithin_Spheroid (col0 POINT_2D, col1 POINT_2D, col2 DOUBLE) Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface + The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (WGS84), with [latitude, longitude] axis order and the distance is returned in meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library to solve the [inverse geodesic problem](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid#Solution_of_the_direct_and_inverse_problems), calculating the distance between two points using an ellipsoidal model of the earth. This is a highly accurate method for calculating the distance between two arbitrary points taking the curvature of the earths surface into account, but is also the slowest. +---- ### ST_Difference -_Returns the "difference" between two geometries_ #### Signature @@ -587,11 +617,10 @@ GEOMETRY ST_Difference (col0 GEOMETRY, col1 GEOMETRY) Returns the "difference" between two geometries - +---- ### ST_Dimension -_Returns the dimension of a geometry._ #### Signature @@ -611,11 +640,10 @@ select st_dimension('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); 2 ``` - +---- ### ST_Disjoint -_Returns if two geometries are disjoint_ #### Signature @@ -627,13 +655,12 @@ BOOLEAN ST_Disjoint (col0 GEOMETRY, col1 GEOMETRY) Returns if two geometries are disjoint - +---- ### ST_Distance -_Returns the distance between two geometries._ -#### Signature +#### Signatures ```sql DOUBLE ST_Distance (col0 POINT_2D, col1 POINT_2D) @@ -654,13 +681,12 @@ select st_distance('POINT(0 0)'::geometry, 'POINT(1 1)'::geometry); 1.4142135623731 ``` - +---- ### ST_Distance_Sphere -_Returns the haversine distance between two geometries._ -#### Signature +#### Signatures ```sql DOUBLE ST_Distance_Sphere (col0 POINT_2D, col1 POINT_2D) @@ -675,11 +701,10 @@ Returns the haversine distance between two geometries. - Returns the distance in meters. - The input is expected to be in WGS84 (EPSG:4326) coordinates, using a [latitude, longitude] axis order. - +---- ### ST_Distance_Spheroid -_Returns the distance between two geometries in meters using a ellipsoidal model of the earths surface_ #### Signature @@ -707,11 +732,10 @@ st_point(52.3130, 4.7725) -- Roughly 5243km! ``` - +---- ### ST_Dump -_Dumps a geometry into a set of sub-geometries and their "path" in the original geometry._ #### Signature @@ -721,7 +745,7 @@ STRUCT(geom GEOMETRY, path INTEGER[])[] ST_Dump (col0 GEOMETRY) #### Description -Dumps a geometry into a set of sub-geometries and their "path" in the original geometry. +Dumps a geometry into a list of sub-geometries and their "path" in the original geometry. #### Example @@ -731,13 +755,12 @@ select st_dump('MULTIPOINT(1 2,3 4)'::geometry); [{'geom': 'POINT(1 2)', 'path': [0]}, {'geom': 'POINT(3 4)', 'path': [1]}] ``` - +---- ### ST_EndPoint -_Returns the end point of a line._ -#### Signature +#### Signatures ```sql GEOMETRY ST_EndPoint (col0 GEOMETRY) @@ -746,20 +769,19 @@ POINT_2D ST_EndPoint (col0 LINESTRING_2D) #### Description -Returns the end point of a line. +Returns the last point of a line. #### Example ```sql -select st_endpoint('LINESTRING(0 0, 1 1)'::geometry); +select ST_EndPoint('LINESTRING(0 0, 1 1)'::geometry); -- POINT(1 1) ``` - +---- ### ST_Envelope -_Returns the minimum bounding box for the input geometry as a polygon geometry._ #### Signature @@ -771,11 +793,10 @@ GEOMETRY ST_Envelope (col0 GEOMETRY) Returns the minimum bounding box for the input geometry as a polygon geometry. - +---- ### ST_Equals -_Compares two geometries for equality_ #### Signature @@ -787,13 +808,12 @@ BOOLEAN ST_Equals (col0 GEOMETRY, col1 GEOMETRY) Compares two geometries for equality - +---- ### ST_Extent -_Returns the minimal bounding box enclosing the input geometry_ -#### Signature +#### Signatures ```sql BOX_2D ST_Extent (col0 GEOMETRY) @@ -804,13 +824,12 @@ BOX_2D ST_Extent (col0 WKB_BLOB) Returns the minimal bounding box enclosing the input geometry - +---- ### ST_ExteriorRing -_Returns the exterior ring (shell) of a polygon geometry._ -#### Signature +#### Signatures ```sql LINESTRING_2D ST_ExteriorRing (col0 POLYGON_2D) @@ -821,13 +840,12 @@ GEOMETRY ST_ExteriorRing (col0 GEOMETRY) Returns the exterior ring (shell) of a polygon geometry. - +---- ### ST_FlipCoordinates -_Returns a new geometry with the coordinates of the input geometry "flipped" so that x = y and y = x._ -#### Signature +#### Signatures ```sql POINT_2D ST_FlipCoordinates (col0 POINT_2D) @@ -841,11 +859,10 @@ GEOMETRY ST_FlipCoordinates (col0 GEOMETRY) Returns a new geometry with the coordinates of the input geometry "flipped" so that x = y and y = x. - +---- ### ST_Force2D -_Forces the vertices of a geometry to have X and Y components_ #### Signature @@ -859,11 +876,10 @@ Forces the vertices of a geometry to have X and Y components This function will drop any Z and M values from the input geometry, if present. If the input geometry is already 2D, it will be returned as is. - +---- ### ST_Force3DM -_Forces the vertices of a geometry to have X, Y and M components_ #### Signature @@ -881,11 +897,10 @@ The following cases apply: - If the input geometry has both a Z component and a M component, the Z component will be removed. - Otherwise, if the input geometry has neither a Z or M component, the new M value will be added to the vertices of the input geometry. - +---- ### ST_Force3DZ -_Forces the vertices of a geometry to have X, Y and Z components_ #### Signature @@ -903,11 +918,10 @@ The following cases apply: - If the input geometry has both a Z component and a M component, the M component will be removed. - Otherwise, if the input geometry has neither a Z or M component, the new Z value will be added to the vertices of the input geometry. - +---- ### ST_Force4D -_Forces the vertices of a geometry to have X, Y, Z and M components_ #### Signature @@ -925,13 +939,12 @@ The following cases apply: - If the input geometry has both a Z component and a M component, the geometry will be returned as is. - Otherwise, if the input geometry has neither a Z or M component, the new Z and M values will be added to the vertices of the input geometry. - +---- ### ST_GeomFromGeoJSON -_Deserializes a GEOMETRY from a GeoJSON fragment._ -#### Signature +#### Signatures ```sql GEOMETRY ST_GeomFromGeoJSON (col0 VARCHAR) @@ -942,11 +955,18 @@ GEOMETRY ST_GeomFromGeoJSON (col0 JSON) Deserializes a GEOMETRY from a GeoJSON fragment. +#### Example +```sql +SELECT ST_GeomFromGeoJSON('{"type":"Point","coordinates":[1.0,2.0]}'); +---- +POINT (1 2) +``` + +---- ### ST_GeomFromHEXEWKB -_Deserialize a GEOMETRY from a HEXEWKB encoded string_ #### Signature @@ -958,11 +978,10 @@ GEOMETRY ST_GeomFromHEXEWKB (col0 VARCHAR) Deserialize a GEOMETRY from a HEXEWKB encoded string - +---- ### ST_GeomFromHEXWKB -_Creates a GEOMETRY from a HEXWKB string_ #### Signature @@ -974,13 +993,12 @@ GEOMETRY ST_GeomFromHEXWKB (col0 VARCHAR) Creates a GEOMETRY from a HEXWKB string - +---- ### ST_GeomFromText -_Deserializes a GEOMETRY from a WKT string, optionally ignoring invalid geometries_ -#### Signature +#### Signatures ```sql GEOMETRY ST_GeomFromText (col0 VARCHAR) @@ -991,13 +1009,12 @@ GEOMETRY ST_GeomFromText (col0 VARCHAR, col1 BOOLEAN) Deserializes a GEOMETRY from a WKT string, optionally ignoring invalid geometries - +---- ### ST_GeomFromWKB -_Deserializes a GEOMETRY from a WKB encoded blob_ -#### Signature +#### Signatures ```sql GEOMETRY ST_GeomFromWKB (col0 WKB_BLOB) @@ -1008,13 +1025,12 @@ GEOMETRY ST_GeomFromWKB (col0 BLOB) Deserializes a GEOMETRY from a WKB encoded blob - +---- ### ST_GeometryType -_Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type._ -#### Signature +#### Signatures ```sql ANY ST_GeometryType (col0 POINT_2D) @@ -1028,13 +1044,12 @@ ANY ST_GeometryType (col0 WKB_BLOB) Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type. - +---- ### ST_HasM -_Check if the input geometry has M values._ -#### Signature +#### Signatures ```sql BOOLEAN ST_HasM (col0 GEOMETRY) @@ -1069,13 +1084,12 @@ SELECT ST_HasM(ST_GeomFromText('POINT ZM(1 1 1 1)')); true ``` - +---- ### ST_HasZ -_Check if the input geometry has Z values._ -#### Signature +#### Signatures ```sql BOOLEAN ST_HasZ (col0 GEOMETRY) @@ -1110,27 +1124,32 @@ SELECT ST_HasZ(ST_GeomFromText('POINT ZM(1 1 1 1)')); true ``` - +---- ### ST_Hilbert -_Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box_ -#### Signature +#### Signatures ```sql UINTEGER ST_Hilbert (col0 DOUBLE, col1 DOUBLE, col2 BOX_2D) +UINTEGER ST_Hilbert (col0 GEOMETRY, col1 BOX_2D) +UINTEGER ST_Hilbert (col0 BOX_2D, col1 BOX_2D) +UINTEGER ST_Hilbert (col0 BOX_2DF, col1 BOX_2DF) +UINTEGER ST_Hilbert (col0 GEOMETRY) ``` #### Description -Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box - +Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box. +If a geometry is provided, the center of the approximate bounding box is used as the point to encode. +If no bounding box is provided, the hilbert curve index is mapped to the full range of a single-presicion float. +For the BOX_2D and BOX_2DF variants, the center of the box is used as the point to encode. +---- ### ST_Intersection -_Returns the "intersection" of geom1 and geom2_ #### Signature @@ -1142,13 +1161,12 @@ GEOMETRY ST_Intersection (col0 GEOMETRY, col1 GEOMETRY) Returns the "intersection" of geom1 and geom2 - +---- ### ST_Intersects -_Returns true if two geometries intersects_ -#### Signature +#### Signatures ```sql BOOLEAN ST_Intersects (col0 BOX_2D, col1 BOX_2D) @@ -1159,11 +1177,10 @@ BOOLEAN ST_Intersects (col0 GEOMETRY, col1 GEOMETRY) Returns true if two geometries intersects - +---- ### ST_Intersects_Extent -_Returns true if the extent of two geometries intersects_ #### Signature @@ -1175,11 +1192,10 @@ BOOLEAN ST_Intersects_Extent (col0 GEOMETRY, col1 GEOMETRY) Returns true if the extent of two geometries intersects - +---- ### ST_IsClosed -_Returns true if a geometry is "closed"_ #### Signature @@ -1191,13 +1207,12 @@ BOOLEAN ST_IsClosed (col0 GEOMETRY) Returns true if a geometry is "closed" - +---- ### ST_IsEmpty -_Returns true if the geometry is "empty"_ -#### Signature +#### Signatures ```sql BOOLEAN ST_IsEmpty (col0 LINESTRING_2D) @@ -1209,11 +1224,10 @@ BOOLEAN ST_IsEmpty (col0 GEOMETRY) Returns true if the geometry is "empty" - +---- ### ST_IsRing -_Returns true if the input line geometry is a ring (both ST_IsClosed and ST_IsSimple)._ #### Signature @@ -1225,11 +1239,10 @@ BOOLEAN ST_IsRing (col0 GEOMETRY) Returns true if the input line geometry is a ring (both ST_IsClosed and ST_IsSimple). - +---- ### ST_IsSimple -_Returns true if the input geometry is "simple"_ #### Signature @@ -1241,11 +1254,10 @@ BOOLEAN ST_IsSimple (col0 GEOMETRY) Returns true if the input geometry is "simple" - +---- ### ST_IsValid -_Returns true if the geometry is topologically "valid"_ #### Signature @@ -1257,13 +1269,12 @@ BOOLEAN ST_IsValid (col0 GEOMETRY) Returns true if the geometry is topologically "valid" - +---- ### ST_Length -_Returns the length of the input line geometry_ -#### Signature +#### Signatures ```sql DOUBLE ST_Length (col0 LINESTRING_2D) @@ -1274,13 +1285,12 @@ DOUBLE ST_Length (col0 GEOMETRY) Returns the length of the input line geometry - +---- ### ST_Length_Spheroid -_Returns the length of the input geometry in meters, using a ellipsoidal model of the earth_ -#### Signature +#### Signatures ```sql DOUBLE ST_Length_Spheroid (col0 LINESTRING_2D) @@ -1295,13 +1305,12 @@ The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/ Returns `0.0` for any geometry that is not a `LINESTRING`, `MULTILINESTRING` or `GEOMETRYCOLLECTION` containing line geometries. - +---- ### ST_LineMerge -_"Merges" the input line geometry, optionally taking direction into account._ -#### Signature +#### Signatures ```sql GEOMETRY ST_LineMerge (col0 GEOMETRY) @@ -1312,11 +1321,10 @@ GEOMETRY ST_LineMerge (col0 GEOMETRY, col1 BOOLEAN) "Merges" the input line geometry, optionally taking direction into account. - +---- ### ST_M -_Returns the M value of a point geometry, or NULL if not a point or empty_ #### Signature @@ -1328,11 +1336,10 @@ DOUBLE ST_M (col0 GEOMETRY) Returns the M value of a point geometry, or NULL if not a point or empty - +---- ### ST_MMax -_Returns the maximum M value of a geometry_ #### Signature @@ -1344,11 +1351,10 @@ DOUBLE ST_MMax (col0 GEOMETRY) Returns the maximum M value of a geometry - +---- ### ST_MMin -_Returns the minimum M value of a geometry_ #### Signature @@ -1360,11 +1366,10 @@ DOUBLE ST_MMin (col0 GEOMETRY) Returns the minimum M value of a geometry - +---- ### ST_MakeEnvelope -_Returns a minimal bounding box polygon enclosing the input geometry_ #### Signature @@ -1376,13 +1381,12 @@ GEOMETRY ST_MakeEnvelope (col0 DOUBLE, col1 DOUBLE, col2 DOUBLE, col3 DOUBLE) Returns a minimal bounding box polygon enclosing the input geometry - +---- ### ST_MakeLine -_Creates a LINESTRING geometry from a pair or list of input points_ -#### Signature +#### Signatures ```sql GEOMETRY ST_MakeLine (col0 GEOMETRY[]) @@ -1393,13 +1397,12 @@ GEOMETRY ST_MakeLine (col0 GEOMETRY, col1 GEOMETRY) Creates a LINESTRING geometry from a pair or list of input points - +---- ### ST_MakePolygon -_Creates a polygon from a shell geometry and an optional set of holes_ -#### Signature +#### Signatures ```sql GEOMETRY ST_MakePolygon (col0 GEOMETRY, col1 GEOMETRY[]) @@ -1410,11 +1413,10 @@ GEOMETRY ST_MakePolygon (col0 GEOMETRY) Creates a polygon from a shell geometry and an optional set of holes - +---- ### ST_MakeValid -_Attempts to make an invalid geometry valid without removing any vertices_ #### Signature @@ -1426,11 +1428,10 @@ GEOMETRY ST_MakeValid (col0 GEOMETRY) Attempts to make an invalid geometry valid without removing any vertices - +---- ### ST_NGeometries -_Returns the number of component geometries in a collection geometry_ #### Signature @@ -1440,16 +1441,15 @@ INTEGER ST_NGeometries (col0 GEOMETRY) #### Description -Returns the number of component geometries in a collection geometry -If the input geometry is not a collection, returns 1 if the geometry is not empty, otherwise 0 - +Returns the number of component geometries in a collection geometry. +If the input geometry is not a collection, this function returns 0 or 1 depending on if the geometry is empty or not. +---- ### ST_NInteriorRings -_Returns the number if interior rings of a polygon_ -#### Signature +#### Signatures ```sql INTEGER ST_NInteriorRings (col0 POLYGON_2D) @@ -1460,13 +1460,12 @@ INTEGER ST_NInteriorRings (col0 GEOMETRY) Returns the number if interior rings of a polygon - +---- ### ST_NPoints -_Returns the number of vertices within a geometry_ -#### Signature +#### Signatures ```sql UBIGINT ST_NPoints (col0 POINT_2D) @@ -1480,11 +1479,10 @@ UINTEGER ST_NPoints (col0 GEOMETRY) Returns the number of vertices within a geometry - +---- ### ST_Normalize -_Returns a "normalized" version of the input geometry._ #### Signature @@ -1496,11 +1494,10 @@ GEOMETRY ST_Normalize (col0 GEOMETRY) Returns a "normalized" version of the input geometry. - +---- ### ST_NumGeometries -_Returns the number of component geometries in a collection geometry_ #### Signature @@ -1510,16 +1507,15 @@ INTEGER ST_NumGeometries (col0 GEOMETRY) #### Description -Returns the number of component geometries in a collection geometry -If the input geometry is not a collection, returns 1 if the geometry is not empty, otherwise 0 - +Returns the number of component geometries in a collection geometry. +If the input geometry is not a collection, this function returns 0 or 1 depending on if the geometry is empty or not. +---- ### ST_NumInteriorRings -_Returns the number if interior rings of a polygon_ -#### Signature +#### Signatures ```sql INTEGER ST_NumInteriorRings (col0 POLYGON_2D) @@ -1530,13 +1526,12 @@ INTEGER ST_NumInteriorRings (col0 GEOMETRY) Returns the number if interior rings of a polygon - +---- ### ST_NumPoints -_Returns the number of vertices within a geometry_ -#### Signature +#### Signatures ```sql UBIGINT ST_NumPoints (col0 POINT_2D) @@ -1550,11 +1545,10 @@ UINTEGER ST_NumPoints (col0 GEOMETRY) Returns the number of vertices within a geometry - +---- ### ST_Overlaps -_Returns true if geom1 "overlaps" geom2_ #### Signature @@ -1566,13 +1560,12 @@ BOOLEAN ST_Overlaps (col0 GEOMETRY, col1 GEOMETRY) Returns true if geom1 "overlaps" geom2 - +---- ### ST_Perimeter -_Returns the length of the perimeter of the geometry_ -#### Signature +#### Signatures ```sql DOUBLE ST_Perimeter (col0 BOX_2D) @@ -1584,13 +1577,12 @@ DOUBLE ST_Perimeter (col0 GEOMETRY) Returns the length of the perimeter of the geometry - +---- ### ST_Perimeter_Spheroid -_Returns the length of the perimeter in meters using an ellipsoidal model of the earths surface_ -#### Signature +#### Signatures ```sql DOUBLE ST_Perimeter_Spheroid (col0 POLYGON_2D) @@ -1605,11 +1597,10 @@ The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/ Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. - +---- ### ST_Point -_Creates a GEOMETRY point_ #### Signature @@ -1621,11 +1612,10 @@ GEOMETRY ST_Point (col0 DOUBLE, col1 DOUBLE) Creates a GEOMETRY point - +---- ### ST_Point2D -_Creates a POINT_2D_ #### Signature @@ -1637,11 +1627,10 @@ POINT_2D ST_Point2D (col0 DOUBLE, col1 DOUBLE) Creates a POINT_2D - +---- ### ST_Point3D -_Creates a POINT_3D_ #### Signature @@ -1653,11 +1642,10 @@ POINT_3D ST_Point3D (col0 DOUBLE, col1 DOUBLE, col2 DOUBLE) Creates a POINT_3D - +---- ### ST_Point4D -_Creates a POINT_4D_ #### Signature @@ -1669,13 +1657,12 @@ POINT_4D ST_Point4D (col0 DOUBLE, col1 DOUBLE, col2 DOUBLE, col3 DOUBLE) Creates a POINT_4D - +---- ### ST_PointN -_Returns the n'th vertex from the input geometry as a point geometry_ -#### Signature +#### Signatures ```sql GEOMETRY ST_PointN (col0 GEOMETRY, col1 INTEGER) @@ -1686,11 +1673,10 @@ POINT_2D ST_PointN (col0 LINESTRING_2D, col1 INTEGER) Returns the n'th vertex from the input geometry as a point geometry - +---- ### ST_PointOnSurface -_Returns a point that is guaranteed to be on the surface of the input geometry. Sometimes a useful alternative to ST_Centroid._ #### Signature @@ -1702,11 +1688,10 @@ GEOMETRY ST_PointOnSurface (col0 GEOMETRY) Returns a point that is guaranteed to be on the surface of the input geometry. Sometimes a useful alternative to ST_Centroid. - +---- ### ST_Points -_Collects all the vertices in the geometry into a multipoint_ #### Signature @@ -1730,13 +1715,12 @@ select st_points('MULTIPOLYGON Z EMPTY'::geometry); MULTIPOINT Z EMPTY ``` - +---- ### ST_QuadKey -_Computes a quadkey from a given lon/lat point._ -#### Signature +#### Signatures ```sql VARCHAR ST_QuadKey (col0 DOUBLE, col1 DOUBLE, col2 INTEGER) @@ -1745,8 +1729,6 @@ VARCHAR ST_QuadKey (col0 GEOMETRY, col1 INTEGER) #### Description -Computes a quadkey from a given lon/lat point. - Compute the [quadkey](https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) for a given lon/lat point at a given level. Note that the the parameter order is __longitude__, __latitude__. @@ -1754,7 +1736,7 @@ Note that the the parameter order is __longitude__, __latitude__. The input coordinates will be clamped to the lon/lat bounds of the earth (longitude between -180 and 180, latitude between -85.05112878 and 85.05112878). -Throws for any geometry that is not a `POINT` +The geometry overload throws an error if the input geometry is not a `POINT` #### Example @@ -1764,11 +1746,10 @@ SELECT ST_QuadKey(st_point(11.08, 49.45), 10); 1333203202 ``` - +---- ### ST_ReducePrecision -_Returns the geometry with all vertices reduced to the target precision_ #### Signature @@ -1780,13 +1761,12 @@ GEOMETRY ST_ReducePrecision (col0 GEOMETRY, col1 DOUBLE) Returns the geometry with all vertices reduced to the target precision - +---- ### ST_RemoveRepeatedPoints -_Returns a new geometry with repeated points removed, optionally within a target distance of eachother._ -#### Signature +#### Signatures ```sql LINESTRING_2D ST_RemoveRepeatedPoints (col0 LINESTRING_2D) @@ -1799,11 +1779,10 @@ GEOMETRY ST_RemoveRepeatedPoints (col0 GEOMETRY, col1 DOUBLE) Returns a new geometry with repeated points removed, optionally within a target distance of eachother. - +---- ### ST_Reverse -_Returns a new version of the input geometry with the order of its vertices reversed_ #### Signature @@ -1815,11 +1794,10 @@ GEOMETRY ST_Reverse (col0 GEOMETRY) Returns a new version of the input geometry with the order of its vertices reversed - +---- ### ST_ShortestLine -_Returns the line between the two closest points between geom1 and geom2_ #### Signature @@ -1831,11 +1809,10 @@ GEOMETRY ST_ShortestLine (col0 GEOMETRY, col1 GEOMETRY) Returns the line between the two closest points between geom1 and geom2 - +---- ### ST_Simplify -_Simplifies the input geometry by collapsing edges smaller than 'distance'_ #### Signature @@ -1847,11 +1824,10 @@ GEOMETRY ST_Simplify (col0 GEOMETRY, col1 DOUBLE) Simplifies the input geometry by collapsing edges smaller than 'distance' - +---- ### ST_SimplifyPreserveTopology -_Returns a simplified geometry but avoids creating invalid topologies_ #### Signature @@ -1863,13 +1839,12 @@ GEOMETRY ST_SimplifyPreserveTopology (col0 GEOMETRY, col1 DOUBLE) Returns a simplified geometry but avoids creating invalid topologies - +---- ### ST_StartPoint -_Returns the first point of a line geometry_ -#### Signature +#### Signatures ```sql GEOMETRY ST_StartPoint (col0 GEOMETRY) @@ -1880,11 +1855,17 @@ POINT_2D ST_StartPoint (col0 LINESTRING_2D) Returns the first point of a line geometry +#### Example + +```sql +select ST_StartPoint('LINESTRING(0 0, 1 1)'::geometry); +-- POINT(0 0) +``` +---- ### ST_Touches -_Returns true if geom1 "touches" geom2_ #### Signature @@ -1896,13 +1877,12 @@ BOOLEAN ST_Touches (col0 GEOMETRY, col1 GEOMETRY) Returns true if geom1 "touches" geom2 - +---- ### ST_Transform -_Transforms a geometry between two coordinate systems_ -#### Signature +#### Signatures ```sql BOX_2D ST_Transform (col0 BOX_2D, col1 VARCHAR, col2 VARCHAR) @@ -1919,7 +1899,7 @@ Transforms a geometry between two coordinate systems The source and target coordinate systems can be specified using any format that the [PROJ library](https://proj.org) supports. -The optional `always_xy` parameter can be used to force the input and output geometries to be interpreted as having a [northing, easting] coordinate axis order regardless of what the source and target coordinate system definition says. This is particularly useful when transforming to/from the [WGS84/EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (what most people think of when they hear "longitude"/"latitude" or "GPS coordinates"), which is defined as having a [latitude, longitude] axis order even though [longitude, latitude] is commonly used in practice (e.g. in [GeoJSON](https://tools.ietf.org/html/rfc7946)). More details available in the [PROJ documentation](https://proj.org/en/9.3/faq.html#why-is-the-axis-ordering-in-proj-not-consistent). +The third optional `always_xy` parameter can be used to force the input and output geometries to be interpreted as having a [easting, northing] coordinate axis order regardless of what the source and target coordinate system definition says. This is particularly useful when transforming to/from the [WGS84/EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (what most people think of when they hear "longitude"/"latitude" or "GPS coordinates"), which is defined as having a [latitude, longitude] axis order even though [longitude, latitude] is commonly used in practice (e.g. in [GeoJSON](https://tools.ietf.org/html/rfc7946)). More details available in the [PROJ documentation](https://proj.org/en/9.3/faq.html#why-is-the-axis-ordering-in-proj-not-consistent). DuckDB spatial vendors its own static copy of the PROJ database of coordinate systems, so if you have your own installation of PROJ on your system the available coordinate systems may differ to what's available in other GIS software. @@ -1929,7 +1909,7 @@ DuckDB spatial vendors its own static copy of the PROJ database of coordinate sy -- Transform a geometry from EPSG:4326 to EPSG:3857 (WGS84 to WebMercator) -- Note that since WGS84 is defined as having a [latitude, longitude] axis order -- we follow the standard and provide the input geometry using that axis order, --- but the output will be [northing, easting] because that is what's defined by +-- but the output will be [easting, northing] because that is what's defined by -- WebMercator. SELECT ST_AsText( @@ -1946,7 +1926,7 @@ POINT (544615.0239773799 6867874.103539125) -- which uses WGS84 but with [longitude, latitude] axis order. We can use the -- `always_xy` parameter to force the input geometry to be interpreted as having -- a [northing, easting] axis order instead, even though the source coordinate --- system definition says otherwise. +-- reference system definition (WGS84) says otherwise. SELECT ST_AsText( ST_Transform( @@ -1961,11 +1941,10 @@ SELECT ST_AsText( POINT (544615.0239773799 6867874.103539125) ``` - +---- ### ST_Union -_Returns the union of two geometries._ #### Signature @@ -1990,13 +1969,12 @@ SELECT ST_AsText( MULTIPOINT (1 2, 3 4) ``` - +---- ### ST_Within -_Returns true if geom1 is "within" geom2_ -#### Signature +#### Signatures ```sql BOOLEAN ST_Within (col0 POINT_2D, col1 POLYGON_2D) @@ -2007,13 +1985,12 @@ BOOLEAN ST_Within (col0 GEOMETRY, col1 GEOMETRY) Returns true if geom1 is "within" geom2 - +---- ### ST_X -_Returns the X value of a point geometry, or NULL if not a point or empty_ -#### Signature +#### Signatures ```sql DOUBLE ST_X (col0 POINT_2D) @@ -2024,16 +2001,16 @@ DOUBLE ST_X (col0 GEOMETRY) Returns the X value of a point geometry, or NULL if not a point or empty - +---- ### ST_XMax -_Returns the maximum X value of a geometry_ -#### Signature +#### Signatures ```sql DOUBLE ST_XMax (col0 BOX_2D) +FLOAT ST_XMax (col0 BOX_2DF) DOUBLE ST_XMax (col0 POINT_2D) DOUBLE ST_XMax (col0 LINESTRING_2D) DOUBLE ST_XMax (col0 POLYGON_2D) @@ -2044,16 +2021,16 @@ DOUBLE ST_XMax (col0 GEOMETRY) Returns the maximum X value of a geometry - +---- ### ST_XMin -_Returns the minimum X value of a geometry_ -#### Signature +#### Signatures ```sql DOUBLE ST_XMin (col0 BOX_2D) +FLOAT ST_XMin (col0 BOX_2DF) DOUBLE ST_XMin (col0 POINT_2D) DOUBLE ST_XMin (col0 LINESTRING_2D) DOUBLE ST_XMin (col0 POLYGON_2D) @@ -2064,13 +2041,12 @@ DOUBLE ST_XMin (col0 GEOMETRY) Returns the minimum X value of a geometry - +---- ### ST_Y -_Returns the Y value of a point geometry, or NULL if not a point or empty_ -#### Signature +#### Signatures ```sql DOUBLE ST_Y (col0 POINT_2D) @@ -2081,16 +2057,16 @@ DOUBLE ST_Y (col0 GEOMETRY) Returns the Y value of a point geometry, or NULL if not a point or empty - +---- ### ST_YMax -_Returns the maximum Y value of a geometry_ -#### Signature +#### Signatures ```sql DOUBLE ST_YMax (col0 BOX_2D) +FLOAT ST_YMax (col0 BOX_2DF) DOUBLE ST_YMax (col0 POINT_2D) DOUBLE ST_YMax (col0 LINESTRING_2D) DOUBLE ST_YMax (col0 POLYGON_2D) @@ -2101,16 +2077,16 @@ DOUBLE ST_YMax (col0 GEOMETRY) Returns the maximum Y value of a geometry - +---- ### ST_YMin -_Returns the minimum Y value of a geometry_ -#### Signature +#### Signatures ```sql DOUBLE ST_YMin (col0 BOX_2D) +FLOAT ST_YMin (col0 BOX_2DF) DOUBLE ST_YMin (col0 POINT_2D) DOUBLE ST_YMin (col0 LINESTRING_2D) DOUBLE ST_YMin (col0 POLYGON_2D) @@ -2121,11 +2097,10 @@ DOUBLE ST_YMin (col0 GEOMETRY) Returns the minimum Y value of a geometry - +---- ### ST_Z -_Returns the Z value of a point geometry, or NULL if not a point or empty_ #### Signature @@ -2137,13 +2112,12 @@ DOUBLE ST_Z (col0 GEOMETRY) Returns the Z value of a point geometry, or NULL if not a point or empty - +---- ### ST_ZMFlag -_Returns a flag indicating the presence of Z and M values in the input geometry._ -#### Signature +#### Signatures ```sql UTINYINT ST_ZMFlag (col0 GEOMETRY) @@ -2182,11 +2156,10 @@ SELECT ST_ZMFlag(ST_GeomFromText('POINT ZM(1 1 1 1)')); 3 ``` - +---- ### ST_ZMax -_Returns the maximum Z value of a geometry_ #### Signature @@ -2198,11 +2171,10 @@ DOUBLE ST_ZMax (col0 GEOMETRY) Returns the maximum Z value of a geometry - +---- ### ST_ZMin -_Returns the minimum Z value of a geometry_ #### Signature @@ -2214,13 +2186,12 @@ DOUBLE ST_ZMin (col0 GEOMETRY) Returns the minimum Z value of a geometry - +---- ## Aggregate Functions ### ST_Envelope_Agg -_Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries_ #### Signature @@ -2232,11 +2203,10 @@ GEOMETRY ST_Envelope_Agg (col0 GEOMETRY) Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries - +---- ### ST_Intersection_Agg -_Computes the intersection of a set of geometries_ #### Signature @@ -2248,11 +2218,10 @@ GEOMETRY ST_Intersection_Agg (col0 GEOMETRY) Computes the intersection of a set of geometries - +---- ### ST_Union_Agg -_Computes the union of a set of input geometries_ #### Signature @@ -2264,14 +2233,12 @@ GEOMETRY ST_Union_Agg (col0 GEOMETRY) Computes the union of a set of input geometries - +---- ## Table Functions ### ST_Drivers -_Returns the list of supported GDAL drivers and file formats_ - #### Signature ```sql @@ -2290,12 +2257,10 @@ Note that far from all of these drivers have been tested properly, and some may SELECT * FROM ST_Drivers(); ``` - +---- ### ST_Read -_Read and import a variety of geospatial file formats using the GDAL library._ - #### Signature ```sql @@ -2308,7 +2273,7 @@ Read and import a variety of geospatial file formats using the GDAL library. The `ST_Read` table function is based on the [GDAL](https://gdal.org/index.html) translator library and enables reading spatial data from a variety of geospatial vector file formats as if they were DuckDB tables. -> See [ST_Drivers](##st_drivers) for a list of supported file formats and drivers. +> See [ST_Drivers](#st_drivers) for a list of supported file formats and drivers. Except for the `path` parameter, all parameters are optional. @@ -2352,12 +2317,10 @@ SELECT * FROM ST_Read('some/file/path/filename.shp'); CREATE TABLE my_geojson_table AS SELECT * FROM ST_Read('some/file/path/filename.json'); ``` - +---- ### ST_ReadOSM -_The ST_ReadOsm() table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.`_ - #### Signature ```sql @@ -2366,7 +2329,7 @@ ST_ReadOSM (col0 VARCHAR) #### Description -The ST_ReadOsm() table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` +The `ST_ReadOsm()` table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` This function uses multithreading and zero-copy protobuf parsing which makes it a lot faster than using the `ST_Read()` OSM driver, however it only outputs the raw OSM data (Nodes, Ways, Relations), without constructing any geometries. For simple node entities (like PoI's) you can trivially construct POINT geometries, but it is also possible to construct LINESTRING and POLYGON geometries by manually joining refs and nodes together in SQL, although with available memory usually being a limiting factor. The `ST_ReadOSM()` function also provides a "replacement scan" to enable reading from a file directly as if it were a table. This is just syntax sugar for calling `ST_ReadOSM()` though. Example: @@ -2395,12 +2358,10 @@ LIMIT 5; └──────────────────────┴────────┴──────────────────────┴─────────┴────────────────────┴────────────┴───────────┴────────────────────────┘ ``` - +---- ### ST_Read_Meta -_Read and the metadata from a variety of geospatial file formats using the GDAL library._ - #### Signature ```sql @@ -2425,5 +2386,5 @@ SELECT FROM st_read_meta('../../tmp/data/amsterdam_roads.fgb'); ``` - +---- diff --git a/generate_function_reference.py b/generate_function_reference.py index 3f6c87f1..a349b77a 100644 --- a/generate_function_reference.py +++ b/generate_function_reference.py @@ -41,7 +41,7 @@ def write_table_of_contents(f, functions): for function in functions: # Summary is the first line of the description summary = function['description'].split('\n')[0] - f.write(f"| [{function['name']}](#{to_kebab_case(function['name'])}) | {summary} |\n") + f.write(f"| [`{function['name']}`](#{to_kebab_case(function['name'])}) | {summary} |\n") def to_kebab_case(name): @@ -76,11 +76,11 @@ def main(): f.write(f"## {func_set[0]}\n\n") set_name = func_set[0] for function in func_set[1]: - f.write(f"### {function['name']}\n\n") - summary = function['description'].split('\n')[0] - f.write(f"_{summary}_\n\n") - - f.write("#### Signature\n\n") + f.write(f"### {function['name']}\n\n\n") + #summary = function['description'].split('\n')[0] + #f.write(f"_{summary}_\n\n") + + f.write("#### Signature\n\n") if len(function['signatures']) == 1 else f.write("#### Signatures\n\n") f.write("```sql\n") for signature in function['signatures']: param_list = ", ".join([f"{param['name']} {param['type']}" for param in signature['params']]) @@ -101,14 +101,15 @@ def main(): f.write("\n```\n\n") else: print(f"No example for {function['name']}") - f.write("\n\n") + #f.write("\n\n") + f.write("----\n\n") # Write table functions f.write("## Table Functions\n\n") for function in table_functions: f.write(f"### {function['name']}\n\n") - summary = function['description'].split('\n')[0] - f.write(f"_{summary}_\n\n") + #summary = function['description'].split('\n')[0] + #f.write(f"_{summary}_\n\n") f.write("#### Signature\n\n") f.write("```sql\n") @@ -131,7 +132,7 @@ def main(): f.write("\n```\n\n") else: print(f"No example for {function['name']}") - f.write("\n\n") + f.write("----\n\n") if __name__ == "__main__": main() diff --git a/spatial/src/spatial/core/functions/scalar/st_area.cpp b/spatial/src/spatial/core/functions/scalar/st_area.cpp index f7f4519a..440cdbe4 100644 --- a/spatial/src/spatial/core/functions/scalar/st_area.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_area.cpp @@ -179,17 +179,17 @@ static void GeometryAreaFunction(DataChunk &args, ExpressionState &state, Vector //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( - Returns the area of a geometry. - Compute the area of a geometry. Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + The area is in the same units as the spatial reference system of the geometry. - The `POINT_2D` and `LINESTRING_2D` variants of this function always return `0.0` but are included for completeness. + The `POINT_2D` and `LINESTRING_2D` overloads of this function always return `0.0` but are included for completeness. )"; static constexpr const char *DOC_EXAMPLE = R"( select ST_Area('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); + -- 1.0 )"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "property"}}; diff --git a/spatial/src/spatial/core/functions/scalar/st_asgeojson.cpp b/spatial/src/spatial/core/functions/scalar/st_asgeojson.cpp index c4479e30..64489ccd 100644 --- a/spatial/src/spatial/core/functions/scalar/st_asgeojson.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_asgeojson.cpp @@ -561,12 +561,24 @@ static constexpr const char *AS_DOC_DESCRIPTION = R"( Returns the geometry as a GeoJSON fragment This does not return a complete GeoJSON document, only the geometry fragment. To construct a complete GeoJSON document or feature, look into using the DuckDB JSON extension in conjunction with this function. + This function supports geometries with Z values, but not M values. )"; static constexpr const char *AS_DOC_EXAMPLE = R"( select ST_AsGeoJSON('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); ---- {"type":"Polygon","coordinates":[[[0.0,0.0],[0.0,1.0],[1.0,1.0],[1.0,0.0],[0.0,0.0]]]} + +-- Convert a geometry into a full GeoJSON feature (requires the JSON extension to be loaded) +SELECT CAST({ + type: 'Feature', + geometry: ST_AsGeoJSON(ST_Point(1,2)), + properties: { + name: 'my_point' + } +} AS JSON); +---- +{"type":"Feature","geometry":{"type":"Point","coordinates":[1.0,2.0]},"properties":{"name":"my_point"}} )"; // FromGeoJSON @@ -575,7 +587,9 @@ static constexpr const char *FROM_DOC_DESCRIPTION = R"( )"; static constexpr const char *FROM_DOC_EXAMPLE = R"( - +SELECT ST_GeomFromGeoJSON('{"type":"Point","coordinates":[1.0,2.0]}'); +---- +POINT (1 2) )"; //------------------------------------------------------------------------------ diff --git a/spatial/src/spatial/core/functions/scalar/st_ashexwkb.cpp b/spatial/src/spatial/core/functions/scalar/st_ashexwkb.cpp index f29626ac..c6d5c50f 100644 --- a/spatial/src/spatial/core/functions/scalar/st_ashexwkb.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_ashexwkb.cpp @@ -53,6 +53,8 @@ static constexpr const char *DOC_DESCRIPTION = R"( static constexpr const char *DOC_EXAMPLE = R"( SELECT ST_AsHexWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +---- +01030000000100000005000000000000000000000000000... )"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}}; diff --git a/spatial/src/spatial/core/functions/scalar/st_assvg.cpp b/spatial/src/spatial/core/functions/scalar/st_assvg.cpp index 50cec461..d27ac099 100644 --- a/spatial/src/spatial/core/functions/scalar/st_assvg.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_assvg.cpp @@ -159,9 +159,9 @@ static constexpr const char *DOC_DESCRIPTION = R"( )"; static constexpr const char *DOC_EXAMPLE = R"( - select ST_AsSVG('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry, false, 15); - ---- - M 0 0 L 0 -1 1 -1 1 0 Z +SELECT ST_AsSVG('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY, false, 15); +---- +M 0 0 L 0 -1 1 -1 1 0 Z )"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}}; diff --git a/spatial/src/spatial/core/functions/scalar/st_astext.cpp b/spatial/src/spatial/core/functions/scalar/st_astext.cpp index 27d5be7b..5012993d 100644 --- a/spatial/src/spatial/core/functions/scalar/st_astext.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_astext.cpp @@ -74,7 +74,9 @@ static constexpr const char *DOC_DESCRIPTION = R"( )"; static constexpr const char *DOC_EXAMPLE = R"( -SELECT ST_AsText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +SELECT ST_AsText(ST_MakeEnvelope(0,0,1,1)); +---- +POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0)) )"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}}; diff --git a/spatial/src/spatial/core/functions/scalar/st_aswkb.cpp b/spatial/src/spatial/core/functions/scalar/st_aswkb.cpp index a06b5509..9adec5e7 100644 --- a/spatial/src/spatial/core/functions/scalar/st_aswkb.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_aswkb.cpp @@ -31,7 +31,9 @@ static constexpr const char *DOC_DESCRIPTION = R"( )"; static constexpr const char *DOC_EXAMPLE = R"( -SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +SELECT ST_AsWKB('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::GEOMETRY)::BLOB; +---- +\x01\x03\x00\x00\x00\x01\x00\x00\x00\x05... )"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "conversion"}}; diff --git a/spatial/src/spatial/core/functions/scalar/st_collect.cpp b/spatial/src/spatial/core/functions/scalar/st_collect.cpp index 1b1e0deb..e60c737c 100644 --- a/spatial/src/spatial/core/functions/scalar/st_collect.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_collect.cpp @@ -82,7 +82,6 @@ static void CollectFunction(DataChunk &args, ExpressionState &state, Vector &res //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( -Collects geometries into a collection geometry Collects a list of geometries into a collection geometry. - If all geometries are `POINT`'s, a `MULTIPOINT` is returned. diff --git a/spatial/src/spatial/core/functions/scalar/st_dump.cpp b/spatial/src/spatial/core/functions/scalar/st_dump.cpp index f59c2ca9..a199c7c5 100644 --- a/spatial/src/spatial/core/functions/scalar/st_dump.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_dump.cpp @@ -117,7 +117,7 @@ static void DumpFunction(DataChunk &args, ExpressionState &state, Vector &result // Documentation //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( -Dumps a geometry into a set of sub-geometries and their "path" in the original geometry. +Dumps a geometry into a list of sub-geometries and their "path" in the original geometry. )"; static constexpr const char *DOC_EXAMPLE = R"( diff --git a/spatial/src/spatial/core/functions/scalar/st_endpoint.cpp b/spatial/src/spatial/core/functions/scalar/st_endpoint.cpp index ce218afb..cf6f3f43 100644 --- a/spatial/src/spatial/core/functions/scalar/st_endpoint.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_endpoint.cpp @@ -87,11 +87,11 @@ static void GeometryEndPointFunction(DataChunk &args, ExpressionState &state, Ve // Documentation //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( -Returns the end point of a line. +Returns the last point of a line. )"; static constexpr const char *DOC_EXAMPLE = R"( -select st_endpoint('LINESTRING(0 0, 1 1)'::geometry); +select ST_EndPoint('LINESTRING(0 0, 1 1)'::geometry); -- POINT(1 1) )"; diff --git a/spatial/src/spatial/core/functions/scalar/st_hilbert.cpp b/spatial/src/spatial/core/functions/scalar/st_hilbert.cpp index 27c80a00..1a4adff6 100644 --- a/spatial/src/spatial/core/functions/scalar/st_hilbert.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_hilbert.cpp @@ -226,10 +226,10 @@ static void HilbertEncodeBoxFunction(DataChunk &args, ExpressionState &state, Ve //------------------------------------------------------------------------------ static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "property"}}; static constexpr const char *DOC_DESCRIPTION = R"( - Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box. - - Only POINT geometries are supported for the GEOMETRY variant. - For the BOX_2D and BOX_2DF variants, the center of the box is used as the point to encode. +Encodes the X and Y values as the hilbert curve index for a curve covering the given bounding box. +If a geometry is provided, the center of the approximate bounding box is used as the point to encode. +If no bounding box is provided, the hilbert curve index is mapped to the full range of a single-presicion float. +For the BOX_2D and BOX_2DF variants, the center of the box is used as the point to encode. )"; static constexpr const char *DOC_EXAMPLE = R"( diff --git a/spatial/src/spatial/core/functions/scalar/st_ngeometries.cpp b/spatial/src/spatial/core/functions/scalar/st_ngeometries.cpp index c5cfe420..6aac4e3d 100644 --- a/spatial/src/spatial/core/functions/scalar/st_ngeometries.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_ngeometries.cpp @@ -41,8 +41,8 @@ static void GeometryNGeometriesFunction(DataChunk &args, ExpressionState &state, // Documentation //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( - Returns the number of component geometries in a collection geometry - If the input geometry is not a collection, returns 1 if the geometry is not empty, otherwise 0 + Returns the number of component geometries in a collection geometry. + If the input geometry is not a collection, this function returns 0 or 1 depending on if the geometry is empty or not. )"; static constexpr const char *DOC_EXAMPLE = R"( diff --git a/spatial/src/spatial/core/functions/scalar/st_quadkey.cpp b/spatial/src/spatial/core/functions/scalar/st_quadkey.cpp index c8c25032..0add5283 100644 --- a/spatial/src/spatial/core/functions/scalar/st_quadkey.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_quadkey.cpp @@ -90,7 +90,6 @@ static void GeometryQuadKeyFunction(DataChunk &args, ExpressionState &state, Vec // Documentation //------------------------------------------------------------------------------ static constexpr const char *DOC_DESCRIPTION = R"( -Computes a quadkey from a given lon/lat point. Compute the [quadkey](https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) for a given lon/lat point at a given level. Note that the the parameter order is __longitude__, __latitude__. @@ -99,7 +98,7 @@ Note that the the parameter order is __longitude__, __latitude__. The input coordinates will be clamped to the lon/lat bounds of the earth (longitude between -180 and 180, latitude between -85.05112878 and 85.05112878). -Throws for any geometry that is not a `POINT` +The geometry overload throws an error if the input geometry is not a `POINT` )"; static constexpr const char *DOC_EXAMPLE = R"( diff --git a/spatial/src/spatial/core/functions/scalar/st_startpoint.cpp b/spatial/src/spatial/core/functions/scalar/st_startpoint.cpp index bbe1a545..91cd5156 100644 --- a/spatial/src/spatial/core/functions/scalar/st_startpoint.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_startpoint.cpp @@ -87,7 +87,10 @@ static constexpr const char *DOC_DESCRIPTION = R"( Returns the first point of a line geometry )"; -static constexpr const char *DOC_EXAMPLE = R"()"; +static constexpr const char *DOC_EXAMPLE = R"( +select ST_StartPoint('LINESTRING(0 0, 1 1)'::geometry); +-- POINT(0 0) +)"; static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}, {"category", "construction"}}; //------------------------------------------------------------------------------ diff --git a/spatial/src/spatial/core/io/osm/st_read_osm.cpp b/spatial/src/spatial/core/io/osm/st_read_osm.cpp index 0a23a178..465cb872 100644 --- a/spatial/src/spatial/core/io/osm/st_read_osm.cpp +++ b/spatial/src/spatial/core/io/osm/st_read_osm.cpp @@ -864,7 +864,7 @@ static unique_ptr ReadOsmPBFReplacementScan(ClientContext &context, Re static constexpr DocTag DOC_TAGS[] = {{"ext", "spatial"}}; static constexpr const char *DOC_DESCRIPTION = R"( - The ST_ReadOsm() table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` + The `ST_ReadOsm()` table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` This function uses multithreading and zero-copy protobuf parsing which makes it a lot faster than using the `ST_Read()` OSM driver, however it only outputs the raw OSM data (Nodes, Ways, Relations), without constructing any geometries. For simple node entities (like PoI's) you can trivially construct POINT geometries, but it is also possible to construct LINESTRING and POLYGON geometries by manually joining refs and nodes together in SQL, although with available memory usually being a limiting factor. The `ST_ReadOSM()` function also provides a "replacement scan" to enable reading from a file directly as if it were a table. This is just syntax sugar for calling `ST_ReadOSM()` though. Example: diff --git a/spatial/src/spatial/gdal/functions/st_read.cpp b/spatial/src/spatial/gdal/functions/st_read.cpp index dce7df55..177548c3 100644 --- a/spatial/src/spatial/gdal/functions/st_read.cpp +++ b/spatial/src/spatial/gdal/functions/st_read.cpp @@ -621,7 +621,7 @@ static constexpr const char *DOC_DESCRIPTION = R"( The `ST_Read` table function is based on the [GDAL](https://gdal.org/index.html) translator library and enables reading spatial data from a variety of geospatial vector file formats as if they were DuckDB tables. - > See [ST_Drivers](##st_drivers) for a list of supported file formats and drivers. + > See [ST_Drivers](#st_drivers) for a list of supported file formats and drivers. Except for the `path` parameter, all parameters are optional. diff --git a/spatial/src/spatial/geographiclib/functions/st_distance_within_spheroid.cpp b/spatial/src/spatial/geographiclib/functions/st_distance_within_spheroid.cpp index 3e1a45a3..210685fd 100644 --- a/spatial/src/spatial/geographiclib/functions/st_distance_within_spheroid.cpp +++ b/spatial/src/spatial/geographiclib/functions/st_distance_within_spheroid.cpp @@ -40,6 +40,8 @@ static void GeodesicPoint2DFunction(DataChunk &args, ExpressionState &state, Vec static constexpr const char *DOC_DESCRIPTION = R"( Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface + + The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (WGS84), with [latitude, longitude] axis order and the distance is returned in meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library to solve the [inverse geodesic problem](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid#Solution_of_the_direct_and_inverse_problems), calculating the distance between two points using an ellipsoidal model of the earth. This is a highly accurate method for calculating the distance between two arbitrary points taking the curvature of the earths surface into account, but is also the slowest. )"; static constexpr const char *DOC_EXAMPLE = R"( diff --git a/spatial/src/spatial/geos/functions/scalar/st_buffer.cpp b/spatial/src/spatial/geos/functions/scalar/st_buffer.cpp index 18aafdb4..e45f6646 100644 --- a/spatial/src/spatial/geos/functions/scalar/st_buffer.cpp +++ b/spatial/src/spatial/geos/functions/scalar/st_buffer.cpp @@ -101,7 +101,7 @@ static constexpr const char *DOC_DESCRIPTION = R"( `cap_style` must be one of "CAP_ROUND", "CAP_FLAT", "CAP_SQUARE". This parameter is case-insensitive. - `mite_limit` only applies when `join_style` is "JOIN_MITRE". It is the ratio of the distance from the corner to the miter point to the corner radius. The default value is 1.0. + `mitre_limit` only applies when `join_style` is "JOIN_MITRE". It is the ratio of the distance from the corner to the mitre point to the corner radius. The default value is 1.0. This is a planar operation and will not take into account the curvature of the earth. )"; diff --git a/spatial/src/spatial/proj/functions.cpp b/spatial/src/spatial/proj/functions.cpp index 990c2109..362c095e 100644 --- a/spatial/src/spatial/proj/functions.cpp +++ b/spatial/src/spatial/proj/functions.cpp @@ -437,7 +437,7 @@ Transforms a geometry between two coordinate systems The source and target coordinate systems can be specified using any format that the [PROJ library](https://proj.org) supports. -The optional `always_xy` parameter can be used to force the input and output geometries to be interpreted as having a [northing, easting] coordinate axis order regardless of what the source and target coordinate system definition says. This is particularly useful when transforming to/from the [WGS84/EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (what most people think of when they hear "longitude"/"latitude" or "GPS coordinates"), which is defined as having a [latitude, longitude] axis order even though [longitude, latitude] is commonly used in practice (e.g. in [GeoJSON](https://tools.ietf.org/html/rfc7946)). More details available in the [PROJ documentation](https://proj.org/en/9.3/faq.html#why-is-the-axis-ordering-in-proj-not-consistent). +The third optional `always_xy` parameter can be used to force the input and output geometries to be interpreted as having a [easting, northing] coordinate axis order regardless of what the source and target coordinate system definition says. This is particularly useful when transforming to/from the [WGS84/EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (what most people think of when they hear "longitude"/"latitude" or "GPS coordinates"), which is defined as having a [latitude, longitude] axis order even though [longitude, latitude] is commonly used in practice (e.g. in [GeoJSON](https://tools.ietf.org/html/rfc7946)). More details available in the [PROJ documentation](https://proj.org/en/9.3/faq.html#why-is-the-axis-ordering-in-proj-not-consistent). DuckDB spatial vendors its own static copy of the PROJ database of coordinate systems, so if you have your own installation of PROJ on your system the available coordinate systems may differ to what's available in other GIS software. )"; @@ -446,7 +446,7 @@ static constexpr const char *DOC_EXAMPLE = R"( -- Transform a geometry from EPSG:4326 to EPSG:3857 (WGS84 to WebMercator) -- Note that since WGS84 is defined as having a [latitude, longitude] axis order -- we follow the standard and provide the input geometry using that axis order, --- but the output will be [northing, easting] because that is what's defined by +-- but the output will be [easting, northing] because that is what's defined by -- WebMercator. SELECT ST_AsText( @@ -463,7 +463,7 @@ POINT (544615.0239773799 6867874.103539125) -- which uses WGS84 but with [longitude, latitude] axis order. We can use the -- `always_xy` parameter to force the input geometry to be interpreted as having -- a [northing, easting] axis order instead, even though the source coordinate --- system definition says otherwise. +-- reference system definition (WGS84) says otherwise. SELECT ST_AsText( ST_Transform(