H3 functions - - Alibaba Cloud Documentation Center

The Lindorm GanosBase spatiotemporal service provides H3 functions for efficient spatial analysis and queries on H3 grids. These functions help you process H3 indexes to convert index types, query relationships between cells, query cell resolutions, and calculate distances between cells. This topic describes all H3 functions supported by the Lindorm GanosBase spatiotemporal service.

Engine and version

H3 functions are available only for the wide table engine.
The wide table engine must be version 2.6.5 or later. For more information about how to view or upgrade the engine version, see Wide table engine versions and Minor version update.
Important
If your wide table engine is earlier than version 2.6.5 and you cannot upgrade it, contact Lindorm technical support on DingTalk (ID: s0s3eg3) to request an upgrade.

Function list

The following table lists the H3 functions that are supported by Lindorm GanosBase.

Function category	Function	Description
Import and conversion	H3	Converts a longitude and latitude pair or a point coordinate into an H3 grid encoding at a specified level.
	H3_H3ToString	Converts an H3 grid encoding of the LONG type to the corresponding STRING type.
	H3_StringToH3	Converts an H3 grid encoding of the STRING type to the corresponding LONG type.
	H3_PolygonToCells	Outputs an array of H3 grid encodings for a polygon object at a specified level.
Export	H3_CellToBoundary	Outputs the polygon border of a specified H3 grid.
Grid validation	H3_IsValidCell	Checks whether an input H3 grid encoding is valid.
	H3_GetResolution	Returns the level of an input H3 grid encoding.
	H3_AreNeighborCells	Checks whether two H3 grids are spatially adjacent. Returns `true` if they are adjacent. Otherwise, returns `false`.
	H3_Contains	Checks whether the grids in an H3Cells array (an array of H3 grid encodings) contain a specified H3 grid.
Grid operations	H3_CellToParent	Takes an H3 grid encoding and a specified level as input, and returns the encoding of the parent grid at the specified level.
Grid operations	H3_CellToChildren	Returns the encodings of the child grids of an H3 grid at a specified level.
H3 grid query	H3_GridPathCells	Gets the path between two H3 grids.
H3 grid query	H3_GridDisk	Takes a grid distance k as input and returns an array of all H3 grid encodings that are within or at the distance k from a center grid.
Distance calculation	H3_Distance	Returns the Euclidean distance between the centroids of two specified H3 grids on a 2D plane.
Distance calculation	H3_DistanceSphere	Returns the spherical distance between the centroids of two specified H3 grids in the WGS84 coordinate system.

Import and conversion

H3

Converts a longitude and latitude pair or a point coordinate into an H3 grid encoding at a specified level.

Syntax

Long H3(Point p)
Long H3(Double lng, Double lat)
Long H3(Point p, Int resolution)
Long H3(Double lng, Double lat, Int resolution)

Parameters

Parameter	Description
p	The point coordinate. The type is POINT.
lng	The longitude. The type is DOUBLE.
lat	The latitude. The type is DOUBLE.
resolution	The grid level. The type is INT. The value ranges from 0 to 15. The default value is 15.

Examples

SELECT H3(128.2, 20.5) AS H3Cell;
SELECT H3(128.2, 20.5, 15) AS H3Cell;
SELECT H3(ST_MakePoInt(128.2, 20.5)) AS H3Cell;
SELECT H3(ST_MakePoInt(128.2, 20.5),15) AS H3Cell;

The preceding statements return the same result:

+--------------------+
|       H3Cell       |
+--------------------+
| 645317832955184368 |
+--------------------+

H3_H3ToString

Converts an H3 grid encoding from the LONG type to the STRING type. If the input is NULL or an invalid H3 grid encoding, this function returns an empty string.

Syntax

String H3_H3ToString(Long H3Cell)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is LONG.

Examples

Example 1: Convert an H3 grid encoding from the LONG type to the STRING type.

SELECT H3_H3ToString(599686042433355775) AS H3Address;

Returned result:

+-----------------+
|    H3Address    |
+-----------------+
| 85283473fffffff |
+-----------------+

Example 2: Check whether the input is valid. If the input is empty or an invalid grid encoding, an empty string is returned.

-- Input an invalid grid code
SELECT H3_H3ToString(0) AS H3Address;

-- Input is empty
SELECT H3_H3ToString(NULL) AS H3Address;

Returned result:

+-----------+
| H3Address |
+-----------+
|           |
+-----------+

H3_StringToH3

Converts an H3 grid encoding from the STRING type to the LONG type. If the input is an empty string or an invalid H3 grid string, this function returns -1.

