h3_stringtoh3 function (Databricks SQL)

Converts the input string, which is expected to be a hexadecimal string representing an H3 cell, to the corresponding BIGINT representation of the H3 cell.

Requires: SQL warehouse version 2022.35 or higher. This version is available in the Preview channel.

Syntax

h3_stringtoh3 ( h3CellIdExpr )

Arguments

  • h3CellIdStringExpr: A well-formed hexadecimal STRING expression representing a valid H3 cell ID.

Returns

A value of type BIGINT. The returned value is the BIGINT representation of the input hexadecimal string.

The function returns NULL if the input is NULL. The function converts the hexadecimal string to the corresponding BIGINT number. The function does partial validation regarding whether the input argument is a valid H3 cell ID. A necessary, but not sufficient condition for a valid H3 ID is that its value is between 0x08001fffffffffff and 0x08ff3b6db6db6db6. The behavior of the function is undefined if the input cell ID is not a valid cell ID.

Error conditions

  • If the value of h3CellIdStringExpr cannot be converted to a BIGINT or if the value corresponds to a BIGINT value that is smaller than 0x08001fffffffffff or larger than 0x08ff3b6db6db6db6, the function returns H3_INVALID_CELL_ID.

Examples

-- Simple example
> SELECT h3_stringtoh3('85283473fffffff')
  599686042433355775

-- Input is an invalid H3 cell ID.
> SELECT h3_stringtoh3('0')
  [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID