Amazon Athena
ユーザーガイド

サポートされる地理空間関数のリスト

Athena の地理空間関数には以下の特性があります。

  • 関数は、空間クエリの一般原則に従います。

  • 関数は、ESRI Java Geometry Library を使用する Presto プラグインとして実装されます。このライブラリには Apache 2 ライセンスが付いています。

  • 関数は、ESRI Geometry API に依存します。

  • ESRI でサポートされる関数の一部は Athena で使用できません。このトピックでは、Athena でサポートされる ESRI 地理空間関数のみを示しています。

  • 地理空間関数ではビューを使用できません。

Athena は 4 種類の地理空間関数をサポートしています。

開始する前に

以下に示すように、2 つのテーブル earthquakes および counties を作成します。

CREATE external TABLE earthquakes ( earthquake_date STRING, latitude DOUBLE, longitude DOUBLE, depth DOUBLE, magnitude DOUBLE, magtype string, mbstations string, gap string, distance string, rms string, source string, eventid string ) ROW FORMAT DELIMITED FIELDS TERMINATED BY ',' STORED AS TEXTFILE LOCATION 's3://my-query-log/csv'
CREATE external TABLE IF NOT EXISTS counties ( Name string, BoundaryShape binary ) ROW FORMAT SERDE 'com.esri.hadoop.hive.serde.JsonSerde' STORED AS INPUTFORMAT 'com.esri.json.hadoop.EnclosedJsonInputFormat' OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' LOCATION 's3://my-query-log/json'

以降の例のいくつかは、これらのテーブルに基づいており、Amazon S3 の場所に保存されている 2 つのサンプルファイルに依存します。これらのファイルは参考専用であり、Athena には含まれていません。

  • earthquakes.csv ファイルは、カリフォルニアで発生した地震を一覧表示します。このファイル内のフィールドは、earthquakes テーブルのフィールドに対応します。

  • california-counties.json ファイルは、JSON エンコード形式の郡のデータを ESRI 準拠形式で表示します。AREA、PERIMETER、STATE、COUNTY、NAME など、多くのフィールドが含まれています。counties テーブルは、このファイルに基づいており、フィールドは Name (文字列) と BoundaryShape (バイナリ) の 2 つのみです。

コンストラクター関数