Syntax

Long H3_StringToH3(string H3Cell)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is STRING.

Examples

Example 1: Input an H3 grid encoding of the STRING type and convert it to the LONG type.

SELECT H3_StringToH3('85283473fffffff') AS H3Cell;

Returned result:

+--------------------+
|       H3Cell       |
+--------------------+
| 599686042433355775 |
+--------------------+

Example 2: Check whether the input is valid. If the input is an empty or invalid H3 grid string, -1 is returned.

-- Input an invalid H3 grid string
SELECT H3_StringToH3('abc') AS H3Cell;

-- Input an empty string
SELECT H3_StringToH3('') AS H3Cell;

Returned result:

+--------+
| H3Cell |
+--------+
| -1     |
+--------+

H3_PolygonToCells

Outputs the H3 index array of a polygon at a specified resolution.

Syntax

Set<Long> H3_PolygonToCells(Polygon poly, Int resolution)

Parameters

Parameter	Description
poly	The polygon object. The type is POLYGON.
resolution	The grid level. The value must be in the range of [0, 15].

Examples

Input a valid polygon and specify the H3 index resolution as 9. The function returns the H3 index array that represents the polygon.

SELECT H3_PolygonToCells(ST_GeomFromText('POLYGON((-122.481889 37.826683,-122.479487 37.808548,-122.474150 37.808904,-122.476510 37.826935,-122.481889 37.826683))'), 9) AS polyCells;

Result:

+--------------------------------+
|           polyCells            |
+--------------------------------+
| [617700171225497599,           |
| 617700171167825919,            |
| 617700171168874495,            |
| 617700171167563775,            |
| 617700171168612351,            |
| 617700171168350207,            |
| 617700171177525247,            |
| 617700171188011007,            |
| 617700171176476671]            |
+--------------------------------+

Export

H3_CellToBoundary

Outputs the polygon border of a specified H3 grid. If the input is empty, NULL, or an invalid H3 grid encoding, this function returns an empty array.

Syntax

Set<Point> H3_CellToBoundary(Long H3Cell)
Set<Point> H3_CellToBoundary(string H3Cell)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is LONG or STRING.

Examples

Example 1: Input an H3 grid encoding of the STRING type to output the polygon border of the corresponding H3 grid.

SELECT H3_CellToBoundary('85283473fffffff') AS boundary;

Returned result:

+--------------------------------+
|            boundary            |
+--------------------------------+
| [Point (-121.92354999630157    |
| 37.42834118609436), Point      |
| (-122.02910130919003           |
| 37.26319797461824), Point      |
| (-121.91508032705622           |
| 37.27135586673191),            |
| Point (-122.090428929044       |
| 37.33755608435299), Point      |
| (-121.86222328902491           |
| 37.353926450852256),           |
| Point (-122.03773496427027     |
| 37.42012867767779)]            |
+--------------------------------+

Example 2: Input an H3 grid encoding of the LONG type to output the polygon border of the corresponding H3 grid.

SELECT H3_CellToBoundary(599686042433355775) AS boundary;

Returned result:

+--------------------------------+
|            boundary            |
+--------------------------------+
| [Point (-121.92354999630157    |
| 37.42834118609436), Point      |
| (-122.02910130919003           |
| 37.26319797461824), Point      |
| (-121.91508032705622           |
| 37.27135586673191),            |
| Point (-122.090428929044       |
| 37.33755608435299), Point      |
| (-121.86222328902491           |
| 37.353926450852256),           |
| Point (-122.03773496427027     |
| 37.42012867767779)]            |
+--------------------------------+

Example 3: Input an empty value, NULL, or an invalid H3 grid encoding. The function returns an empty array.

-- Input is empty
SELECT H3_CellToBoundary('') AS boundary;

-- Input NULL
SELECT H3_CellToBoundary(NULL) AS boundary;

-- Input an invalid H3 grid code
SELECT H3_CellToBoundary(0) AS boundary;

Returned result:

+----------+
| boundary |
+----------+
| []       |
+----------+

Grid validation

H3_IsValidCell

Checks whether an input H3 grid encoding is valid. This function returns true if the encoding is valid. Otherwise, it returns false. If the input is empty or NULL, this function returns false.

Syntax

boolean H3_IsValidCell(Long H3Cell)
boolean H3_IsValidCell(string H3Cell)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is LONG or STRING.

Examples

Example 1: Check whether the input H3 grid encoding is valid. The following examples show valid inputs.

