地理空間関数¶
Presto の地理空間関数は、接頭辞 ST_ で始まるものが SQL/MM 仕様をサポートし、Open Geospatial Consortium（OGC）の OpenGIS Specifications に準拠しています。そのため、多くの Presto 地理空間関数は、操作対象のジオメトリが単純かつ有効であることを要求します（より正確には、想定しています）。たとえば、ポリゴンの穴がポリゴンの外部に定義されている場合に面積を計算したり、単純でない境界線からポリゴンを作成したりすることは意味がありません。
Presto の地理空間関数は、空間オブジェクトの Well-Known Text（WKT）形式と Well-Known Binary（WKB）形式をサポートしています。
POINT (0 0)LINESTRING (0 0, 1 1, 1 2)POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1))MULTIPOINT (0 0, 1 2)MULTILINESTRING ((0 0, 1 1, 1 2), (2 3, 3 2, 5 4))MULTIPOLYGON (((0 0, 4 0, 4 4, 0 4, 0 0), (1 1, 2 1, 2 2, 1 2, 1 1)), ((-1 -1, -1 -2, -2 -2, -2 -1, -1 -1)))GEOMETRYCOLLECTION (POINT(2 3), LINESTRING (2 3, 3 4))
WKT または WKB からジオメトリオブジェクトを作成するには、ST_GeometryFromText 関数と ST_GeomFromBinary 関数を使用します。WKT/WKB では、座標の順序は (x, y) です。球面/地理空間用途では、これは (latitude, longitude) ではなく (longitude, latitude) を意味します。
Geometry型の基礎は平面です。平面上の2点間の最短距離は直線です。つまり、ジオメトリに関する計算（面積、距離、長さ、交差など）は、デカルト座標系と直線ベクトルを用いて計算できます。
SphericalGeography型は、「地理座標」（測地座標、または緯度/経度、経度/緯度と呼ばれることもあります）で表される空間フィーチャをネイティブにサポートします。地理座標は、角度単位（度）で表される球座標です。
SphericalGeography型の基礎は球体です。球体上の2点間の最短距離は大円弧です。つまり、ジオグラフィに関する計算（面積、距離、長さ、交差など）は、より複雑な数学を用いて球体上で計算する必要があります。地球の実際の回転楕円体形状を考慮したより正確な測定はサポートされていません。
SphericalGeographyオブジェクトの場合、測定関数ST_DistanceとST_Lengthによって返される値はメートル単位です。ST_Areaによって返される値は平方メートルです。
ジオメトリオブジェクトをジオグラフィオブジェクトに変換するには、to_spherical_geography()関数を使用します。例として、ST_Distance(ST_Point(-71.0882, 42.3607), ST_Point(-74.1197, 40.6976))はユークリッド平面上の入力値の単位で3.4577を返しますが、ST_Distance(to_spherical_geography(ST_Point(-71.0882, 42.3607)), to_spherical_geography(ST_Point(-74.1197, 40.6976)))はメートル単位で312822.179を返します。
コンストラクタ¶
- ST_AsBinary(Geometry) -> varbinary()¶
ジオメトリのWKB表現を返します。
- ST_AsText(Geometry) -> varchar()¶
ジオメトリのWKT表現を返します。空のジオメトリの場合、
ST_AsText(ST_LineFromText('LINESTRING EMPTY'))は'MULTILINESTRING EMPTY'を生成し、ST_AsText(ST_Polygon('POLYGON EMPTY'))は'MULTIPOLYGON EMPTY'を生成します。
- ST_GeometryFromText(varchar) -> Geometry()¶
WKT表現からジオメトリ型オブジェクトを返します。
- ST_GeomFromBinary(varbinary) -> Geometry()¶
WKB表現からジオメトリ型オブジェクトを返します。
- ST_LineFromText(varchar) -> LineString()¶
WKT表現からジオメトリ型ラインストリングオブジェクトを返します。
- ST_LineString(array(Point)) -> LineString()¶
点の配列から形成されたLineStringを返します。入力配列に2つ以上の空でない点が含まれていない場合、空のLineStringが返されます。配列の要素が
nullまたは空、または前の要素と同じである場合、例外をスローします。返されるジオメトリは単純ではない可能性があります（例：自己交差する可能性があります、または入力に応じて重複した頂点を含む可能性があります）。
- ST_MultiPoint(array(Point)) -> MultiPoint()¶
指定された点から形成されたMultiPointジオメトリオブジェクトを返します。入力配列が空の場合、
nullを返します。配列の要素がnullまたは空である場合、例外をスローします。入力配列に重複がある場合、返されるジオメトリは単純ではなく、重複した点を含む可能性があります。
- ST_Point(x, y) -> Point()¶
指定された座標値を持つジオメトリ型点オブジェクトを返します。
- ST_Polygon(varchar) -> Polygon()¶
WKT表現からジオメトリ型ポリゴンオブジェクトを返します。
- to_spherical_geography(Geometry) -> SphericalGeography()¶
ジオメトリオブジェクトを地球の半径の球体上のSphericalGeographyオブジェクトに変換します。この関数は、2D空間で定義された
POINT、MULTIPOINT、LINESTRING、MULTILINESTRING、POLYGON、MULTIPOLYGONジオメトリ、またはそのようなジオメトリのGEOMETRYCOLLECTIONにのみ適用可能です。入力ジオメトリの各点について、point.xが[-180.0, 180.0]の範囲内であり、point.yが[-90.0, 90.0]の範囲内であることを検証し、それらを(経度、緯度)度として使用してSphericalGeography結果の形状を構築します。
- to_geometry(SphericalGeography) -> Geometry()¶
SphericalGeographyオブジェクトをジオメトリオブジェクトに変換します。
空間関係テスト¶
- ST_Contains(Geometry, Geometry) -> boolean()¶
第2のジオメトリの点が第1のジオメトリの外部に存在せず、かつ第1のジオメトリの内部の少なくとも1点が第2のジオメトリの内部に存在する場合にのみ
trueを返します。
- ST_Crosses(Geometry, Geometry) -> boolean()¶
提供されたジオメトリが内部点をいくつか（すべてではない）共有する場合に
trueを返します。
- ST_Disjoint(Geometry, Geometry) -> boolean()¶
与えられたジオメトリが空間的に交差しない場合（空間を共有しない場合）に
trueを返します。
- ST_Equals(Geometry, Geometry) -> boolean()¶
与えられたジオメトリが同じジオメトリを表す場合に
trueを返します。
- ST_Intersects(Geometry, Geometry) -> boolean()¶
与えられたジオメトリが2次元で空間的に交差する場合（空間の一部を共有する場合）は
trueを返し、交差しない場合（互いに素な場合）はfalseを返します。
- ST_Overlaps(Geometry, Geometry) -> boolean()¶
与えられたジオメトリが空間を共有し、同じ次元を持ちますが、互いに完全に含まれていない場合に
trueを返します。
- ST_Relate(Geometry, Geometry) -> boolean()¶
最初のジオメトリが2番目のジオメトリと空間的に関連している場合に
trueを返します。
- ST_Touches(Geometry, Geometry) -> boolean()¶
与えられたジオメトリが少なくとも1つの点を共有しますが、それらの内部が交差しない場合に
trueを返します。
- ST_Within(Geometry, Geometry) -> boolean()¶
最初のジオメトリが2番目のジオメトリに完全に含まれる場合に
trueを返します。
演算¶
- geometry_union(array(Geometry)) -> Geometry()¶
入力ジオメトリの点集合の和集合を表すジオメトリを返します。この関数は、まず入力ジオメトリを集計する
array_agg()geometry_union_agg()
- ST_Boundary(Geometry) -> Geometry()¶
このジオメトリの組み合わせ境界の閉包を返します。
- ST_Buffer(Geometry, distance) -> Geometry()¶
指定されたジオメトリからの距離が、指定された距離以下であるすべての点を表すジオメトリを返します。ジオメトリの点が非常に接近している場合（
delta < 1e-8）、空のジオメトリを返す可能性があります。
- ST_Difference(Geometry, Geometry) -> Geometry()¶
与えられたジオメトリの点集合の差を表すジオメトリ値を返します。
- ST_Envelope(Geometry) -> Geometry()¶
ジオメトリの境界矩形ポリゴンを返します。
- ST_EnvelopeAsPts(Geometry) -> array(Geometry)¶
2つの点の配列を返します。ジオメトリの境界矩形ポリゴンの左下隅と右上隅です。入力ジオメトリが空の場合は
nullを返します。
- expand_envelope(Geometry, double) -> Geometry()¶
ジオメトリの境界矩形ポリゴンを、指定した距離だけ拡張して返します。空のジオメトリは空のポリゴンを返します。負またはNaNの距離はエラーを返します。正の無限大の距離は、未定義の結果につながる可能性があります。
- ST_ExteriorRing(Geometry) -> Geometry()¶
入力ポリゴンの外部リングを表すラインストリングを返します。
- ST_Intersection(Geometry, Geometry) -> Geometry()¶
2つのジオメトリの点集合の共通部分を表すジオメトリ値を返します。
- ST_SymDifference(Geometry, Geometry) -> Geometry()¶
2つのジオメトリの点集合の対称差を表すジオメトリ値を返します。
- ST_Union(Geometry, Geometry) -> Geometry()¶
入力ジオメトリの点集合の和集合を表すジオメトリを返します。
参照：
geometry_union()、geometry_union_agg()
アクセサ¶
- ST_Area(Geometry) -> double()¶
ジオメトリの2次元ユークリッド面積を返します。
Point型とLineString型の場合は0.0を返します。GeometryCollection型の場合は、個々のジオメトリの面積の合計を返します。
- ST_Area(SphericalGeography) -> double()¶
地球の球面モデルを使用して、ポリゴンまたはマルチポリゴンの面積を平方メートルで返します。
- ST_Centroid(Geometry) -> Point()¶
ジオメトリの数学的な重心を表す点の値を返します。
- ST_Centroid(SphericalGeography) -> Point()¶
球面ジオメトリの数学的な重心を表す点の値を返します。
PointとMultiPointを入力としてサポートし、地球の表面（球面）に投影された3次元重心を返します。例：MULTIPOINT (0 -45, 0 45, 30 0, -30 0) は Point(0, 0) を返します。注：3次元重心が(0, 0, 0)の場合、球面重心は未定義であり、任意の点が返されます。例：MULTIPOINT (0 0, -180 0) は Point(-90, 45) を返します。
- ST_ConvexHull(Geometry) -> Geometry()¶
すべての入力ジオメトリを囲む最小の凸ジオメトリを返します。
- ST_CoordDim(Geometry) -> bigint()¶
ジオメトリの座標次元を返します。
- ST_Dimension(Geometry) -> bigint()¶
このジオメトリオブジェクトの本質的な次元を返します。これは、座標次元以下でなければなりません。
- ST_Distance(Geometry, Geometry) -> double()¶
投影単位で、2つのジオメトリ間の2次元デカルト最小距離（空間参照に基づく）を返します。
- ST_Distance(SphericalGeography, SphericalGeography) -> double()¶
2つのSphericalGeography点間の測地線距離をメートルで返します。
- geometry_nearest_points(Geometry, Geometry) -> array(Point)¶
各ジオメトリ上で、互いに最も近い点を返します。いずれかのジオメトリが空の場合、
NULLを返します。それ以外の場合は、ジオメトリ上の任意の2点間の最小距離を持つ2つの点の配列を返します。最初の点は最初のGeometry引数から、2番目の点は2番目のGeometry引数から取得されます。最小距離を持つペアが複数ある場合、1つのペアが任意に選択されます。
- ST_GeometryN(Geometry, index) -> Geometry()¶
指定されたインデックス（インデックスは1から始まる）にあるジオメトリ要素を返します。ジオメトリがジオメトリの集合（例：GEOMETRYCOLLECTIONまたはMULTI*）の場合、指定されたインデックスのジオメトリを返します。指定されたインデックスが1未満、または集合内の要素の総数を超える場合は
NULLを返します。要素の総数を知るには、:func:ST_NumGeometriesを使用してください。単一のジオメトリ（例：POINT、LINESTRING、POLYGON）は、1つの要素の集合として扱われます。空のジオメトリは空の集合として扱われます。
- ST_InteriorRingN(Geometry, index) -> Geometry()¶
指定されたインデックス（インデックスは1から始まる）にある内部リング要素を返します。指定されたインデックスが1未満、または入力ジオメトリの内部リングの総数を超える場合は
NULLを返します。入力ジオメトリがポリゴンでない場合はエラーをスローします。要素の総数を知るには、:func:ST_NumInteriorRingを使用してください。
- ST_GeometryType(Geometry) -> varchar()¶
ジオメトリの型を返します。
- ST_IsClosed(Geometry) -> boolean()¶
ラインストリングの始点と終点が一致する場合、
trueを返します。
- ST_IsEmpty(Geometry) -> boolean()¶
このジオメトリが空のジオメトリコレクション、ポリゴン、ポイントなどである場合、
trueを返します。
- ST_IsSimple(Geometry) -> boolean()¶
このジオメトリに、自己交差や自己接線などの異常な幾何学的点が含まれていない場合、
trueを返します。ジオメトリが単純でない理由を特定するには、geometry_invalid_reason()を使用してください。
- ST_IsRing(Geometry) -> boolean()¶
線が閉じている場合、かつ単純な線である場合にのみ
trueを返します。
- ST_IsValid(Geometry) -> boolean()¶
入力ジオメトリが正しく形成されている場合に限り、
trueを返します。geometry_invalid_reason()を使用して、ジオメトリが正しく形成されていない理由を確認してください。
- ST_Length(Geometry) -> double()¶
ラインストリングまたはマルチラインストリングの長さを、投影単位で二次元平面（空間参照に基づく）上のユークリッド測定法を使用して返します。
- ST_Length(SphericalGeography) -> double()¶
地球の球面モデル上のラインストリングまたはマルチラインストリングの長さを返します。これは、ラインストリング上の隣接する点間の測地線距離の合計に相当します。
- ST_PointN(LineString, index) -> Point()¶
指定されたインデックス（インデックスは1から始まる）にあるラインストリングの頂点を返します。指定されたインデックスが1未満、またはコレクションの要素の総数を超える場合は、
NULLを返します。要素の総数を確認するには、:func:ST_NumPointsを使用してください。
- ST_Points(Geometry) -> array(Point)¶
ラインストリング内の点の配列を返します。
- ST_XMax(Geometry) -> double()¶
ジオメトリのバウンディングボックスのX最大値を返します。
- ST_YMax(Geometry) -> double()¶
ジオメトリのバウンディングボックスのY最大値を返します。
- ST_XMin(Geometry) -> double()¶
ジオメトリのバウンディングボックスのX最小値を返します。
- ST_YMin(Geometry) -> double()¶
ジオメトリのバウンディングボックスのY最小値を返します。
- ST_StartPoint(Geometry) -> point()¶
LineStringジオメトリの最初の点をPointとして返します。
ST_PointN(geometry, 1)のショートカットです。
- ST_EndPoint(Geometry) -> point()¶
LineStringジオメトリの最後の点をPointとして返します。
ST_PointN(geometry, ST_NumPoints(geometry))のショートカットです。
- ST_X(Point) -> double()¶
点のX座標を返します。
- ST_Y(Point) -> double()¶
点のY座標を返します。
- ST_InteriorRings(Geometry) -> array(Geometry)¶
入力ジオメトリにあるすべての内部リングの配列を返します。ポリゴンに内部リングがない場合は空の配列を返します。入力ジオメトリが空の場合は
nullを返します。入力ジオメトリがポリゴンでない場合はエラーをスローします。
- ST_NumGeometries(Geometry) -> bigint()¶
コレクション内のジオメトリの数を返します。ジオメトリがジオメトリのコレクション（例：GEOMETRYCOLLECTIONまたはMULTI*）である場合は、ジオメトリの数を返します。単一のジオメトリの場合は1を、空のジオメトリの場合は0を返します。GEOMETRYCOLLECTION内の空のジオメトリはジオメトリとしてカウントされます。例：
ST_NumGeometries(ST_GeometryFromText('GEOMETRYCOLLECTION(MULTIPOINT EMPTY)'))は1になります。
- ST_Geometries(Geometry) -> array(Geometry)¶
指定されたコレクション内のジオメトリの配列を返します。入力ジオメトリがマルチジオメトリでない場合は、1要素の配列を返します。入力ジオメトリが空の場合は
nullを返します。たとえば、MultiLineStringはLineStringの配列を作成します。GeometryCollectionは、その構成要素のフラット化されていない配列を生成します。
GEOMETRYCOLLECTION(MULTIPOINT(0 0, 1 1), GEOMETRYCOLLECTION(MULTILINESTRING((2 2, 3 3))))はarray[MULTIPOINT(0 0, 1 1), GEOMETRYCOLLECTION(MULTILINESTRING((2 2, 3 3)))]を生成します。
- flatten_geometry_collections(Geometry) -> array(Geometry)¶
Geometry内のGeometryCollectionsを再帰的にフラット化し、GeometryCollection以外の構成ジオメトリの配列を返します。配列の順序は任意であり、依存すべきではありません。例
POINT (0 0) -> [POINT (0 0)]、MULTIPOINT (0 0, 1 1) -> [MULTIPOINT (0 0, 1 1)]、GEOMETRYCOLLECTION (POINT (0 0), GEOMETRYCOLLECTION (POINT (1 1))) -> [POINT (0 0), POINT (1 1)]、GEOMETRYCOLLECTION EMPTY -> []。
- ST_NumPoints(Geometry) -> bigint()¶
ジオメトリ内の点の数を返します。これは、点とラインストリングのみに適用されるSQL/MM
ST_NumPoints関数の拡張です。
- ST_NumInteriorRing(Geometry) -> bigint()¶
ポリゴンの内部リングのコレクションのカーディナリティを返します。
- simplify_geometry(Geometry, double) -> Geometry()¶
ダグラス・プッカーアルゴリズムを使用して、入力ジオメトリの「簡略化された」バージョンを返します。無効な派生ジオメトリ（特にポリゴン）の作成を回避します。
- line_locate_point(LineString, Point) -> double()¶
LineString上の与えられたPointに最も近い点の位置を、総2Dライン長の割合として表す0〜1の間の浮動小数点数を返します。
LineStringまたはPointが空または
nullの場合はnullを返します。
- line_interpolate_point(LineString, double) -> Geometry()¶
double引数で指定された割合の距離にあるLineString上のPointを返します。距離が0〜1の間でない場合は、例外をスローします。
LineStringが空の場合は空のPointを返します。LineStringまたはdoubleがnullの場合は
nullを返します。
- geometry_invalid_reason(Geometry) -> varchar()¶
入力ジオメトリが無効または単純でない理由を返します。ジオメトリが無効でも単純でもない場合、無効性の理由のみを返します。入力が有効で単純な場合は
nullを返します。
- great_circle_distance(latitude1, longitude1, latitude2, longitude2) -> double()¶
地球表面上の2点間の測地線距離をキロメートル単位で返します。
- geometry_as_geojson(Geometry) -> varchar()¶
入力ジオメトリによって定義されたGeoJSONエンコードを返します。ジオメトリが原子（非マルチ）空の場合は、この関数はnullを返します。
- geometry_from_geojson(varchar) -> Geometry()¶
GeoJSON表現からジオメトリタイプのオブジェクトを返します。ジオメトリが原子（マルチではない）ジオメトリタイプである場合、空にすることはできません。
集約関数¶
- convex_hull_agg(Geometry) -> Geometry()¶
すべての入力ジオメトリを囲む最小の凸ジオメトリを返します。
- geometry_union_agg(Geometry) -> Geometry()¶
入力ジオメトリすべての点集合の和集合を表すジオメトリを返します。
Bingタイル¶
これらの関数は、ジオメトリとBingタイル間の変換を行います。Bingタイルでは、xとyはtile_xとtile_yを表します。Bingタイルは、zoom、x、yを効率的にエンコードする内部表現を使用して、BigIntとの間でキャストできます。
cast(cast(tile AS BIGINT) AS BINGTILE)
すべてのタイルはbigintにキャストできますが、有効なタイルを表していないbigintからのキャストは例外を発生させます。
- bing_tile(x, y, zoom_level) -> BingTile()¶
XY座標とズームレベルからBingタイルオブジェクトを作成します。ズームレベル1～23がサポートされています。
- bing_tile(quadKey) -> BingTile()¶
quadkeyからBingタイルオブジェクトを作成します。
- bing_tile_parent(tile) -> BingTile()¶
1つ下のズームレベルのBingタイルの親を返します。タイルがズームレベル0の場合、例外をスローします。
- bing_tile_parent(tile, newZoom) -> BingTile()¶
指定された下のズームレベルのBingタイルの親を返します。newZoomが0未満、またはnewZoomがタイルのズームレベルより大きい場合、例外をスローします。
- bing_tile_children(tile) -> array(BingTile)¶
1つ上のズームレベルのBingタイルの子を返します。タイルが最大ズームレベルの場合、例外をスローします。
- bing_tile_children(tile, newZoom) -> array(BingTile)¶
指定された上のズームレベルのBingタイルの子を返します。newZoomが最大ズームレベルより大きい場合、またはnewZoomがタイルのズームレベルより小さい場合、例外をスローします。
- bing_tile_at(latitude, longitude, zoom_level) -> BingTile()¶
指定された緯度と経度の点を含む、指定されたズームレベルのBingタイルを返します。緯度は
[-85.05112878, 85.05112878]の範囲内である必要があります。経度は[-180, 180]の範囲内である必要があります。ズームレベル1～23がサポートされています。
- bing_tiles_around(latitude, longitude, zoom_level) -> array(BingTile)¶
指定された緯度と経度の引数で指定された点を取り囲むBingタイルのコレクションを、指定されたズームレベルで返します。
- bing_tiles_around(latitude, longitude, zoom_level, radius_in_km) -> array(BingTile)¶
指定された(緯度、経度)点を中心とする指定された半径(km)の円を覆う、指定されたズームレベルのBingタイルの最小セットを返します。
- bing_tile_coordinates(tile) -> row<x, y>()¶
指定されたBingタイルのXY座標を返します。
- bing_tile_polygon(tile) -> Geometry()¶
指定されたBingタイルのポリゴン表現を返します。
- bing_tile_quadkey(tile) -> varchar()¶
指定されたBingタイルのquadkeyを返します。
- bing_tile_zoom_level(tile) -> tinyint()¶
指定されたBingタイルのズームレベルを返します。
- geometry_to_bing_tiles(geometry, zoom_level) -> array(BingTile)¶
指定されたズームレベルで指定されたジオメトリを完全にカバーするBingタイルの最小セットを返します。ズームレベル1～23がサポートされています。
- geometry_to_dissolved_bing_tiles(geometry, max_zoom_level) -> array(BingTile)¶
指定されたズームレベルで指定されたジオメトリを完全にカバーするBingタイルの最小セットを返し、子全体のセットを親に再帰的に溶解します。これにより、異なるズームレベルのタイルの配列が小さくなります。たとえば、溶解されていないカバーが[“00”, “01”, “02”, “03”, “10”]の場合、溶解されたカバーは[“0”, “10”]になります。ズームレベル1～23がサポートされています。