適用於：
Databricks SQL Databricks Runtime 17.1 和更新版本
Important
這項功能目前處於 公開預覽版。
備註
這項功能不適用於 Databricks SQL Classic 倉儲。 若要深入瞭解 Databricks SQL 倉儲，請參閱 SQL 倉儲類型。
將新點加入至輸入線串 GEOGRAPHY 或 GEOMETRY 值的第 n 個位置。
Syntax
st_addpoint ( geo1Expr, geo2Expr[, indexExpr] )
Arguments
-
geo1Expr：GEOGRAPHY或GEOMETRY值，代表一個行字串。 -
geo2Expr：GEOGRAPHY或GEOMETRY值，表示一個點。 -
indexExpr：選擇性INTEGER值，表示應該加入新點的行字串中以 1 為基礎的位置。 預設值為 -1。
Returns
如果GEOGRAPHY和geo1Expr都是geo2Expr型別，則為GEOGRAPHY型別的值；如果GEOMETRY和geo1Expr都是geo2Expr型別，則為GEOMETRY型別的值。
如果 indexExpr 為正數，則 GEOGRAPHY 或 GEOMETRY 回傳的值是一個新的線串，其第 indexExpr 點（從左計算）設為 geo2Expr。
如果 indexExpr 為負數，則會從右邊測量新增點所在行字符串的第 1 個位置。
- 如果任何輸入為
NULL，則函式會傳NULL回 。 - 輸出行字串的SRID值等於輸入
GEOGRAPHY或GEOMETRY值的通用SRID值。 - 輸出
GEOGRAPHY或GEOMETRY的行字串的維度與geo1Expr的維度相同。 如果geo2Expr座標的維度在geo1Expr中不存在，則將對應座標設定為 0。
錯誤條件
- 如果
geo1Expr的類型為GEOGRAPHY，且geo2Expr的類型為GEOMETRY，或反之亦然，則函式會傳回DATATYPE_MISMATCH。 - 如果 和
geo1Exprgeo2Expr的 SRID 值不同，函式會傳回 ST_DIFFERENT_SRID_VALUES。 - 當發生以下任一情況時，該函式會傳回 ST_INVALID_ARGUMENT.INVALID_TYPE。
- 的
geo1Expr值不是線串。 -
geo2Expr的值不是一個點。
- 的
- 函式會傳回 ST_INVALID_ARGUMENT。EMPTY_LINESTRING 的
geo1Expr值是否為空的行字串。 - 函式會傳回 ST_INVALID_ARGUMENT。EMPTY_POINT 的
geo2Expr值是否為空點。 - 如果 值
indexExpr的絕對值為 0 或大於線串中的點數加上 1，則函數會傳回 ST_INVALID_ARGUMENT。INVALID_INDEX_VALUE。
Examples
-- We do not specify a position; the point is appended at the end (right) of the linestring.
> SELECT st_asewkt(st_addpoint(st_geomfromtext('LINESTRING(1 2,3 4)', 4326), st_geomfromtext('POINT(7 8)', 4326)));
SRID=4326;LINESTRING(1 2,3 4,7 8)
-- A positive index indicates the position. We add the point at that position in the linestring.
> SELECT st_astext(st_addpoint(st_geomfromtext('LINESTRING(1 2,3 4)'), st_geomfromtext('POINT(7 8)'), 3));
LINESTRING(1 2,3 4,7 8)
-- The position is specified as a negative index. The point is added at that position counting from the right.
-- The point is missing a Z coordinate. This is set to 0 when the point is added in the linestring.
> SELECT st_asewkt(st_addpoint(st_geogfromtext('LINESTRING ZM (1 2 3 4,5 6 7 8)'), st_geogfromtext('POINT M (0 9 99)'), -1));
SRID=4326;LINESTRING ZM (1 2 3 4,5 6 7 8,0 9 0 99)