Returns the H3 cells that are within (grid) distance
k of the origin cell. The set of these H3 cells is called the
k-ring of the origin cell.
Requires: SQL warehouse version 2022.35 or higher. This version is available in the Preview channel.
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 are within grid distance
k of the input H3 cell, where
k is the value of the
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.
-- Simple example where the first argument is a BIGINT. > SELECT h3_kring(599686042433355775, 1) [599686042433355775,599686030622195711,599686044580839423,599686038138388479,599686043507097599,599686015589810175,599686014516068351] -- Simple example where the first argument is a STRING. > SELECT h3_kring('85283473fffffff', 1) [85283473fffffff,85283447fffffff,8528347bfffffff,85283463fffffff,85283477fffffff,8528340ffffffff,8528340bfffffff] -- First input is an invalid H3 cell ID. > SELECT h3_kring(0, 0) [H3_INVALID_CELL_ID] 0 is not a valid H3 cell ID -- Second input is an invalid grid distance value. > SELECT h3_kring('85283473fffffff', -1) [H3_INVALID_GRID_DISTANCE_VALUE] H3 grid distance -1 must be non-negative