Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update spatial function docs #3693

Merged
merged 1 commit into from
Sep 19, 2024
Merged

Update spatial function docs #3693

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 88 additions & 10 deletions docs/extensions/spatial/functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
| [`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 @@
| [`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 @@

| 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 @@
| [`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 @@
#### 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 @@

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 @@

----

### 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 @@

#### 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 @@

#### 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