-- Input an H3 grid code of LONG type
SELECT H3_IsValidCell(599686042433355775) AS isValid;

-- Input an H3 grid code of STRING type
SELECT H3_IsValidCell('85283473fffffff') AS isValid;

Returned result:

+---------+
| isValid |
+---------+
| true    |
+---------+

Example 2: Check whether the input H3 grid encoding is valid. The following examples show invalid inputs.

-- Input an H3 grid code of LONG type
SELECT H3_IsValidCell(12) AS isValid;

-- Input an H3 grid code of STRING type
SELECT H3_IsValidCell('abc') AS isValid;

Returned result:

+---------+
| isValid |
+---------+
| false   |
+---------+

Example 3: The input is empty or NULL. The function returns false.

-- Input is empty
SELECT H3_IsValidCell('') AS isValid;

-- Input NULL
SELECT H3_IsValidCell(NULL) AS isValid;

Returned result:

+---------+
| isValid |
+---------+
| false   |
+---------+

H3_GetResolution

Returns the level of an input H3 grid encoding.

Syntax

Int H3_GetResolution(Long H3Cell)
Int H3_GetResolution(string H3Cell)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is LONG or STRING.

Examples

Example 1: Input an H3 grid encoding in the LONG format to return its grid level.

SELECT H3_GetResolution(599686042433355775) AS resolution;

Returned result:

+------------+
| resolution |
+------------+
| 5          |
+------------+

Example 2: Input an H3 grid encoding in the STRING format to return its grid level.

SELECT H3_GetResolution('85283473fffffff') AS resolution;

Returned result:

+------------+
| resolution |
+------------+
| 5          |
+------------+

H3_AreNeighborCells

Checks whether two H3 grids are spatially adjacent. This function returns true if they are adjacent. Otherwise, it returns false. If either encoding is invalid, NULL, or the two encodings have different levels, the function returns false.

Note

Before you use the H3_AreNeighborCells function, use the H3_GetResolution function to query the level of the H3 grids. For more information about how to use the H3_GetResolution function, see H3_GetResolution.

Syntax

boolean H3_AreNeighborCells(Long H3Cell1, Long H3Cell2)
boolean H3_AreNeighborCells(string H3Cell1, string H3Cell2)

Parameters

Parameter	Description
H3Cell1, H3Cell2	The H3 grid encodings. The type is LONG or STRING.

Examples

Example 1: Input two H3 grid encodings in the LONG format to check whether the corresponding H3 grids are spatially adjacent.

SELECT H3_AreNeighborCells(605546022931791871, 605546023066009599) as isNeighbor;

Returned result:

+------------+
| isNeighbor |
+------------+
| true       |
+------------+

Example 2: Input two H3 grid encodings in the STRING format to check whether the corresponding H3 grids are spatially adjacent.

SELECT H3_AreNeighborCells('86754e66fffffff','86754e64fffffff') as isNeighbor;

Returned result:

+------------+
| isNeighbor |
+------------+
| true       |
+------------+

Example 3: An H3 grid encoding is invalid, the input is NULL, or the two H3 grids have different levels. The function returns false.

-- Input H3 grid code is invalid
SELECT H3_AreNeighborCells(1234,5678) as isNeighbor;

-- Either H3 grid code is NULL
SELECT H3_AreNeighborCells(1234,NULL) as isNeighbor;

-- The two H3 grid resolutions differ: '85283473fffffff' has resolution 5, '87283082bffffff' has resolution 7
SELECT H3_AreNeighborCells('85283473fffffff','87283082bffffff') as isNeighbor;

Returned result:

+------------+
| isNeighbor |
+------------+
| false      |
+------------+

H3_Contains

Checks whether the grids in an H3Cells array (an array of H3 grid encodings) contain a specified H3 grid.

Assume that a grid corresponding to an encoding in H3Cells is A, and the specified H3 grid is B. The function returns true if one of the following conditions is met:

A is the same as B.
B is a child grid of A.

If the H3 grid encoding is invalid or NULL, the function returns false. If the H3Cells array contains invalid grid encodings, the invalid encodings are ignored during calculation and no error is reported.

Syntax

boolean H3_Contains(Set<Long> H3Cells, Long H3)

Parameters

Parameter	Description
H3Cells	An array of H3 grid encodings.
H3	The specified H3 grid encoding.

Examples

Example 1: Check whether the grids in a valid H3Cells array contain a specified H3 grid.

