H3 地理空间函数
适用于：
Databricks SQL Databricks Runtime
H3 是一个全局网格索引系统。 网格系统使用形状（如矩形或三角形）对某个表面（在本例中为地球的表面）进行分割。 H3 系统设计为使用六边形（和几个五边形），在其层次结构中提供 16 个级别的分辨率。 分辨率越高，分割的形状越小。
H3 表达式仅在 Databricks SQL 专业层已启用 Photon 的群集中和 Databricks SQL 数据仓库中受支持。
另请参阅：
H3 用于地理空间分析
H3 支持用于处理和分析空间数据的常见模式。 首先，通过标准格式（纬度和经度、已知文本 (WKT)、已知二进制 (WKB) 或 GeoJSON 到 H3 单元格 ID）为地理空间数据编制索引。 使用单个数据集，你可以按单元格 ID 聚合来回答位置驱动型问题。 使用多个索引数据集，你可以使用单元格 ID 将它们组合在一起，从而揭示不同数据集彼此之间的关系。 数据集的这种联接在语义上是空间联接，但不需要空间谓词。
在 Databricks 中使用 H3 有什么好处？
利用 Delta Lake 功能对 H3 索引数据进行高效存储和布局。 使用 Delta Lake 的 OPTIMIZE 操作（可以在 H3 单元格 ID 的基础上进行 Z 排序），你可以对数据进行空间归置。 此外，Delta Lake 的数据跳过算法使用归置性以智能方式减少需要读取的数据量。
你可以灵活地处理数据。 可以选择使用已存储为大整数或字符串的 H3 单元格 ID。 为了在使用 H3 单元格 ID 时获得最佳性能，请使用大整数表示形式。 有关 H3 表达式的详细用法，请参阅 SQL 参考指南。
注意
无需安装 H3 库。 从 Databricks Runtime 11.2 开始，它作为一个可见依赖项包含在 Databricks Runtime 中（使用 3.7.0 版 H3 Java 库）。
导入 Databricks 函数以获取 H3 (Databricks Runtime)
Databricks SQL 和 Spark SQL 无需导入。
若要在笔记本中导入适用于 Python 或 Scala 的 H3 函数，请使用以下命令：
Python
from pyspark.databricks.sql import functions as dbf
Scala
import com.databricks.sql.functions._
H3 地理空间函数列表 (Databricks SQL)
导入
| 函数 | 说明 |
|---|---|
| h3_coverash3(geographyExpr, resolutionExpr) | 返回 H3 单元格 ID（表示为 BIGINT）的 ARRAY，这些 ID 对应于具有指定分辨率的最小六边形或五边形集，完全覆盖输入线性或区域地理位置。 |
| h3_coverash3string(geographyExpr, resolutionExpr) | 返回 H3 单元格 ID（表示为 STRING）的 ARRAY，这些 ID 对应于具有指定分辨率的最小六边形或五边形集，完全覆盖输入线性或区域地理位置。 |
| h3_longlatash3(longitudeExpr, latitudeExpr, resolutionExpr) | 返回对应于指定分辨率下提供的经纬度的 H3 单元格 ID（表示为 BIGINT）。 |
| h3_longlatash3string(longitudeExpr, latitudeExpr, resolutionExpr) | 返回对应于指定分辨率下提供的经纬度的 H3 单元格 ID（表示为十六进制 STRING）。 |
| h3_pointash3(geographyExpr, resolutionExpr) | 返回对应于指定分辨率下提供的点的 H3 单元格 ID（表示为 BIGINT）。 |
| h3_pointash3string(geographyExpr, resolutionExpr) | 返回对应于指定分辨率下提供的点的 H3 单元格 ID（表示为 STRING）。 |
| h3_polyfillash3(geographyExpr, resolutionExpr) | 返回 H3 单元格 ID（表示为 BIGINT）的 ARRAY，这些 ID 对应于具有指定分辨率的六边形或五边形，它们均包含在输入区域地理位置中。 |
| h3_polyfillash3string(geographyExpr, resolutionExpr) | 返回 H3 单元格 ID（表示为 STRING）的 ARRAY，这些 ID 对应于具有指定分辨率的六边形或五边形，它们均包含在输入区域地理位置中。 |
| h3_tessellateaswkb(geographyExpr, resolutionExpr) | 使用指定分辨率的 H3 单元格返回输入地理的分割。 |
| h3_try_polyfillash3(geographyExpr, resolutionExpr) | 返回 H3 单元格 ID（表示为 BIGINT）的 ARRAY，这些 ID 对应于具有指定分辨率的六边形或五边形，它们均包含在输入区域地理位置中。 |
| h3_try_polyfillash3string(geographyExpr, resolutionExpr) | 返回 H3 单元格 ID（表示为 STRING）的 ARRAY，这些 ID 对应于具有指定分辨率的六边形或五边形，它们均包含在输入区域地理位置中。 |
导出
| 函数 | 说明 |
|---|---|
| h3_boundaryasgeojson(h3CellIdExpr) | 以 GeoJSON 格式返回输入 H3 单元格的多边形边界。 |
| h3_boundaryaswkb(h3CellIdExpr) | 以 WKB 格式返回输入 H3 单元格的多边形边界。 |
| h3_boundaryaswkt(h3CellIdExpr) | 以 WKT 格式返回输入 H3 单元格的多边形边界。 |
| h3_centerasgeojson(h3CellIdExpr) | 返回输入 H3 单元格的中心（表示为 GeoJSON 格式的点）。 |
| h3_centeraswkb(h3CellIdExpr) | 返回输入 H3 单元格的中心（表示为 WKB 格式的点）。 |
| h3_centeraswkt(h3CellIdExpr) | 返回输入 H3 单元格的中心（表示为 WKT 格式的点）。 |
转换
| 函数 | 说明 |
|---|---|
| h3_h3tostring(h3CellIdExpr) | 将输入 H3 单元格 ID 转换为其等效的十六进制字符串表示形式。 |
| h3_stringtoh3(h3CellIdStringExpr) | 将输入字符串（预期为表示 H3 单元格 ID 的十六进制字符串）转换为 H3 单元格 ID 的对应 BIGINT 表示形式。 |
谓词
| 函数 | 说明 |
|---|---|
| h3_ischildof(h3CellId1Expr, h3CellId2Expr) | 如果第一个 H3 单元格 ID 与第二个 H3 单元格 ID 相同或者是第二个 H3 单元格 ID 的子级，则返回 true。 |
| h3_ispentagon(h3CellIdExpr) | 如果输入 BIGINT 或十六进制 STRING 对应于五边形 H3 单元格，则返回 true。 |
有效期
| 函数 | 说明 |
|---|---|
| h3_isvalid(expr) | 如果输入 BIGINT 或 STRING 是有效的 H3 单元 ID，则返回 true。 |
| h3_try_validate(h3CellIdExpr) | 如果输入值对应于有效的 H3 单元格 ID，则返回 BIGINT 或 STRING 类型的输入值，否则返回 NULL。 |
| h3_validate(h3CellIdExpr) | 如果输入值对应于有效的 H3 单元格 ID，则返回 BIGINT 或 STRING 类型的输入值，否则发出错误。 |
距离相关
| 函数 | 说明 |
|---|---|
| h3_distance(h3CellId1Expr, h3CellId2Expr) | 返回两个输入 H3 单元格 ID 的网格距离。 |
| h3_hexring(h3CellIdExpr, kExpr) | 返回一个 H3 单元格 ID 数组，这些 ID 形成一个以原点 H3 单元格为中心的空心六边形环，与原点 H3 单元格的网格距离为 k。 |
| h3_kring(h3CellIdExpr, kExpr) | 返回距原点单元格 ID k 个（网格）距离的 H3 单元格 ID。 |
| h3_kringdistances(h3CellIdExpr, kExpr) | 返回距原点 H3 单元格 ID k 个网格距离的所有 H3 单元格 ID（表示为长整型或字符串），以及它们到原点 H3 单元格 ID 的距离。 |
| h3_try_distance(h3CellId1Expr, h3CellId2Expr) | 返回相同分辨率的两个输入 H3 单元格 ID 的网格距离，如果距离未定义，则返回 NULL。 |
遍历
| 函数 | 说明 |
|---|---|
| h3_maxchild(h3CellIdExpr, resolutionExpr) | 以指定的分辨率返回输入 H3 单元格的最大值的子项。 |
| h3_minchild(h3CellIdExpr, resolutionExpr) | 以指定的分辨率返回输入 H3 单元格的最小值的子项。 |
| h3_resolution(h3CellIdExpr) | 返回输入 H3 单元格 ID 的分辨率。 |
| h3_tochildren(h3CellIdExpr, resolutionExpr) | 返回指定分辨率下输入 H3 单元格 ID 的子 H3 单元格 ID 的数组。 |
| h3_toparent(h3CellIdExpr, resolutionExpr) | 返回指定分辨率下输入 H3 单元格 ID 的父 H3 单元格 ID。 |
压缩
| 函数 | 说明 |
|---|---|
| h3_compact(h3CellIdsExpr) | 尽可能以最佳方式压缩 H3 单元格 ID 的输入集。 |
| h3_uncompact(h3CellIdsExpr, resolutionExpr) | 将 H3 单元格 ID 的输入集解压缩为指定的分辨率。 |