From 56b17a15ecfce934b7b891180e063b69359b536e Mon Sep 17 00:00:00 2001 From: Max Gabrielsson Date: Mon, 27 Nov 2023 14:50:29 +0100 Subject: [PATCH 1/3] small fixes --- spatial/src/spatial/core/functions/scalar/st_collect.cpp | 5 ++++- spatial/src/spatial/core/functions/scalar/st_distance.cpp | 4 ++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/spatial/src/spatial/core/functions/scalar/st_collect.cpp b/spatial/src/spatial/core/functions/scalar/st_collect.cpp index 425c4cb6..6fc64301 100644 --- a/spatial/src/spatial/core/functions/scalar/st_collect.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_collect.cpp @@ -30,7 +30,10 @@ static void CollectFunction(DataChunk &args, ExpressionState &state, Vector &res if (format.validity.RowIsValid(mapped_idx)) { auto geometry_blob = ((string_t *)format.data)[mapped_idx]; auto geometry = lstate.factory.Deserialize(geometry_blob); - geometries.push_back(geometry); + // Dont add empty geometries + if(!geometry.IsEmpty()) { + geometries.push_back(geometry); + } } } diff --git a/spatial/src/spatial/core/functions/scalar/st_distance.cpp b/spatial/src/spatial/core/functions/scalar/st_distance.cpp index 5360546b..5ee8c6cf 100644 --- a/spatial/src/spatial/core/functions/scalar/st_distance.cpp +++ b/spatial/src/spatial/core/functions/scalar/st_distance.cpp @@ -64,6 +64,10 @@ static void PointToPointDistanceFunction(DataChunk &args, ExpressionState &state for (idx_t i = 0; i < count; i++) { out_data[i] = std::sqrt(std::pow(left_x[i] - right_x[i], 2) + std::pow(left_y[i] - right_y[i], 2)); } + + if(count == 1) { + result.SetVectorType(VectorType::CONSTANT_VECTOR); + } } //------------------------------------------------------------------------------ From 100d4c45cf41a0739e3c44bae41777e107c592a2 Mon Sep 17 00:00:00 2001 From: Max Gabrielsson Date: Mon, 27 Nov 2023 15:03:13 +0100 Subject: [PATCH 2/3] add initial doc stubs --- docs/docs.md | 1782 +++++++++++++++++ docs/src/README.md | 80 + docs/src/aggregate_functions.json | 3 + .../functions/aggregate/st_envelope_agg.md | 31 + .../aggregate/st_intersection_agg.md | 31 + docs/src/functions/aggregate/st_union_agg.md | 31 + docs/src/functions/scalar/st_area.md | 73 + docs/src/functions/scalar/st_area_spheroid.md | 44 + docs/src/functions/scalar/st_asgeojson.md | 38 + docs/src/functions/scalar/st_ashexwkb.md | 37 + docs/src/functions/scalar/st_astext.md | 69 + docs/src/functions/scalar/st_aswkb.md | 33 + docs/src/functions/scalar/st_boundary.md | 31 + docs/src/functions/scalar/st_buffer.md | 49 + docs/src/functions/scalar/st_centroid.md | 72 + docs/src/functions/scalar/st_collect.md | 31 + .../functions/scalar/st_collectionextract.md | 47 + docs/src/functions/scalar/st_contains.md | 54 + .../functions/scalar/st_containsproperly.md | 35 + docs/src/functions/scalar/st_convexhull.md | 28 + docs/src/functions/scalar/st_coveredby.md | 35 + docs/src/functions/scalar/st_covers.md | 35 + docs/src/functions/scalar/st_crosses.md | 35 + docs/src/functions/scalar/st_difference.md | 35 + docs/src/functions/scalar/st_dimension.md | 37 + docs/src/functions/scalar/st_disjoint.md | 32 + docs/src/functions/scalar/st_distance.md | 84 + .../functions/scalar/st_distance_spheroid.md | 45 + docs/src/functions/scalar/st_dump.md | 34 + docs/src/functions/scalar/st_dwithin.md | 39 + .../functions/scalar/st_dwithin_spheroid.md | 39 + docs/src/functions/scalar/st_endpoint.md | 43 + docs/src/functions/scalar/st_envelope.md | 31 + docs/src/functions/scalar/st_equals.md | 32 + docs/src/functions/scalar/st_extent.md | 28 + docs/src/functions/scalar/st_exteriorring.md | 40 + .../functions/scalar/st_flipcoordinates.md | 67 + docs/src/functions/scalar/st_geometrytype.md | 58 + .../functions/scalar/st_geomfromgeojson.md | 31 + .../functions/scalar/st_geomfromhexewkb.md | 31 + .../src/functions/scalar/st_geomfromhexwkb.md | 31 + docs/src/functions/scalar/st_geomfromtext.md | 44 + docs/src/functions/scalar/st_geomfromwkb.md | 40 + docs/src/functions/scalar/st_intersection.md | 35 + docs/src/functions/scalar/st_intersects.md | 48 + .../functions/scalar/st_intersects_extent.md | 35 + docs/src/functions/scalar/st_isclosed.md | 31 + docs/src/functions/scalar/st_isempty.md | 49 + docs/src/functions/scalar/st_isring.md | 31 + docs/src/functions/scalar/st_issimple.md | 31 + docs/src/functions/scalar/st_isvalid.md | 31 + docs/src/functions/scalar/st_length.md | 40 + .../functions/scalar/st_length_spheroid.md | 43 + docs/src/functions/scalar/st_linemerge.md | 44 + .../scalar/st_linestring2dfromwkb.md | 31 + docs/src/functions/scalar/st_makeenvelope.md | 40 + docs/src/functions/scalar/st_makeline.md | 44 + docs/src/functions/scalar/st_makepolygon.md | 44 + docs/src/functions/scalar/st_normalize.md | 31 + docs/src/functions/scalar/st_numgeometries.md | 32 + .../functions/scalar/st_numinteriorrings.md | 41 + docs/src/functions/scalar/st_numpoints.md | 68 + docs/src/functions/scalar/st_overlaps.md | 35 + docs/src/functions/scalar/st_perimeter.md | 49 + .../functions/scalar/st_perimeter_spheroid.md | 42 + docs/src/functions/scalar/st_point.md | 35 + docs/src/functions/scalar/st_point2d.md | 35 + .../src/functions/scalar/st_point2dfromwkb.md | 31 + docs/src/functions/scalar/st_point3d.md | 39 + docs/src/functions/scalar/st_point4d.md | 43 + docs/src/functions/scalar/st_pointn.md | 48 + .../src/functions/scalar/st_pointonsurface.md | 31 + .../functions/scalar/st_polygon2dfromwkb.md | 31 + .../functions/scalar/st_reduceprecision.md | 32 + .../scalar/st_removerepeatedpoints.md | 66 + docs/src/functions/scalar/st_reverse.md | 31 + docs/src/functions/scalar/st_simplify.md | 32 + .../scalar/st_simplifypreservetopology.md | 35 + docs/src/functions/scalar/st_startpoint.md | 40 + docs/src/functions/scalar/st_touches.md | 35 + docs/src/functions/scalar/st_transform.md | 176 ++ docs/src/functions/scalar/st_union.md | 41 + docs/src/functions/scalar/st_within.md | 48 + docs/src/functions/scalar/st_x.md | 40 + docs/src/functions/scalar/st_xmax.md | 67 + docs/src/functions/scalar/st_xmin.md | 67 + docs/src/functions/scalar/st_y.md | 40 + docs/src/functions/scalar/st_ymax.md | 67 + docs/src/functions/scalar/st_ymin.md | 67 + docs/src/functions/table/st_drivers.md | 82 + docs/src/functions/table/st_read.md | 109 + docs/src/functions/table/st_readosm.md | 53 + docs/src/generate.py | 154 ++ docs/src/get_functions.sql | 37 + docs/src/intro.md | 19 + docs/src/scalar_functions.json | 86 + docs/src/table_functions.json | 4 + docs/src/types/geometry.md | 0 docs/src/verify.py | 158 ++ 99 files changed, 6279 insertions(+) create mode 100644 docs/docs.md create mode 100644 docs/src/README.md create mode 100644 docs/src/aggregate_functions.json create mode 100644 docs/src/functions/aggregate/st_envelope_agg.md create mode 100644 docs/src/functions/aggregate/st_intersection_agg.md create mode 100644 docs/src/functions/aggregate/st_union_agg.md create mode 100644 docs/src/functions/scalar/st_area.md create mode 100644 docs/src/functions/scalar/st_area_spheroid.md create mode 100644 docs/src/functions/scalar/st_asgeojson.md create mode 100644 docs/src/functions/scalar/st_ashexwkb.md create mode 100644 docs/src/functions/scalar/st_astext.md create mode 100644 docs/src/functions/scalar/st_aswkb.md create mode 100644 docs/src/functions/scalar/st_boundary.md create mode 100644 docs/src/functions/scalar/st_buffer.md create mode 100644 docs/src/functions/scalar/st_centroid.md create mode 100644 docs/src/functions/scalar/st_collect.md create mode 100644 docs/src/functions/scalar/st_collectionextract.md create mode 100644 docs/src/functions/scalar/st_contains.md create mode 100644 docs/src/functions/scalar/st_containsproperly.md create mode 100644 docs/src/functions/scalar/st_convexhull.md create mode 100644 docs/src/functions/scalar/st_coveredby.md create mode 100644 docs/src/functions/scalar/st_covers.md create mode 100644 docs/src/functions/scalar/st_crosses.md create mode 100644 docs/src/functions/scalar/st_difference.md create mode 100644 docs/src/functions/scalar/st_dimension.md create mode 100644 docs/src/functions/scalar/st_disjoint.md create mode 100644 docs/src/functions/scalar/st_distance.md create mode 100644 docs/src/functions/scalar/st_distance_spheroid.md create mode 100644 docs/src/functions/scalar/st_dump.md create mode 100644 docs/src/functions/scalar/st_dwithin.md create mode 100644 docs/src/functions/scalar/st_dwithin_spheroid.md create mode 100644 docs/src/functions/scalar/st_endpoint.md create mode 100644 docs/src/functions/scalar/st_envelope.md create mode 100644 docs/src/functions/scalar/st_equals.md create mode 100644 docs/src/functions/scalar/st_extent.md create mode 100644 docs/src/functions/scalar/st_exteriorring.md create mode 100644 docs/src/functions/scalar/st_flipcoordinates.md create mode 100644 docs/src/functions/scalar/st_geometrytype.md create mode 100644 docs/src/functions/scalar/st_geomfromgeojson.md create mode 100644 docs/src/functions/scalar/st_geomfromhexewkb.md create mode 100644 docs/src/functions/scalar/st_geomfromhexwkb.md create mode 100644 docs/src/functions/scalar/st_geomfromtext.md create mode 100644 docs/src/functions/scalar/st_geomfromwkb.md create mode 100644 docs/src/functions/scalar/st_intersection.md create mode 100644 docs/src/functions/scalar/st_intersects.md create mode 100644 docs/src/functions/scalar/st_intersects_extent.md create mode 100644 docs/src/functions/scalar/st_isclosed.md create mode 100644 docs/src/functions/scalar/st_isempty.md create mode 100644 docs/src/functions/scalar/st_isring.md create mode 100644 docs/src/functions/scalar/st_issimple.md create mode 100644 docs/src/functions/scalar/st_isvalid.md create mode 100644 docs/src/functions/scalar/st_length.md create mode 100644 docs/src/functions/scalar/st_length_spheroid.md create mode 100644 docs/src/functions/scalar/st_linemerge.md create mode 100644 docs/src/functions/scalar/st_linestring2dfromwkb.md create mode 100644 docs/src/functions/scalar/st_makeenvelope.md create mode 100644 docs/src/functions/scalar/st_makeline.md create mode 100644 docs/src/functions/scalar/st_makepolygon.md create mode 100644 docs/src/functions/scalar/st_normalize.md create mode 100644 docs/src/functions/scalar/st_numgeometries.md create mode 100644 docs/src/functions/scalar/st_numinteriorrings.md create mode 100644 docs/src/functions/scalar/st_numpoints.md create mode 100644 docs/src/functions/scalar/st_overlaps.md create mode 100644 docs/src/functions/scalar/st_perimeter.md create mode 100644 docs/src/functions/scalar/st_perimeter_spheroid.md create mode 100644 docs/src/functions/scalar/st_point.md create mode 100644 docs/src/functions/scalar/st_point2d.md create mode 100644 docs/src/functions/scalar/st_point2dfromwkb.md create mode 100644 docs/src/functions/scalar/st_point3d.md create mode 100644 docs/src/functions/scalar/st_point4d.md create mode 100644 docs/src/functions/scalar/st_pointn.md create mode 100644 docs/src/functions/scalar/st_pointonsurface.md create mode 100644 docs/src/functions/scalar/st_polygon2dfromwkb.md create mode 100644 docs/src/functions/scalar/st_reduceprecision.md create mode 100644 docs/src/functions/scalar/st_removerepeatedpoints.md create mode 100644 docs/src/functions/scalar/st_reverse.md create mode 100644 docs/src/functions/scalar/st_simplify.md create mode 100644 docs/src/functions/scalar/st_simplifypreservetopology.md create mode 100644 docs/src/functions/scalar/st_startpoint.md create mode 100644 docs/src/functions/scalar/st_touches.md create mode 100644 docs/src/functions/scalar/st_transform.md create mode 100644 docs/src/functions/scalar/st_union.md create mode 100644 docs/src/functions/scalar/st_within.md create mode 100644 docs/src/functions/scalar/st_x.md create mode 100644 docs/src/functions/scalar/st_xmax.md create mode 100644 docs/src/functions/scalar/st_xmin.md create mode 100644 docs/src/functions/scalar/st_y.md create mode 100644 docs/src/functions/scalar/st_ymax.md create mode 100644 docs/src/functions/scalar/st_ymin.md create mode 100644 docs/src/functions/table/st_drivers.md create mode 100644 docs/src/functions/table/st_read.md create mode 100644 docs/src/functions/table/st_readosm.md create mode 100755 docs/src/generate.py create mode 100644 docs/src/get_functions.sql create mode 100644 docs/src/intro.md create mode 100644 docs/src/scalar_functions.json create mode 100644 docs/src/table_functions.json create mode 100644 docs/src/types/geometry.md create mode 100644 docs/src/verify.py diff --git a/docs/docs.md b/docs/docs.md new file mode 100644 index 00000000..eab4c4b6 --- /dev/null +++ b/docs/docs.md @@ -0,0 +1,1782 @@ +# DuckDB Spatial Extension + + +The spatial extension provides support for geospatial data processing in DuckDB. + +## Installing and Loading + +To install and load the DuckDB `spatial` extension, simply run: + +```sql +INSTALL spatial; +LOAD spatial; +``` + +You can also get the latest beta version of the extension for the latest stable release of DuckDB. This version is built and reuploaded every time a pull request is merged into the `main` branch on spatial extensions GitHub repository. +Install it by executing: + +```sql +FORCE INSTALL spatial FROM 'http://nightly-extensions.duckdb.org'; +``` +Note that this will overwrite any existing `spatial` extension installed for the current version of DuckDB. +# Scalar Functions + +| Name | 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) | Returns 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_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_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 | +| [ST_DWithin](##st_dwithin) | Returns if two geometries are within a target distance of eachother | +| [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_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_GeometryType](##st_geometrytype) | Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type. | +| [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_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_LineString2DFromWKB](##st_linestring2dfromwkb) | Deserialize a LINESTRING_2D from a WKB encoded geometry blob | +| [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_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 points 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_Point2DFromWKB](##st_point2dfromwkb) | Deserialize a POINT_2D from a WKB encoded geometry blob | +| [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_Polygon2DFromWKB](##st_polygon2dfromwkb) | Deserialize a POLYGON_2D from a WKB encoded blob | +| [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_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 coordinate of a point geometry, or NULL if not a point or empty | +| [ST_XMax](##st_xmax) | Returns the maximum x coordinate of a geometry | +| [ST_XMin](##st_xmin) | Returns the minimum x coordinate of a geometry | +| [ST_Y](##st_y) | Returns the y coordinate of a point geometry, or NULL if not a point or empty. | +| [ST_YMax](##st_ymax) | Returns the maximum y coordinate of a geometry | +| [ST_YMin](##st_ymin) | Returns the minimum y coordinate of a geometry | + +## ST_Area + +_Returns the area of a geometry._ + +- __DOUBLE__ ST_Area(geom __GEOMETRY__) +- __DOUBLE__ ST_Area(point_2D __POINT_2D__) +- __DOUBLE__ ST_Area(linestring_2d __LINESTRING_2D__) +- __DOUBLE__ ST_Area(polygon_2d __POLYGON_2D__) +- __DOUBLE__ ST_Area(box __BOX_2D__) + +### Description + +Compute the area of a geometry. + +Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + +The `POINT_2D` and `LINESTRING_2D` variants of this function always return `0.0` but are included for completeness. + +### Examples + +```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_ + +- __DOUBLE__ ST_Area_Spheroid(polygon __POLYGON_2D__) +- __DOUBLE__ ST_Area_Spheroid(geometry __GEOMETRY__) + +### Description + +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 area is returned in square meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the area using an ellipsoidal model of the earth. This is a highly accurate method for calculating the area of a polygon taking the curvature of the earth into account, but is also the slowest. + +Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + + +### Examples + +TODO + +## ST_AsGeoJSON + +_Returns the geometry as a GeoJSON fragment_ + +- __VARCHAR__ ST_AsGeoJSON(geom __GEOMETRY__) + +### Description + +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. + +### Examples + +```sql +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]]]} + +``` + +## ST_AsHEXWKB + +_Returns the geometry as a HEXWKB string_ + +- __VARCHAR__ ST_AsHEXWKB(geom __GEOMETRY__) + +### Description + +Returns the geometry as a HEXWKB string + +### Examples + +```sql +select st_ashexwkb('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +``` + +## ST_AsText + +_Returns the geometry as a WKT string_ + +- __VARCHAR__ ST_AsText(geom __GEOMETRY__) +- __VARCHAR__ ST_AsText(point_2d __POINT_2D__) +- __VARCHAR__ ST_AsText(linestring_2d __LINESTRING_2D__) +- __VARCHAR__ ST_AsText(polygon_2d __POLYGON_2D__) +- __VARCHAR__ ST_AsText(box __BOX_2D__) + +### Description + +Returns the geometry as a WKT string + +### Examples + +```sql +select st_astext('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +``` + +## ST_AsWKB + +_Returns the geometry as a WKB blob_ + +- __WKB_BLOB__ ST_AsWKB(geom __GEOMETRY__) + +### Description + +Returns the geometry as a WKB blob + +### Examples + +```sql +select st_aswkb('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +``` + +## ST_Boundary + +_Returns the "boundary" of a geometry_ + +- __GEOMETRY__ ST_Boundary(geometry __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Buffer + +_Returns a buffer around the input geometry at the target distance_ + +- __GEOMETRY__ ST_Buffer(geom __GEOMETRY__, distance __DOUBLE__) +- __GEOMETRY__ ST_Buffer(geom __GEOMETRY__, distance __DOUBLE__, num_triangles __INTEGER__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Centroid + +_Returns the centroid of a geometry._ + +- __GEOMETRY__ ST_Centroid(geom __GEOMETRY__) +- __POINT_2D__ ST_Centroid(point_2d __POINT_2D__) +- __POINT_2D__ ST_Centroid(linestring_2d __LINESTRING_2D__) +- __POINT_2D__ ST_Centroid(polygon_2d __POLYGON_2D__) +- __POINT_2D__ ST_Centroid(box __BOX_2D__) + +### Description + +Calculate the centroid of the geometry + +### Examples + +```sql +select st_centroid('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +-- POINT(0.5 0.5) +``` + +End of example + +## ST_Collect + +_Collects geometries into a collection geometry_ + +- __GEOMETRY__ ST_Collect(geometries __GEOMETRY[]__) + +### Description + +Collects a list of geometries into a collection geometry + +### Examples + +TODO + +## ST_CollectionExtract + +_Extracts a sub-geometry from a collection geometry_ + +- __GEOMETRY__ ST_CollectionExtract(geom __GEOMETRY__) +- __GEOMETRY__ ST_CollectionExtract(geom __GEOMETRY__, dimension __INTEGER__) + +### Description + +Extracts a sub-geometry from a collection geometry + +### Examples + +```sql +select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1); +-- POINT(1 2) +``` + +## ST_Contains + +_Returns true if geom1 contains geom2._ + +- __BOOLEAN__ ST_Contains(geom1 __GEOMETRY__, geom2 __GEOMETRY__) +- __BOOLEAN__ ST_Contains(polygon_2d __POLYGON_2D__, point __POINT_2D__) + +### Description + +Returns true if geom1 contains geom2. + +### Examples + +```sql +select st_contains('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry, 'POINT(0.5 0.5)'::geometry); +-- true +``` + +## ST_ContainsProperly + +_Returns true if geom1 "properly contains" geom2_ + +- __BOOLEAN__ ST_ContainsProperly(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_ConvexHull + +_Returns the convex hull enclosing the geometry_ + +- __GEOMETRY__ ST_ConvexHull(col0 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_CoveredBy + +_Returns true if geom1 is "covered" by geom2_ + +- __BOOLEAN__ ST_CoveredBy(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Covers + +_Returns if geom1 "covers" geom2_ + +- __BOOLEAN__ ST_Covers(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Crosses + +_Returns true if geom1 "crosses" geom2_ + +- __BOOLEAN__ ST_Crosses(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Difference + +_Returns the "difference" between two geometries_ + +- __GEOMETRY__ ST_Difference(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Dimension + +_Returns the dimension of a geometry._ + +- __INTEGER__ ST_Dimension(geom __GEOMETRY__) + +### Description + +Returns the dimension of a geometry. + +### Examples + +```sql +select st_dimension('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +-- 2 +``` + +## ST_Disjoint + +_Returns if two geometries are disjoint_ + +- __BOOLEAN__ ST_Disjoint(col0 __GEOMETRY__, col1 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Distance + +_Returns the distance between two geometries._ + +- __DOUBLE__ ST_Distance(geom1 __GEOMETRY__, geom2 __GEOMETRY__) +- __DOUBLE__ ST_Distance(point1 __POINT_2D__, point2 __POINT_2D__) +- __DOUBLE__ ST_Distance(point __POINT_2D__, linestring_2d __LINESTRING_2D__) +- __DOUBLE__ ST_Distance(linestring_2d __LINESTRING_2D__, point __POINT_2D__) + +### Description + +Returns the distance between two geometries. + +### Examples + +```sql +select st_distance('POINT(0 0)'::geometry, 'POINT(1 1)'::geometry); +-- 1.4142135623731 +``` + +End of example + +## ST_Distance_Spheroid + +_Returns the distance between two geometries in meters using a ellipsoidal model of the earths surface_ + +- __DOUBLE__ ST_Distance_Spheroid(point __POINT_2D__, p2 __POINT_2D__) + +### Description + +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. + +### Examples + +```sql +-- Note: the coordinates are in WGS84 and [latitude, longitude] axis order +-- Whats the distance between New York and Amsterdam (JFK and AMS airport)? +SELECT st_distance_spheroid( + st_point(40.6446, 73.7797), + st_point(52.3130, 4.7725) +); +---- +5243187.666873225 +-- Roughly 5243km! +``` + +## ST_Dump + +_Dumps a geometry into a set of sub-geometries_ + +- __STRUCT(geom GEOMETRY, path INTEGER[])[]__ ST_Dump(geom __GEOMETRY__) + +### Description + +Dumps a geometry into a set of sub-geometries and their "path" in the original geometry. + +### Examples + +```sql +select st_dump('MULTIPOINT(1 2,3 4)'::geometry); +-- [{'geom': 'POINT(1 2)', 'path': [0]}, {'geom': 'POINT(3 4)', 'path': [1]}] +``` + +## ST_DWithin + +_Returns if two geometries are within a target distance of eachother_ + +- __BOOLEAN__ ST_DWithin(geom1 __GEOMETRY__, geom2 __GEOMETRY__, distance __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_DWithin_Spheroid + +_Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface_ + +- __DOUBLE__ ST_DWithin_Spheroid(p1 __POINT_2D__, p2 __POINT_2D__, distance __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_EndPoint + +_Returns the end point of a line._ + +- __GEOMETRY__ ST_EndPoint(line __GEOMETRY__) +- __POINT_2D__ ST_EndPoint(line __LINESTRING_2D__) + +### Description + +Returns the end point of a line. + +### Examples + +```sql +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._ + +- __GEOMETRY__ ST_Envelope(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Equals + +_Compares two geometries for equality_ + +- __BOOLEAN__ ST_Equals(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Extent + +_Returns the minimal bounding box enclosing the input geometry_ + +- __BOX_2D__ ST_Extent(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_ExteriorRing + +_Returns the exterior ring (shell) of a polygon geometry._ + +- __LINESTRING_2D__ ST_ExteriorRing(polygon __POLYGON_2D__) +- __GEOMETRY__ ST_ExteriorRing(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_FlipCoordinates + +_Returns a new geometry with the coordinates of the input geometry "flipped" so that x = y and y = x._ + +- __POINT_2D__ ST_FlipCoordinates(point __POINT_2D__) +- __LINESTRING_2D__ ST_FlipCoordinates(line __LINESTRING_2D__) +- __POLYGON_2D__ ST_FlipCoordinates(polygon __POLYGON_2D__) +- __BOX_2D__ ST_FlipCoordinates(box __BOX_2D__) +- __GEOMETRY__ ST_FlipCoordinates(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_GeometryType + +_Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type._ + +- __ANY__ ST_GeometryType(point __POINT_2D__) +- __ANY__ ST_GeometryType(line __LINESTRING_2D__) +- __ANY__ ST_GeometryType(polygon __POLYGON_2D__) +- __ANY__ ST_GeometryType(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_GeomFromGeoJSON + +_Deserializes a GEOMETRY from a GeoJSON fragment._ + +- __GEOMETRY__ ST_GeomFromGeoJSON(geojson __VARCHAR__) + +### Description + +TODO + +### Examples + +TODO + +## ST_GeomFromHEXEWKB + +_Deserialize a GEOMETRY from a HEXEWKB encoded string_ + +- __GEOMETRY__ ST_GeomFromHEXEWKB(hexewkb __VARCHAR__) + +### Description + +TODO + +### Examples + +TODO + +## ST_GeomFromHEXWKB + +_Creates a GEOMETRY from a HEXWKB string_ + +- __GEOMETRY__ ST_GeomFromHEXWKB(hexwkb __VARCHAR__) + +### Description + +TODO + +### Examples + +TODO + +## ST_GeomFromText + +_Deserializes a GEOMETRY from a WKT string, optionally ignoring invalid geometries_ + +- __GEOMETRY__ ST_GeomFromText(wkt __VARCHAR__) +- __GEOMETRY__ ST_GeomFromText(wkt __VARCHAR__, ignore_invalid __BOOLEAN__) + +### Description + +TODO + +### Examples + +TODO + +## ST_GeomFromWKB + +_Deserializes a GEOMETRY from a WKB encoded blob_ + +- __GEOMETRY__ ST_GeomFromWKB(blob __WKB_BLOB__) +- __GEOMETRY__ ST_GeomFromWKB(blob __BLOB__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Intersection + +_Returns the "intersection" of geom1 and geom2_ + +- __GEOMETRY__ ST_Intersection(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Intersects + +_Returns true if two geometries intersects_ + +- __BOOLEAN__ ST_Intersects(box1 __BOX_2D__, box2 __BOX_2D__) +- __BOOLEAN__ ST_Intersects(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Intersects_Extent + +_Returns true if the extent of two geometries intersects_ + +- __BOOLEAN__ ST_Intersects_Extent(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_IsClosed + +_Returns true if a geometry is "closed"_ + +- __BOOLEAN__ ST_IsClosed(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_IsEmpty + +_Returns true if the geometry is "empty"_ + +- __BOOLEAN__ ST_IsEmpty(line __LINESTRING_2D__) +- __BOOLEAN__ ST_IsEmpty(polygon __POLYGON_2D__) +- __BOOLEAN__ ST_IsEmpty(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_IsRing + +_Returns true if the input line geometry is a ring (both ST_IsClosed and ST_IsSimple)._ + +- __BOOLEAN__ ST_IsRing(line __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_IsSimple + +_Returns true if the input geometry is "simple"_ + +- __BOOLEAN__ ST_IsSimple(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_IsValid + +_Returns true if the geometry is topologically "valid"_ + +- __BOOLEAN__ ST_IsValid(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Length + +_Returns the length of the input line geometry_ + +- __DOUBLE__ ST_Length(line __LINESTRING_2D__) +- __DOUBLE__ ST_Length(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Length_Spheroid + +_Returns the length of the input geometry in meters, using a ellipsoidal model of the earth_ + +- __DOUBLE__ ST_Length_Spheroid(line __LINESTRING_2D__) +- __DOUBLE__ ST_Length_Spheroid(geom __GEOMETRY__) + +### Description + +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 length is returned in square meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the length using an ellipsoidal model of the earth. This is a highly accurate method for calculating the length of a line geometry taking the curvature of the earth into account, but is also the slowest. + +Returns `0.0` for any geometry that is not a `LINESTRING`, `MULTILINESTRING` or `GEOMETRYCOLLECTION` containing line geometries. + + +### Examples + +TODO + +## ST_LineMerge + +_"Merges" the input line geometry, optionally taking direction into account._ + +- __GEOMETRY__ ST_LineMerge(linework __GEOMETRY__) +- __GEOMETRY__ ST_LineMerge(linework __GEOMETRY__, directed __BOOLEAN__) + +### Description + +TODO + +### Examples + +TODO + +## ST_LineString2DFromWKB + +_Deserialize a LINESTRING_2D from a WKB encoded geometry blob_ + +- __LINESTRING_2D__ ST_LineString2DFromWKB(blob __WKB_BLOB__) + +### Description + +TODO + +### Examples + +TODO + +## ST_MakeEnvelope + +_Returns a minimal bounding box polygon enclosing the input geometry_ + +- __GEOMETRY__ ST_MakeEnvelope(col0 __DOUBLE__, col1 __DOUBLE__, col2 __DOUBLE__, col3 __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_MakeLine + +_Creates a LINESTRING geometry from a pair or list of input points_ + +- __GEOMETRY__ ST_MakeLine(points __GEOMETRY[]__) +- __GEOMETRY__ ST_MakeLine(start_point __GEOMETRY__, end_point __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_MakePolygon + +_Creates a polygon from a shell geometry and an optional set of holes_ + +- __GEOMETRY__ ST_MakePolygon(shell __GEOMETRY__, holes __GEOMETRY[]__) +- __GEOMETRY__ ST_MakePolygon(shell __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Normalize + +_Returns a "normalized" version of the input geometry._ + +- __GEOMETRY__ ST_Normalize(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_NumGeometries + +_Returns the number of component geometries in a collection geometry_ + +- __INTEGER__ ST_NumGeometries(geom __GEOMETRY__) + + +__aliases:__ st_ngeometries +### Description + +TODO + +### Examples + +TODO + +## ST_NumInteriorRings + +_Returns the number if interior rings of a polygon_ + +- __INTEGER__ ST_NumInteriorRings(polygon __POLYGON_2D__) +- __INTEGER__ ST_NumInteriorRings(geom __GEOMETRY__) + + +__aliases:__ st_ninteriorrings +### Description + +TODO + +### Examples + +TODO + +## ST_NumPoints + +_Returns the number of points within a geometry_ + +- __UBIGINT__ ST_NumPoints(point __POINT_2D__) +- __UBIGINT__ ST_NumPoints(line __LINESTRING_2D__) +- __UBIGINT__ ST_NumPoints(polygon __POLYGON_2D__) +- __UBIGINT__ ST_NumPoints(geom __BOX_2D__) +- __UINTEGER__ ST_NumPoints(geom __GEOMETRY__) + + +__aliases:__ st_npoints +### Description + +TODO + +### Examples + +TODO + +## ST_Overlaps + +_Returns true if geom1 "overlaps" geom2_ + +- __BOOLEAN__ ST_Overlaps(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Perimeter + +_Returns the length of the perimeter of the geometry_ + +- __DOUBLE__ ST_Perimeter(box __BOX_2D__) +- __DOUBLE__ ST_Perimeter(geom __POLYGON_2D__) +- __DOUBLE__ ST_Perimeter(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Perimeter_Spheroid + +_Returns the length of the perimeter in meters using an ellipsoidal model of the earths surface_ + +- __DOUBLE__ ST_Perimeter_Spheroid(polygon __POLYGON_2D__) +- __DOUBLE__ ST_Perimeter_Spheroid(geom __GEOMETRY__) + +### Description + +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 length is returned in meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the perimeter using an ellipsoidal model of the earth. This is a highly accurate method for calculating the perimeter of a polygon taking the curvature of the earth into account, but is also the slowest. + +Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + +### Examples + +TODO + +## ST_Point + +_Creates a GEOMETRY point_ + +- __GEOMETRY__ ST_Point(x __DOUBLE__, y __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Point2D + +_Creates a POINT_2D_ + +- __POINT_2D__ ST_Point2D(x __DOUBLE__, y __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Point2DFromWKB + +_Deserialize a POINT_2D from a WKB encoded geometry blob_ + +- __POINT_2D__ ST_Point2DFromWKB(blob __WKB_BLOB__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Point3D + +_Creates a POINT_3D_ + +- __POINT_3D__ ST_Point3D(x __DOUBLE__, y __DOUBLE__, z __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Point4D + +_Creates a POINT_4D_ + +- __POINT_4D__ ST_Point4D(x __DOUBLE__, y __DOUBLE__, z __DOUBLE__, m __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_PointN + +_Returns the n'th vertex from the input geometry as a point geometry_ + +- __GEOMETRY__ ST_PointN(geom __GEOMETRY__, n __INTEGER__) +- __POINT_2D__ ST_PointN(line __LINESTRING_2D__, n __INTEGER__) + +### Description + +TODO + +### Examples + +TODO + +## ST_PointOnSurface + +_Returns a point that is guaranteed to be on the surface of the input geometry. Sometimes a useful alternative to ST_Centroid._ + +- __GEOMETRY__ ST_PointOnSurface(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Polygon2DFromWKB + +_Deserialize a POLYGON_2D from a WKB encoded blob_ + +- __POLYGON_2D__ ST_Polygon2DFromWKB(blob __WKB_BLOB__) + +### Description + +TODO + +### Examples + +TODO + +## ST_ReducePrecision + +_Returns the geometry with all vertices reduced to the target precision_ + +- __GEOMETRY__ ST_ReducePrecision(geom __GEOMETRY__, precision __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_RemoveRepeatedPoints + +_Returns a new geometry with repeated points removed, optionally within a target distance of eachother._ + +- __LINESTRING_2D__ ST_RemoveRepeatedPoints(line __LINESTRING_2D__) +- __LINESTRING_2D__ ST_RemoveRepeatedPoints(line __LINESTRING_2D__, distance __DOUBLE__) +- __GEOMETRY__ ST_RemoveRepeatedPoints(geom __GEOMETRY__) +- __GEOMETRY__ ST_RemoveRepeatedPoints(geom __GEOMETRY__, distance __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Reverse + +_Returns a new version of the input geometry with the order of its vertices reversed_ + +- __GEOMETRY__ ST_Reverse(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Simplify + +_Simplifies the input geometry by collapsing edges smaller than 'distance'_ + +- __GEOMETRY__ ST_Simplify(geom __GEOMETRY__, distance __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_SimplifyPreserveTopology + +_Returns a simplified geometry but avoids creating invalid topologies_ + +- __GEOMETRY__ ST_SimplifyPreserveTopology(geom __GEOMETRY__, distance __DOUBLE__) + +### Description + +TODO + +### Examples + +TODO + +## ST_StartPoint + +_Returns the first point of a line geometry_ + +- __GEOMETRY__ ST_StartPoint(geom __GEOMETRY__) +- __POINT_2D__ ST_StartPoint(line __LINESTRING_2D__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Touches + +_Returns true if geom1 "touches" geom2_ + +- __BOOLEAN__ ST_Touches(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Transform + +_Transforms a geometry between two coordinate systems_ + +- __BOX_2D__ ST_Transform(box __BOX_2D__, source_crs __VARCHAR__, target_crs __VARCHAR__) +- __BOX_2D__ ST_Transform(box __BOX_2D__, source_crs __VARCHAR__, target_crs __VARCHAR__, always_xy __BOOLEAN__) +- __POINT_2D__ ST_Transform(point __POINT_2D__, source_crs __VARCHAR__, target_crs __VARCHAR__) +- __POINT_2D__ ST_Transform(point __POINT_2D__, source_crs __VARCHAR__, target_crs __VARCHAR__, always_xy __BOOLEAN__) +- __GEOMETRY__ ST_Transform(geom __GEOMETRY__, source_crs __VARCHAR__, target_crs __VARCHAR__) +- __GEOMETRY__ ST_Transform(geom __GEOMETRY__, source_crs __VARCHAR__, target_crs __VARCHAR__, always_xy __BOOLEAN__) + +### Description + +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). + +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. + +### Examples + +```sql + +-- 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 +-- WebMercator. + +SELECT ST_AsText( + ST_Transform( + st_point(52.373123, 4.892360), + 'EPSG:4326', + 'EPSG:3857' + ) +); +---- +POINT (544615.0239773799 6867874.103539125) + +-- Alternatively, let's say we got our input point from e.g. a GeoJSON file, +-- 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. + +SELECT ST_AsText( + ST_Transform( + -- note the axis order is reversed here + st_point(4.892360, 52.373123), + 'EPSG:4326', + 'EPSG:3857', + always_xy := true + ) +); +---- +POINT (544615.0239773799 6867874.103539125) + + +``` + +## ST_Union + +_Returns the union of two geometries._ + +- __GEOMETRY__ ST_Union(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +Returns the union of two geometries. + +### Examples + +```sql +SELECT ST_AsText( + ST_Union( + ST_GeomFromText('POINT(1 2)'), + ST_GeomFromText('POINT(3 4)') + ) +); +---- +MULTIPOINT (1 2, 3 4) +``` + +## ST_Within + +_Returns true if geom1 is "within" geom2_ + +- __BOOLEAN__ ST_Within(point __POINT_2D__, polygon __POLYGON_2D__) +- __BOOLEAN__ ST_Within(geom1 __GEOMETRY__, geom2 __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_X + +_Returns the X coordinate of a point geometry, or NULL if not a point or empty_ + +- __DOUBLE__ ST_X(point __POINT_2D__) +- __DOUBLE__ ST_X(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_XMax + +_Returns the maximum x coordinate of a geometry_ + +- __DOUBLE__ ST_XMax(box __BOX_2D__) +- __DOUBLE__ ST_XMax(point __POINT_2D__) +- __DOUBLE__ ST_XMax(line __LINESTRING_2D__) +- __DOUBLE__ ST_XMax(polygon __POLYGON_2D__) +- __DOUBLE__ ST_XMax(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_XMin + +_Returns the minimum x coordinate of a geometry_ + +- __DOUBLE__ ST_XMin(box __BOX_2D__) +- __DOUBLE__ ST_XMin(point __POINT_2D__) +- __DOUBLE__ ST_XMin(line __LINESTRING_2D__) +- __DOUBLE__ ST_XMin(polygon __POLYGON_2D__) +- __DOUBLE__ ST_XMin(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Y + +_Returns the y coordinate of a point geometry, or NULL if not a point or empty._ + +- __DOUBLE__ ST_Y(point __POINT_2D__) +- __DOUBLE__ ST_Y(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_YMax + +_Returns the maximum y coordinate of a geometry_ + +- __DOUBLE__ ST_YMax(box __BOX_2D__) +- __DOUBLE__ ST_YMax(point __POINT_2D__) +- __DOUBLE__ ST_YMax(line __LINESTRING_2D__) +- __DOUBLE__ ST_YMax(polygon __POLYGON_2D__) +- __DOUBLE__ ST_YMax(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_YMin + +_Returns the minimum y coordinate of a geometry_ + +- __DOUBLE__ ST_YMin(box __BOX_2D__) +- __DOUBLE__ ST_YMin(point __POINT_2D__) +- __DOUBLE__ ST_YMin(line __LINESTRING_2D__) +- __DOUBLE__ ST_YMin(polygon __POLYGON_2D__) +- __DOUBLE__ ST_YMin(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +# Aggregate Functions + +| Name | 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 + +_Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries_ + +- __GEOMETRY__ ST_Envelope_Agg(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Intersection_Agg + +_Computes the intersection of a set of geometries_ + +- __GEOMETRY__ ST_Intersection_Agg(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +## ST_Union_Agg + +_Computes the union of a set of input geometries_ + +- __GEOMETRY__ ST_Union_Agg(geom __GEOMETRY__) + +### Description + +TODO + +### Examples + +TODO + +# Table Functions + +## ST_Drivers + +_Returns the list of supported GDAL drivers_ + +- ST_Drivers() + +### Description + +Returns the list of supported GDAL drivers and file formats for [ST_Read](##st_read). + +Note that far from all of these drivers have been tested properly, and some may require additional options to be passed to work as expected. If you run into any issues please first consult the [consult the GDAL docs](https://gdal.org/drivers/vector/index.html). + +### Examples + +```sql +SELECT * FROM ST_Drivers(); +``` + +| short_name | long_name | can_create | can_copy | can_open | help_url | +|----------------|------------------------------------------------------|------------|----------|----------|----------------------------------------------------| +| ESRI Shapefile | ESRI Shapefile | true | false | true | https://gdal.org/drivers/vector/shapefile.html | +| MapInfo File | MapInfo File | true | false | true | https://gdal.org/drivers/vector/mitab.html | +| UK .NTF | UK .NTF | false | false | true | https://gdal.org/drivers/vector/ntf.html | +| LVBAG | Kadaster LV BAG Extract 2.0 | false | false | true | https://gdal.org/drivers/vector/lvbag.html | +| S57 | IHO S-57 (ENC) | true | false | true | https://gdal.org/drivers/vector/s57.html | +| DGN | Microstation DGN | true | false | true | https://gdal.org/drivers/vector/dgn.html | +| OGR_VRT | VRT - Virtual Datasource | false | false | true | https://gdal.org/drivers/vector/vrt.html | +| Memory | Memory | true | false | true | | +| CSV | Comma Separated Value (.csv) | true | false | true | https://gdal.org/drivers/vector/csv.html | +| GML | Geography Markup Language (GML) | true | false | true | https://gdal.org/drivers/vector/gml.html | +| GPX | GPX | true | false | true | https://gdal.org/drivers/vector/gpx.html | +| KML | Keyhole Markup Language (KML) | true | false | true | https://gdal.org/drivers/vector/kml.html | +| GeoJSON | GeoJSON | true | false | true | https://gdal.org/drivers/vector/geojson.html | +| GeoJSONSeq | GeoJSON Sequence | true | false | true | https://gdal.org/drivers/vector/geojsonseq.html | +| ESRIJSON | ESRIJSON | false | false | true | https://gdal.org/drivers/vector/esrijson.html | +| TopoJSON | TopoJSON | false | false | true | https://gdal.org/drivers/vector/topojson.html | +| OGR_GMT | GMT ASCII Vectors (.gmt) | true | false | true | https://gdal.org/drivers/vector/gmt.html | +| GPKG | GeoPackage | true | true | true | https://gdal.org/drivers/vector/gpkg.html | +| SQLite | SQLite / Spatialite | true | false | true | https://gdal.org/drivers/vector/sqlite.html | +| WAsP | WAsP .map format | true | false | true | https://gdal.org/drivers/vector/wasp.html | +| OpenFileGDB | ESRI FileGDB | true | false | true | https://gdal.org/drivers/vector/openfilegdb.html | +| DXF | AutoCAD DXF | true | false | true | https://gdal.org/drivers/vector/dxf.html | +| CAD | AutoCAD Driver | false | false | true | https://gdal.org/drivers/vector/cad.html | +| FlatGeobuf | FlatGeobuf | true | false | true | https://gdal.org/drivers/vector/flatgeobuf.html | +| Geoconcept | Geoconcept | true | false | true | | +| GeoRSS | GeoRSS | true | false | true | https://gdal.org/drivers/vector/georss.html | +| VFK | Czech Cadastral Exchange Data Format | false | false | true | https://gdal.org/drivers/vector/vfk.html | +| PGDUMP | PostgreSQL SQL dump | true | false | false | https://gdal.org/drivers/vector/pgdump.html | +| OSM | OpenStreetMap XML and PBF | false | false | true | https://gdal.org/drivers/vector/osm.html | +| GPSBabel | GPSBabel | true | false | true | https://gdal.org/drivers/vector/gpsbabel.html | +| WFS | OGC WFS (Web Feature Service) | false | false | true | https://gdal.org/drivers/vector/wfs.html | +| OAPIF | OGC API - Features | false | false | true | https://gdal.org/drivers/vector/oapif.html | +| EDIGEO | French EDIGEO exchange format | false | false | true | https://gdal.org/drivers/vector/edigeo.html | +| SVG | Scalable Vector Graphics | false | false | true | https://gdal.org/drivers/vector/svg.html | +| ODS | Open Document/ LibreOffice / OpenOffice Spreadsheet | true | false | true | https://gdal.org/drivers/vector/ods.html | +| XLSX | MS Office Open XML spreadsheet | true | false | true | https://gdal.org/drivers/vector/xlsx.html | +| Elasticsearch | Elastic Search | true | false | true | https://gdal.org/drivers/vector/elasticsearch.html | +| Carto | Carto | true | false | true | https://gdal.org/drivers/vector/carto.html | +| AmigoCloud | AmigoCloud | true | false | true | https://gdal.org/drivers/vector/amigocloud.html | +| SXF | Storage and eXchange Format | false | false | true | https://gdal.org/drivers/vector/sxf.html | +| Selafin | Selafin | true | false | true | https://gdal.org/drivers/vector/selafin.html | +| JML | OpenJUMP JML | true | false | true | https://gdal.org/drivers/vector/jml.html | +| PLSCENES | Planet Labs Scenes API | false | false | true | https://gdal.org/drivers/vector/plscenes.html | +| CSW | OGC CSW (Catalog Service for the Web) | false | false | true | https://gdal.org/drivers/vector/csw.html | +| VDV | VDV-451/VDV-452/INTREST Data Format | true | false | true | https://gdal.org/drivers/vector/vdv.html | +| MVT | Mapbox Vector Tiles | true | false | true | https://gdal.org/drivers/vector/mvt.html | +| NGW | NextGIS Web | true | true | true | https://gdal.org/drivers/vector/ngw.html | +| MapML | MapML | true | false | true | https://gdal.org/drivers/vector/mapml.html | +| PMTiles | ProtoMap Tiles | true | false | true | https://gdal.org/drivers/vector/pmtiles.html | +| JSONFG | OGC Features and Geometries JSON | true | false | true | https://gdal.org/drivers/vector/jsonfg.html | +| TIGER | U.S. Census TIGER/Line | false | false | true | https://gdal.org/drivers/vector/tiger.html | +| AVCBin | Arc/Info Binary Coverage | false | false | true | https://gdal.org/drivers/vector/avcbin.html | +| AVCE00 | Arc/Info E00 (ASCII) Coverage | false | false | true | https://gdal.org/drivers/vector/avce00.html | + +## ST_Read + +_Import data from a variety of geospatial file formats_ + +- ST_Read(path __VARCHAR__, sequential_layer_scan __BOOLEAN__, max_batch_size __INTEGER__, keep_wkb __BOOLEAN__, layer __VARCHAR__, allowed_drivers __VARCHAR[]__, spatial_filter __WKB_BLOB__, spatial_filter_box __BOX_2D__, sibling_files __VARCHAR[]__, open_options __VARCHAR[]__) + +### Description + + +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. + +Except for the `path` parameter, all parameters are optional. + +| Parameter | Type | Description | +| --------- | -----| ----------- | +| `path` | VARCHAR | The path to the file to read. Mandatory | +| `sequential_layer_scan` | BOOLEAN | If set to true, the table function will scan through all layers sequentially and return the first layer that matches the given layer name. This is required for some drivers to work properly, e.g., the OSM driver. | +| `spatial_filter` | WKB_BLOB | If set to a WKB blob, the table function will only return rows that intersect with the given WKB geometry. Some drivers may support efficient spatial filtering natively, in which case it will be pushed down. Otherwise the filtering is done by GDAL which may be much slower. | +| `open_options` | VARCHAR[] | A list of key-value pairs that are passed to the GDAL driver to control the opening of the file. E.g., the GeoJSON driver supports a FLATTEN_NESTED_ATTRIBUTES=YES option to flatten nested attributes. | +| `layer` | VARCHAR | The name of the layer to read from the file. If NULL, the first layer is returned. Can also be a layer index (starting at 0). | +| `allowed_drivers` | VARCHAR[] | A list of GDAL driver names that are allowed to be used to open the file. If empty, all drivers are allowed. | +| `sibling_files` | VARCHAR[] | A list of sibling files that are required to open the file. E.g., the ESRI Shapefile driver requires a .shx file to be present. Although most of the time these can be discovered automatically. | +| `spatial_filter_box` | BOX_2D | If set to a BOX_2D, the table function will only return rows that intersect with the given bounding box. Similar to spatial_filter. | +| `keep_wkb` | BOOLEAN | If set, the table function will return geometries in a wkb_geometry column with the type WKB_BLOB (which can be cast to BLOB) instead of GEOMETRY. This is useful if you want to use DuckDB with more exotic geometry subtypes that DuckDB spatial doesnt support representing in the GEOMETRY type yet. | + +Note that GDAL is single-threaded, so this table function will not be able to make full use of parallelism. + +### Examples + +```sql +-- Read a Shapefile +SELECT * FROM ST_Read('some/file/path/filename.shp'); + +-- Read a GeoJSON file +CREATE TABLE my_geojson_table AS SELECT * FROM ST_Read('some/file/path/filename.json'); + +``` + +### Replacement scans + +By using `ST_Read`, the spatial extension also provides “replacement scans” for common geospatial file formats, allowing you to query files of these formats as if they were tables directly. + +```sql +SELECT * FROM './path/to/some/shapefile/dataset.shp'; +``` + +In practice this is just syntax-sugar for calling ST_Read, so there is no difference in performance. If you want to pass additional options, you should use the ST_Read table function directly. + +The following formats are currently recognized by their file extension: + +| Format | Extension | +| ------ | --------- | +| ESRI ShapeFile | .shp | +| GeoPackage | .gpkg | +| FlatGeoBuf | .fgb | + +## ST_ReadOSM + +_Reads compressed OpenStreetMap data_ + +- ST_ReadOSM(path __VARCHAR__) + +### Description + +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. + +### Examples + +```sql +SELECT * +FROM ST_ReadOSM('tmp/data/germany.osm.pbf') +WHERE tags['highway'] != [] +LIMIT 5; +``` + +``` +┌──────────────────────┬────────┬──────────────────────┬─────────┬────────────────────┬────────────┬───────────┬────────────────────────┐ +│ kind │ id │ tags │ refs │ lat │ lon │ ref_roles │ ref_types │ +│ enum('node', 'way'… │ int64 │ map(varchar, varch… │ int64[] │ double │ double │ varchar[] │ enum('node', 'way', … │ +├──────────────────────┼────────┼──────────────────────┼─────────┼────────────────────┼────────────┼───────────┼────────────────────────┤ +│ node │ 122351 │ {bicycle=yes, butt… │ │ 53.5492951 │ 9.977553 │ │ │ +│ node │ 122397 │ {crossing=no, high… │ │ 53.520990100000006 │ 10.0156924 │ │ │ +│ node │ 122493 │ {TMC:cid_58:tabcd_… │ │ 53.129614600000004 │ 8.1970173 │ │ │ +│ node │ 123566 │ {highway=traffic_s… │ │ 54.617268200000005 │ 8.9718171 │ │ │ +│ node │ 125801 │ {TMC:cid_58:tabcd_… │ │ 53.070685000000005 │ 8.7819939 │ │ │ +└──────────────────────┴────────┴──────────────────────┴─────────┴────────────────────┴────────────┴───────────┴────────────────────────┘ +``` + +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: + +```sql +SELECT * FROM 'tmp/data/germany.osm.pbf' LIMIT 5; +``` + +# Functions by tag + +__construction__ +- [ST_Envelope_Agg](##st_envelope_agg) +- [ST_Intersection_Agg](##st_intersection_agg) +- [ST_Union_Agg](##st_union_agg) +- [ST_Boundary](##st_boundary) +- [ST_Collect](##st_collect) +- [ST_CollectionExtract](##st_collectionextract) +- [ST_Difference](##st_difference) +- [ST_Dump](##st_dump) +- [ST_Envelope](##st_envelope) +- [ST_ExteriorRing](##st_exteriorring) +- [ST_FlipCoordinates](##st_flipcoordinates) +- [ST_LineMerge](##st_linemerge) +- [ST_MakeLine](##st_makeline) +- [ST_MakePolygon](##st_makepolygon) +- [ST_Normalize](##st_normalize) +- [ST_Point](##st_point) +- [ST_Point2D](##st_point2d) +- [ST_Point3D](##st_point3d) +- [ST_Point4D](##st_point4d) +- [ST_PointN](##st_pointn) +- [ST_PointOnSurface](##st_pointonsurface) +- [ST_RemoveRepeatedPoints](##st_removerepeatedpoints) +- [ST_Reverse](##st_reverse) +- [ST_SimplifyPreserveTopology](##st_simplifypreservetopology) +- [ST_StartPoint](##st_startpoint) +- [ST_Transform](##st_transform) + +__property__ +- [ST_Area](##st_area) +- [ST_Area_Spheroid](##st_area_spheroid) +- [ST_Centroid](##st_centroid) +- [ST_Dimension](##st_dimension) +- [ST_Distance](##st_distance) +- [ST_EndPoint](##st_endpoint) +- [ST_GeometryType](##st_geometrytype) +- [ST_Intersects](##st_intersects) +- [ST_IsClosed](##st_isclosed) +- [ST_IsEmpty](##st_isempty) +- [ST_IsRing](##st_isring) +- [ST_IsSimple](##st_issimple) +- [ST_IsValid](##st_isvalid) +- [ST_Length](##st_length) +- [ST_Length_Spheroid](##st_length_spheroid) +- [ST_NumGeometries](##st_numgeometries) +- [ST_NumInteriorRings](##st_numinteriorrings) +- [ST_NumPoints](##st_numpoints) +- [ST_Perimeter](##st_perimeter) +- [ST_Perimeter_Spheroid](##st_perimeter_spheroid) +- [ST_X](##st_x) +- [ST_XMax](##st_xmax) +- [ST_XMin](##st_xmin) +- [ST_Y](##st_y) +- [ST_YMax](##st_ymax) +- [ST_YMin](##st_ymin) + +__spheroid__ +- [ST_Area_Spheroid](##st_area_spheroid) +- [ST_Distance_Spheroid](##st_distance_spheroid) +- [ST_Length_Spheroid](##st_length_spheroid) +- [ST_Perimeter_Spheroid](##st_perimeter_spheroid) + +__conversion__ +- [ST_AsGeoJSON](##st_asgeojson) +- [ST_AsHEXWKB](##st_ashexwkb) +- [ST_AsText](##st_astext) +- [ST_AsWKB](##st_aswkb) +- [ST_GeomFromGeoJSON](##st_geomfromgeojson) +- [ST_GeomFromHEXEWKB](##st_geomfromhexewkb) +- [ST_GeomFromHEXWKB](##st_geomfromhexwkb) +- [ST_GeomFromText](##st_geomfromtext) +- [ST_GeomFromWKB](##st_geomfromwkb) +- [ST_LineString2DFromWKB](##st_linestring2dfromwkb) +- [ST_Point2DFromWKB](##st_point2dfromwkb) +- [ST_Polygon2DFromWKB](##st_polygon2dfromwkb) + +__relation__ +- [ST_Contains](##st_contains) +- [ST_ContainsProperly](##st_containsproperly) +- [ST_CoveredBy](##st_coveredby) +- [ST_Covers](##st_covers) +- [ST_Crosses](##st_crosses) +- [ST_Distance_Spheroid](##st_distance_spheroid) +- [ST_DWithin](##st_dwithin) +- [ST_DWithin_Spheroid](##st_dwithin_spheroid) +- [ST_Intersection](##st_intersection) +- [ST_Intersects_Extent](##st_intersects_extent) +- [ST_Overlaps](##st_overlaps) +- [ST_Touches](##st_touches) +- [ST_Within](##st_within) + diff --git a/docs/src/README.md b/docs/src/README.md new file mode 100644 index 00000000..9a3c3037 --- /dev/null +++ b/docs/src/README.md @@ -0,0 +1,80 @@ +# DuckDB Spatial Docs + +This directory contains the source code for the DuckDB Spatial documentation. + +## Building the docs + +The full `docs.md` file is generated from the source files in this directory (`/docs/src/`) using a simple `generate.py` python3 script that lightly formats and concatenates a bunch of separate markdown files. To build the docs, simply run: + +```bash +python3 generate.py +``` + +and the `docs.md` file will be generated in the parent directory (`/docs/docs.md`) + +## Writing docs +The docs are written in Markdown, with some additional metadata stored in a json "frontmatter". The metadata is used to generate the `docs.md` file. Each function has its own file, with the filename corresponding to the function name. For example, the `ST_AsGeoJSON` function is documented in the `/functions/scalar/st_asgeojson.md` file. These file are the source of truth for the documentation, and the `docs.md` file is generated from these files. + +**Do not edit the `docs.md` file directly**. + +### Frontmatter +The frontmatter is a json object that contains metadata about the documentation item. The frontmatter is enclosed in a pair of `---` lines, and is the first thing in the file. For example, the frontmatter for the `ST_AsGeoJSON` function is: + +```json +--- +{ + "id": "st_asgeojson", + "title": "ST_AsGeoJSON", + "type": "scalar_function", + "signatures": [ + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Returns the geometry as a GeoJSON fragment", + "tags": [ + "conversion" + ] +} +--- +``` + +The frontmatter always contains the following fields: + +| Field | Description | +| --- | --- | +| `type` | The documentation item type. e.g. `scalar_function`, `aggregate_function`, `table_function` | +| `id` | The documentation item id (unique, used internally by the doc generator) | + +#### Functions +Scalar and aggregate functions have the following additional fields: + +| Field | Description | +| --- | --- | +| `title` | The function title (capitalized, human friendly name) | +| `signatures` | An array of function signatures. See signatures below | +| `aliases` | An array of function aliases. | +| `summary` | A short summary of the function | +| `tags` | An array of tags for the function. e.g. `conversion`, `geometry`, `measurement` | + +Since functions can be overloaded, the `signatures` field is an array of function signatures. Each signature has the following fields: + +| Field | Description | +| --- | --- | +| `returns` | The return type of the function, in SQL | +| `parameters` | An array of function parameters. See parameters below | + +Each function parameter has the following fields: + +| Field | Description | +| --- | --- | +| `name` | The parameter name | +| `type` | The parameter type, in SQL | + diff --git a/docs/src/aggregate_functions.json b/docs/src/aggregate_functions.json new file mode 100644 index 00000000..0ead933a --- /dev/null +++ b/docs/src/aggregate_functions.json @@ -0,0 +1,3 @@ +{"type":"aggregate_function","id":"st_intersection_agg","title":"ST_Intersection_Agg","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"aggregate_function","id":"st_envelope_agg","title":"ST_Envelope_Agg","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"aggregate_function","id":"st_union_agg","title":"ST_Union_Agg","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} diff --git a/docs/src/functions/aggregate/st_envelope_agg.md b/docs/src/functions/aggregate/st_envelope_agg.md new file mode 100644 index 00000000..10d84d0c --- /dev/null +++ b/docs/src/functions/aggregate/st_envelope_agg.md @@ -0,0 +1,31 @@ +--- +{ + "type": "aggregate_function", + "title": "ST_Envelope_Agg", + "id": "st_envelope_agg", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/aggregate/st_intersection_agg.md b/docs/src/functions/aggregate/st_intersection_agg.md new file mode 100644 index 00000000..7f3ab916 --- /dev/null +++ b/docs/src/functions/aggregate/st_intersection_agg.md @@ -0,0 +1,31 @@ +--- +{ + "type": "aggregate_function", + "title": "ST_Intersection_Agg", + "id": "st_intersection_agg", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Computes the intersection of a set of geometries", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/aggregate/st_union_agg.md b/docs/src/functions/aggregate/st_union_agg.md new file mode 100644 index 00000000..d70c3f60 --- /dev/null +++ b/docs/src/functions/aggregate/st_union_agg.md @@ -0,0 +1,31 @@ +--- +{ + "type": "aggregate_function", + "title": "ST_Union_Agg", + "id": "st_union_agg", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Computes the union of a set of input geometries", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_area.md b/docs/src/functions/scalar/st_area.md new file mode 100644 index 00000000..ead5899a --- /dev/null +++ b/docs/src/functions/scalar/st_area.md @@ -0,0 +1,73 @@ +--- +{ + "id": "st_area", + "title": "ST_Area", + "type": "scalar_function", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point_2D", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "linestring_2d", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon_2d", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + } + ], + "aliases": [], + "summary": "Returns the area of a geometry.", + "see_also": [ "st_area_spheroid", "st_perimeter" ], + "tags": [ "property" ] +} +--- + +### Description + +Compute the area of a geometry. + +Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + +The `POINT_2D` and `LINESTRING_2D` variants of this function always return `0.0` but are included for completeness. + +### Examples + +```sql +select ST_Area('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +-- 1.0 +``` \ No newline at end of file diff --git a/docs/src/functions/scalar/st_area_spheroid.md b/docs/src/functions/scalar/st_area_spheroid.md new file mode 100644 index 00000000..c365b9b0 --- /dev/null +++ b/docs/src/functions/scalar/st_area_spheroid.md @@ -0,0 +1,44 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Area_Spheroid", + "id": "st_area_spheroid", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geometry", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the area of a geometry in meters, using an ellipsoidal model of the earth", + "tags": [ + "property", + "spheroid" + ] +} +--- + +### Description + +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 area is returned in square meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the area using an ellipsoidal model of the earth. This is a highly accurate method for calculating the area of a polygon taking the curvature of the earth into account, but is also the slowest. + +Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_asgeojson.md b/docs/src/functions/scalar/st_asgeojson.md new file mode 100644 index 00000000..b77c782d --- /dev/null +++ b/docs/src/functions/scalar/st_asgeojson.md @@ -0,0 +1,38 @@ +--- +{ + "id": "st_asgeojson", + "title": "ST_AsGeoJSON", + "type": "scalar_function", + "signatures": [ + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Returns the geometry as a GeoJSON fragment", + "tags": [ + "conversion" + ] +} +--- + +### Description + +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. + +### Examples + +```sql +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]]]} + +``` \ No newline at end of file diff --git a/docs/src/functions/scalar/st_ashexwkb.md b/docs/src/functions/scalar/st_ashexwkb.md new file mode 100644 index 00000000..13bff24b --- /dev/null +++ b/docs/src/functions/scalar/st_ashexwkb.md @@ -0,0 +1,37 @@ +--- +{ + "id": "st_ashexwkb", + "title": "ST_AsHEXWKB", + "type": "scalar_function", + "signatures": [ + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Returns the geometry as a HEXWKB string", + "description": "Actually returns HEXEWKB", + "tags": [ + "conversion" + ], + "see_also": [ + "st_aswkb" + ] +} +--- + +### Description + +Returns the geometry as a HEXWKB string + +### Examples + +```sql +select st_ashexwkb('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +``` \ No newline at end of file diff --git a/docs/src/functions/scalar/st_astext.md b/docs/src/functions/scalar/st_astext.md new file mode 100644 index 00000000..3b1421a2 --- /dev/null +++ b/docs/src/functions/scalar/st_astext.md @@ -0,0 +1,69 @@ +--- +{ + "id": "st_astext", + "title": "ST_AsText", + "type": "scalar_function", + "signatures": [ + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "point_2d", + "type": "POINT_2D" + } + ] + }, + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "linestring_2d", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "polygon_2d", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "VARCHAR", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + } + ], + "aliases": [], + "summary": "Returns the geometry as a WKT string", + "tags": [ + "conversion" + ] +} +--- + +### Description + +Returns the geometry as a WKT string + +### Examples + +```sql +select st_astext('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +``` \ No newline at end of file diff --git a/docs/src/functions/scalar/st_aswkb.md b/docs/src/functions/scalar/st_aswkb.md new file mode 100644 index 00000000..8a7ffa0c --- /dev/null +++ b/docs/src/functions/scalar/st_aswkb.md @@ -0,0 +1,33 @@ +--- +{ + "id": "st_aswkb", + "title": "ST_AsWKB", + "type": "scalar_function", + "signatures": [ + { + "returns": "WKB_BLOB", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Returns the geometry as a WKB blob", + "tags": [ + "conversion" + ] +} +--- + +### Description + +Returns the geometry as a WKB blob + +### Examples + +```sql +select st_aswkb('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +``` diff --git a/docs/src/functions/scalar/st_boundary.md b/docs/src/functions/scalar/st_boundary.md new file mode 100644 index 00000000..59f16607 --- /dev/null +++ b/docs/src/functions/scalar/st_boundary.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Boundary", + "id": "st_boundary", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geometry", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the \"boundary\" of a geometry", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_buffer.md b/docs/src/functions/scalar/st_buffer.md new file mode 100644 index 00000000..97893c70 --- /dev/null +++ b/docs/src/functions/scalar/st_buffer.md @@ -0,0 +1,49 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Buffer", + "id": "st_buffer", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "distance", + "type": "DOUBLE" + }, + { + "name": "num_triangles", + "type": "INTEGER" + } + ] + } + ], + "summary": "Returns a buffer around the input geometry at the target distance" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_centroid.md b/docs/src/functions/scalar/st_centroid.md new file mode 100644 index 00000000..b3171fda --- /dev/null +++ b/docs/src/functions/scalar/st_centroid.md @@ -0,0 +1,72 @@ +--- +{ + "id": "st_centroid", + "title": "ST_Centroid", + "type": "scalar_function", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "point_2d", + "type": "POINT_2D" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "linestring_2d", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "polygon_2d", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + } + ], + "aliases": [], + "summary": "Returns the centroid of a geometry.", + "tags": [ + "property" + ] +} +--- + +### Description + +Calculate the centroid of the geometry + +### Examples + +```sql +select st_centroid('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +-- POINT(0.5 0.5) +``` + +End of example diff --git a/docs/src/functions/scalar/st_collect.md b/docs/src/functions/scalar/st_collect.md new file mode 100644 index 00000000..8963e503 --- /dev/null +++ b/docs/src/functions/scalar/st_collect.md @@ -0,0 +1,31 @@ +--- + { + "id": "st_collect", + "title": "ST_Collect", + "type": "scalar_function", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geometries", + "type": "GEOMETRY[]" + } + ] + } + ], + "aliases": [], + "summary": "Collects geometries into a collection geometry", + "tags": [ + "construction" + ] +} +--- + +### Description + +Collects a list of geometries into a collection geometry + +### Examples + +TODO diff --git a/docs/src/functions/scalar/st_collectionextract.md b/docs/src/functions/scalar/st_collectionextract.md new file mode 100644 index 00000000..b280d752 --- /dev/null +++ b/docs/src/functions/scalar/st_collectionextract.md @@ -0,0 +1,47 @@ +--- +{ + "id": "st_collectionextract", + "title": "ST_CollectionExtract", + "type": "scalar_function", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "dimension", + "type": "INTEGER" + } + ] + } + ], + "aliases": [], + "summary": "Extracts a sub-geometry from a collection geometry", + "tags": [ + "construction" + ] +} +--- + +### Description + +Extracts a sub-geometry from a collection geometry + +### Examples + +```sql +select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1); +-- POINT(1 2) +``` diff --git a/docs/src/functions/scalar/st_contains.md b/docs/src/functions/scalar/st_contains.md new file mode 100644 index 00000000..c06a1f41 --- /dev/null +++ b/docs/src/functions/scalar/st_contains.md @@ -0,0 +1,54 @@ +--- +{ + "id": "st_contains", + "title": "ST_Contains", + "type": "scalar_function", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "polygon_2d", + "type": "POLYGON_2D" + }, + { + "name": "point", + "type": "POINT_2D" + } + ] + } + ], + "aliases": [], + "summary": "Returns true if geom1 contains geom2.", + "tags": [ + "relation" + ], + "see_also": [ + "st_within" + ] +} +--- + +### Description + +Returns true if geom1 contains geom2. + +### Examples + +```sql +select st_contains('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry, 'POINT(0.5 0.5)'::geometry); +-- true +``` diff --git a/docs/src/functions/scalar/st_containsproperly.md b/docs/src/functions/scalar/st_containsproperly.md new file mode 100644 index 00000000..a1f3b7f9 --- /dev/null +++ b/docs/src/functions/scalar/st_containsproperly.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_ContainsProperly", + "id": "st_containsproperly", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if geom1 \"properly contains\" geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_convexhull.md b/docs/src/functions/scalar/st_convexhull.md new file mode 100644 index 00000000..2000d7ec --- /dev/null +++ b/docs/src/functions/scalar/st_convexhull.md @@ -0,0 +1,28 @@ +--- +{ + "type": "scalar_function", + "title": "ST_ConvexHull", + "id": "st_convexhull", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "col0", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the convex hull enclosing the geometry" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_coveredby.md b/docs/src/functions/scalar/st_coveredby.md new file mode 100644 index 00000000..66548755 --- /dev/null +++ b/docs/src/functions/scalar/st_coveredby.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_CoveredBy", + "id": "st_coveredby", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if geom1 is \"covered\" by geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_covers.md b/docs/src/functions/scalar/st_covers.md new file mode 100644 index 00000000..3ee490ac --- /dev/null +++ b/docs/src/functions/scalar/st_covers.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Covers", + "id": "st_covers", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns if geom1 \"covers\" geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_crosses.md b/docs/src/functions/scalar/st_crosses.md new file mode 100644 index 00000000..004b129e --- /dev/null +++ b/docs/src/functions/scalar/st_crosses.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Crosses", + "id": "st_crosses", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if geom1 \"crosses\" geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_difference.md b/docs/src/functions/scalar/st_difference.md new file mode 100644 index 00000000..39e55b1f --- /dev/null +++ b/docs/src/functions/scalar/st_difference.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Difference", + "id": "st_difference", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the \"difference\" between two geometries", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_dimension.md b/docs/src/functions/scalar/st_dimension.md new file mode 100644 index 00000000..d68b79eb --- /dev/null +++ b/docs/src/functions/scalar/st_dimension.md @@ -0,0 +1,37 @@ +--- +{ + "id": "st_dimension", + "title": "ST_Dimension", + "type": "scalar_function", + "signatures": [ + { + "returns": "INTEGER", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Returns the dimension of a geometry.", + "tags": [ + "property" + ], + "see_also": [ + "st_geometrytype" + ] +} +--- + +### Description + +Returns the dimension of a geometry. + +### Examples + +```sql +select st_dimension('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'::geometry); +-- 2 +``` diff --git a/docs/src/functions/scalar/st_disjoint.md b/docs/src/functions/scalar/st_disjoint.md new file mode 100644 index 00000000..314244e1 --- /dev/null +++ b/docs/src/functions/scalar/st_disjoint.md @@ -0,0 +1,32 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Disjoint", + "id": "st_disjoint", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "col0", + "type": "GEOMETRY" + }, + { + "name": "col1", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns if two geometries are disjoint" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_distance.md b/docs/src/functions/scalar/st_distance.md new file mode 100644 index 00000000..8b36c780 --- /dev/null +++ b/docs/src/functions/scalar/st_distance.md @@ -0,0 +1,84 @@ +--- +{ + "id": "st_distance", + "title": "ST_Distance", + "type": "scalar_function", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point1", + "type": "POINT_2D" + }, + { + "name": "point2", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + }, + { + "name": "linestring_2d", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "linestring_2d", + "type": "LINESTRING_2D" + }, + { + "name": "point", + "type": "POINT_2D" + } + ] + } + ], + "aliases": [], + "summary": "Returns the distance between two geometries.", + "description": "/functions/scalar/st_distance.md", + "example": "/functions/scalar/st_distance_example.md", + "see_also": [ + "st_distance_spheroid" + ], + "tags": [ + "property" + ] +} +--- + +### Description + +Returns the distance between two geometries. + +### Examples + +```sql +select st_distance('POINT(0 0)'::geometry, 'POINT(1 1)'::geometry); +-- 1.4142135623731 +``` + +End of example diff --git a/docs/src/functions/scalar/st_distance_spheroid.md b/docs/src/functions/scalar/st_distance_spheroid.md new file mode 100644 index 00000000..04f2537a --- /dev/null +++ b/docs/src/functions/scalar/st_distance_spheroid.md @@ -0,0 +1,45 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Distance_Spheroid", + "id": "st_distance_spheroid", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + }, + { + "name": "p2", + "type": "POINT_2D" + } + ] + } + ], + "summary": "Returns the distance between two geometries in meters using a ellipsoidal model of the earths surface", + "tags": [ + "relation", + "spheroid" + ] +} +--- + +### Description + +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. + +### Examples + +```sql +-- Note: the coordinates are in WGS84 and [latitude, longitude] axis order +-- Whats the distance between New York and Amsterdam (JFK and AMS airport)? +SELECT st_distance_spheroid( + st_point(40.6446, 73.7797), + st_point(52.3130, 4.7725) +); +---- +5243187.666873225 +-- Roughly 5243km! +``` \ No newline at end of file diff --git a/docs/src/functions/scalar/st_dump.md b/docs/src/functions/scalar/st_dump.md new file mode 100644 index 00000000..31567267 --- /dev/null +++ b/docs/src/functions/scalar/st_dump.md @@ -0,0 +1,34 @@ +--- +{ + "id": "st_dump", + "title": "ST_Dump", + "type": "scalar_function", + "signatures": [ + { + "returns": "STRUCT(geom GEOMETRY, path INTEGER[])[]", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Dumps a geometry into a set of sub-geometries", + "tags": [ + "construction" + ] +} +--- + +### Description + +Dumps a geometry into a set of sub-geometries and their "path" in the original geometry. + +### Examples + +```sql +select st_dump('MULTIPOINT(1 2,3 4)'::geometry); +-- [{'geom': 'POINT(1 2)', 'path': [0]}, {'geom': 'POINT(3 4)', 'path': [1]}] +``` \ No newline at end of file diff --git a/docs/src/functions/scalar/st_dwithin.md b/docs/src/functions/scalar/st_dwithin.md new file mode 100644 index 00000000..1b3b6f76 --- /dev/null +++ b/docs/src/functions/scalar/st_dwithin.md @@ -0,0 +1,39 @@ +--- +{ + "type": "scalar_function", + "title": "ST_DWithin", + "id": "st_dwithin", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Returns if two geometries are within a target distance of eachother", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_dwithin_spheroid.md b/docs/src/functions/scalar/st_dwithin_spheroid.md new file mode 100644 index 00000000..8cba020e --- /dev/null +++ b/docs/src/functions/scalar/st_dwithin_spheroid.md @@ -0,0 +1,39 @@ +--- +{ + "type": "scalar_function", + "title": "ST_DWithin_Spheroid", + "id": "st_dwithin_spheroid", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "p1", + "type": "POINT_2D" + }, + { + "name": "p2", + "type": "POINT_2D" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Returns if two POINT_2D's are within a target distance in meters, using an ellipsoidal model of the earths surface", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_endpoint.md b/docs/src/functions/scalar/st_endpoint.md new file mode 100644 index 00000000..b971fbb3 --- /dev/null +++ b/docs/src/functions/scalar/st_endpoint.md @@ -0,0 +1,43 @@ +--- +{ + "id": "st_endpoint", + "title": "ST_EndPoint", + "type": "scalar_function", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "line", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + } + ], + "aliases": [], + "summary": "Returns the end point of a line.", + "tags": [ + "property" + ] +} +--- + +### Description + +Returns the end point of a line. + +### Examples + +```sql +select st_endpoint('LINESTRING(0 0, 1 1)'::geometry); +-- POINT(1 1) +``` diff --git a/docs/src/functions/scalar/st_envelope.md b/docs/src/functions/scalar/st_envelope.md new file mode 100644 index 00000000..7e0f34b6 --- /dev/null +++ b/docs/src/functions/scalar/st_envelope.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Envelope", + "id": "st_envelope", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the minimum bounding box for the input geometry as a polygon geometry.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_equals.md b/docs/src/functions/scalar/st_equals.md new file mode 100644 index 00000000..b9759692 --- /dev/null +++ b/docs/src/functions/scalar/st_equals.md @@ -0,0 +1,32 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Equals", + "id": "st_equals", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Compares two geometries for equality" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_extent.md b/docs/src/functions/scalar/st_extent.md new file mode 100644 index 00000000..0a94c69e --- /dev/null +++ b/docs/src/functions/scalar/st_extent.md @@ -0,0 +1,28 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Extent", + "id": "st_extent", + "signatures": [ + { + "returns": "BOX_2D", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the minimal bounding box enclosing the input geometry" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_exteriorring.md b/docs/src/functions/scalar/st_exteriorring.md new file mode 100644 index 00000000..0043e90c --- /dev/null +++ b/docs/src/functions/scalar/st_exteriorring.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_ExteriorRing", + "id": "st_exteriorring", + "signatures": [ + { + "returns": "LINESTRING_2D", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the exterior ring (shell) of a polygon geometry.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_flipcoordinates.md b/docs/src/functions/scalar/st_flipcoordinates.md new file mode 100644 index 00000000..cf0bba5f --- /dev/null +++ b/docs/src/functions/scalar/st_flipcoordinates.md @@ -0,0 +1,67 @@ +--- +{ + "type": "scalar_function", + "title": "ST_FlipCoordinates", + "id": "st_flipcoordinates", + "signatures": [ + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "LINESTRING_2D", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "POLYGON_2D", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "BOX_2D", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns a new geometry with the coordinates of the input geometry \"flipped\" so that x = y and y = x.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_geometrytype.md b/docs/src/functions/scalar/st_geometrytype.md new file mode 100644 index 00000000..6599db68 --- /dev/null +++ b/docs/src/functions/scalar/st_geometrytype.md @@ -0,0 +1,58 @@ +--- +{ + "type": "scalar_function", + "title": "ST_GeometryType", + "id": "st_geometrytype", + "signatures": [ + { + "returns": "ANY", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "ANY", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "ANY", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "ANY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns a 'GEOMETRY_TYPE' enum identifying the input geometry type.", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_geomfromgeojson.md b/docs/src/functions/scalar/st_geomfromgeojson.md new file mode 100644 index 00000000..1b76376b --- /dev/null +++ b/docs/src/functions/scalar/st_geomfromgeojson.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_GeomFromGeoJSON", + "id": "st_geomfromgeojson", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geojson", + "type": "VARCHAR" + } + ] + } + ], + "summary": "Deserializes a GEOMETRY from a GeoJSON fragment.", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_geomfromhexewkb.md b/docs/src/functions/scalar/st_geomfromhexewkb.md new file mode 100644 index 00000000..51eb25ab --- /dev/null +++ b/docs/src/functions/scalar/st_geomfromhexewkb.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_GeomFromHEXEWKB", + "id": "st_geomfromhexewkb", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "hexewkb", + "type": "VARCHAR" + } + ] + } + ], + "summary": "Deserialize a GEOMETRY from a HEXEWKB encoded string", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_geomfromhexwkb.md b/docs/src/functions/scalar/st_geomfromhexwkb.md new file mode 100644 index 00000000..426f768b --- /dev/null +++ b/docs/src/functions/scalar/st_geomfromhexwkb.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_GeomFromHEXWKB", + "id": "st_geomfromhexwkb", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "hexwkb", + "type": "VARCHAR" + } + ] + } + ], + "summary": "Creates a GEOMETRY from a HEXWKB string", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_geomfromtext.md b/docs/src/functions/scalar/st_geomfromtext.md new file mode 100644 index 00000000..2f49473d --- /dev/null +++ b/docs/src/functions/scalar/st_geomfromtext.md @@ -0,0 +1,44 @@ +--- +{ + "type": "scalar_function", + "title": "ST_GeomFromText", + "id": "st_geomfromtext", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "wkt", + "type": "VARCHAR" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "wkt", + "type": "VARCHAR" + }, + { + "name": "ignore_invalid", + "type": "BOOLEAN" + } + ] + } + ], + "summary": "Deserializes a GEOMETRY from a WKT string, optionally ignoring invalid geometries", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_geomfromwkb.md b/docs/src/functions/scalar/st_geomfromwkb.md new file mode 100644 index 00000000..ae0b97da --- /dev/null +++ b/docs/src/functions/scalar/st_geomfromwkb.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_GeomFromWKB", + "id": "st_geomfromwkb", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "blob", + "type": "WKB_BLOB" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "blob", + "type": "BLOB" + } + ] + } + ], + "summary": "Deserializes a GEOMETRY from a WKB encoded blob", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_intersection.md b/docs/src/functions/scalar/st_intersection.md new file mode 100644 index 00000000..e3d41a89 --- /dev/null +++ b/docs/src/functions/scalar/st_intersection.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Intersection", + "id": "st_intersection", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the \"intersection\" of geom1 and geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_intersects.md b/docs/src/functions/scalar/st_intersects.md new file mode 100644 index 00000000..ce0a803f --- /dev/null +++ b/docs/src/functions/scalar/st_intersects.md @@ -0,0 +1,48 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Intersects", + "id": "st_intersects", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "box1", + "type": "BOX_2D" + }, + { + "name": "box2", + "type": "BOX_2D" + } + ] + }, + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if two geometries intersects", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_intersects_extent.md b/docs/src/functions/scalar/st_intersects_extent.md new file mode 100644 index 00000000..b8dcd538 --- /dev/null +++ b/docs/src/functions/scalar/st_intersects_extent.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Intersects_Extent", + "id": "st_intersects_extent", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if the extent of two geometries intersects", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_isclosed.md b/docs/src/functions/scalar/st_isclosed.md new file mode 100644 index 00000000..91886966 --- /dev/null +++ b/docs/src/functions/scalar/st_isclosed.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_IsClosed", + "id": "st_isclosed", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if a geometry is \"closed\"", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_isempty.md b/docs/src/functions/scalar/st_isempty.md new file mode 100644 index 00000000..755af543 --- /dev/null +++ b/docs/src/functions/scalar/st_isempty.md @@ -0,0 +1,49 @@ +--- +{ + "type": "scalar_function", + "title": "ST_IsEmpty", + "id": "st_isempty", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if the geometry is \"empty\"", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_isring.md b/docs/src/functions/scalar/st_isring.md new file mode 100644 index 00000000..609230b0 --- /dev/null +++ b/docs/src/functions/scalar/st_isring.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_IsRing", + "id": "st_isring", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "line", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if the input line geometry is a ring (both ST_IsClosed and ST_IsSimple).", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_issimple.md b/docs/src/functions/scalar/st_issimple.md new file mode 100644 index 00000000..30b7bb19 --- /dev/null +++ b/docs/src/functions/scalar/st_issimple.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_IsSimple", + "id": "st_issimple", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if the input geometry is \"simple\"", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_isvalid.md b/docs/src/functions/scalar/st_isvalid.md new file mode 100644 index 00000000..160f4262 --- /dev/null +++ b/docs/src/functions/scalar/st_isvalid.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_IsValid", + "id": "st_isvalid", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if the geometry is topologically \"valid\"", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_length.md b/docs/src/functions/scalar/st_length.md new file mode 100644 index 00000000..a7b2fc42 --- /dev/null +++ b/docs/src/functions/scalar/st_length.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Length", + "id": "st_length", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the length of the input line geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_length_spheroid.md b/docs/src/functions/scalar/st_length_spheroid.md new file mode 100644 index 00000000..c6167c68 --- /dev/null +++ b/docs/src/functions/scalar/st_length_spheroid.md @@ -0,0 +1,43 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Length_Spheroid", + "id": "st_length_spheroid", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the length of the input geometry in meters, using a ellipsoidal model of the earth", + "tags": [ + "property", "spheroid" + ] +} +--- + +### Description + +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 length is returned in square meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the length using an ellipsoidal model of the earth. This is a highly accurate method for calculating the length of a line geometry taking the curvature of the earth into account, but is also the slowest. + +Returns `0.0` for any geometry that is not a `LINESTRING`, `MULTILINESTRING` or `GEOMETRYCOLLECTION` containing line geometries. + + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_linemerge.md b/docs/src/functions/scalar/st_linemerge.md new file mode 100644 index 00000000..cbabed15 --- /dev/null +++ b/docs/src/functions/scalar/st_linemerge.md @@ -0,0 +1,44 @@ +--- +{ + "type": "scalar_function", + "title": "ST_LineMerge", + "id": "st_linemerge", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "linework", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "linework", + "type": "GEOMETRY" + }, + { + "name": "directed", + "type": "BOOLEAN" + } + ] + } + ], + "summary": "\"Merges\" the input line geometry, optionally taking direction into account.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_linestring2dfromwkb.md b/docs/src/functions/scalar/st_linestring2dfromwkb.md new file mode 100644 index 00000000..a2835faf --- /dev/null +++ b/docs/src/functions/scalar/st_linestring2dfromwkb.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_LineString2DFromWKB", + "id": "st_linestring2dfromwkb", + "signatures": [ + { + "returns": "LINESTRING_2D", + "parameters": [ + { + "name": "blob", + "type": "WKB_BLOB" + } + ] + } + ], + "summary": "Deserialize a LINESTRING_2D from a WKB encoded geometry blob", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_makeenvelope.md b/docs/src/functions/scalar/st_makeenvelope.md new file mode 100644 index 00000000..f5b9bed7 --- /dev/null +++ b/docs/src/functions/scalar/st_makeenvelope.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_MakeEnvelope", + "id": "st_makeenvelope", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "col0", + "type": "DOUBLE" + }, + { + "name": "col1", + "type": "DOUBLE" + }, + { + "name": "col2", + "type": "DOUBLE" + }, + { + "name": "col3", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Returns a minimal bounding box polygon enclosing the input geometry" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_makeline.md b/docs/src/functions/scalar/st_makeline.md new file mode 100644 index 00000000..053b0b7c --- /dev/null +++ b/docs/src/functions/scalar/st_makeline.md @@ -0,0 +1,44 @@ +--- +{ + "type": "scalar_function", + "title": "ST_MakeLine", + "id": "st_makeline", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "points", + "type": "GEOMETRY[]" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "start_point", + "type": "GEOMETRY" + }, + { + "name": "end_point", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Creates a LINESTRING geometry from a pair or list of input points", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_makepolygon.md b/docs/src/functions/scalar/st_makepolygon.md new file mode 100644 index 00000000..cc51b352 --- /dev/null +++ b/docs/src/functions/scalar/st_makepolygon.md @@ -0,0 +1,44 @@ +--- +{ + "type": "scalar_function", + "title": "ST_MakePolygon", + "id": "st_makepolygon", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "shell", + "type": "GEOMETRY" + }, + { + "name": "holes", + "type": "GEOMETRY[]" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "shell", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Creates a polygon from a shell geometry and an optional set of holes", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_normalize.md b/docs/src/functions/scalar/st_normalize.md new file mode 100644 index 00000000..49b9d46a --- /dev/null +++ b/docs/src/functions/scalar/st_normalize.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Normalize", + "id": "st_normalize", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns a \"normalized\" version of the input geometry.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_numgeometries.md b/docs/src/functions/scalar/st_numgeometries.md new file mode 100644 index 00000000..b7e80a39 --- /dev/null +++ b/docs/src/functions/scalar/st_numgeometries.md @@ -0,0 +1,32 @@ +--- +{ + "type": "scalar_function", + "title": "ST_NumGeometries", + "id": "st_numgeometries", + "aliases": [ "st_ngeometries" ], + "signatures": [ + { + "returns": "INTEGER", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the number of component geometries in a collection geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_numinteriorrings.md b/docs/src/functions/scalar/st_numinteriorrings.md new file mode 100644 index 00000000..a3f62fb8 --- /dev/null +++ b/docs/src/functions/scalar/st_numinteriorrings.md @@ -0,0 +1,41 @@ +--- +{ + "type": "scalar_function", + "title": "ST_NumInteriorRings", + "id": "st_numinteriorrings", + "aliases": [ "st_ninteriorrings" ], + "signatures": [ + { + "returns": "INTEGER", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "INTEGER", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the number if interior rings of a polygon", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_numpoints.md b/docs/src/functions/scalar/st_numpoints.md new file mode 100644 index 00000000..b0f261bd --- /dev/null +++ b/docs/src/functions/scalar/st_numpoints.md @@ -0,0 +1,68 @@ +--- +{ + "type": "scalar_function", + "title": "ST_NumPoints", + "id": "st_numpoints", + "aliases": [ "st_npoints" ], + "signatures": [ + { + "returns": "UBIGINT", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "UBIGINT", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "UBIGINT", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "UBIGINT", + "parameters": [ + { + "name": "geom", + "type": "BOX_2D" + } + ] + }, + { + "returns": "UINTEGER", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the number of points within a geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_overlaps.md b/docs/src/functions/scalar/st_overlaps.md new file mode 100644 index 00000000..97a75c46 --- /dev/null +++ b/docs/src/functions/scalar/st_overlaps.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Overlaps", + "id": "st_overlaps", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if geom1 \"overlaps\" geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_perimeter.md b/docs/src/functions/scalar/st_perimeter.md new file mode 100644 index 00000000..75de08a3 --- /dev/null +++ b/docs/src/functions/scalar/st_perimeter.md @@ -0,0 +1,49 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Perimeter", + "id": "st_perimeter", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the length of the perimeter of the geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_perimeter_spheroid.md b/docs/src/functions/scalar/st_perimeter_spheroid.md new file mode 100644 index 00000000..86e11167 --- /dev/null +++ b/docs/src/functions/scalar/st_perimeter_spheroid.md @@ -0,0 +1,42 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Perimeter_Spheroid", + "id": "st_perimeter_spheroid", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the length of the perimeter in meters using an ellipsoidal model of the earths surface", + "tags": [ + "property", "spheroid" + ] +} +--- + +### Description + +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 length is returned in meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library, calculating the perimeter using an ellipsoidal model of the earth. This is a highly accurate method for calculating the perimeter of a polygon taking the curvature of the earth into account, but is also the slowest. + +Returns `0.0` for any geometry that is not a `POLYGON`, `MULTIPOLYGON` or `GEOMETRYCOLLECTION` containing polygon geometries. + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_point.md b/docs/src/functions/scalar/st_point.md new file mode 100644 index 00000000..0b2d4a46 --- /dev/null +++ b/docs/src/functions/scalar/st_point.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Point", + "id": "st_point", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "x", + "type": "DOUBLE" + }, + { + "name": "y", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Creates a GEOMETRY point", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_point2d.md b/docs/src/functions/scalar/st_point2d.md new file mode 100644 index 00000000..6e04ed4d --- /dev/null +++ b/docs/src/functions/scalar/st_point2d.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Point2D", + "id": "st_point2d", + "signatures": [ + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "x", + "type": "DOUBLE" + }, + { + "name": "y", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Creates a POINT_2D", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_point2dfromwkb.md b/docs/src/functions/scalar/st_point2dfromwkb.md new file mode 100644 index 00000000..ce6e561a --- /dev/null +++ b/docs/src/functions/scalar/st_point2dfromwkb.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Point2DFromWKB", + "id": "st_point2dfromwkb", + "signatures": [ + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "blob", + "type": "WKB_BLOB" + } + ] + } + ], + "summary": "Deserialize a POINT_2D from a WKB encoded geometry blob", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_point3d.md b/docs/src/functions/scalar/st_point3d.md new file mode 100644 index 00000000..173c5b4a --- /dev/null +++ b/docs/src/functions/scalar/st_point3d.md @@ -0,0 +1,39 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Point3D", + "id": "st_point3d", + "signatures": [ + { + "returns": "POINT_3D", + "parameters": [ + { + "name": "x", + "type": "DOUBLE" + }, + { + "name": "y", + "type": "DOUBLE" + }, + { + "name": "z", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Creates a POINT_3D", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_point4d.md b/docs/src/functions/scalar/st_point4d.md new file mode 100644 index 00000000..4cf15cc5 --- /dev/null +++ b/docs/src/functions/scalar/st_point4d.md @@ -0,0 +1,43 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Point4D", + "id": "st_point4d", + "signatures": [ + { + "returns": "POINT_4D", + "parameters": [ + { + "name": "x", + "type": "DOUBLE" + }, + { + "name": "y", + "type": "DOUBLE" + }, + { + "name": "z", + "type": "DOUBLE" + }, + { + "name": "m", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Creates a POINT_4D", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_pointn.md b/docs/src/functions/scalar/st_pointn.md new file mode 100644 index 00000000..bd293424 --- /dev/null +++ b/docs/src/functions/scalar/st_pointn.md @@ -0,0 +1,48 @@ +--- +{ + "type": "scalar_function", + "title": "ST_PointN", + "id": "st_pointn", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "n", + "type": "INTEGER" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + }, + { + "name": "n", + "type": "INTEGER" + } + ] + } + ], + "summary": "Returns the n'th vertex from the input geometry as a point geometry", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_pointonsurface.md b/docs/src/functions/scalar/st_pointonsurface.md new file mode 100644 index 00000000..1e9058b2 --- /dev/null +++ b/docs/src/functions/scalar/st_pointonsurface.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_PointOnSurface", + "id": "st_pointonsurface", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns a point that is guaranteed to be on the surface of the input geometry. Sometimes a useful alternative to ST_Centroid.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_polygon2dfromwkb.md b/docs/src/functions/scalar/st_polygon2dfromwkb.md new file mode 100644 index 00000000..9439bb43 --- /dev/null +++ b/docs/src/functions/scalar/st_polygon2dfromwkb.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Polygon2DFromWKB", + "id": "st_polygon2dfromwkb", + "signatures": [ + { + "returns": "POLYGON_2D", + "parameters": [ + { + "name": "blob", + "type": "WKB_BLOB" + } + ] + } + ], + "summary": "Deserialize a POLYGON_2D from a WKB encoded blob", + "tags": [ + "conversion" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_reduceprecision.md b/docs/src/functions/scalar/st_reduceprecision.md new file mode 100644 index 00000000..5e9e7780 --- /dev/null +++ b/docs/src/functions/scalar/st_reduceprecision.md @@ -0,0 +1,32 @@ +--- +{ + "type": "scalar_function", + "title": "ST_ReducePrecision", + "id": "st_reduceprecision", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "precision", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Returns the geometry with all vertices reduced to the target precision" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_removerepeatedpoints.md b/docs/src/functions/scalar/st_removerepeatedpoints.md new file mode 100644 index 00000000..80cf3943 --- /dev/null +++ b/docs/src/functions/scalar/st_removerepeatedpoints.md @@ -0,0 +1,66 @@ +--- +{ + "type": "scalar_function", + "title": "ST_RemoveRepeatedPoints", + "id": "st_removerepeatedpoints", + "signatures": [ + { + "returns": "LINESTRING_2D", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "LINESTRING_2D", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Returns a new geometry with repeated points removed, optionally within a target distance of eachother.", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_reverse.md b/docs/src/functions/scalar/st_reverse.md new file mode 100644 index 00000000..65c9a427 --- /dev/null +++ b/docs/src/functions/scalar/st_reverse.md @@ -0,0 +1,31 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Reverse", + "id": "st_reverse", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns a new version of the input geometry with the order of its vertices reversed", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_simplify.md b/docs/src/functions/scalar/st_simplify.md new file mode 100644 index 00000000..108799dc --- /dev/null +++ b/docs/src/functions/scalar/st_simplify.md @@ -0,0 +1,32 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Simplify", + "id": "st_simplify", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Simplifies the input geometry by collapsing edges smaller than 'distance'" +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_simplifypreservetopology.md b/docs/src/functions/scalar/st_simplifypreservetopology.md new file mode 100644 index 00000000..7940e023 --- /dev/null +++ b/docs/src/functions/scalar/st_simplifypreservetopology.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_SimplifyPreserveTopology", + "id": "st_simplifypreservetopology", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "distance", + "type": "DOUBLE" + } + ] + } + ], + "summary": "Returns a simplified geometry but avoids creating invalid topologies", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_startpoint.md b/docs/src/functions/scalar/st_startpoint.md new file mode 100644 index 00000000..a159c332 --- /dev/null +++ b/docs/src/functions/scalar/st_startpoint.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_StartPoint", + "id": "st_startpoint", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + } + ], + "summary": "Returns the first point of a line geometry", + "tags": [ + "construction" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_touches.md b/docs/src/functions/scalar/st_touches.md new file mode 100644 index 00000000..6e4794ac --- /dev/null +++ b/docs/src/functions/scalar/st_touches.md @@ -0,0 +1,35 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Touches", + "id": "st_touches", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if geom1 \"touches\" geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_transform.md b/docs/src/functions/scalar/st_transform.md new file mode 100644 index 00000000..c7ba0064 --- /dev/null +++ b/docs/src/functions/scalar/st_transform.md @@ -0,0 +1,176 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Transform", + "id": "st_transform", + "signatures": [ + { + "returns": "BOX_2D", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + }, + { + "name": "source_crs", + "type": "VARCHAR" + }, + { + "name": "target_crs", + "type": "VARCHAR" + } + ] + }, + { + "returns": "BOX_2D", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + }, + { + "name": "source_crs", + "type": "VARCHAR" + }, + { + "name": "target_crs", + "type": "VARCHAR" + }, + { + "name": "always_xy", + "type": "BOOLEAN" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + }, + { + "name": "source_crs", + "type": "VARCHAR" + }, + { + "name": "target_crs", + "type": "VARCHAR" + } + ] + }, + { + "returns": "POINT_2D", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + }, + { + "name": "source_crs", + "type": "VARCHAR" + }, + { + "name": "target_crs", + "type": "VARCHAR" + }, + { + "name": "always_xy", + "type": "BOOLEAN" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "source_crs", + "type": "VARCHAR" + }, + { + "name": "target_crs", + "type": "VARCHAR" + } + ] + }, + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + }, + { + "name": "source_crs", + "type": "VARCHAR" + }, + { + "name": "target_crs", + "type": "VARCHAR" + }, + { + "name": "always_xy", + "type": "BOOLEAN" + } + ] + } + ], + "summary": "Transforms a geometry between two coordinate systems", + "tags": [ + "construction" + ] +} +--- + +### Description + +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). + +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. + +### Examples + +```sql + +-- 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 +-- WebMercator. + +SELECT ST_AsText( + ST_Transform( + st_point(52.373123, 4.892360), + 'EPSG:4326', + 'EPSG:3857' + ) +); +---- +POINT (544615.0239773799 6867874.103539125) + +-- Alternatively, let's say we got our input point from e.g. a GeoJSON file, +-- 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. + +SELECT ST_AsText( + ST_Transform( + -- note the axis order is reversed here + st_point(4.892360, 52.373123), + 'EPSG:4326', + 'EPSG:3857', + always_xy := true + ) +); +---- +POINT (544615.0239773799 6867874.103539125) + + +``` diff --git a/docs/src/functions/scalar/st_union.md b/docs/src/functions/scalar/st_union.md new file mode 100644 index 00000000..d4cdbca6 --- /dev/null +++ b/docs/src/functions/scalar/st_union.md @@ -0,0 +1,41 @@ +--- + { + "id": "st_union", + "title": "ST_Union", + "type": "scalar_function", + "signatures": [ + { + "returns": "GEOMETRY", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "aliases": [], + "summary": "Returns the union of two geometries." +} +--- + +### Description + +Returns the union of two geometries. + +### Examples + +```sql +SELECT ST_AsText( + ST_Union( + ST_GeomFromText('POINT(1 2)'), + ST_GeomFromText('POINT(3 4)') + ) +); +---- +MULTIPOINT (1 2, 3 4) +``` diff --git a/docs/src/functions/scalar/st_within.md b/docs/src/functions/scalar/st_within.md new file mode 100644 index 00000000..3709e7d3 --- /dev/null +++ b/docs/src/functions/scalar/st_within.md @@ -0,0 +1,48 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Within", + "id": "st_within", + "signatures": [ + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + }, + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "BOOLEAN", + "parameters": [ + { + "name": "geom1", + "type": "GEOMETRY" + }, + { + "name": "geom2", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns true if geom1 is \"within\" geom2", + "tags": [ + "relation" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_x.md b/docs/src/functions/scalar/st_x.md new file mode 100644 index 00000000..aa0f1162 --- /dev/null +++ b/docs/src/functions/scalar/st_x.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_X", + "id": "st_x", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the X coordinate of a point geometry, or NULL if not a point or empty", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_xmax.md b/docs/src/functions/scalar/st_xmax.md new file mode 100644 index 00000000..65e5b7a8 --- /dev/null +++ b/docs/src/functions/scalar/st_xmax.md @@ -0,0 +1,67 @@ +--- +{ + "type": "scalar_function", + "title": "ST_XMax", + "id": "st_xmax", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the maximum x coordinate of a geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_xmin.md b/docs/src/functions/scalar/st_xmin.md new file mode 100644 index 00000000..176eec46 --- /dev/null +++ b/docs/src/functions/scalar/st_xmin.md @@ -0,0 +1,67 @@ +--- +{ + "type": "scalar_function", + "title": "ST_XMin", + "id": "st_xmin", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the minimum x coordinate of a geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_y.md b/docs/src/functions/scalar/st_y.md new file mode 100644 index 00000000..07944488 --- /dev/null +++ b/docs/src/functions/scalar/st_y.md @@ -0,0 +1,40 @@ +--- +{ + "type": "scalar_function", + "title": "ST_Y", + "id": "st_y", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the y coordinate of a point geometry, or NULL if not a point or empty.", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_ymax.md b/docs/src/functions/scalar/st_ymax.md new file mode 100644 index 00000000..73dac394 --- /dev/null +++ b/docs/src/functions/scalar/st_ymax.md @@ -0,0 +1,67 @@ +--- +{ + "type": "scalar_function", + "title": "ST_YMax", + "id": "st_ymax", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the maximum y coordinate of a geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/scalar/st_ymin.md b/docs/src/functions/scalar/st_ymin.md new file mode 100644 index 00000000..3b1195f4 --- /dev/null +++ b/docs/src/functions/scalar/st_ymin.md @@ -0,0 +1,67 @@ +--- +{ + "type": "scalar_function", + "title": "ST_YMin", + "id": "st_ymin", + "signatures": [ + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "box", + "type": "BOX_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "point", + "type": "POINT_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "line", + "type": "LINESTRING_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "polygon", + "type": "POLYGON_2D" + } + ] + }, + { + "returns": "DOUBLE", + "parameters": [ + { + "name": "geom", + "type": "GEOMETRY" + } + ] + } + ], + "summary": "Returns the minimum y coordinate of a geometry", + "tags": [ + "property" + ] +} +--- + +### Description + +TODO + +### Examples + +TODO + diff --git a/docs/src/functions/table/st_drivers.md b/docs/src/functions/table/st_drivers.md new file mode 100644 index 00000000..07756577 --- /dev/null +++ b/docs/src/functions/table/st_drivers.md @@ -0,0 +1,82 @@ +--- +{ + "type": "table_function", + "title": "ST_Drivers", + "id": "st_drivers", + "signatures": [ + { + "parameters": [] + } + ], + "summary": "Returns the list of supported GDAL drivers", + "tags": [] +} +--- + +### Description + +Returns the list of supported GDAL drivers and file formats for [ST_Read](##st_read). + +Note that far from all of these drivers have been tested properly, and some may require additional options to be passed to work as expected. If you run into any issues please first consult the [consult the GDAL docs](https://gdal.org/drivers/vector/index.html). + +### Examples + +```sql +SELECT * FROM ST_Drivers(); +``` + +| short_name | long_name | can_create | can_copy | can_open | help_url | +|----------------|------------------------------------------------------|------------|----------|----------|----------------------------------------------------| +| ESRI Shapefile | ESRI Shapefile | true | false | true | https://gdal.org/drivers/vector/shapefile.html | +| MapInfo File | MapInfo File | true | false | true | https://gdal.org/drivers/vector/mitab.html | +| UK .NTF | UK .NTF | false | false | true | https://gdal.org/drivers/vector/ntf.html | +| LVBAG | Kadaster LV BAG Extract 2.0 | false | false | true | https://gdal.org/drivers/vector/lvbag.html | +| S57 | IHO S-57 (ENC) | true | false | true | https://gdal.org/drivers/vector/s57.html | +| DGN | Microstation DGN | true | false | true | https://gdal.org/drivers/vector/dgn.html | +| OGR_VRT | VRT - Virtual Datasource | false | false | true | https://gdal.org/drivers/vector/vrt.html | +| Memory | Memory | true | false | true | | +| CSV | Comma Separated Value (.csv) | true | false | true | https://gdal.org/drivers/vector/csv.html | +| GML | Geography Markup Language (GML) | true | false | true | https://gdal.org/drivers/vector/gml.html | +| GPX | GPX | true | false | true | https://gdal.org/drivers/vector/gpx.html | +| KML | Keyhole Markup Language (KML) | true | false | true | https://gdal.org/drivers/vector/kml.html | +| GeoJSON | GeoJSON | true | false | true | https://gdal.org/drivers/vector/geojson.html | +| GeoJSONSeq | GeoJSON Sequence | true | false | true | https://gdal.org/drivers/vector/geojsonseq.html | +| ESRIJSON | ESRIJSON | false | false | true | https://gdal.org/drivers/vector/esrijson.html | +| TopoJSON | TopoJSON | false | false | true | https://gdal.org/drivers/vector/topojson.html | +| OGR_GMT | GMT ASCII Vectors (.gmt) | true | false | true | https://gdal.org/drivers/vector/gmt.html | +| GPKG | GeoPackage | true | true | true | https://gdal.org/drivers/vector/gpkg.html | +| SQLite | SQLite / Spatialite | true | false | true | https://gdal.org/drivers/vector/sqlite.html | +| WAsP | WAsP .map format | true | false | true | https://gdal.org/drivers/vector/wasp.html | +| OpenFileGDB | ESRI FileGDB | true | false | true | https://gdal.org/drivers/vector/openfilegdb.html | +| DXF | AutoCAD DXF | true | false | true | https://gdal.org/drivers/vector/dxf.html | +| CAD | AutoCAD Driver | false | false | true | https://gdal.org/drivers/vector/cad.html | +| FlatGeobuf | FlatGeobuf | true | false | true | https://gdal.org/drivers/vector/flatgeobuf.html | +| Geoconcept | Geoconcept | true | false | true | | +| GeoRSS | GeoRSS | true | false | true | https://gdal.org/drivers/vector/georss.html | +| VFK | Czech Cadastral Exchange Data Format | false | false | true | https://gdal.org/drivers/vector/vfk.html | +| PGDUMP | PostgreSQL SQL dump | true | false | false | https://gdal.org/drivers/vector/pgdump.html | +| OSM | OpenStreetMap XML and PBF | false | false | true | https://gdal.org/drivers/vector/osm.html | +| GPSBabel | GPSBabel | true | false | true | https://gdal.org/drivers/vector/gpsbabel.html | +| WFS | OGC WFS (Web Feature Service) | false | false | true | https://gdal.org/drivers/vector/wfs.html | +| OAPIF | OGC API - Features | false | false | true | https://gdal.org/drivers/vector/oapif.html | +| EDIGEO | French EDIGEO exchange format | false | false | true | https://gdal.org/drivers/vector/edigeo.html | +| SVG | Scalable Vector Graphics | false | false | true | https://gdal.org/drivers/vector/svg.html | +| ODS | Open Document/ LibreOffice / OpenOffice Spreadsheet | true | false | true | https://gdal.org/drivers/vector/ods.html | +| XLSX | MS Office Open XML spreadsheet | true | false | true | https://gdal.org/drivers/vector/xlsx.html | +| Elasticsearch | Elastic Search | true | false | true | https://gdal.org/drivers/vector/elasticsearch.html | +| Carto | Carto | true | false | true | https://gdal.org/drivers/vector/carto.html | +| AmigoCloud | AmigoCloud | true | false | true | https://gdal.org/drivers/vector/amigocloud.html | +| SXF | Storage and eXchange Format | false | false | true | https://gdal.org/drivers/vector/sxf.html | +| Selafin | Selafin | true | false | true | https://gdal.org/drivers/vector/selafin.html | +| JML | OpenJUMP JML | true | false | true | https://gdal.org/drivers/vector/jml.html | +| PLSCENES | Planet Labs Scenes API | false | false | true | https://gdal.org/drivers/vector/plscenes.html | +| CSW | OGC CSW (Catalog Service for the Web) | false | false | true | https://gdal.org/drivers/vector/csw.html | +| VDV | VDV-451/VDV-452/INTREST Data Format | true | false | true | https://gdal.org/drivers/vector/vdv.html | +| MVT | Mapbox Vector Tiles | true | false | true | https://gdal.org/drivers/vector/mvt.html | +| NGW | NextGIS Web | true | true | true | https://gdal.org/drivers/vector/ngw.html | +| MapML | MapML | true | false | true | https://gdal.org/drivers/vector/mapml.html | +| PMTiles | ProtoMap Tiles | true | false | true | https://gdal.org/drivers/vector/pmtiles.html | +| JSONFG | OGC Features and Geometries JSON | true | false | true | https://gdal.org/drivers/vector/jsonfg.html | +| TIGER | U.S. Census TIGER/Line | false | false | true | https://gdal.org/drivers/vector/tiger.html | +| AVCBin | Arc/Info Binary Coverage | false | false | true | https://gdal.org/drivers/vector/avcbin.html | +| AVCE00 | Arc/Info E00 (ASCII) Coverage | false | false | true | https://gdal.org/drivers/vector/avce00.html | diff --git a/docs/src/functions/table/st_read.md b/docs/src/functions/table/st_read.md new file mode 100644 index 00000000..cc3a4bff --- /dev/null +++ b/docs/src/functions/table/st_read.md @@ -0,0 +1,109 @@ +--- +{ + "type": "table_function", + "title": "ST_Read", + "id": "st_read", + "signatures": [ + { + "parameters": [ + { + "name": "path", + "type": "VARCHAR" + }, + { + "name": "sequential_layer_scan", + "type": "BOOLEAN" + }, + { + "name": "max_batch_size", + "type": "INTEGER" + }, + { + "name": "keep_wkb", + "type": "BOOLEAN" + }, + { + "name": "layer", + "type": "VARCHAR" + }, + { + "name": "allowed_drivers", + "type": "VARCHAR[]" + }, + { + "name": "spatial_filter", + "type": "WKB_BLOB" + }, + { + "name": "spatial_filter_box", + "type": "BOX_2D" + }, + { + "name": "sibling_files", + "type": "VARCHAR[]" + }, + { + "name": "open_options", + "type": "VARCHAR[]" + } + ] + } + ], + "summary": "Import data from a variety of geospatial file formats", + "tags": [] +} +--- + +### Description + + +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. + +Except for the `path` parameter, all parameters are optional. + +| Parameter | Type | Description | +| --------- | -----| ----------- | +| `path` | VARCHAR | The path to the file to read. Mandatory | +| `sequential_layer_scan` | BOOLEAN | If set to true, the table function will scan through all layers sequentially and return the first layer that matches the given layer name. This is required for some drivers to work properly, e.g., the OSM driver. | +| `spatial_filter` | WKB_BLOB | If set to a WKB blob, the table function will only return rows that intersect with the given WKB geometry. Some drivers may support efficient spatial filtering natively, in which case it will be pushed down. Otherwise the filtering is done by GDAL which may be much slower. | +| `open_options` | VARCHAR[] | A list of key-value pairs that are passed to the GDAL driver to control the opening of the file. E.g., the GeoJSON driver supports a FLATTEN_NESTED_ATTRIBUTES=YES option to flatten nested attributes. | +| `layer` | VARCHAR | The name of the layer to read from the file. If NULL, the first layer is returned. Can also be a layer index (starting at 0). | +| `allowed_drivers` | VARCHAR[] | A list of GDAL driver names that are allowed to be used to open the file. If empty, all drivers are allowed. | +| `sibling_files` | VARCHAR[] | A list of sibling files that are required to open the file. E.g., the ESRI Shapefile driver requires a .shx file to be present. Although most of the time these can be discovered automatically. | +| `spatial_filter_box` | BOX_2D | If set to a BOX_2D, the table function will only return rows that intersect with the given bounding box. Similar to spatial_filter. | +| `keep_wkb` | BOOLEAN | If set, the table function will return geometries in a wkb_geometry column with the type WKB_BLOB (which can be cast to BLOB) instead of GEOMETRY. This is useful if you want to use DuckDB with more exotic geometry subtypes that DuckDB spatial doesnt support representing in the GEOMETRY type yet. | + +Note that GDAL is single-threaded, so this table function will not be able to make full use of parallelism. + +### Examples + +```sql +-- Read a Shapefile +SELECT * FROM ST_Read('some/file/path/filename.shp'); + +-- Read a GeoJSON file +CREATE TABLE my_geojson_table AS SELECT * FROM ST_Read('some/file/path/filename.json'); + +``` + +### Replacement scans + +By using `ST_Read`, the spatial extension also provides “replacement scans” for common geospatial file formats, allowing you to query files of these formats as if they were tables directly. + +```sql +SELECT * FROM './path/to/some/shapefile/dataset.shp'; +``` + +In practice this is just syntax-sugar for calling ST_Read, so there is no difference in performance. If you want to pass additional options, you should use the ST_Read table function directly. + +The following formats are currently recognized by their file extension: + +| Format | Extension | +| ------ | --------- | +| ESRI ShapeFile | .shp | +| GeoPackage | .gpkg | +| FlatGeoBuf | .fgb | + + diff --git a/docs/src/functions/table/st_readosm.md b/docs/src/functions/table/st_readosm.md new file mode 100644 index 00000000..e4b14412 --- /dev/null +++ b/docs/src/functions/table/st_readosm.md @@ -0,0 +1,53 @@ +--- +{ + "type": "table_function", + "title": "ST_ReadOSM", + "id": "st_readosm", + "signatures": [ + { + "parameters": [ + { + "name": "path", + "type": "VARCHAR" + } + ] + } + ], + "summary": "Reads compressed OpenStreetMap data", + "tags": [] +} +--- + +### Description + +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. + +### Examples + +```sql +SELECT * +FROM ST_ReadOSM('tmp/data/germany.osm.pbf') +WHERE tags['highway'] != [] +LIMIT 5; +``` + +``` +┌──────────────────────┬────────┬──────────────────────┬─────────┬────────────────────┬────────────┬───────────┬────────────────────────┐ +│ kind │ id │ tags │ refs │ lat │ lon │ ref_roles │ ref_types │ +│ enum('node', 'way'… │ int64 │ map(varchar, varch… │ int64[] │ double │ double │ varchar[] │ enum('node', 'way', … │ +├──────────────────────┼────────┼──────────────────────┼─────────┼────────────────────┼────────────┼───────────┼────────────────────────┤ +│ node │ 122351 │ {bicycle=yes, butt… │ │ 53.5492951 │ 9.977553 │ │ │ +│ node │ 122397 │ {crossing=no, high… │ │ 53.520990100000006 │ 10.0156924 │ │ │ +│ node │ 122493 │ {TMC:cid_58:tabcd_… │ │ 53.129614600000004 │ 8.1970173 │ │ │ +│ node │ 123566 │ {highway=traffic_s… │ │ 54.617268200000005 │ 8.9718171 │ │ │ +│ node │ 125801 │ {TMC:cid_58:tabcd_… │ │ 53.070685000000005 │ 8.7819939 │ │ │ +└──────────────────────┴────────┴──────────────────────┴─────────┴────────────────────┴────────────┴───────────┴────────────────────────┘ +``` + +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: + +```sql +SELECT * FROM 'tmp/data/germany.osm.pbf' LIMIT 5; +``` diff --git a/docs/src/generate.py b/docs/src/generate.py new file mode 100755 index 00000000..e84d7308 --- /dev/null +++ b/docs/src/generate.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +import os +import json + + +def write_function(f, info, content): + f.write(f"## {info['title']}\n") + f.write(f"\n_{info['summary']}_\n\n") + # Write signatures + for signature in info['signatures']: + params = ', '.join([f"{param['name']} __{param['type']}__" for param in signature['parameters']]) + if 'returns' not in signature: + sig = f"{info['title']}({params})" + else: + sig = f"__{signature['returns']}__ {info['title']}({params})" + f.write(f"- {sig}\n") + + f.write("\n") + + # Write list of aliases + if 'aliases' in info and info['aliases']: + f.write(f"\n__aliases:__ {', '.join(info['aliases'])}\n") + + # Finally write the content + f.write(f"{content}\n") + + # Write some whitespace too + f.write("\n") + + +def main(): + tagged_items = { } + scalar_functions = { } + aggregate_functions = { } + table_functions = { } + items = [] + + # Recursively find all doc items in the functions directory + for root, _, files in os.walk("functions"): + for file in files: + if file.endswith(".md"): + items.append(os.path.join(root, file)) + + # Sort the items by name + items.sort() + + # Read all the items and parse the frontmatter + for item in items: + with open(item, 'r') as f: + frontmatter = "" + line = f.readline() + if not line.startswith("---"): + raise ValueError(f"Invalid frontmatter in {item}: could not find starting '---'") + + line = f.readline() + while not line.startswith("---"): + frontmatter += line + line = f.readline() + + # Parse the frontmatter as JSON + try: + data = json.loads(frontmatter) + except json.JSONDecodeError as e: + raise ValueError(f"Invalid frontmatter in {item}: {e}") + + # Add the item to the appropriate list + doc_type = data['type'] + doc_id = data['id'] + doc_item = { + 'meta': data, + 'content': f.read().strip() + } + if doc_type == 'scalar_function': + scalar_functions[doc_id] = doc_item + elif doc_type == 'aggregate_function': + aggregate_functions[doc_id] = doc_item + elif doc_type == 'table_function': + table_functions[doc_id] = doc_item + else: + raise ValueError(f"Invalid doc type {doc_type} in {item}") + + # Add the item id to the tagged items list + if 'tags' in data and data['tags']: + for tag in data['tags']: + if tag not in tagged_items: + tagged_items[tag] = [] + tagged_items[tag].append(doc_id) + + + # Now write the combined output file one step up + outfile = os.path.join(os.path.dirname(os.path.realpath(__file__)), "..", "docs.md") + with open(outfile, 'w') as f: + + # Write the header + f.write("# DuckDB Spatial Extension\n\n") + + # Write the intro from the into.md file + with open(os.path.join(os.path.dirname(os.path.realpath(__file__)), "intro.md"), 'r') as intro: + f.write(intro.read()) + + f.write("\n") + + # Write all scalar functions + if scalar_functions: + f.write(f"# Scalar Functions\n\n") + + # Write ToC + f.write(f"| Name | Summary |\n") + f.write(f"| ---- | ----------- |\n") + for func in scalar_functions.values(): + f.write(f"| [{func['meta']['title']}](##{func['meta']['id']}) | {func['meta']['summary']} |\n") + f.write("\n") + + # Write individual functions + for func in scalar_functions.values(): + write_function(f, func['meta'], func['content']) + + # Write all aggregate functions + if aggregate_functions: + f.write(f"# Aggregate Functions\n\n") + + # Write ToC + f.write(f"| Name | Summary |\n") + f.write(f"| ---- | ----------- |\n") + for func in aggregate_functions.values(): + f.write(f"| [{func['meta']['title']}](##{func['meta']['id']}) | {func['meta']['summary']} |\n") + f.write("\n") + + # Write individual functions + for func in aggregate_functions.values(): + write_function(f, func['meta'], func['content']) + + # Write all table functions + if table_functions: + f.write(f"# Table Functions\n\n") + for func in table_functions.values(): + write_function(f, func['meta'], func['content']) + + if tagged_items: + # Write all tagged items + f.write(f"# Functions by tag\n\n") + for tag, entries in tagged_items.items(): + f.write(f"__{tag}__\n") + for entry in entries: + if entry in scalar_functions: + f.write(f"- [{scalar_functions[entry]['meta']['title']}](##{entry})\n") + elif entry in aggregate_functions: + f.write(f"- [{aggregate_functions[entry]['meta']['title']}](##{entry})\n") + f.write("\n") + + + +if __name__ == '__main__': + main() \ No newline at end of file diff --git a/docs/src/get_functions.sql b/docs/src/get_functions.sql new file mode 100644 index 00000000..eb94f8da --- /dev/null +++ b/docs/src/get_functions.sql @@ -0,0 +1,37 @@ +SELECT * FROM duckdb_functions() WHERE function_name LIKE 'st\_%' ESCAPE '\'; + +-- Get all scalars +COPY ( +SELECT + 'scalar_function' as "type", + lower(function_name) as id, + function_name as title, + list( {'returns': return_type, 'parameters': parameter_types} ) as signatures +FROM duckdb_functions() +WHERE function_name LIKE 'ST\_%' ESCAPE '\' AND function_type = 'scalar' +GROUP BY function_name +) TO 'scalar_functions.json'; + +-- Get all aggregates +COPY ( +SELECT + 'aggregate_function' as "type", + lower(function_name) as id, + function_name as title, + list( {'returns': return_type, 'parameters': parameter_types} ) as signatures +FROM duckdb_functions() +WHERE function_name LIKE 'ST\_%' ESCAPE '\' AND function_type = 'aggregate' +GROUP BY function_name +) TO 'aggregate_functions.json'; + +--- Get all table funcs +COPY ( +SELECT + 'table_function' as "type", + lower(function_name) as id, + function_name as title, + list( {'returns': return_type, 'parameters': parameter_types} ) as signatures +FROM duckdb_functions() +WHERE function_name LIKE 'ST\_%' ESCAPE '\' AND function_type = 'table' +GROUP BY function_name +) TO 'table_functions.json'; \ No newline at end of file diff --git a/docs/src/intro.md b/docs/src/intro.md new file mode 100644 index 00000000..0f531ce7 --- /dev/null +++ b/docs/src/intro.md @@ -0,0 +1,19 @@ + +The spatial extension provides support for geospatial data processing in DuckDB. + +## Installing and Loading + +To install and load the DuckDB `spatial` extension, simply run: + +```sql +INSTALL spatial; +LOAD spatial; +``` + +You can also get the latest beta version of the extension for the latest stable release of DuckDB. This version is built and reuploaded every time a pull request is merged into the `main` branch on spatial extensions GitHub repository. +Install it by executing: + +```sql +FORCE INSTALL spatial FROM 'http://nightly-extensions.duckdb.org'; +``` +Note that this will overwrite any existing `spatial` extension installed for the current version of DuckDB. \ No newline at end of file diff --git a/docs/src/scalar_functions.json b/docs/src/scalar_functions.json new file mode 100644 index 00000000..bcee1b15 --- /dev/null +++ b/docs/src/scalar_functions.json @@ -0,0 +1,86 @@ +{"type":"scalar_function","id":"st_length_spheroid","title":"ST_Length_Spheroid","signatures":[{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_union","title":"ST_Union","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_disjoint","title":"ST_Disjoint","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_convexhull","title":"ST_ConvexHull","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_x","title":"ST_X","signatures":[{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_makeenvelope","title":"ST_MakeEnvelope","signatures":[{"returns":"GEOMETRY","parameters":["DOUBLE","DOUBLE","DOUBLE","DOUBLE"]}]} +{"type":"scalar_function","id":"st_extent","title":"ST_Extent","signatures":[{"returns":"BOX_2D","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_collect","title":"ST_Collect","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY[]"]}]} +{"type":"scalar_function","id":"st_simplify","title":"ST_Simplify","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","DOUBLE"]}]} +{"type":"scalar_function","id":"st_reduceprecision","title":"ST_ReducePrecision","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","DOUBLE"]}]} +{"type":"scalar_function","id":"st_equals","title":"ST_Equals","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_buffer","title":"ST_Buffer","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","DOUBLE"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","DOUBLE","INTEGER"]}]} +{"type":"scalar_function","id":"st_xmin","title":"ST_XMin","signatures":[{"returns":"DOUBLE","parameters":["BOX_2D"]},{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_point4d","title":"ST_Point4D","signatures":[{"returns":"POINT_4D","parameters":["DOUBLE","DOUBLE","DOUBLE","DOUBLE"]}]} +{"type":"scalar_function","id":"st_ngeometries","title":"ST_NGeometries","signatures":[{"returns":"INTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_geomfromhexwkb","title":"ST_GeomFromHEXWKB","signatures":[{"returns":"GEOMETRY","parameters":["VARCHAR"]}]} +{"type":"scalar_function","id":"st_dimension","title":"ST_Dimension","signatures":[{"returns":"INTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_isclosed","title":"ST_IsClosed","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_dwithin","title":"ST_DWithin","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY","DOUBLE"]}]} +{"type":"scalar_function","id":"st_difference","title":"ST_Difference","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_covers","title":"ST_Covers","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_coveredby","title":"ST_CoveredBy","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_startpoint","title":"ST_StartPoint","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]},{"returns":"POINT_2D","parameters":["LINESTRING_2D"]}]} +{"type":"scalar_function","id":"st_point2d","title":"ST_Point2D","signatures":[{"returns":"POINT_2D","parameters":["DOUBLE","DOUBLE"]}]} +{"type":"scalar_function","id":"st_dump","title":"ST_Dump","signatures":[{"returns":"STRUCT(geom GEOMETRY, path INTEGER[])[]","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_contains","title":"ST_Contains","signatures":[{"returns":"BOOLEAN","parameters":["POLYGON_2D","POINT_2D"]},{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_touches","title":"ST_Touches","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_pointonsurface","title":"ST_PointOnSurface","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_linemerge","title":"ST_LineMerge","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","BOOLEAN"]}]} +{"type":"scalar_function","id":"st_issimple","title":"ST_IsSimple","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_isring","title":"ST_IsRing","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_envelope","title":"ST_Envelope","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_crosses","title":"ST_Crosses","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_length","title":"ST_Length","signatures":[{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_geomfromwkb","title":"ST_GeomFromWKB","signatures":[{"returns":"GEOMETRY","parameters":["WKB_BLOB"]},{"returns":"GEOMETRY","parameters":["BLOB"]}]} +{"type":"scalar_function","id":"st_geometrytype","title":"ST_GeometryType","signatures":[{"returns":"ANY","parameters":["POINT_2D"]},{"returns":"ANY","parameters":["LINESTRING_2D"]},{"returns":"ANY","parameters":["POLYGON_2D"]},{"returns":"ANY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_distance","title":"ST_Distance","signatures":[{"returns":"DOUBLE","parameters":["POINT_2D","POINT_2D"]},{"returns":"DOUBLE","parameters":["POINT_2D","LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["LINESTRING_2D","POINT_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_area_spheroid","title":"ST_Area_Spheroid","signatures":[{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_dwithin_spheroid","title":"ST_DWithin_Spheroid","signatures":[{"returns":"DOUBLE","parameters":["POINT_2D","POINT_2D","DOUBLE"]}]} +{"type":"scalar_function","id":"st_simplifypreservetopology","title":"ST_SimplifyPreserveTopology","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","DOUBLE"]}]} +{"type":"scalar_function","id":"st_isvalid","title":"ST_IsValid","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_transform","title":"ST_Transform","signatures":[{"returns":"BOX_2D","parameters":["BOX_2D","VARCHAR","VARCHAR"]},{"returns":"BOX_2D","parameters":["BOX_2D","VARCHAR","VARCHAR","BOOLEAN"]},{"returns":"POINT_2D","parameters":["POINT_2D","VARCHAR","VARCHAR"]},{"returns":"POINT_2D","parameters":["POINT_2D","VARCHAR","VARCHAR","BOOLEAN"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","VARCHAR","VARCHAR"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","VARCHAR","VARCHAR","BOOLEAN"]}]} +{"type":"scalar_function","id":"st_point3d","title":"ST_Point3D","signatures":[{"returns":"POINT_3D","parameters":["DOUBLE","DOUBLE","DOUBLE"]}]} +{"type":"scalar_function","id":"st_point","title":"ST_Point","signatures":[{"returns":"GEOMETRY","parameters":["DOUBLE","DOUBLE"]}]} +{"type":"scalar_function","id":"st_perimeter","title":"ST_Perimeter","signatures":[{"returns":"DOUBLE","parameters":["BOX_2D"]},{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_ninteriorrings","title":"ST_NInteriorRings","signatures":[{"returns":"INTEGER","parameters":["POLYGON_2D"]},{"returns":"INTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_numgeometries","title":"ST_NumGeometries","signatures":[{"returns":"INTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_intersects_extent","title":"ST_Intersects_Extent","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_intersects","title":"ST_Intersects","signatures":[{"returns":"BOOLEAN","parameters":["BOX_2D","BOX_2D"]},{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_endpoint","title":"ST_EndPoint","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]},{"returns":"POINT_2D","parameters":["LINESTRING_2D"]}]} +{"type":"scalar_function","id":"st_within","title":"ST_Within","signatures":[{"returns":"BOOLEAN","parameters":["POINT_2D","POLYGON_2D"]},{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_distance_spheroid","title":"ST_Distance_Spheroid","signatures":[{"returns":"DOUBLE","parameters":["POINT_2D","POINT_2D"]}]} +{"type":"scalar_function","id":"st_reverse","title":"ST_Reverse","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_overlaps","title":"ST_Overlaps","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_normalize","title":"ST_Normalize","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_containsproperly","title":"ST_ContainsProperly","signatures":[{"returns":"BOOLEAN","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_ymin","title":"ST_YMin","signatures":[{"returns":"DOUBLE","parameters":["BOX_2D"]},{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_ymax","title":"ST_YMax","signatures":[{"returns":"DOUBLE","parameters":["BOX_2D"]},{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_xmax","title":"ST_XMax","signatures":[{"returns":"DOUBLE","parameters":["BOX_2D"]},{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_pointn","title":"ST_PointN","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","INTEGER"]},{"returns":"POINT_2D","parameters":["LINESTRING_2D","INTEGER"]}]} +{"type":"scalar_function","id":"st_makeline","title":"ST_MakeLine","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY[]"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_isempty","title":"ST_IsEmpty","signatures":[{"returns":"BOOLEAN","parameters":["LINESTRING_2D"]},{"returns":"BOOLEAN","parameters":["POLYGON_2D"]},{"returns":"BOOLEAN","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_linestring2dfromwkb","title":"ST_LineString2DFromWKB","signatures":[{"returns":"LINESTRING_2D","parameters":["WKB_BLOB"]}]} +{"type":"scalar_function","id":"st_point2dfromwkb","title":"ST_Point2DFromWKB","signatures":[{"returns":"POINT_2D","parameters":["WKB_BLOB"]}]} +{"type":"scalar_function","id":"st_geomfromhexewkb","title":"ST_GeomFromHEXEWKB","signatures":[{"returns":"GEOMETRY","parameters":["VARCHAR"]}]} +{"type":"scalar_function","id":"st_flipcoordinates","title":"ST_FlipCoordinates","signatures":[{"returns":"POINT_2D","parameters":["POINT_2D"]},{"returns":"LINESTRING_2D","parameters":["LINESTRING_2D"]},{"returns":"POLYGON_2D","parameters":["POLYGON_2D"]},{"returns":"BOX_2D","parameters":["BOX_2D"]},{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_aswkb","title":"ST_AsWKB","signatures":[{"returns":"WKB_BLOB","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_geomfromgeojson","title":"ST_GeomFromGeoJSON","signatures":[{"returns":"GEOMETRY","parameters":["VARCHAR"]}]} +{"type":"scalar_function","id":"st_asgeojson","title":"ST_AsGeoJSON","signatures":[{"returns":"VARCHAR","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_intersection","title":"ST_Intersection","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","GEOMETRY"]}]} +{"type":"scalar_function","id":"st_boundary","title":"ST_Boundary","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_polygon2dfromwkb","title":"ST_Polygon2DFromWKB","signatures":[{"returns":"POLYGON_2D","parameters":["WKB_BLOB"]}]} +{"type":"scalar_function","id":"st_exteriorring","title":"ST_ExteriorRing","signatures":[{"returns":"LINESTRING_2D","parameters":["POLYGON_2D"]},{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_centroid","title":"ST_Centroid","signatures":[{"returns":"POINT_2D","parameters":["POINT_2D"]},{"returns":"POINT_2D","parameters":["LINESTRING_2D"]},{"returns":"POINT_2D","parameters":["POLYGON_2D"]},{"returns":"POINT_2D","parameters":["BOX_2D"]},{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_ashexwkb","title":"ST_AsHEXWKB","signatures":[{"returns":"VARCHAR","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_astext","title":"ST_AsText","signatures":[{"returns":"VARCHAR","parameters":["POINT_2D"]},{"returns":"VARCHAR","parameters":["LINESTRING_2D"]},{"returns":"VARCHAR","parameters":["POLYGON_2D"]},{"returns":"VARCHAR","parameters":["BOX_2D"]},{"returns":"VARCHAR","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_perimeter_spheroid","title":"ST_Perimeter_Spheroid","signatures":[{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_geomfromtext","title":"ST_GeomFromText","signatures":[{"returns":"GEOMETRY","parameters":["VARCHAR"]},{"returns":"GEOMETRY","parameters":["VARCHAR","BOOLEAN"]}]} +{"type":"scalar_function","id":"st_y","title":"ST_Y","signatures":[{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_removerepeatedpoints","title":"ST_RemoveRepeatedPoints","signatures":[{"returns":"LINESTRING_2D","parameters":["LINESTRING_2D"]},{"returns":"LINESTRING_2D","parameters":["LINESTRING_2D","DOUBLE"]},{"returns":"GEOMETRY","parameters":["GEOMETRY"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","DOUBLE"]}]} +{"type":"scalar_function","id":"st_numpoints","title":"ST_NumPoints","signatures":[{"returns":"UBIGINT","parameters":["POINT_2D"]},{"returns":"UBIGINT","parameters":["LINESTRING_2D"]},{"returns":"UBIGINT","parameters":["POLYGON_2D"]},{"returns":"UBIGINT","parameters":["BOX_2D"]},{"returns":"UINTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_npoints","title":"ST_NPoints","signatures":[{"returns":"UBIGINT","parameters":["POINT_2D"]},{"returns":"UBIGINT","parameters":["LINESTRING_2D"]},{"returns":"UBIGINT","parameters":["POLYGON_2D"]},{"returns":"UBIGINT","parameters":["BOX_2D"]},{"returns":"UINTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_numinteriorrings","title":"ST_NumInteriorRings","signatures":[{"returns":"INTEGER","parameters":["POLYGON_2D"]},{"returns":"INTEGER","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_makepolygon","title":"ST_MakePolygon","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY","GEOMETRY[]"]},{"returns":"GEOMETRY","parameters":["GEOMETRY"]}]} +{"type":"scalar_function","id":"st_collectionextract","title":"ST_CollectionExtract","signatures":[{"returns":"GEOMETRY","parameters":["GEOMETRY"]},{"returns":"GEOMETRY","parameters":["GEOMETRY","INTEGER"]}]} +{"type":"scalar_function","id":"st_area","title":"ST_Area","signatures":[{"returns":"DOUBLE","parameters":["POINT_2D"]},{"returns":"DOUBLE","parameters":["LINESTRING_2D"]},{"returns":"DOUBLE","parameters":["POLYGON_2D"]},{"returns":"DOUBLE","parameters":["GEOMETRY"]},{"returns":"DOUBLE","parameters":["BOX_2D"]}]} diff --git a/docs/src/table_functions.json b/docs/src/table_functions.json new file mode 100644 index 00000000..6d95515a --- /dev/null +++ b/docs/src/table_functions.json @@ -0,0 +1,4 @@ +{"type":"table_function","id":"st_read","title":"ST_Read","signatures":[{"returns":null,"parameters":["VARCHAR","BOOLEAN","INTEGER","BOOLEAN","VARCHAR","VARCHAR[]","WKB_BLOB","BOX_2D","VARCHAR[]","VARCHAR[]"]}]} +{"type":"table_function","id":"st_drivers","title":"ST_Drivers","signatures":[{"returns":null,"parameters":[]}]} +{"type":"table_function","id":"st_list_proj_crs","title":"ST_List_Proj_CRS","signatures":[{"returns":null,"parameters":[]}]} +{"type":"table_function","id":"st_readosm","title":"ST_ReadOSM","signatures":[{"returns":null,"parameters":["VARCHAR"]}]} diff --git a/docs/src/types/geometry.md b/docs/src/types/geometry.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/verify.py b/docs/src/verify.py new file mode 100644 index 00000000..dcea2a54 --- /dev/null +++ b/docs/src/verify.py @@ -0,0 +1,158 @@ +import os +import json + +def read_yes_no(text) -> bool: + print(text) + while True: + choice = input().lower() + if choice in ["y", "yes"]: + return True + elif choice in ["n", "no"]: + return False + else: + print("Please respond with 'y/es' or 'n/o'") + + +def try_parse_frontmatter(f, filename): + frontmatter = "" + line = f.readline() + if not line.startswith("---"): + raise ValueError(f"Invalid frontmatter in {filename}: could not find starting '---'") + + line = f.readline() + while not line.startswith("---"): + frontmatter += line + line = f.readline() + + # Parse the frontmatter as JSON + try: + return json.loads(frontmatter) + except json.JSONDecodeError as e: + raise ValueError(f"Invalid frontmatter in {filename}: {e}") + + +def main(): + + # Recursively find all doc items in the functions directory + items = { } + aliases = { } + for root, _, files in os.walk("functions"): + for file in files: + if file.endswith(".md"): + # Get the file base name (without path and extension) + base = os.path.splitext(os.path.basename(file))[0] + + # Parse the frontmatter + with open(os.path.join(root, file), 'r') as f: + try: + info = try_parse_frontmatter(f, base) + items[base] = info + if 'aliases' in info: + for alias in info['aliases']: + if alias in aliases: + print(f"Duplicate alias '{alias}' in {base}") + aliases[alias] = info['id'] + except ValueError as e: + pass # Ignore invalid frontmatter + + + # Read the scalar_functions.json file + # TODO: Call DuckDB and generate these instead + collections = [ + {'file': 'functions/scalar_functions.json', 'doc_type': 'scalar_function'}, + {'file': 'functions/aggregate_functions.json', 'doc_type': 'aggregate_function'}, + {'file': 'functions/table_functions.json', 'doc_type': 'table_function'}, + ] + for collection in collections: + with open(os.path.join(os.path.dirname(__file__), collection['file'])) as f: + doc_type = collection['doc_type'] + + for line in f: + func = json.loads(line) + id = func['id'] + + if id not in items: + if id in aliases: + print(f"Found alias for scalar function {id} => {aliases[id]}, skipping...") + continue + + print(f"Missing doc item for scalar function {id}") + if read_yes_no(f"Create doc item for scalar function {id}? (y/n)"): + print(f"Signatures: {func['signatures']}") + print("Summary:") + summary = input() + sigs = [] + for sig in func['signatures']: + print(f"Provide parameter names for signature: {sig}") + params = [] + for i in range(len(sig['parameters'])): + param_type = sig['parameters'][i] + print(f"Parameter {i} ({param_type}):") + params.append({ + "name": input(), + "type": param_type, + }) + sigs.append({ + "returns": sig['returns'], + "parameters": params, + }) + + print(f"Tags: (space separated)") + tags = input().split(" ") + + items[id] = { + "type": doc_type, + "title": func['title'], + "id": func['id'], + "signatures": sigs, + "summary": summary, + } + + if len(tags) > 0: + items[id]['tags'] = tags + + with open(os.path.join("functions", id + ".md"), 'w') as f: + f.write("---\n") + f.write(json.dumps(items[id], indent=4)) + f.write("\n---\n") + f.write("\n### Description\n\n") + f.write("TODO\n\n") + f.write("### Examples\n\n") + f.write("TODO\n\n") + + continue + + + #print(f"Found doc item for scalar function {id}") + # Check if signatures match + for func_sig in func['signatures']: + match = False + for doc_sig in items[id]['signatures']: + + if doc_type != "table_function" and doc_sig['returns'] != func_sig['returns']: + continue + + if len(doc_sig['parameters']) != len(func_sig['parameters']): + continue + + parameter_mismatch = False + for i in range(len(func_sig['parameters'])): + if doc_sig['parameters'][i]['type'] != func_sig['parameters'][i]: + parameter_mismatch = True + break + + if parameter_mismatch: + continue + + match = True + break + + if match: + #print(f"Found\tsignature for scalar function {id}:\t{func_sig}") + pass + else: + print(f"Missing\tsignature for scalar function {id}:\t{func_sig}") + + +if __name__ == "__main__": + main() \ No newline at end of file From b56e9e239f32fb4e026d69bc714031df0c5e6557 Mon Sep 17 00:00:00 2001 From: Max Gabrielsson Date: Mon, 27 Nov 2023 15:34:22 +0100 Subject: [PATCH 3/3] update st_collec test --- docs/docs.md | 51 ++++++++++++++++++++++++- docs/src/functions/scalar/st_collect.md | 42 +++++++++++++++++++- docs/src/generate.py | 9 +++++ test/sql/geometry/st_collect.test | 2 +- 4 files changed, 99 insertions(+), 5 deletions(-) diff --git a/docs/docs.md b/docs/docs.md index eab4c4b6..e9f6430a 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -1,5 +1,14 @@ # DuckDB Spatial Extension +__Table of contents__ + +- [Introduction](#introduction) +- [Scalar Functions](#scalar-functions) +- [Aggregate Functions](#aggregate-functions) +- [Table Functions](#table-functions) +- [Functions by tag](#functions-by-tag) +# Introduction + The spatial extension provides support for geospatial data processing in DuckDB. @@ -283,11 +292,49 @@ _Collects geometries into a collection geometry_ ### Description -Collects a list of 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. +- If all geometries are `POLYGON`'s, a `MULTIPOLYGON` is returned. +- Otherwise if the input collection contains a mix of geometry types, a `GEOMETRYCOLLECTION` is returned. + +Empty and `NULL` geometries are ignored. If all geometries are empty or `NULL`, a `GEOMETRYCOLLECTION EMPTY` is returned. ### Examples -TODO +```sql +-- With all POINT's, a MULTIPOINT is returned +SELECT ST_Collect([ST_Point(1, 2), ST_Point(3, 4)]); +---- +MULTIPOINT (1 2, 3 4) + +-- With mixed geometry types, a GEOMETRYCOLLECTION is returned +SELECT ST_Collect([ST_Point(1, 2), ST_GeomFromText('LINESTRING(3 4, 5 6)')]); +---- +GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (3 4, 5 6)) + +-- Note that the empty geometry is ignored, so the result is a MULTIPOINT +SELECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +MULTIPOINT (1 2) + +-- If all geometries are empty or NULL, a GEOMETRYCOLLECTION EMPTY is returned +SELECT ST_Collect([NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +GEOMETRYCOLLECTION EMPTY +``` + +Tip: You can use the `ST_Collect` function together with the `list()` aggregate function to collect multiple rows of geometries into a single geometry collection: + +```sql +CREATE TABLE points (geom GEOMETRY); + +INSERT INTO points VALUES (ST_Point(1, 2)), (ST_Point(3, 4)); + +SELECT ST_Collect(list(geom)) FROM points; +---- +MULTIPOINT (1 2, 3 4) +``` ## ST_CollectionExtract diff --git a/docs/src/functions/scalar/st_collect.md b/docs/src/functions/scalar/st_collect.md index 8963e503..e7f6f321 100644 --- a/docs/src/functions/scalar/st_collect.md +++ b/docs/src/functions/scalar/st_collect.md @@ -24,8 +24,46 @@ ### Description -Collects a list of 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. +- If all geometries are `POLYGON`'s, a `MULTIPOLYGON` is returned. +- Otherwise if the input collection contains a mix of geometry types, a `GEOMETRYCOLLECTION` is returned. + +Empty and `NULL` geometries are ignored. If all geometries are empty or `NULL`, a `GEOMETRYCOLLECTION EMPTY` is returned. ### Examples -TODO +```sql +-- With all POINT's, a MULTIPOINT is returned +SELECT ST_Collect([ST_Point(1, 2), ST_Point(3, 4)]); +---- +MULTIPOINT (1 2, 3 4) + +-- With mixed geometry types, a GEOMETRYCOLLECTION is returned +SELECT ST_Collect([ST_Point(1, 2), ST_GeomFromText('LINESTRING(3 4, 5 6)')]); +---- +GEOMETRYCOLLECTION (POINT (1 2), LINESTRING (3 4, 5 6)) + +-- Note that the empty geometry is ignored, so the result is a MULTIPOINT +SELECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +MULTIPOINT (1 2) + +-- If all geometries are empty or NULL, a GEOMETRYCOLLECTION EMPTY is returned +SELECT ST_Collect([NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); +---- +GEOMETRYCOLLECTION EMPTY +``` + +Tip: You can use the `ST_Collect` function together with the `list()` aggregate function to collect multiple rows of geometries into a single geometry collection: + +```sql +CREATE TABLE points (geom GEOMETRY); + +INSERT INTO points VALUES (ST_Point(1, 2)), (ST_Point(3, 4)); + +SELECT ST_Collect(list(geom)) FROM points; +---- +MULTIPOINT (1 2, 3 4) +``` diff --git a/docs/src/generate.py b/docs/src/generate.py index e84d7308..d74a3039 100755 --- a/docs/src/generate.py +++ b/docs/src/generate.py @@ -94,7 +94,16 @@ def main(): # Write the header f.write("# DuckDB Spatial Extension\n\n") + # Write a table of contents + f.write("__Table of contents__\n\n") + f.write("- [Introduction](#introduction)\n") + f.write("- [Scalar Functions](#scalar-functions)\n") + f.write("- [Aggregate Functions](#aggregate-functions)\n") + f.write("- [Table Functions](#table-functions)\n") + f.write("- [Functions by tag](#functions-by-tag)\n") + # Write the intro from the into.md file + f.write("# Introduction\n\n") with open(os.path.join(os.path.dirname(os.path.realpath(__file__)), "intro.md"), 'r') as intro: f.write(intro.read()) diff --git a/test/sql/geometry/st_collect.test b/test/sql/geometry/st_collect.test index 4b0b62dc..1b3bc008 100644 --- a/test/sql/geometry/st_collect.test +++ b/test/sql/geometry/st_collect.test @@ -40,7 +40,7 @@ MULTIPOINT (1 2) query I SElECT ST_Collect([ST_Point(1, 2), NULL, ST_GeomFromText('GEOMETRYCOLLECTION EMPTY')]); ---- -GEOMETRYCOLLECTION (POINT (1 2), GEOMETRYCOLLECTION EMPTY) +MULTIPOINT (1 2) # Test with only null query I