# Geospatial expressions

Points, Polygons, LineStrings, and other geospatial types.

# GeoSpatialValue

`GeoSpatialValue()`

## Methods

Name | Description |
---|---|

area | Compute the area of a geospatial value. |

as_binary | Get the geometry as well-known bytes (WKB) without the SRID data. |

as_ewkb | Get the geometry as well-known bytes (WKB) with the SRID data. |

as_ewkt | Get the geometry as well-known text (WKT) with the SRID data. |

as_text | Get the geometry as well-known text (WKT) without the SRID data. |

azimuth | Return the angle in radians from the horizontal of the vector defined by the inputs. |

buffer | Return all points whose distance from this geometry is less than or equal to `radius` . |

centroid | Returns the centroid of the geometry. |

contains | Check if the geometry contains the `right` . |

contains_properly | Check if the first geometry contains the second one. |

covered_by | Check if the first geometry is covered by the second one. |

covers | Check if the first geometry covers the second one. |

crosses | Check if the geometries have at least one interior point in common. |

d_fully_within | Check if `self` is entirely within `distance` from `right` . |

d_within | Check if `self` is partially within `distance` from `right` . |

difference | Return the difference of two geometries. |

disjoint | Check if the geometries have no points in common. |

distance | Compute the distance between two geospatial expressions. |

end_point | Return the last point of a `LINESTRING` geometry as a `POINT` . |

envelope | Returns a geometry representing the bounding box of `self` . |

geo_equals | Check if the geometries are equal. |

geometry_n | Get the 1-based Nth geometry of a multi geometry. |

geometry_type | Get the type of a geometry. |

intersection | Return the intersection of two geometries. |

intersects | Check if the geometries share any points. |

is_valid | Check if the geometry is valid. |

length | Compute the length of a geospatial expression. |

line_locate_point | Locate the distance a point falls along the length of a line. |

line_merge | Merge a `MultiLineString` into a `LineString` . |

line_substring | Clip a substring from a LineString. |

max_distance | Returns the 2-dimensional max distance between two geometries in projected units. |

n_points | Return the number of points in a geometry. Works for all geometries. |

n_rings | Return the number of rings for polygons and multipolygons. |

ordering_equals | Check if two geometries are equal and have the same point ordering. |

overlaps | Check if the geometries share space, have the same dimension, and are not completely contained by each other. |

perimeter | Compute the perimeter of a geospatial expression. |

point_n | Return the Nth point in a single linestring in the geometry. |

set_srid | Set the spatial reference identifier for the `ST_Geometry` . |

simplify | Simplify a given geometry. |

srid | Return the spatial reference identifier for the ST_Geometry. |

start_point | Return the first point of a `LINESTRING` geometry as a `POINT` . |

touches | Check if the geometries have at least one point in common, but do not intersect. |

transform | Transform a geometry into a new SRID. |

union | Merge two geometries into a union geometry. |

within | Check if the first geometry is completely inside of the second. |

x | Return the X coordinate of `self` , or NULL if not available. |

x_max | Return the X maxima of a geometry. |

x_min | Return the X minima of a geometry. |

y | Return the Y coordinate of `self` , or NULL if not available. |

y_max | Return the Y maxima of a geometry. |

y_min | Return the Y minima of a geometry. |

### area

`area()`

Compute the area of a geospatial value.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
The area of `self` |

### as_binary

`as_binary()`

Get the geometry as well-known bytes (WKB) without the SRID data.

#### Returns

Type | Description |
---|---|

`BinaryValue` |
Binary value |

### as_ewkb

`as_ewkb()`

Get the geometry as well-known bytes (WKB) with the SRID data.

#### Returns

Type | Description |
---|---|

`BinaryValue` |
WKB value |

### as_ewkt

`as_ewkt()`

Get the geometry as well-known text (WKT) with the SRID data.

#### Returns

Type | Description |
---|---|

`StringValue` |
String value |

### as_text

`as_text()`

Get the geometry as well-known text (WKT) without the SRID data.

#### Returns

Type | Description |
---|---|

`StringValue` |
String value |

### azimuth

`azimuth(right)`

Return the angle in radians from the horizontal of the vector defined by the inputs.

