h3_ischildof function

  • Article

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

Returns true if the first H3 cell is the same as or a child of the second H3 cell.

Syntax

h3_ischildof ( h3CellId1Expr, h3cellId2Expr )

Arguments

  • h3CellId1Expr: A BIGINT expression, or a hexadecimal STRING expression representing an H3 cell ID.
  • h3CellId2Expr: A BIGINT expression, or a hexadecimal STRING expression representing an H3 cell ID.

Returns

A value of type BOOLEAN indicating whether the first H3 cell the same as or a child of the second H3 cell.

The function returns NULL if any one of the inputs is NULL. The function does partial validation regarding whether any of the two input arguments 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 any of the two input cell IDs is not a valid cell ID.

Error conditions

  • If h3CellId1Expr or h3CellId2Expr 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.

Examples

-- Simple example taking two longs as input.
> SELECT h3_ischildof(608693241318998015, 599686042433355775)
  true

-- Simple example taking two strings as input.
> SELECT h3_ischildof('88283471b9fffff', '85283473fffffff')
  true

-- Simple example taking a long integer and a string as input.
> SELECT h3_ischildof(580260664489017343, '85283473fffffff')
  false

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

-- Second input is an invalid H3 cell ID.
> SELECT h3_ischildof(608693241318998015, 'xyz')
  [H3_INVALID_CELL_ID] 'xyz' is not a valid H3 cell ID