适用于：
Databricks SQL Databricks Runtime 17.1 及更高版本
Important
此功能目前以公共预览版提供。
注释
此功能在 Databricks SQL 经典仓库上不可用。 若要详细了解 Databricks SQL 仓库，请参阅 SQL 仓库类型。
将新点添加到输入线字符串 GEOGRAPHY 或 GEOMETRY 值中的第 n 个位置。
Syntax
st_addpoint ( geo1Expr, geo2Expr[, indexExpr] )
Arguments
-
geo1Expr：一个GEOGRAPHY或者GEOMETRY值，用以表示线字符串。 -
geo2Expr：表示GEOGRAPHYGEOMETRY点的值。 -
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。 - 如果 SRID 值
geo1Expr不同geo2Expr，函数将返回 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)