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 的输入集解压缩为指定的分辨率。 |