Applies to: Databricks SQL Databricks Runtime 11.2 and above
Returns an array of H3 cells that form a hollow hexagonal ring centered at the origin H3 cell and that are at grid distance
k from the origin H3 cell.
h3CellIdExpr: A BIGINT expression, or a hexadecimal STRING expression representing an H3 cell ID.
kExpr: An INTEGER expression representing the grid distance.
kExprmust be non-negative.
An ARRAY of values of the same type as the type of the
h3CellIdExpr expression, corresponding to the H3 cell IDs that have the same resolution as the input H3 cell and that form a hollow ring centered at the origin H3 cell at distance
k is the value of
The function returns NULL if any one of the 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
The behavior of the function is undefined if the input cell ID is not a valid cell ID.
If the value of the grid distance is zero, the returned array contains a single value equal to the input H3 cell ID.
h3CellIdExpris a STRING that cannot be converted to a BIGINT or corresponds to a BIGINT value that is smaller than
0x08001fffffffffffor larger than
0x08ff3b6db6db6db6, the function returns H3_INVALID_CELL_ID.
kExpris negative, the function returns H3_INVALID_GRID_DISTANCE_VALUE.
If there is a pentagon anywhere in the
k-ring of the origin cell, the function returns H3_PENTAGON_ENCOUNTERED_ERROR.
-- Simple example where the first argument is a BIGINT. > SELECT h3_hexring(599686042433355775, 1) [599686014516068351,599686030622195711,599686044580839423,599686038138388479,599686043507097599,599686015589810175] -- Simple example where the first argument is a STRING. > SELECT h3_hexring('85283473fffffff', 1) [8528340bfffffff,85283447fffffff,8528347bfffffff,85283463fffffff,85283477fffffff,8528340ffffffff] -- First input is an invalid H3 cell ID. > SELECT h3_hexring(0, 0) [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID -- Second input is an invalid grid distance value. > SELECT h3_hexring('85283473fffffff', -1) [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative -- The input cell is a hexagonal cell adjacent to a pentagonal cell (the 2-ring of the hexagonal cell contains the pentagon). > SELECT H3_HexRing('8007fffffffffff', 2) [H3_PENTAGON_ENCOUNTERED_ERROR] A pentagon was encountered while computing the hex ring of '8007fffffffffff' with grid distance 2