Angle is computed clockwise from down-to-up on the clock: 12=0; 3=PI/2; 6=PI; 9=3PI/2.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`FloatingValue` |
azimuth |

### buffer

`buffer(radius)`

Return all points whose distance from this geometry is less than or equal to `radius`

.

Calculations are in the Spatial Reference System of this Geometry.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`radius` |
float | `ir` .`FloatingValue` |
Floating expression | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Geometry expression |

### centroid

`centroid()`

Returns the centroid of the geometry.

#### Returns

Type | Description |
---|---|

`PointValue` |
The centroid |

### contains

`contains(right)`

Check if the geometry contains the `right`

.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` contains `right` |

### contains_properly

`contains_properly(right)`

Check if the first geometry contains the second one.

Excludes common border points.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether self contains right excluding border points. |

### covered_by

`covered_by(right)`

Check if the first geometry is covered by the second one.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` is covered by `right` |

### covers

`covers(right)`

Check if the first geometry covers the second one.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` covers `right` |

### crosses

`crosses(right)`

Check if the geometries have at least one interior point in common.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` and `right` have at least one common interior point. |

### d_fully_within

`d_fully_within(right, distance)`

Check if `self`

is entirely within `distance`

from `right`

.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

`distance` |
`ir` .`FloatingValue` |
Distance to check | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` is within a specified distance from `right` . |

### d_within

`d_within(right, distance)`

Check if `self`

is partially within `distance`

from `right`

.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

`distance` |
`ir` .`FloatingValue` |
Distance to check | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` is partially within `distance` from `right` . |

### difference

`difference(right)`

Return the difference of two geometries.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Difference of `self` and `right` |

### disjoint

`disjoint(right)`

Check if the geometries have no points in common.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` and `right` are disjoint |

### distance

`distance(right)`

Compute the distance between two geospatial expressions.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry or geography | required |

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Distance between `self` and `right` |

### end_point

`end_point()`

Return the last point of a `LINESTRING`

geometry as a `POINT`

.

Return `NULL`

if the input parameter is not a `LINESTRING`

#### Returns

Type | Description |
---|---|

`PointValue` |
End point |

### envelope

`envelope()`

Returns a geometry representing the bounding box of `self`

.

#### Returns

Type | Description |
---|---|

`PolygonValue` |
A polygon |

### geo_equals

`geo_equals(right)`

Check if the geometries are equal.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` equals `right` |

### geometry_n

`geometry_n(n)`

Get the 1-based Nth geometry of a multi geometry.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`n` |
int | `ir` .`IntegerValue` |
Nth geometry index | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Geometry value |

### geometry_type

`geometry_type()`

Get the type of a geometry.

#### Returns

Type | Description |
---|---|

`StringValue` |
String representing the type of `self` . |

### intersection

`intersection(right)`

Return the intersection of two geometries.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Intersection of `self` and `right` |

### intersects

`intersects(right)`

Check if the geometries share any points.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` intersects `right` |

### is_valid

`is_valid()`

Check if the geometry is valid.

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` is valid |

### length

`length()`

Compute the length of a geospatial expression.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Length of `self` |

### line_locate_point

`line_locate_point(right)`

Locate the distance a point falls along the length of a line.

Returns a float between zero and one representing the location of the closest point on the linestring to the given point, as a fraction of the total 2d line length.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
`PointValue` |
Point geometry | required |

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Fraction of the total line length |

### line_merge

`line_merge()`

Merge a `MultiLineString`

into a `LineString`

.

Returns a (set of) LineString(s) formed by sewing together the constituent line work of a MultiLineString. If a geometry other than a LineString or MultiLineString is given, this will return an empty geometry collection.

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Merged linestrings |

### line_substring

`line_substring(start, end)`

Clip a substring from a LineString.

Returns a linestring that is a substring of the input one, starting and ending at the given fractions of the total 2d length. The second and third arguments are floating point values between zero and one. This only works with linestrings.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`start` |
`ir` .`FloatingValue` |
Start value | required |

`end` |
`ir` .`FloatingValue` |
End value | required |

#### Returns

Type | Description |
---|---|

`LineStringValue` |
Clipped linestring |

### max_distance

`max_distance(right)`

Returns the 2-dimensional max distance between two geometries in projected units.

