H3 地理空间函数

适用于:勾选“是” Databricks SQL 勾选“是” Databricks Runtime

H3 是一个全局网格索引系统。 网格系统使用形状(如矩形或三角形)对某个表面(在本例中为地球的表面)进行分割。 H3 系统设计为使用六边形(和几个五边形),在其层次结构中提供 16 个级别的分辨率。 分辨率越高,分割的形状越小。

H3 表达式仅在 Databricks SQL 专业层/无服务器层已启用 Photon 的群集中和 Databricks SQL 数据仓库中受支持。

请详细阅读 H3 分辨率H3 起源

另请参阅:

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