h3_maxchild function

  • Article

Returns the child of maximum value of the input H3 cell at the specified resolution.

Applies to: check marked yes Databricks SQL preview check marked yes Databricks Runtime 11.3 LTS and above

Syntax

h3_maxchild ( h3cellIdExpr, resolutionExpr )

Arguments

  • h3CellIdExpr: A BIGINT expression, or a hexadecimal STRING expression representing an H3 cell ID.
  • resolutionExpr : An INT expression, whose value is expected to be between h3_resolution(h3CellIdExpr) and 15 inclusive, specifying the resolution of the child H3 cell ID.

Returns

A value of the same type as the type of the h3CellIdExpr expression, corresponding to the child of maximum value of the input H3 cell ID at the specified resolution.

The function returns NULL if any of the two input expressions is NULL. 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. If the value of the resolutionExpr is equal to the resolution of the input H3 cell ID, the input H3 cell ID is returned.

Error conditions

  • If h3CellIdExpr is a STRING that cannot be converted to a BIGINT or corresponds to a BIGINT value that is smaller than 0x08001fffffffffff or larger than 0x08ff3b6db6db6db6, the function returns H3_INVALID_CELL_ID.
  • If resolutionExpr is smaller than h3_resolution(h3CellIdExpr) or larger than 15, the function returns H3_INVALID_RESOLUTION_VALUE.

Examples

-- Simple example taking a long as input.
> SELECT h3_maxchild(599686042433355775, 10)
  622204040416821247

-- Simple example taking a valid hexadecimal string as input.
> SELECT h3_maxchild('85283473fffffff', 10)
  8a2834736db7fff

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

-- Second input is an invalid resolution value.
> SELECT h3_maxchild('85283473fffffff', 4)
  [H3_INVALID_RESOLUTION_VALUE] H3 resolution 4 must be between 5 and 15, inclusive