使用空間資料類型
自 JDBC 驅動程式預覽版本 6.5.0 開始，支援空間資料類型 (Geometry 和 Geography)。 預存程序、資料表值參數 (TVP)、BulkCopy 和 Always Encrypted 目前不支援空間資料類型。 此頁面顯示 Geometry 和 Geography 資料類型搭配 JDBC Driver 的各種使用案例。 如需空間資料類型的概觀，請參閱空間資料類型概觀頁面。
建立 Geometry / Geography 物件
建立 Geometry / Geography 物件的主要方式有兩種：從 Well-Known Text (WKT) 或內部 SQL Server 格式 (CLR) 轉換。
從 WKT 建立
String geoWKT = "LINESTRING(1 0, 0 1, -1 0)";
Geometry geomWKT = Geometry.STGeomFromText(geoWKT, 0);
Geography geogWKT = Geography.STGeomFromText(geoWKT, 4326);
此程式碼會建立空間參考系統識別碼 (Spatial Reference System Identifier，SRID) 為 0 的 LINESTRING Geometry 物件，以及 SRID 為 4326 的 Geography 物件。
從 CLR 建立
byte[] geomCLR = Hex.decodeHex("00000000010403000000000000000000F03F00000000000000000000000000000000000000000000F03F000000000000F0BF000000000000000001000000010000000001000000FFFFFFFF0000000002".toCharArray());
byte[] geogCLR = Hex.decodeHex("E61000000104030000000000000000000000000000000000F03F000000000000F03F00000000000000000000000000000000000000000000F0BF01000000010000000001000000FFFFFFFF0000000002".toCharArray());
Geometry geomWKT = Geometry.deserialize(geomCLR);
Geography geogWKT = Geography.deserialize(geogCLR);
此程式碼會建立 Geometry 和 Geography 物件，相當於過去從 WKT 建立的物件。
使用 Geometry / Geography 物件
假設使用者在 SQL Server 上擁有如下的資料表：
CREATE TABLE sampleTable (c1 geometry)
以下為插入 Geometry 值的範例指令碼：
String geoWKT = "LINESTRING(1 0, 0 1, -1 0)";
Geometry geomWKT = Geometry.STGeomFromText(geoWKT, 0);
SQLServerPreparedStatement pstmt = (SQLServerPreparedStatement) connection.prepareStatement("insert into sampleTable values (?)");
pstmt.setGeometry(1, geomWKT);
pstmt.execute();
您可以使用 Geography 資料行和 setGeography() 方法，針對 Geography 對應項目完成相同的作業。
讀取 Geometry / Geography 資料行：
try(SQLServerResultSet rs = (SQLServerResultSet)stmt.executeQuery("select * from geomTable")) {
while(rs.next()){
rs.getGeometry(1);
}
}
您可以使用 Geography 資料行和 getGeography() 方法，針對 Geography 對應項目完成相同的作業。
新引進的 API
這些方法是此次新增所引入的新公用 API，類別為 SQLServerPreparedStatement、SQLServerResultSet、Geometry 和 Geography。
SQLServerPreparedStatement
| 方法 | 描述 |
|---|---|
| void setGeometry(int n, Geometry x) | 將指定參數設定為指定的 microsoft.sql.Geometry 類別物件。 |
| void setGeography(int n, Geography x) | 將指定參數設定為指定的 microsoft.sql.Geography 類別物件。 |
SQLServerResultSet
| 方法 | 描述 |
|---|---|
| Geometry getGeometry（int columnIndex） | 使用 Java 程式設計語言，以 com.microsoft.sqlserver.jdbc.Geometry 物件形式，傳回這個 ResultSet 物件之目前資料列中指定資料行的值。 |
| Geometry getGeometry(String columnName) | 使用 Java 程式設計語言，以 com.microsoft.sqlserver.jdbc.Geometry 物件形式，傳回這個 ResultSet 物件之目前資料列中指定資料行的值。 |
| `地理 getGeography（int 欄位索引）` | 使用 Java 程式設計語言，以 com.microsoft.sqlserver.jdbc.Geography 物件形式，傳回這個 ResultSet 物件之目前資料列中指定資料行的值。 |
| Geography getGeography(String columnName) | 使用 Java 程式設計語言，以 com.microsoft.sqlserver.jdbc.Geography 物件形式，傳回這個 ResultSet 物件之目前資料列中指定資料行的值。 |
幾何形狀
| 方法 | 描述 |
|---|---|
Geometry STGeomFromText(String wkt、int SRID) |
從開放地理空間協會 (OGC) Well-Known Text (WKT) 表示法傳回之 Geometry 執行個體的建構函式，經由此執行個體夾帶的任何 Z (高度) 值和 M (測量) 值來擴充。 |
Geometry STGeomFromWKB(byte[] wkb) |
從開放地理空間協會 (OGC) Well-Known Binary (WKB) 表示法傳回之 Geometry 執行個體的建構函式。 注意:此方法目前會使用內部 SQL Server 格式 (CLR) 來建立 Geometry 執行個體，此為驅動程式中的已知問題，且已規劃於未來變更成改為接受 WKB 資料。 對於已經使用此方法的現有使用者，請考慮改為切換成 deserialize(byte)。 |
| Geometries deserialize(byte[] clr) | 針對空間資料從內部 SQL Server 格式取得 Geometry 執行個體的建構函式。 |
| Geometry parse(String wkt) | 從開放地理空間協會 (OGC) Well-Known Text (WKT) 表示法傳回之 Geometry 執行個體的建構函式。 空間參考識別碼預設為 0。 |
| Geometry point(double x, double y, int SRID) | Geometry 執行個體的建構函式，其會根據 Point 執行個體的 X 和 Y 值與空間參考識別碼來代表該執行個體。 |
| String STAsText() | 傳回 Geometry 執行個體的開放地理空間協會 (OGC) Well-Known Text (WKT) 表示法。 此文字不會包含此執行個體所夾帶的任何 Z (標高) 或 M (測量) 值。 |
| byte[] STAsBinary() | 傳回 Geometry 執行個體的內部 SQL Server 格式 (CLR) 表示法。 這個值不會包含此執行個體所夾帶的任何 Z 或 M 值。 |
| byte[] serialize() | 傳回表示 Geometry 類型之內部 SQL Server 格式的位元組。 |
| boolean hasM() | 傳回物件是否包含 M (量值) 值。 |
| boolean hasZ() | 傳回物件是否包含 Z (海拔) 值。 |
| Double getX() | 傳回 X 座標值。 |
| Double getY() | 傳回 Y 座標值。 |
| Double getM() | 傳回物件的 M (量值) 值。 |
| Double getZ() | 傳回物件的 Z (海拔) 值。 |
| int getSrid() | 傳回空間參考識別碼 (SRID) 值。 |
| boolean isNull() | 傳回 Geometry 物件是否為 Null。 |
| int STNumPoints() | 傳回 Geometry 物件中的點數目。 |
| String STGeometryType() | 傳回幾何執行個體表示的開放式地理空間協會 (Open Geospatial Consortium，OGC) 類型名稱。 |
| String asTextZM() | 傳回 Geometry 物件的 Well-Known Text (WKT) 表示法。 |
| String toString() | 傳回 Geometry 物件的字串表示法。 |
[地理位置]
| 方法 | 描述 |
|---|---|
| Geography STGeomFromText(String wkt, int SRID) | 從開放地理空間協會 (OGC) Well-Known Text (WKT) 表示法傳回之 Geography 執行個體的建構函式，經由此執行個體夾帶的任何 Z (高度) 值和 M (測量) 值來擴充。 |
Geography STGeomFromWKB(byte[] wkb) |
從開放地理空間協會 (OGC) Well-Known Binary (WKB) 表示法傳回之 Geography 執行個體的建構函式。 注意:此方法目前會使用內部 SQL Server 格式 (CLR) 來建立 Geometry 執行個體，但未來將會變更成改為接受 WKB 資料，因為此方法 (STGeomFromWKB) 的 SQL Server 對應項目使用 WKB。 對於已經使用此方法的現有使用者，請考慮改為切換成 deserialize(byte)。 |
| Geography deserialize(byte[] clr) | 針對空間資料從內部 SQL Server 格式取得 Geography 執行個體的建構函式。 |
| Geography parse(String wkt) | 從開放地理空間協會 (OGC) Well-Known Text (WKT) 表示法傳回之 Geography 執行個體的建構函式。 空間參考識別碼預設為 0。 |
| Geography point(double lon, double lat, int SRID) | 代表位置執行個體 (經緯度及空間參考識別碼) 之地理執行個體的建構函式。 |
| String STAsText() | 傳回 Geography 執行個體的開放地理空間協會 (OGC) Well-Known Text (WKT) 表示法。 此文字不會包含此執行個體所夾帶的任何 Z (標高) 或 M (測量) 值。 |
| byte[] STAsBinary()) | 傳回 Geography 執行個體的內部 SQL Server 格式 (CLR) 表示法。 這個值不會包含此執行個體所夾帶的任何 Z 或 M 值。 |
| byte[] serialize() | 傳回表示 Geography 類型之內部 SQL Server 格式的位元組。 |
| boolean hasM() | 傳回物件是否包含 M (量值) 值。 |
| boolean hasZ() | 傳回物件是否包含 Z (海拔) 值。 |
| Double getLatitude() | 傳回緯度值。 |
| Double getLongitude() | 傳回經度值。 |
| Double getM() | 傳回物件的 M (量值) 值。 |
| Double getZ() | 傳回物件的 Z (海拔) 值。 |
| int getSrid() | 傳回空間參考識別碼 (SRID) 值。 |
| boolean isNull() | 傳回 Geography 物件是否為 Null。 |
| int STNumPoints() | 傳回 Geography 物件中的點數目。 |
| String STGeographyType() | 傳回 Geography 執行個體表示的開放式地理空間協會 (Open Geospatial Consortium，OGC) 類型名稱。 |
| String asTextZM() | 傳回 Geography 物件的 Well-Known Text (WKT) 表示法。 |
| String toString() | 傳回 Geography 物件的字串表示法。 |
空間資料類型的限制
從 SQL Server 2012 和更新版本才開始支援空間子資料類型：CircularString、CompoundCurve、CurvePolygon 及 FullGlobe。
Always Encrypted 無法與空間資料類型搭配使用。
空間資料類型目前不支援預存程序、TVP 和 BulkCopy 作業。