本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 查詢地理空間資料
<a name="querying-geospatial-data"></a>

地理空間資料包含識別符來指定物體的地理位置。這類資料的例子包括天氣報告、地圖方向、含地理位置的推文、商店位置，以及飛機航線。地理空間資料在商業分析、報告和預測方面扮演重要角色。

地理空間識別符 (例如經緯度) 可讓您將任何郵寄地址轉換為一組地理座標。

## 什麼是地理空間查詢？
<a name="geospatial-query-what-is"></a>

地理空間查詢為 Athena 中支援的特殊 SQL 查詢類型。它們與非空間 SQL 查詢的差別在於下列各方面：
+ 使用以下特殊化幾何資料類型：`point`、`line`、`multiline`、`polygon` 和 `multipolygon`。
+ 表示幾何資料類型之間的關係，例如 `distance`、`equals`、`crosses`、`touches`、`overlaps`、`disjoint` 等等。

您可以在 Athena 中使用地理空間查詢，執行這些和其他類似操作：
+ 尋找兩點之間的距離。
+ 檢查是否一個區域 (多邊形) 包含其他區域。
+ 檢查一個線條是否與其他線條或多邊形交錯或碰觸。

例如，若要在 Athena 中從瑞尼爾山之地理座標的類型 `double` 值中取得 `point` 幾何資料類型，請如下列範例所示，使用 `ST_Point (longitude, latitude)` 地理空間函數。

```
ST_Point(-121.7602, 46.8527)
```

## 輸入資料格式和幾何資料類型
<a name="geospatial-input-data-formats-supported-geometry-types"></a>

若要在 Athena 中使用地理空間函數，請以 WKT 格式輸入資料，或使用 Hive JSON SerDe。您也可以使用 Athena 中支援的幾何資料類型。

### 輸入資料格式
<a name="input-data-formats"></a>

為處理地理空間查詢，Athena 支援以下資料格式的輸入資料：
+  **WKT (已知文字)**。在 Athena 中，WKT 會以 `varchar(x)` 或 `string` 資料類型表示。
+  **JSON 編碼的地理空間資料**。為剖析具有地理空間資料的 JSON 檔案並為它們建立資料表，Athena 會使用 [Hive SerDe JSON](https://github.com/Esri/spatial-framework-for-hadoop/wiki/Hive-JSON-SerDe)。如需有關在 Athena 中使用此 SerDe 的詳細資訊，請參閱 [JSON SerDe 程式庫](json-serde.md)。

### 幾何資料類型
<a name="geometry-data-types"></a>

為處理地理空間查詢，Athena 支援以下特殊幾何資料類型：
+  `point` 
+  `line` 
+  `polygon` 
+  `multiline` 
+  `multipolygon` 

## 支援的地理空間函數
<a name="geospatial-functions-list"></a>

如需有關 Athena 引擎版本 3 中地理空間函數的資訊，請參閱 Trino 文件中的 [Geospatial functions](https://trino.io/docs/current/functions/geospatial.html) (地理空間函數)。

# 範例：地理空間查詢
<a name="geospatial-example-queries"></a>

本主題中的範例會從 GitHub 上可用的範例資料建立兩個資料表，並根據該資料查詢資料表。範例資料位於下列檔案中，僅供說明之用且不保證準確無誤：
+ **[https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/earthquake-data/earthquakes.csv](https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/earthquake-data/earthquakes.csv)** – 列出在加州發生的地震。範例 `earthquakes` 資料表使用此資料的欄位。
+ **[https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/counties-data/california-counties.json](https://github.com/Esri/gis-tools-for-hadoop/blob/master/samples/data/counties-data/california-counties.json)** – 以[符合 ESRI 規範的 GeoJSON 格式](https://doc.arcgis.com/en/arcgis-online/reference/geojson.htm)列出加州的郡資料。該資料包含許多欄位，例如 `AREA`、`PERIMETER`、`STATE`、`COUNTY` 和 `NAME`，但範例 `counties` 資料表僅使用兩個欄位：`Name` (字串) 和 `BoundaryShape` (二進位)。
**注意**  
Athena 使用 `com.esri.json.hadoop.EnclosedEsriJsonInputFormat`，將 JSON 資料轉換為地理空間二進位格式。

以下程式碼範例會建立名為 `earthquakes` 的資料表：

```
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://amzn-s3-demo-bucket/my-query-log/csv/';
```

以下程式碼範例會建立名為 `counties` 的資料表：

```
CREATE external TABLE IF NOT EXISTS counties
 (
 Name string,
 BoundaryShape binary
 )
ROW FORMAT SERDE 'com.esri.hadoop.hive.serde.EsriJsonSerDe'
STORED AS INPUTFORMAT 'com.esri.json.hadoop.EnclosedEsriJsonInputFormat'
OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
LOCATION 's3://amzn-s3-demo-bucket/my-query-log/json/';
```

下列範例查詢使用 `counties` 和 `earthquake` 資料表上的 `CROSS JOIN` 函數。該範例使用 `ST_CONTAINS` 查詢其界限包括地震位置的郡，該地震位置是使用 `ST_POINT` 指定。該查詢會將這類郡依名稱分組、依計數排序，並依遞減順序傳回。

```
SELECT counties.name,
        COUNT(*) cnt
FROM counties
CROSS JOIN earthquakes
WHERE ST_CONTAINS (ST_GeomFromLegacyBinary(counties.boundaryshape), ST_POINT(earthquakes.longitude, earthquakes.latitude))
GROUP BY  counties.name
ORDER BY  cnt DESC
```

此查詢會傳回：

```
+------------------------+
| name             | cnt |
+------------------------+
| Kern             | 36  |
+------------------------+
| San Bernardino   | 35  |
+------------------------+
| Imperial         | 28  |
+------------------------+
| Inyo             | 20  |
+------------------------+
| Los Angeles      | 18  |
+------------------------+
| Riverside        | 14  |
+------------------------+
| Monterey         | 14  |
+------------------------+
| Santa Clara      | 12  |
+------------------------+
| San Benito       | 11  |
+------------------------+
| Fresno           | 11  |
+------------------------+
| San Diego        | 7   |
+------------------------+
| Santa Cruz       | 5   |
+------------------------+
| Ventura          | 3   |
+------------------------+
| San Luis Obispo  | 3   |
+------------------------+
| Orange           | 2   |
+------------------------+
| San Mateo        | 1   |
+------------------------+
```

## 其他資源
<a name="geospatial-example-queries-additional-resources"></a>

如需地理空間查詢的其他範例，請參閱下列部落格文章：
+ [使用 UDFs 和 擴展 Amazon Athena 中的地理空間查詢 AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/) 
+ [使用 Amazon Athena 和 Amazon Quick 視覺化超過 200 年的全球氣候資料](https://aws.amazon.com/blogs/big-data/visualize-over-200-years-of-global-climate-data-using-amazon-athena-and-amazon-quicksight/)。
+ [使用 Amazon Athena 查詢 OpenStreetMap](https://aws.amazon.com/blogs/big-data/querying-openstreetmap-with-amazon-athena/)