SELECT H3_Contains(H3_PolygonToCells(ST_GeomFromText('POLYGON((-122.481889 37.826683,-122.479487 37.808548,-122.474150 37.808904,-122.476510 37.826935,-122.481889 37.826683))'), 9),H3(-122.47801264775836, 37.81777525405899)) AS isContained;

Returned result:

+-------------+
| isContained |
+-------------+
| true        |
+-------------+

A result of true indicates inclusion.

Example 2: Check whether the grids in a valid H3Cells array contain a specified H3 grid.

SELECT H3_Contains(H3_PolygonToCells(ST_GeomFromText('POLYGON((-122.481889 37.826683,-122.479487 37.808548,-122.474150 37.808904,-122.476510 37.826935,-122.481889 37.826683))'), 9), 605546022931791871) AS isContained;

Returned result:

+-------------+
| isContained |
+-------------+
| false       |
+-------------+

A result of false indicates that a containment relationship does not exist.

Example 3: The input H3 grid encoding is invalid or NULL. The function returns false.

-- Input H3 grid code is NULL
SELECT H3_Contains(H3_PolygonToCells(ST_GeomFromText('POLYGON((-122.481889 37.826683,-122.479487 37.808548,-122.474150 37.808904,-122.476510 37.826935,-122.481889 37.826683))'), 9), NULL) AS isContained;

-- Input H3 grid code is invalid
SELECT H3_Contains(H3_PolygonToCells(ST_GeomFromText('POLYGON((-122.481889 37.826683,-122.479487 37.808548,-122.474150 37.808904,-122.476510 37.826935,-122.481889 37.826683))'), 9), 1233453435457) AS isContained;

Returned result:

+-------------+
| isContained |
+-------------+
| false       |
+-------------+

Grid operations

H3_CellToParent

Takes an H3 grid encoding and a specified level as input, and returns the encoding of the parent grid at that level.

If the input grid encoding is invalid, or the input level is a child of the current encoding's level, the function returns -1 or an empty string. If the specified level is the same as the current grid's level, the grid itself is returned.

Note

In H3 grids, a larger level number indicates a lower level. For example, level 5 is a child of level 0. You can use the H3_GetResolution function to query the level of a grid. For more information, see H3_GetResolution.

Syntax

Long H3_CellToParent(Long H3Cell, Int resolution)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is LONG.
resolution	The specified grid level. The value must be in the range of (0, level of the specified grid encoding]. For example, if the level of H3Cell is 5, the value of resolution must be in the range of (0, 5].

Examples

Example 1: Input an H3 grid encoding of the LONG type to return the encoding of the parent grid at level 0.

SELECT H3_CellToParent(599686042433355775, 0) AS parent;

Returned result:

+--------------------+
|       parent       |
+--------------------+
| 577199624117288959 |
+--------------------+

Example 2: Returns the grid codes of all parent grids at level 5 for a specified H3 grid code of the STRING type.

SELECT H3_CellToParent(599686042433355775, 5) AS parent;

Returned result:

+--------------------+
|       parent       |
+--------------------+
| 599686042433355775 |
+--------------------+

Example 3: The grid encoding is invalid or NULL, or the input level is a child of the current encoding's level or NULL. The function returns -1.

-- Input grid code is invalid
SELECT H3_CellToParent(123, 5) AS parent;

-- Input resolution is a child of the current code
SELECT H3_CellToParent(599686042433355775, 9) AS parent;

-- Input resolution is NULL
SELECT H3_CellToParent(599686042433355775, NULL) AS parent;

-- Both the grid code and resolution are NULL
SELECT H3_CellToParent(NULL, NULL) AS parent;

Returned result:

+--------+
| parent |
+--------+
| -1     |
+--------+

H3_CellToChildren

Returns an array of all child grid encodings for an H3 grid at a specified level.

If the input grid encoding is invalid, or the input level is a parent of or the same as the current encoding's level, this function returns an empty array.

Note

Syntax

Set<Long> H3_CellToChildren(Long H3Cell, Int resolution)
Set<String> H3_CellToChildren(string H3Cell, Int resolution)

Parameters

Parameter	Description
H3Cell	The H3 grid encoding. The type is LONG or STRING.
resolution	The specified grid level. The value must be in the range of (level of the specified grid encoding, 15]. For example, if the level of H3Cell is 5, the value of resolution must be in the range of (5, 15].

Examples

Example 1: Input an H3 grid encoding of the LONG type and specify grid level 6. The function returns the encodings of all child grids at that level.

SELECT H3_CellToChildren(599686042433355775, 6) AS children;

Returned result:

+--------------------------------+
|            children            |
+--------------------------------+
| [604189641121202175,           |
| 604189641255419903,            |
| 604189641389637631,            |
| 604189641523855359,            |
| 604189641658073087,            |
| 604189641792290815,            |
| 604189641926508543]            |
+--------------------------------+

Example 2: Given an H3 grid encoding of the STRING type and a specified grid level of 6, the function returns the encodings of all child grids at that level.

SELECT H3_CellToChildren('85283473fffffff', 6) AS children;

Result:

+--------------------------------+
|            children            |
+--------------------------------+
| [86283470fffffff,              |
| 862834727ffffff,               |
| 862834737ffffff,               |
| 862834707ffffff,               |
| 862834717ffffff,               |
| 86283471fffffff,               |
| 86283472fffffff]               |
+--------------------------------+

Example 3: The grid encoding is invalid, or the specified level is a parent of or the same as the current encoding's level. The function returns an empty array.

-- Input grid code is invalid
SELECT H3_CellToChildren(0,15) AS children;

-- The given resolution is a parent of the current code
SELECT H3_CellToChildren('85283473fffffff', 3) AS children;

-- The given resolution equals the current code resolution
SELECT H3_CellToChildren('85283473fffffff', 5) AS children;

Returned result:

+----------+
| children |
+----------+
| []       |
+----------+

Grid query

H3_GridPathCells

Retrieves the H3 grid path between two specified H3 grids. The path includes the start and end H3 grids. If an input H3 grid encoding is invalid, this function returns an empty array. If the two input encodings have different resolutions, this function returns null.

Syntax

Set<Long> H3_GridPathCells(Long startCell, Long endCell)
Set<String> H3_GridPathCells(String startCell, String endCell)

Parameters

Parameter	Description
startCell	The start H3 grid encoding. The type is LONG or STRING. Note The type of startCell must be the same as the type of endCell.
endCell	The end H3 grid encoding. The type is LONG or STRING. Note The type of endCell must be the same as the type of startCell.

Examples

Example 1: Input two H3 grid encodings to return the path between the two grids.

SELECT H3_GridPathCells(H3(123.1, 25.1, 8),H3(123.2, 25.2, 8)) AS pathCell;

Returned result:

+--------------------------------+
|            pathCell            |
+--------------------------------+
| [613820806174081023,           |
| 613820806136332287,            |
| 613820806132137983,            |
| 613820806325075967,            |
| 613820789795323903,            |
| 613820789791129599,            |
| 613820789942124543,            |
| 613820806163595263,            |
| 613820806327173119,            |
| 613820806314590207,            |
| 613820789986164735,            |
| 613820789981970431,            |
| 613820789944221695,            |
| 613820789940027391,            |
| 613820789969387519,            |
| 613820789965193215,            |
| 613820789709340671,            |
| 613820789705146367]            |
+--------------------------------+

Example 2: An input H3 grid encoding is invalid. The function returns an empty array.

SELECT H3_GridPathCells(587769229395099647, 123) as pathCell;

Returned result:

+----------+
| pathCell |
+----------+
| []       |
+----------+

Example 3: The two input grid encodings have different levels. The function returns null.

-- The two grid resolutions differ: 587769229395099647 has resolution 2, 599686042433355775 has resolution 5
SELECT H3_GridPathCells(587769229395099647, 599686042433355775) as pathCell;

Returned result:

+----------+
| pathCell |
+----------+
| []       |
+----------+

H3_GridDisk

Takes a specified H3 grid encoding and a grid distance k as input, and returns an array of all H3 grid encodings at the same level that are within or at the distance k from the specified grid. For example, if the input grid is A and you set k=1, the function returns grid A and the ring of grids that surround it. If you set k=2, the function returns grid A and the two rings of grids that surround it.

If the input H3 grid encoding is NULL or invalid, this function returns an empty array. If the input grid distance k is 0, the grid itself is returned.

Syntax

Set<Long> H3_GridDisk(Long H3Cell, Int k)
Set<String> H3_GridDisk(String H3Cell, Int k)

Parameters

Parameter name	Description
H3Cell	The H3 grid encoding. The type is LONG or STRING.
k	The grid distance.

Examples

Example 1: Return all grid encodings that are within or at a distance of 1 from the center grid.

SELECT H3_GridDisk(599686042433355775, 1) AS grid;

Returned result:

+--------------------------------+
|              grid              |
+--------------------------------+
| [599686015589810175,           |
| 599686014516068351,            |
| 599686038138388479,            |
| 599686042433355775,            |
| 599686044580839423,            |
| 599686043507097599,            |
| 599686030622195711]            |
+--------------------------------+

Example 2: Specify a distance of 0 to return the grid itself.

SELECT H3_GridDisk(599686042433355775, 0) AS grid;

Returned result:

+----------------------+
|         grid         |
+----------------------+
| [599686042433355775] |
+----------------------+

Example 3: The input H3 grid is NULL or invalid. The function returns an empty array.

-- Input H3 grid code is NULL
SELECT H3_GridDisk(NULL, 0) AS grid;

-- Input H3 grid code is invalid
SELECT H3_GridDisk(123456, 0) AS grid;

Returned result:

+------+
| grid |
+------+
| []   |
+------+

Distance calculation

H3_Distance

Returns the Euclidean distance between the centroids of two specified H3 grids on a 2D plane. If an input H3 grid encoding is NULL or invalid, or the two grids have different levels, this function returns -1.

Syntax

BigDecimal H3_Distance(Long startCell, Long endCell)
BigDecimal H3_Distance(String startCell, String endCell)

Parameters

Parameter Name	Description
startCell	The start H3 grid encoding. The type is LONG or STRING. Note The type of startCell and endCell must be the same.
endCell	The end H3 grid encoding. The type is LONG or STRING. Note The type of endCell and startCell must be the same.

Examples

Example 1: Input two H3 grid encodings of the LONG type to return the Euclidean distance between the grid centroids on a 2D plane.

SELECT H3_distance(587769229395099647, 587026509290536959) as distance;

Returned result:

+-------------------+
|     distance      |
+-------------------+
| 4.489061432072522 |
+-------------------+

Example 2: Input two H3 grid encodings of the STRING type to return the Euclidean distance between the grid centroids on a 2D plane.

SELECT H3_distance('825897fffffffff','8282cffffffffff') as distance;

Returned result:

+-------------------+
|     distance      |
+-------------------+
| 4.489061432072522 |
+-------------------+

Example 3: An input H3 grid encoding is NULL or invalid, or the two grids have different levels. The function returns -1.

-- Input H3 grid code is invalid
SELECT H3_distance(587769229395099647, 345) AS distance;

-- Input H3 grid code is NULL
SELECT H3_distance(587769229395099647, NULL) AS distance;

-- The two H3 grid resolutions differ: 587769229395099647 has resolution 2, 599686042433355775 has resolution 5
SELECT H3_distance(587769229395099647, 599686042433355775) AS distance;

Returned result:

+----------+
| distance |
+----------+
| -1       |
+----------+

H3_DistanceSphere

Returns the spherical distance in meters (m) between the centroids of two specified H3 grids in the WGS84 coordinate system. If an input H3 grid encoding is NULL or invalid, or the two grids have different levels, this function returns -1.

Syntax

BigDecimal H3_DistanceSphere(Long startCell, Long endCell)
BigDecimal H3_DistanceSphere(String startCell, String endCell)

Parameters

Parameter name	Description
startCell	The start H3 grid encoding. The type is LONG or STRING. Note The type of startCell and endCell must be the same.
endCell	The end H3 grid encoding. The type is LONG or STRING. Note The type of endCell and startCell must be the same.

Examples

Example 1: Input two H3 grid encodings of the LONG type to return the spherical distance between the grid centroids in the WGS84 coordinate system.

SELECT H3_DistanceSphere(587769229395099647, 587026509290536959) as distance;

Returned result:

+--------------------+
|      distance      |
+--------------------+
| 497180.06581361144 |
+--------------------+

Example 2: Input two H3 grid encodings of the STRING type to return the spherical distance between the grid centroids in the WGS84 coordinate system.

SELECT H3_DistanceSphere('825897fffffffff','8282cffffffffff') as distance;

Returned result:

+--------------------+
|      distance      |
+--------------------+
| 497180.06581361144 |
+--------------------+

Example 3: An input H3 grid encoding is NULL or invalid, or the two grids have different levels. The function returns -1.

-- Input H3 grid code is invalid
SELECT H3_DistanceSphere(587769229395099647, 345) AS distance;

-- Input H3 grid code is NULL
SELECT H3_DistanceSphere(587769229395099647, NULL) AS distance;

-- The two grid resolutions differ: 587769229395099647 has resolution 2, 599686042433355775 has resolution 5
SELECT H3_DistanceSphere(587769229395099647, 599686042433355775) AS distance;

Returned result:

+----------+
| distance |
+----------+
| -1       |
+----------+