If `self`

and `right`

are the same geometry the function will return the distance between the two vertices most far from each other in that geometry.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Maximum distance |

### n_points

`n_points()`

Return the number of points in a geometry. Works for all geometries.

#### Returns

Type | Description |
---|---|

`IntegerValue` |
Number of points |

### n_rings

`n_rings()`

Return the number of rings for polygons and multipolygons.

Outer rings are counted as well.

#### Returns

Type | Description |
---|---|

`IntegerValue` |
Number of rings |

### ordering_equals

`ordering_equals(right)`

Check if two geometries are equal and have the same point ordering.

Returns true if the two geometries are equal and the coordinates are in the same order.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether points and orderings are equal. |

### overlaps

`overlaps(right)`

Check if the geometries share space, have the same dimension, and are not completely contained by each other.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Overlaps indicator |

### perimeter

`perimeter()`

Compute the perimeter of a geospatial expression.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Perimeter of `self` |

### point_n

`point_n(n)`

Return the Nth point in a single linestring in the geometry.

Negative values are counted backwards from the end of the LineString, so that -1 is the last point. Returns NULL if there is no linestring in the geometry.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`n` |
`ir` .`IntegerValue` |
Nth point index | required |

#### Returns

Type | Description |
---|---|

`PointValue` |
Nth point in `self` |

### set_srid

`set_srid(srid)`

Set the spatial reference identifier for the `ST_Geometry`

.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`srid` |
`ir` .`IntegerValue` |
SRID integer value | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | `self` with SRID set to `srid` |

### simplify

`simplify(tolerance, preserve_collapsed)`

Simplify a given geometry.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`tolerance` |
`ir` .`FloatingValue` |
Tolerance | required |

`preserve_collapsed` |
`ir` .`BooleanValue` |
Whether to preserve collapsed geometries | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Simplified geometry |

### srid

`srid()`

Return the spatial reference identifier for the ST_Geometry.

#### Returns

Type | Description |
---|---|

`IntegerValue` |
SRID |

### start_point

`start_point()`

Return the first point of a `LINESTRING`

geometry as a `POINT`

.

Return `NULL`

if the input parameter is not a `LINESTRING`

#### Returns

Type | Description |
---|---|

`PointValue` |
Start point |

### touches

`touches(right)`

Check if the geometries have at least one point in common, but do not intersect.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether self and right are touching |

### transform

`transform(srid)`

Transform a geometry into a new SRID.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`srid` |
`ir` .`IntegerValue` |
Integer expression | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Transformed geometry |

### union

`union(right)`

Merge two geometries into a union geometry.

Returns the pointwise union of the two geometries. This corresponds to the non-aggregate version the PostGIS ST_Union.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

GeoSpatialValue | Union of geometries |

### within

`within(right)`

Check if the first geometry is completely inside of the second.

#### Parameters

Name | Type | Description | Default |
---|---|---|---|

`right` |
GeoSpatialValue | Right geometry | required |

#### Returns

Type | Description |
---|---|

`BooleanValue` |
Whether `self` is in `right` . |

### x

`x()`

Return the X coordinate of `self`

, or NULL if not available.

Input must be a point.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
X coordinate of `self` |

### x_max

`x_max()`

Return the X maxima of a geometry.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
X maxima |

### x_min

`x_min()`

Return the X minima of a geometry.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
X minima |

### y

`y()`

Return the Y coordinate of `self`

, or NULL if not available.

Input must be a point.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Y coordinate of `self` |

### y_max

`y_max()`

Return the Y maxima of a geometry.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Y maxima |

### y_min

`y_min()`

Return the Y minima of a geometry.

#### Returns

Type | Description |
---|---|

`FloatingValue` |
Y minima |

# GeoSpatialColumn

`GeoSpatialColumn()`

## Methods

Name | Description |
---|---|

unary_union | Aggregate a set of geometries into a union. |

### unary_union

`unary_union()`

Aggregate a set of geometries into a union.

This corresponds to the aggregate version of the PostGIS ST_Union. We give it a different name (following the corresponding method in GeoPandas) to avoid name conflicts with the non-aggregate version.

#### Returns

Type | Description |
---|---|

`GeoSpatialScalar` |
Union of geometries |