Share via

h3_kringdistances 函数

  • 项目

适用于：check marked yes Databricks SQL check marked yes Databricks Runtime 11.2 及更高版本

返回距原点 H3 单元格 k 个网格距离内的所有 H3 单元格（表示为长整型或字符串），以及它们到原点 H3 单元格的距离。

语法

h3_kringdistances ( h3CellIdExpr, kExpr )

参数

  • h3CellIdExpr：表示 H3 单元格 ID 的 BIGINT 表达式或十六进制 STRING 表达式。
  • kExpr：表示网格距离的 INTEGER 表达式。 kExpr 必须为非负值。

返回

具有两个字段（分别名为 cellid 和 distance）的命名结构的 ARRAY，其中结构中的第一个字段是 H3 单元格 ID（表示为长整型或字符串），结构中的第二个字段是其到原点 H3 单元格的距离（表示为整数）。 输出中 H3 单元 ID 的类型与 h3CellIdExpr 的类型相同。

返回的 ARRAY 中的元素根据它们到原点 H3 单元格的距离进行排序。 返回的 ARRAY 中对应相同距离的元素可按任意顺序返回。 如果任一输入表达式为 NULL，则该函数返回 NULL。 该函数对输入参数是否为有效的 H3 单元格 ID 进行部分验证。 有效 H3 ID 的必要不充分条件是其值介于 0x08001fffffffffff 和 0x08ff3b6db6db6db6 之间。 如果输入单元格 ID 不是有效的单元格 ID，则表示该函数的行为未定义。 如果网格距离的值为零，则返回的数组包含一个等于输入 H3 单元格 ID 的值。

错误条件

  • 如果 h3CellIdExpr 是无法转换为 BIGINT 的 STRING 或对应于小于 0x08001fffffffffff 或大于 0x08ff3b6db6db6db6 的 BIGINT 值，则该函数返回 H3_INVALID_CELL_ID
  • 如果 kExpr 为负数，则该函数返回 H3_INVALID_GRID_DISTANCE_VALUE

示例

-- Simple example where the first argument is a BIGINT.
> SELECT h3_kringdistances(599686042433355775, 1)
  [{"cellid":599686042433355775,"distance":0},{"cellid":599686030622195711,"distance":1},{"cellid":599686044580839423,"distance":1},{"cellid":599686038138388479,"distance":1},{"cellid":599686043507097599,"distance":1},{"cellid":599686015589810175,"distance":1},{"cellid":599686014516068351,"distance":1}]

-- Simple example where the first argument is a STRING.
> SELECT h3_kringdistances('85283473fffffff', 1)
  [{"cellid":"85283473fffffff","distance":0},{"cellid":"85283447fffffff","distance":1},{"cellid":"8528347bfffffff","distance":1},{"cellid":"85283463fffffff","distance":1},{"cellid":"85283477fffffff","distance":1},{"cellid":"8528340ffffffff","distance":1},{"cellid":"8528340bfffffff","distance":1}]

-- First input is an invalid H3 cell ID.
> SELECT h3_kringdistances(0, 0)
  [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID

-- Second input is an invalid grid distance value.
> SELECT h3_kringdistances('85283473fffffff', -1)
  [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative