本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 空間資料 Amazon Neptune 現在支援空間查詢，可讓您在圖形中存放和分析幾何資料。雖然 通常用於地理位置 （例如地圖上的座標），但空間特徵適用於位置和鄰近程度重要的任何二維資料。使用此功能來回答以下問題：「哪些商店在此客戶 5 英里內？」、「尋找與此服務區域相交的所有交付路由」或「此平面圖中的哪些元件與 HVAC 區域重疊？」 Neptune 使用業界標準的空間類型函數實作空間支援，該函數可與點、多邊形和其他幾何形狀搭配使用。您可以將空間資料儲存為節點和邊緣上的屬性，然後使用空間函數來計算距離、檢查點是否落在邊界內，或尋找重疊區域，全都在您的 openCypher 查詢內。 **常見使用案例**： + **地理應用程式**：以位置為基礎的建議、地理圍欄、路由規劃和區域分析 + **設施和空間管理**：平面圖配置、設備配置和區域涵蓋範圍 + **網路拓撲**：實體基礎設施映射、涵蓋區域和服務界限 + **設計和 CAD**：2D 設計中的元件定位、碰撞偵測和空間關係 + **遊戲開發**：角色定位、碰撞偵測和area-of-effect計算 Amazon Neptune 中的空間類型實作遵循 ISO/IEC 13249-3：2016 指令，例如其他資料庫。[空間函數](access-graph-opencypher-22-spatial-functions.md) 以 openCypher 查詢語言提供。 ## 座標系統 Neptune 在整個資料庫中有一個空間參考識別符 (SRID)。座標系統的同質性可減少查詢中的使用者錯誤，並改善資料庫效能。第一個版本 (1.4.7.0) 支援笛卡爾座標系統，也稱為 SRID 0。 SRID 0 的 Neptune 實作與經度和緯度值相容。使用 根據 WGS84/SRID 4326 `ST_DistanceSpheroid`計算距離。 目前的實作支援儲存 3D 座標。空間函數目前僅支援使用 x 軸和 y 軸 (2 維） 座標。可用的空間函數目前不支援 z 軸座標。 ## 儲存位置資料 使用幾何屬性類型將位置資料存放在節點和邊緣上。從 Well-Known Text (WKT) 格式建立幾何值，這是將地理形狀表示為文字的標準方式。例如，若要存放點位置： ``` CREATE (n:airport {code: 'ATL', location: ST_GeomFromText('POINT (-84.4281 33.6367)')}) ``` 使用地理座標時，第一個引數 (x) 代表經度，第二個引數 (y) 代表經度。這遵循空間資料庫中使用的標準座標順序和 ISO 19125 標準。 **注意** Neptune 現在支援稱為「幾何」的新資料類型。節點或邊緣的幾何屬性可以使用 `ST_GeomFromText`函數從 WKT 字串建立。 Neptune 會自動將點資料存放在專門的空間索引中，以改善空間類型函數的效能。例如，`ST_Contains`用來尋找多邊形內的點是由特殊空間索引加速。 [ 幾何之 Well-Known Text 表示法的 Wikipedia 頁面 ](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) ## 大量載入空間資料 大量載入資料時，請在 CSV 標頭中指定幾何類型。Neptune 會剖析 WKT 字串並建立適當的幾何屬性： ``` :ID,:LABEL,code:String,city:String,location:Geometry 21,airport,ATL,Atlanta,POINT (-84.42810059 33.63669968) 32,airport,ANC,Anchorage,POINT (-149.9960022 61.17440033) 43,airport,AUS,Austin,POINT (-97.66989899 30.19449997) ``` 如需完整的 CSV 格式詳細資訊，請參閱 [openCypher 大量載入格式](bulk-load-tutorial-format-opencypher.md)。 ## 查詢空間資料 下列查詢範例使用 [air-routes 資料集](https://github.com/krlawrence/graph/tree/main/sample-data)，示範如何在 Neptune 中使用空間函數。 如果您的資料具有單獨的經緯度屬性，而不是幾何屬性，您可以在查詢時將其轉換為點。尋找距離指定位置最近的 10 個機場： ``` MATCH (a:airport) WITH a, ST_GeomFromText('POINT (' + a.lon + ' ' + a.lat + ')') AS airportLocation WITH a, airportLocation, ST_Distance(ST_GeomFromText('POINT (-84.4281 33.6367)'), airportLocation) AS distance WHERE distance IS NOT NULL RETURN a.code, a.city, distance ORDER BY distance ASC LIMIT 10 ``` 如果您已將位置儲存為 `ST_Point`，則可以直接使用這些位置值： 1. 設定 屬性 ``` MATCH (a:airport) SET a.location = ST_GeomFromText('POINT (' + a.lon + ' ' + a.lat + ')') ``` 1. 使用 ST\$1Distance 查詢： ``` MATCH (a:airport) WHERE a.location IS NOT NULL WITH a, ST_Distance(ST_GeomFromText('POINT (-84.4281 33.6367)'), a.location) AS distance RETURN a.code, a.city, distance ORDER BY distance ASC LIMIT 10 ``` ### 使用 Bolt 驅動程式 大多數查詢方法將幾何值傳回為 WKT 字串，這些字串可供人類讀取。如果您使用的是 Bolt 驅動程式，幾何值會以 WKB (Well-Known Binary) 格式傳回以提高效率。將 WKB 轉換為應用程式中的幾何物件： ``` try (Session session = driver.session()) { Result result = session.run("MATCH (n:airport {code: 'ATL'}) RETURN n.location as geom"); Record record = result.single(); byte[] wkbBytes = record.get("geom").asByteArray(); // Convert WKB to Geometry object using JTS library WKBReader wkbReader = new WKBReader(); Geometry geom = wkbReader.read(wkbBytes); } ``` # 空間函數 下列空間函數可在 Neptune openCypher 中使用，以使用幾何資料類型： + [ST\$1Point](access-graph-opencypher-22-spatial-functions-st-point.md) + [ST\$1GeomFromText](access-graph-opencypher-22-spatial-functions-st-geomfromtext.md) + [ST\$1AsText](access-graph-opencypher-22-spatial-functions-st-astext.md) + [ST\$1GeometryType](access-graph-opencypher-22-spatial-functions-st-geometrytype.md) + [ST\$1Equals](access-graph-opencypher-22-spatial-functions-st-equals.md) + [ST\$1Contains](access-graph-opencypher-22-spatial-functions-st-contains.md) + [ST\$1Intersects](access-graph-opencypher-22-spatial-functions-st-intersect.md) + [ST\$1Distance](access-graph-opencypher-22-spatial-functions-st-distance.md) + [ST\$1DistanceSpheroid](access-graph-opencypher-22-spatial-functions-st-distancespheroid.md) + [ST\$1Envelope](access-graph-opencypher-22-spatial-functions-st-envelope.md) + [ST\$1Buffer](access-graph-opencypher-22-spatial-functions-st-buffer.md) # ST\$1Point ST\$1Point 會從輸入座標值傳回點。 **語法** ``` ST_Point(x, y, z) ``` **Arguments (引數)** + `x` - DOUBLE PRECISION 資料類型的值，代表第一個座標。 + `y` - 資料類型 DOUBLE PRECISION 的值，代表第二個座標。 + `z` - （選用） **座標順序** 使用地理座標時，第一個引數 (`x`) 代表**經度**，第二個引數 (`y`) 代表**經度**。這遵循空間資料庫中使用的標準座標順序和 ISO 19125 標準。 ``` // Correct: longitude first, latitude second ST_Point(-84.4281, 33.6367) // Atlanta airport // Incorrect: latitude first, longitude second ST_Point(33.6367, -84.4281) // This will return NaN in distance calculations ``` **有效的座標範圍** 對於地理資料，請確保座標落在有效範圍內： + 經度 (`x`)：-180 到 180 + 緯度 (`y`)：-90 到 90 與距離計算函數搭配使用時，超出這些範圍的座標將傳回 `NaN`（非數字），例如 `ST_DistanceSpheroid`。 **傳回類型** 子類型 POINT 的 GEOMETRY 如果 x 或 y 為 Null，則會傳回 Null。 **範例** 下列會從輸入座標建構點幾何。 ``` RETURN ST_Point(5.0, 7.0); POINT(5 7) ``` # ST\$1GeomFromText ST\$1GeomFromText 會從輸入幾何的已知文字 (WKT) 表示法建構幾何物件。 **語法** ``` ST_GeomFromText(wkt_string) ``` **Arguments (引數)** + `wkt_string` - 資料類型 STRING 的值，它是幾何的 WKT 表示法。 **傳回類型** GEOMETRY 如果 wkt\$1string 為 null，則傳回 null。 如果 wkt\$1string 無效，則會傳回 BadRequestException。 **範例** ``` RETURN ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))') POLYGON((0 0,0 1,1 1,1 0,0 0)) ``` # ST\$1AsText ST\$1AsText 會傳回輸入幾何的已知文字 (WKT) 表示法。 **語法** ``` ST_AsText(geo) ``` **Arguments (引數)** + `geo` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 的表達式。 **傳回類型** STRING 如果 geo 為 null，則傳回 null。 如果輸入參數不是幾何，則會傳回 BadRequestException。 如果結果大於 64-KB STRING，則會傳回錯誤。 **範例** ``` RETURN ST_AsText(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))')) POLYGON((0 0,0 1,1 1,1 0,0 0)) ``` # ST\$1GeometryType ST\$1GeometryType 會將幾何的類型傳回為字串。 **語法** ``` ST_GeometryType(geom) ``` **Arguments (引數)** + `geom` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 **傳回類型** STRING 如果 geom 為 Null，則會傳回 Null。 如果輸入參數不是幾何，則會傳回 BadRequestException。 **範例** ``` RETURN ST_GeometryType(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)')); ST_LineString ``` # ST\$1Equals 如果輸入幾何的 2D 投影在拓撲上相等，ST\$1Equals 會傳回 true。如果幾何具有相等點集，則視為拓撲相等。在拓撲相等幾何中，頂點的順序可能會有所不同，同時維持此相等性。 **語法** ``` ST_Equals(geom1, geom2) ``` **Arguments (引數)** + `geom1` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 + `geom2` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。這個值會和 geom1 比較，以判斷其是否與 geom1 相等。 **傳回類型** BOOLEAN 如果 geom1 或 geom2 為 Null，則會傳回 Null。 如果 geom1 或 geom2 不是 Geometries，則會傳回 BadRequestException。 **範例** ``` RETURN ST_Equals( ST_GeomFromText('POLYGON ((0 2,1 1,0 -1,0 2))'), ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))')); false ``` 以下檢查兩個 linestring 在幾何上是否相等。 ``` RETURN ST_Equals( ST_GeomFromText('LINESTRING (1 0, 10 0)'), ST_GeomFromText('LINESTRING(1 0,5 0,10 0)')); true ``` # ST\$1Contains ST\$1Contains 會在第一個輸入幾何的 2D 投影包含第二個輸入幾何的 2D 投影時傳回 true。如果 B 中的每個點都是 A 中的點，且其內部具有非空交集，則幾何 A 包含幾何 B。ST\$1Contains(A， B) 等同於 ST\$1Within(B， A)。 **語法** ``` ST_Contains(geom1, geom2) ``` **Arguments (引數)** + `geom1` - GEOMETRY 類型的值或評估為 GEOMETRY 類型的表達式。 + `geom2` - GEOMETRY 類型的值或評估為 GEOMETRY 類型的表達式。這個值會和 geom1 比較，以判斷其是否包含在 geom1 中。 **傳回類型** BOOLEAN 如果 geom1 或 geom2 為 Null，則會傳回 Null。 如果輸入參數不是幾何，則會傳回 BadRequestException。 **範例** ``` RETURN ST_Contains( ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'), ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))')); false ``` # ST\$1Intersects ST\$1Intersects 會在兩個輸入幾何的 2D 投影至少擁有一個相同點時傳回 True。 **語法** ``` ST_Intersects(geom1, geom2) ``` **Arguments (引數)** + `geom1` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 + `geom2` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 **傳回類型** BOOLEAN 如果 geom1 或 geom2 為 Null，則會傳回 Null。 如果輸入參數不是幾何，則會傳回 BadRequestException。 **範例** ``` RETURN ST_Intersects( ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(2 2,2 5,5 5,5 2,2 2))'), ST_GeomFromText('MULTIPOINT((4 4),(6 6))')); true ``` # ST\$1Distance 對於輸入幾何，ST\$1Distance 會傳回兩個輸入幾何值的 2D 投影之間的最小歐幾里得距離。 **語法** ``` ST_Distance(geo1, geo2) ``` **Arguments (引數)** + `geo1` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 + `geo2` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 的表達式。 **傳回類型** DOUBLE PRECISION 與輸入幾何的單位相同。 如果 geo1 或 geo2 為 null，則會傳回 null。 如果輸入參數不是幾何，則會傳回 BadRequestException。 **範例** ``` RETURN ST_Distance( ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'), ST_GeomFromText('POLYGON((-1 -3,-2 -1,0 -3,-1 -3))')); 1.4142135623731 ``` # ST\$1DistanceSpheroid 傳回兩個 lon/lat 幾何之間的最小距離，以公尺為單位。球狀體是 WGS84/SRID 4326。 **語法** ``` ST_DistanceSpheroid(geom1, geom2); ``` **Arguments (引數)** + `geom1` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 + `geom2` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 **傳回類型** FLOAT 如果 geom 為 Null，則會傳回 Null。 **範例** ``` RETURN ST_DistanceSpheroid( ST_GeomFromText('POINT(-110 42)'), ST_GeomFromText('POINT(-118 38)')) 814278.77 ``` # ST\$1Envelope ST\$1Enelope 會傳回輸入幾何的最小週框方塊，如下所示。 + 如果輸入幾何是空的，則傳回的幾何會是 POINT EMPTY。 + 如果輸入幾何圖形的最小週框方塊退化為一點，則傳回的幾何為一點。 + 如果上述都不是 true，則函數會傳回counter-clockwise-oriented的多邊形，其頂點是最小週框方塊的邊角。 對於所有非空輸入，此函數對輸入幾何的 2D 投影進行操作。 **語法** ``` ST_Envelope(geom) ``` **Arguments (引數)** + `geom` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 **傳回類型** GEOMETRY 如果 geom 為 Null，則會傳回 Null。 **範例** ``` RETURN ST_Envelope(ST_GeomFromText("POLYGON ((2 1, 4 3, 6 1, 5 5, 3 4, 2 1))")) POLYGON ((2 1, 6 1, 6 5, 2 5, 2 1)) ``` # ST\$1Buffer ST\$1Buffer 傳回 2D 幾何，該幾何表示與投影在 xy 笛卡爾平面上的輸入幾何的距離小於或等於輸入距離的所有點。 **語法** ``` ST_Buffer(geom, distance, number_of_segments_per_quarter_circle) ``` **Arguments (引數)** + `geom` - 資料類型 GEOMETRY 的值，或評估為 GEOMETRY 類型的表達式。 + `distance` - DOUBLE PRECISION 資料類型的值，代表緩衝區的距離 （或半徑）。 + `number_of_segments_per_quarter_circle` - 資料類型 INTEGER 的值 （應大於或等於 0)。此值決定了圍繞輸入幾何的每個頂點近似四分之一圓的點數。負值預設為零。預設值為 8。 **傳回類型** GEOMETRY ST\$1Buffer 函數會傳回 xy 笛卡爾平面中的二維 (2D) 幾何。 **範例** ``` RETURN ST_Buffer(ST_GeomFromText('LINESTRING (1 2,5 2,5 8)'), 2, 4); POLYGON ((3 4, 3 8, 3.1522409349774265 8.76536686473018, 3.585786437626905 9.414213562373096, 4.234633135269821 9.847759065022574, 5 10, 5.765366864730179 9.847759065022574, 6.414213562373095 9.414213562373096, 6.847759065022574 8.76536686473018, 7 8, 7 2, 6.847759065022574 1.2346331352698203, 6.414213562373095 0.5857864376269051, 5.765366864730179 0.1522409349774265, 5 0, 1 0, 0.2346331352698193 0.152240934977427, -0.4142135623730954 0.5857864376269051, -0.8477590650225737 1.2346331352698208, -1 2.0000000000000004, -0.8477590650225735 2.7653668647301797, -0.4142135623730949 3.414213562373095, 0.2346331352698206 3.8477590650225735, 1 4, 3 4)) ``` 以下會傳回近似圓的輸入點幾何緩衝區。由於此命令指定 3 作為每四分之一圓的線段數，因此函數使用三個線段來近似四分之一圓。 ``` RETURN ST_Buffer(ST_GeomFromText('POINT (1 1)'), 1.0, 8)); POLYGON ((2 1, 1.9807852804032304 0.8049096779838718, 1.9238795325112867 0.6173165676349102, 1.8314696123025453 0.4444297669803978, 1.7071067811865475 0.2928932188134525, 1.5555702330196022 0.1685303876974548, 1.3826834323650898 0.0761204674887133, 1.1950903220161284 0.0192147195967696, 1 0, 0.8049096779838718 0.0192147195967696, 0.6173165676349103 0.0761204674887133, 0.444429766980398 0.1685303876974545, 0.2928932188134525 0.2928932188134524, 0.1685303876974546 0.4444297669803978, 0.0761204674887133 0.6173165676349102, 0.0192147195967696 0.8049096779838714, 0 0.9999999999999999, 0.0192147195967696 1.1950903220161284, 0.0761204674887132 1.3826834323650896, 0.1685303876974545 1.555570233019602, 0.2928932188134523 1.7071067811865475, 0.4444297669803978 1.8314696123025453, 0.6173165676349097 1.9238795325112865, 0.8049096779838714 1.9807852804032304, 0.9999999999999998 2, 1.1950903220161284 1.9807852804032304, 1.38268343236509 1.9238795325112865, 1.5555702330196017 1.8314696123025453, 1.7071067811865475 1.7071067811865477, 1.8314696123025453 1.5555702330196022, 1.9238795325112865 1.3826834323650905, 1.9807852804032304 1.1950903220161286, 2 1)) ```