Skip to content

Commit

Permalink
update spatial function list
Browse files Browse the repository at this point in the history
  • Loading branch information
@Maxxen
Maxxen committed Sep 19, 2024
1 parent ff73832 commit 1274694
Showing 1 changed file with 88 additions and 10 deletions.
98 changes: 88 additions & 10 deletions docs/extensions/spatial/functions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ title: Spatial Functions
| [`ST_Buffer`](#st_buffer) | Returns a buffer around the input geometry at the target distance |
| [`ST_Centroid`](#st_centroid) | Calculates the centroid of a geometry |
| [`ST_Collect`](#st_collect) | Collects a list of geometries into a collection geometry. |
| [`ST_CollectionExtract`](#st_collectionextract) | Extracts a sub-geometry from a collection geometry |
| [`ST_CollectionExtract`](#st_collectionextract) | Extracts geometries from a GeometryCollection into a typed multi 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 |
Expand Down Expand Up @@ -72,6 +72,7 @@ title: Spatial Functions
| [`ST_MakeLine`](#st_makeline) | Creates a LINESTRING geometry from a pair or list of input points |
| [`ST_MakePolygon`](#st_makepolygon) | Creates a polygon from a shell geometry and an optional set of holes |
| [`ST_MakeValid`](#st_makevalid) | Attempts to make an invalid geometry valid without removing any vertices |
| [`ST_Multi`](#st_multi) | Turns a single geometry into a multi geometry. |
| [`ST_NGeometries`](#st_ngeometries) | Returns the number of component geometries in a collection geometry. |
| [`ST_NInteriorRings`](#st_ninteriorrings) | Returns the number if interior rings of a polygon |
| [`ST_NPoints`](#st_npoints) | Returns the number of vertices within a geometry |
Expand Down Expand Up @@ -116,7 +117,8 @@ title: Spatial Functions

| Function | Summary |
| --------------------------------------------- | -------------------------------------------------------------------------------- |
| [`ST_Envelope_Agg`](#st_envelope_agg) | Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries |
| [`ST_Envelope_Agg`](#st_envelope_agg) | Alias for [ST_Extent_Agg](#st_extent_agg). |
| [`ST_Extent_Agg`](#st_extent_agg) | Computes the minimal-bounding-box polygon containing 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 |

Expand All @@ -127,7 +129,7 @@ title: Spatial Functions
| [`ST_Drivers`](#st_drivers) | Returns the list of supported GDAL drivers and file formats |
| [`ST_Read`](#st_read) | Read and import a variety of geospatial file formats using the GDAL library. |
| [`ST_ReadOSM`](#st_readosm) | The `ST_ReadOsm()` table function enables reading compressed OpenStreetMap data directly from a `.osm.pbf file.` |
| [`ST_Read_Meta`](#st_read_meta) | Read and the metadata from a variety of geospatial file formats using the GDAL library. |
| [`ST_Read_Meta`](#st_read_meta) | Read the metadata from a variety of geospatial file formats using the GDAL library. |

----

Expand Down Expand Up @@ -459,19 +461,34 @@ MULTIPOINT (1 2, 3 4)
#### Signatures

```sql
GEOMETRY ST_CollectionExtract (col0 GEOMETRY)
GEOMETRY ST_CollectionExtract (col0 GEOMETRY, col1 INTEGER)
GEOMETRY ST_CollectionExtract (geom GEOMETRY)
GEOMETRY ST_CollectionExtract (geom GEOMETRY, type INTEGER)
```

#### Description

Extracts a sub-geometry from a collection geometry
Extracts geometries from a GeometryCollection into a typed multi geometry.

If the input geometry is a GeometryCollection, the function will return a multi geometry, determined by the `type` parameter.
- if `type` = 1, returns a MultiPoint containg all the Points in the collection
- if `type` = 2, returns a MultiLineString containg all the LineStrings in the collection
- if `type` = 3, returns a MultiPolygon containg all the Polygons in the collection

If no `type` parameters is provided, the function will return a multi geometry matching the highest "surface dimension"
of the contained geometries. E.g. if the collection contains only Points, a MultiPoint will be returned. But if the

Check failure on line 478 in docs/extensions/spatial/functions.md

View workflow job for this annotation

GitHub Actions / markdown 

[vale] reported by reviewdog 🐶
[USEnglish.use-of-comma] Use 'e.g., ' instead of 'E.g.'

Raw Output:
{"message": "[USEnglish.use-of-comma] Use 'e.g., ' instead of 'E.g.'", "location": {"path": "docs/extensions/spatial/functions.md", "range": {"start": {"line": 478, "column": 30}}}, "severity": "ERROR"}
collection contains both Points and LineStrings, a MultiLineString will be returned. Similarly, if the collection
contains Polygons, a MultiPolygon will be returned. Contained geometries of a lower surface dimension will be ignored.

If the input geometry contains nested GeometryCollections, their geometries will be extracted recursively and included
into the final multi geometry as well.

If the input geometry is not a GeometryCollection, the function will return the input geometry as is.

#### Example

```sql
select st_collectionextract('MULTIPOINT(1 2,3 4)'::geometry, 1);
-- POINT(1 2)
-- MULTIPOINT (1 2, 3 4)
```

----
Expand Down Expand Up @@ -719,7 +736,7 @@ DOUBLE ST_Distance_Spheroid (col0 POINT_2D, col1 POINT_2D)

Returns the distance between two geometries in meters using a ellipsoidal model of the earths surface

The input geometry is assumed to be in the [EPSG:4326](https://en.wikipedia.org/wiki/World_Geodetic_System) coordinate system (WGS84), with [latitude, longitude] axis order and the distance is returned in meters. This function uses the [GeographicLib](https://geographiclib.sourceforge.io/) library to solve the [inverse geodesic problem](https://en.wikipedia.org/wiki/Geodesics_on_an_ellipsoid#Solution_of_the_direct_and_inverse_problems), calculating the distance between two points using an ellipsoidal model of the earth. This is a highly accurate method for calculating the distance between two arbitrary points taking the curvature of the earths surface into account, but is also the slowest.
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 limit is expected to be 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.

#### Example

Expand Down Expand Up @@ -1433,6 +1450,36 @@ Attempts to make an invalid geometry valid without removing any vertices

----

### ST_Multi


#### Signature

```sql
GEOMETRY ST_Multi (col0 GEOMETRY)
```

#### Description

Turns a single geometry into a multi geometry.

If the geometry is already a multi geometry, it is returned as is.

#### Example

```sql
SELECT ST_Multi(ST_GeomFromText('POINT(1 2)'));
-- MULTIPOINT (1 2)

SELECT ST_Multi(ST_GeomFromText('LINESTRING(1 1, 2 2)'));
-- MULTILINESTRING ((1 1, 2 2))

SELECT ST_Multi(ST_GeomFromText('POLYGON((0 0, 0 1, 1 1, 1 0, 0 0))'));
-- MULTIPOLYGON (((0 0, 0 1, 1 1, 1 0, 0 0)))
```

----

### ST_NGeometries


Expand Down Expand Up @@ -2204,7 +2251,38 @@ GEOMETRY ST_Envelope_Agg (col0 GEOMETRY)

#### Description

Computes a minimal-bounding-box polygon 'enveloping' the set of input geometries
Alias for [ST_Extent_Agg](#st_extent_agg).

Computes the minimal-bounding-box polygon containing the set of input geometries.

#### Example

```sql
SELECT ST_Extent_Agg(geom) FROM UNNEST([ST_Point(1,1), ST_Point(5,5)]) AS _(geom);
-- POLYGON ((1 1, 1 5, 5 5, 5 1, 1 1))
```

----

### ST_Extent_Agg


#### Signature

```sql
GEOMETRY ST_Extent_Agg (col0 GEOMETRY)
```

#### Description

Computes the minimal-bounding-box polygon containing the set of input geometries

#### Example

```sql
SELECT ST_Extent_Agg(geom) FROM UNNEST([ST_Point(1,1), ST_Point(5,5)]) AS _(geom);
-- POLYGON ((1 1, 1 5, 5 5, 5 1, 1 1))
```

----

Expand Down Expand Up @@ -2374,7 +2452,7 @@ ST_Read_Meta (col0 VARCHAR[])

#### Description

Read and the metadata from a variety of geospatial file formats using the GDAL library.
Read the metadata from a variety of geospatial file formats using the GDAL library.

The `ST_Read_Meta` table function accompanies the `ST_Read` table function, but instead of reading the contents of a file, this function scans the metadata instead.
Since the data model of the underlying GDAL library is quite flexible, most of the interesting metadata is within the returned `layers` column, which is a somewhat complex nested structure of DuckDB `STRUCT` and `LIST` types.
Expand Down

0 comments on commit 1274694

Please sign in to comment.