コンストラクター地理空間関数では、point`line、または polygon のバイナリ表現を取得します。また、特定のジオメトリデータ型をテキストに変換したり、テキスト (WKT) からジオメトリデータ型のバイナリ表現を取得したりできます。

ST_POINT(double, double)

値を point データ型で返します。この値は、ジオメトリデータ型 point のバイナリ表現です。

ST_POINT のジオメトリデータ型 point の場合、Athena が使用するマップ単位はデカルト座標、角度単位は空間参照であり、線形単位で指定され、全地球測位システム (GPS) 世界測地系 (WGS1984 または WGS84) 形式に基づいています。たとえば、ST_BUFFER(ST_POINT(40.705220,-74.006801), 15.0) という表記では、マップ座標はデカルト座標系の単位で指定され、角度の値 15 は WGS84 に基づいた線形単位で指定されています。

構文:

SELECT ST_POINT(longitude, latitude) FROM earthquakes LIMIT 1;

別の構文で、座標系を point データ型の 2 つの値として指定することもできます。

SELECT ST_POINT('point (0 0)') FROM earthquakes LIMIT 1;

例.次の例では、earthquakes.csv の特定の経度と緯度の座標系を使用しています。

SELECT ST_POINT(61.56, -158.54) FROM earthquakes LIMIT 1;

ジオメトリデータ型 point の次のバイナリ表現が返されます。

00 00 00 00 01 01 00 00 00 48 e1 7a 14 ae c7 4e 40 e1 7a 14 ae 47 d1 63 c0

ST_LINE(varchar)

値を line データ型で返します。この値は、ジオメトリデータ型 line のバイナリ表現です。例:

SELECT ST_Line('linestring(1 1, 2 2, 3 3)')

ST_POLYGON(varchar)

値を polygon データ型で返します。この値は、ジオメトリデータ型 polygon のバイナリ表現です。例:

SELECT ST_Polygon('polygon ((1 1, 4 1, 1 4))')

ST_GEOMETRY_TO_TEXT (varbinary)

指定した各ジオメトリデータ型をテキストに変換します。値をジオメトリデータ型で返します。この値は、ジオメトリデータ型の WKT 表現です。例:

SELECT ST_GEOMETRY_TO_TEXT(ST_POINT(61.56, -158.54))

ST_GEOMETRY_FROM_TEXT (varchar)

テキストをジオメトリデータ型に変換します。値をジオメトリデータ型で返します。この値は、ジオメトリデータ型のバイナリ表現です。例:

SELECT ST_GEOMETRY_FROM_TEXT(ST_GEOMETRY_TO_TEXT(ST_Point(1, 2)))

地理空間関係関数

以下の関数は、入力として指定した 2 つの異なるジオメトリ間の関係を表現します。結果を boolean 型で返します。ジオメトリのペアを指定する順序が重要になります。最初のジオメトリ値は左ジオメトリ、2 番目のジオメトリ値は右ジオメトリと呼ばれます。

これら関数は以下を返します。

  • TRUE。関数が記述する関係が満たされた場合に限ります。

  • FALSE。関数が記述する関係が満たされない場合に限ります。

ST_CONTAINS (geometry, geometry)

左ジオメトリに右ジオメトリが含まれている場合に限り、TRUE を返します。例:

SELECT ST_CONTAINS('POLYGON((0 2,1 1,0 -1,0 2))', 'POLYGON((-1 3,2 1,0 -3,-1 3))')
SELECT ST_CONTAINS('POLYGON((0 2,1 1,0 -1,0 2))', ST_Point(0, 0));
SELECT ST_CONTAINS(ST_GEOMETRY_FROM_TEXT('POLYGON((0 2,1 1,0 -1,0 2))'), ST_GEOMETRY_FROM_TEXT('POLYGON((-1 3,2 1,0 -3,-1 3))'))

ST_CROSSES (geometry, geometry)

左ジオメトリが右ジオメトリとクロスする場合に限り、TRUE を返します。例:

SELECT ST_CROSSES(ST_LINE('linestring(1 1, 2 2 )'), ST_LINE('linestring(0 1, 2 2)'))

ST_DISJOINT (geometry, geometry)

左ジオメトリと右ジオメトリの共通部分が空の場合に限り、TRUE を返します。例:

SELECT ST_DISJOINT(ST_LINE('linestring(0 0, 0 1)'), ST_LINE('linestring(1 1, 1 0)'))

ST_EQUALS (geometry, geometry)

左ジオメトリに右ジオメトリと等しい場合に限り、TRUE を返します。例:

SELECT ST_EQUALS(ST_LINE('linestring( 0 0, 1 1)'), ST_LINE('linestring(1 3, 2 2)'))

ST_INTERSECTS (geometry, geometry)

左ジオメトリが右ジオメトリとインターセクトする場合に限り、TRUE を返します。例:

SELECT ST_INTERSECTS(ST_LINE('linestring(8 7, 7 8)'), ST_POLYGON('polygon((1 1, 4 1, 4 4, 1 4))'))

ST_OVERLAPS (geometry, geometry)

左ジオメトリが右ジオメトリにオーバーラップする場合に限り、TRUE を返します。例:

SELECT ST_OVERLAPS(ST_POLYGON('polygon((2 0, 2 1, 3 1))'), ST_POLYGON('polygon((1 1, 1 4, 4 4, 4 1))'))

ST_RELATE (geometry, geometry)

左ジオメトリが右ジオメトリとの間に指定した DE-9IM (Dimensionally Extended nine-Intersection Model) 関係がある場合に限り、TRUE を返します。詳細については、Wikipedia のトピック「DE-9IM」を参照してください。例:

SELECT ST_RELATE(ST_LINE('linestring(0 0, 3 3)'), ST_LINE('linestring(1 1, 4 4)'), 'T********')

ST_TOUCHES (geometry, geometry)

左ジオメトリが右ジオメトリに接する場合に限り、TRUE を返します。

例:

SELECT ST_TOUCHES(ST_POINT(8, 8), ST_POLYGON('polygon((1 1, 1 4, 4 4, 4 1))'))

ST_WITHIN (geometry, geometry)

左ジオメトリが右ジオメトリ内にある場合に限り、TRUE を返します。

例:

SELECT ST_WITHIN(ST_POINT(8, 8), ST_POLYGON('polygon((1 1, 1 4, 4 4, 4 1))'))

オペレーション関数

オペレーション関数では、ジオメトリデータ型の値に対してオペレーションを実行します。たとえば、単一のジオメトリデータ型の境界、2 つのジオメトリデータ型の共通部分、左ジオメトリと右ジオメトリ間の差異 (両方が同じデータ型の場合)、および特定のジオメトリデータ型の外部バッファや外部リングを取得できます。

すべてのオペレーション関数では、いずれかのジオメトリデータ型を入力として受け取り、そのバイナリ表現を返します。

ST_BOUNDARY (geometry)

いずれかのジオメトリデータ型を入力として受け取り、boundary ジオメトリデータ型のバイナリ表現を返します。

例:

SELECT ST_BOUNDARY(ST_LINE('linestring(0 1, 1 0)')))
SELECT ST_BOUNDARY(ST_POLYGON('polygon((1 1, 1 4, 4 4, 4 1))'))

ST_BUFFER (geometry, double)

いずれかのジオメトリデータ型 (point、line、polygon、multiline、multipolygon、および double 型として distance) を入力として受け取ります。指定した距離 (または半径) でバッファリングされたジオメトリデータ型のバイナリ表現を返します。

例:

SELECT ST_BUFFER(ST_Point(1, 2), 2.0)

ST_DIFFERENCE (geometry, geometry)

左ジオメトリと右ジオメトリ間の差異のバイナリ表現を返します。例:

SELECT ST_GEOMETRY_TO_TEXT(ST_DIFFERENCE(ST_POLYGON('polygon((0 0, 0 10, 10 10, 10 0))'), ST_POLYGON('polygon((0 0, 0 5, 5 5, 5 0))')))

ST_ENVELOPE (geometry)

いずれかのジオメトリデータ型を入力として受け取り、エンベロープのバイナリ表現を返します。エンベロープは指定したジオメトリデータ型を囲む四角形です。例:

SELECT ST_ENVELOPE(ST_LINE('linestring(0 1, 1 0)'))
SELECT ST_ENVELOPE(ST_POLYGON('polygon((1 1, 1 4, 4 4, 4 1))'))

ST_EXTERIOR_RING (geometry)

入力タイプ polygon の外部リングのバイナリ表現を返します。例:

SELECT ST_EXTERIOR_RING(ST_POLYGON(1,1, 1,4, 4,1))
SELECT ST_EXTERIOR_RING(ST_POLYGON('polygon ((0 0, 8 0, 0 8, 0 0), (1 1, 1 5, 5 1, 1 1))'))

ST_INTERSECTION (geometry, geometry)

左ジオメトリと右ジオメトリの共通部分のバイナリ表現を返します。例:

SELECT ST_INTERSECTION(ST_POINT(1,1), ST_POINT(1,1))
SELECT ST_INTERSECTION(ST_LINE('linestring(0 1, 1 0)'), ST_POLYGON('polygon((1 1, 1 4, 4 4, 4 1))'))
SELECT ST_GEOMETRY_TO_TEXT(ST_INTERSECTION(ST_POLYGON('polygon((2 0, 2 3, 3 0))'), ST_POLYGON('polygon((1 1, 4 1, 4 4, 1 4))')))

ST_SYMMETRIC_DIFFERENCE (geometry, geometry)

左ジオメトリと右ジオメトリ間の幾何学的な対称差のバイナリ表現を返します。例:

SELECT ST_GEOMETRY_TO_TEXT(ST_SYMMETRIC_DIFFERENCE(ST_LINE('linestring(0 2, 2 2)'), ST_LINE('linestring(1 2, 3 2)')))

アクセサ関数

アクセサ関数は、varchar 型、bigint 型、または double 型を、さまざまな geometry データ型から取得するのに役立ちます。ここで、geometry は Athena でサポートされているジオメトリデータ型 (pointlinepolygonmultiline、および multipolygon) のいずれかです。たとえば、polygon ジオメトリデータ型の面積、指定したジオメトリデータ型の最大と最小の X 値と Y 値、line の長さ、または指定したジオメトリデータ型のポイント数を取得できます。

ST_AREA (geometry)

ジオメトリデータ型 polygon を入力として受け取り、面積を double 型で返します。例:

SELECT ST_AREA(ST_POLYGON('polygon((1 1, 4 1, 4 4, 1 4))'))

ST_CENTROID (geometry)

ジオメトリデータ型 polygon を入力として受け取り、ポリゴンのエンベロープの中心である pointvarchar 型で返します。例:

SELECT ST_CENTROID(ST_GEOMETRY_FROM_TEXT('polygon ((0 0, 3 6, 6 0, 0 0))'))

ST_COORDINATE_DIMENSION (geometry)

サポートされているいずれかのジオメトリ型を入力として受け取り、座標コンポーネントの数を bigint 型で返します。例:

SELECT ST_COORDINATE_DIMENSION(ST_POINT(1.5,2.5))

ST_DIMENSION (geometry)

サポートされているいずれかのジオメトリ型を入力として受け取り、ジオメトリの空間ディメンションを bigint 型で返します。例:

SELECT ST_DIMENSION(ST_POLYGON('polygon((1 1, 4 1, 4 4, 1 4))'))

ST_DISTANCE (geometry, geometry)

左ジオメトリと右ジオメトリ間の距離を double 型で返します。例:

SELECT ST_DISTANCE(ST_POINT(0.0,0.0), ST_POINT(3.0,4.0))

ST_IS_CLOSED (geometry)

ラインが閉じている場合に限り、TRUE (boolean 型) を返します。例:

SELECT ST_IS_CLOSED(ST_LINE('linestring(0 2, 2 2)'))

ST_IS_EMPTY (geometry)

指定したジオメトリが空の場合に限り、TRUE (boolean 型) を返します。例:

SELECT ST_IS_EMPTY(ST_POINT(1.5, 2.5))

ST_IS_RING (geometry)

line 型が閉じていてシンプルである場合に限り、TRUE (boolean 型) を返します。例:

SELECT ST_IS_RING(ST_LINE('linestring(0 2, 2 2)'))

ST_LENGTH (geometry)

line の長さを double 型で返します。例:

SELECT ST_LENGTH(ST_LINE('linestring(0 2, 2 2)'))

ST_MAX_X (geometry)

ジオメトリの X 座標の最大値を double 型で返します。例:

SELECT ST_MAX_X(ST_LINE('linestring(0 2, 2 2)'))

ST_MAX_Y (geometry)

ジオメトリの Y 座標の最大値を double 型で返します。例:

SELECT ST_MAX_Y(ST_LINE('linestring(0 2, 2 2)'))

ST_MIN_X (geometry)

ジオメトリの X 座標の最小値を double 型で返します。例:

SELECT ST_MIN_X(ST_LINE('linestring(0 2, 2 2)'))

ST_MIN_Y (geometry)

ジオメトリの Y 座標の最小値を double 型で返します。例:

SELECT ST_MAX_Y(ST_LINE('linestring(0 2, 2 2)'))

ST_START_POINT (geometry)

line ジオメトリデータ型の最初のポイントを point 型で返します。例:

SELECT ST_START_POINT(ST_LINE('linestring(0 2, 2 2)'))

ST_END_POINT (geometry)

line ジオメトリデータ型の最後のポイントを point 型で返します。例:

SELECT ST_END_POINT(ST_LINE('linestring(0 2, 2 2)'))

ST_X (point)

ポイントの X 座標を double 型で返します。例:

SELECT ST_X(ST_POINT(1.5, 2.5))

ST_Y (point)

ポイントの Y 座標を double 型で返します。例:

SELECT ST_Y(ST_POINT(1.5, 2.5))

ST_POINT_NUMBER (geometry)

ジオメトリのポイント数を bigint 型で返します。例:

SELECT ST_POINT_NUMBER(ST_POINT(1.5, 2.5))

ST_INTERIOR_RING_NUMBER (geometry)

polygon ジオメトリの内部リング数を bigint 型で返します。例:

SELECT ST_INTERIOR_RING_NUMBER(ST_POLYGON('polygon ((0 0, 8 0, 0 8, 0 0), (1 1, 1 5, 5 1, 1 1))'))