What are the H3 functions supported by Lindorm - Lindorm

You can use the H3 functions provided by Lindorm GanosBase to efficiently analyze or query spatial data based on H3 grids. These H3 functions can help you process H3 indexes, such as convert index types, query the relationship between cells, query the resolution of cells, and calculate the distance between cells. This topic describes all H3 function supported by Lindorm GanosBase.

Applicable engines and versions

The H3 functions described in this topic are applicable only to LindormTable.
The H3 functions described in this topic are supported by LindormTable 2.6.5 and later versions. For more information about how to view or upgrade the version of LindormTable, see Release notes of LindormTable and Upgrade the minor engine version of a Lindorm instance.
Important
If the LindormTable version of your Lindorm instance is earlier than 2.6.5 and cannot be upgraded, contact the technical support (DingTalk ID: s0s3eg3).

Functions

The following table shows the H3 functions supported by Lindorm GanosBase.

Category	Function	Description
Data import and conversion	H3	Converts a latitude/longitude pair or a coordinate point to an H3 index at the specified resolution.
	H3_H3ToString	Converts the data type of an H3 index from LONG to STRING.
	H3_StringToH3	Converts the data type of an H3 index from STRING to LONG.
	H3_PolygonToCells	Outputs the H3 index array of a polygon at the specified resolution.
Data export	H3_CellToBoundary	Outputs the polygon boundary of the specified H3 cell.
Cell determination	H3_IsValidCell	Determines whether the input H3 index is valid.
	H3_GetResolution	Returns the resolution of the input H3 index.
	H3_AreNeighborCells	Determines whether two H3 cells are spatially adjacent. If the two cells are adjacent, `true` is returned. Otherwise, `false` is returned.
	H3_Contains	Determines whether the cells indicated by the specified H3Cells object contain the specified H3 cell.
H3 cell operations	H3_CellToParent	Returns the H3 index of the parent cell of the specified H3 cell at the specified resolution.
H3 cell operations	H3_CellToChildren	Returns the H3 index of the child cell of the specified H3 cell at the specified resolution.
Queries related to H3 cells	H3_GridPathCells	Obtains the path between two H3 cells.
Queries related to H3 cells	H3_GridDisk	Returns the H3 indexes of all cells whose distance from the center cell is less than the specified distance k.
Distance calculation	H3_Distance	Returns the 2D Euclidean distance between the central points of two specified H3 cells.
Distance calculation	H3_DistanceSphere	Returns the spherical distance between the central points of two specified H3 cells in WGS84

Data import and conversion

H3

This function converts a latitude/longitude pair or a coordinate point to an H3 index at the specified resolution.

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	A coordinate point of the POINT data type.
lng	A longitude value of the DOUBLE data type.
lat	A latitude value of the DOUBLE data type.
resolution	The H3 index resolution of the INT data type. Valid values: 0 to 15. Default value: 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 following same result is returned for the preceding sample statements:

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

H3_H3ToString

This function converts the data type of an H3 index from LONG to STRING. If the input H3 index is NULL of invalid, an empty string is returned.

Syntax

String H3_H3ToString(Long H3Cell)

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG data type.

Examples

Example 1: Converts the data type of an H3 index from LONG to STRING.

SELECT H3_H3ToString(599686042433355775) AS H3Address;

The following result is returned:

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

Example 2: Check whether the input H3 index is valid. If the input H3 index is NULL or invalid, an empty string is returned.

-- Input an invalid H3 index.
SELECT H3_H3ToString(0) AS H3Address;

--Input the value NULL.
SELECT H3_H3ToString(NULL) AS H3Address;

The following result is returned:

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

H3_StringToH3

This function converts the data type of an H3 index from STRING to LONG. If the input H3 index is an empty string or invalid, the value -1 is returned.

Syntax

Long H3_StringToH3(string H3Cell)

Parameters

Parameter	Description
H3Cell	An H3 index of the STRING data type.

Examples

Example 1: Converts the data type of an H3 index from STRING to LONG.

SELECT H3_StringToH3('85283473fffffff') AS H3Cell;

The following result is returned:

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

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

-- Input an invalid H3 index.
SELECT H3_StringToH3('abc') AS H3Cell;

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

The following result is returned:

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

H3_PolygonToCells

This function outputs the H3 index array of a polygon at the specified resolution.

Syntax

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

Parameters

Parameter	Description
poly	A polygon object of the POLYGON data type.
resolution	The H3 index resolution. Valid values: 0 to 15.

Examples

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

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;

The following result is returned:

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

Data export

H3_CellToBoundary

This function outputs the polygon boundary of the specified H3 cell. If the input H3 index is an empty string, NULL, or invalid, an empty array is returned.

Syntax

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

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG or STRING data type.

Examples

Example 1: Obtain the polygon boundary of an H3 cell specified by the input H3 index of the STRING data type.

SELECT H3_CellToBoundary('85283473fffffff') AS boundary;

The following result is returned:

+--------------------------------+
|            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: Obtain the polygon boundary of an H3 cell specified by the input H3 index of the LONG data type.

SELECT H3_CellToBoundary(599686042433355775) AS boundary;

The following result is returned:

+--------------------------------+
|            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 string, NULL, or an invalid value as the H3 index. An empty array is returned.

-- Input an empty string.
SELECT H3_CellToBoundary('') AS boundary;

-- Input the value NULL.
SELECT H3_CellToBoundary(NULL) AS boundary;

-- Input an invalid H3 index.
SELECT H3_CellToBoundary(0) AS boundary;

The following result is returned:

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

Cell determination

H3_IsValidCell

This function determines whether the input H3 index is valid. If the input H3 index is valid, true is returned. Otherwise, false is returned. If the input H3 index is an empty string or NULL, false is returned.

Syntax

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

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG or STRING data type.

Examples

Example 1: Check whether the input H3 index is valid. The H3 indexes in the following sample statements are valid:

-- Input an H3 index of the LONG data type.
SELECT H3_IsValidCell(599686042433355775) AS isValid;

-- Input an H3 index of the STRING data type.
SELECT H3_IsValidCell('85283473fffffff') AS isValid;

The following result is returned:

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

Example 2: Check whether the input H3 index is valid. The H3 indexes in the following sample statements are invalid:

-- Input an H3 index of the LONG data type.
SELECT H3_IsValidCell(12) AS isValid;

-- Input an H3 index of the STRING data type.
SELECT H3_IsValidCell('abc') AS isValid;

The following result is returned:

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

Example 3: Input an empty string or NULL as the H3 index. The value false is returned.

-- Input an empty string.
SELECT H3_IsValidCell('') AS isValid;

-- Input the value NULL.
SELECT H3_IsValidCell(NULL) AS isValid;

The following result is returned:

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

H3_GetResolution

This function returns the resolution of the input H3 index.

Syntax

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

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG or STRING data type.

Examples

Example 1: Return the resolution of the input H3 index of the LONG data type.

SELECT H3_GetResolution(599686042433355775) AS resolution;

The following result is returned:

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

Example 2: Return the resolution of the input H3 index of the STRING data type.

SELECT H3_GetResolution('85283473fffffff') AS resolution;

The following result is returned:

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

H3_AreNeighborCells

This function determines whether two H3 cells are spatially adjacent. If the two cells are adjacent, true is returned. Otherwise, false is returned. If any of the specified H3 indexes is NULL or invalid, or the specified H3 indexes are at different resolutions, false is returned.

Note

Before you use the H3_AreNeighborCells function, you can use the H3_GetResolution function to query the resolution of an H3 index. 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 indexes of the LONG or STRING data type.

Examples

Example 1: Input two H3 indexes of the LONG data type and determine whether the H3 cells represented by the two H3 indexes are spatially adjacent.
```
SELECT H3_AreNeighborCells(605546022931791871, 605546023066009599) as isNeighbor;
```
The following result is returned:
```
+------------+
| isNeighbor |
+------------+
| true       |
+------------+
```
Example 2: Input two H3 indexes of the STRING data type and determine whether the H3 cells represented by the two H3 indexes are spatially adjacent.
```
SELECT H3_AreNeighborCells('86754e66fffffff','86754e64fffffff') as isNeighbor;
```
The following result is returned:
```
+------------+
| isNeighbor |
+------------+
| true       |
+------------+
```

Example 3: Input two invalid H3 indexes, a NULL value, or two H3 indexes at different resolutions. The value false is returned.

-- Input two invalid H3 indexes.
SELECT H3_AreNeighborCells(1234,5678) as isNeighbor;

-- Set one of the input H3 indexes to NULL.
SELECT H3_AreNeighborCells(1234,NULL) as isNeighbor;

-- Input two H3 indexes at different resolutions. The H3 index '85283473fffffff' is at resolution 5, and the H3 index '87283082bffffff' is at resolution 7.
SELECT H3_AreNeighborCells('85283473fffffff','87283082bffffff') as isNeighbor;

The following result is returned:

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

H3_Contains

This function determines whether the cells indicated by the specified H3Cells object contain the specified H3 cell.

For example, the H3 cells indicated by the specified H3Cells object contains an H3 cell named A, and another H3 cell named B is specified for the function. This function returns true when one of the following conditions is met:

A and B are identical.
B is a child cell of A.

If the H3 index of B is invalid or NULL, false is returned. If the H3 index array of the H3Cells object contains invalid H3 indexes, the invalid H3 indexes are ignored and no error is reported.

Syntax

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

Parameters

Parameter	Description
H3Cells	The H3 index array.
H3	The H3 index.

Examples

Example 1: Check whether the specified H3 cell is contained by the cells indicated by the valid H3Cells object.

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;

The following result is returned:

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

The value true is returned, which indicates that the specified H3 cell is contained by the cells indicated by the valid H3Cells object.

Example 2: Check whether the specified H3 cell is contained by the cells indicated by the valid H3Cells object.

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;

The following result is returned:

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

The value false is returned, which indicates that the specified H3 cell is not contained by the cells indicated by the valid H3Cells object.

Example 3: Input an H3 index that is invalid or NULL. The value false is returned.

-- Input an H3 index whose value 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 an invalid H3 index.
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;

The following result is returned:

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

H3 cell operations

H3_CellToParent

This function returns the H3 index of the parent cell of the specified H3 cell at the specified resolution.

If the specified H3 index is invalid or the specified resolution is the child resolution of the current H3 index, the value -1 or an empty string is returned. If the specified resolution is the same as the resolution of the current H3 index, the H3 index is returned.

Note

A larger resolution value represents a resolution at a lower level. For example, resolution 5 is a child resolution of resolution 0. You can use the H3_GetResolution function to query the resolution of an H3 cell. For more information, see H3_GetResolution.

Syntax

Long H3_CellToParent(Long H3Cell, Int resolution)

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG data type.
resolution	The specified resolution. Valid values: (0, Resolution of the H3Cell value]. For example, if the resolution of the H3 cell specified by H3Cell is 5, the value range of the resolution parameter is (0, 5].

Examples

Example 1: Input an H3 index of the LONG data type and return the H3 indexes of all parent cells of the cell specified by the H3 index at resolution 0.
```
SELECT H3_CellToParent(599686042433355775, 0) AS parent;
```
The following result is returned:
```
+--------------------+
|       parent       |
+--------------------+
| 577199624117288959 |
+--------------------+
```
Example 2: Input an H3 index of the STRING data type and return the H3 indexes of all parent cells of the cell specified by the H3 index at resolution 5.
```
SELECT H3_CellToParent(599686042433355775, 5) AS parent;
```
The following result is returned:
```
+--------------------+
|       parent       |
+--------------------+
| 599686042433355775 |
+--------------------+
```

Example 3: Input an H3 index that is invalid or NULL, or specify a resolution that is NULL or the child resolution of the current H3 index. The value -1 is returned.

-- Input an invalid H3 index.
SELECT H3_CellToParent(123, 5) AS parent;

-- Specify a resolution that is the child resolution of the current H3 index.
SELECT H3_CellToParent(599686042433355775, 9) AS parent;

-- Specify a resolution of NULL.
SELECT H3_CellToParent(599686042433355775, NULL) AS parent;

-- Input an H3 index of NULL and specify a resolution of NULL.
SELECT H3_CellToParent(NULL, NULL) AS parent;

The following result is returned:

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

H3_CellToChildren

This function returns the H3 index of the child cell of the specified H3 cell at the specified resolution.

If the specified H3 index is invalid or the specified resolution is the parent resolution or the current resolution of the H3 index, an empty array is returned.

Note

Syntax

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

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG or STRING data type.
resolution	The specified resolution. Valid values: (Resolution of the specified H3 index, 15]. For example, if the resolution of the H3 cell specified by H3Cell is 5, the value range of the resolution parameter is (5, 15].

Examples

Example 1: Input an H3 index of the LONG data type and return the H3 indexes of all child cells of the cell specified by the H3 index at resolution 6.

SELECT H3_CellToChildren(599686042433355775, 6) AS children;

The following result is returned:

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

Example 2: Input an H3 index of the STRING data type and return the H3 indexes of all child cells of the cell specified by the H3 index at resolution 6.

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

The following result is returned:

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

Example 3: Input an invalid H3 index, or specify a resolution that is the parent resolution or current resolution of the H3 index. An empty array is returned.

-- Input an invalid H3 index.
SELECT H3_CellToChildren(0,15) AS children;

-- Specify a resolution that is the parent resolution of the H3 index.
SELECT H3_CellToChildren('85283473fffffff', 3) AS children;

-- Specify a resolution that is the current resolution of the H3 index.
SELECT H3_CellToChildren('85283473fffffff', 5) AS children;

The following result is returned:

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

Queries related to H3 cells

H3_GridPathCells

Obtains the H3 cell path between two H3 cells, including the start cell and end cell. If the input H3 index is invalid, an empty array is returned. If the resolutions of the two specified H3 indexes are different, the value null is returned.

Syntax

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

Parameters

Parameter	Description
startCell	The H3 index of the start cell. The data type of this parameter is LONG or STRING. Note The data types of startCell and endCell must be the same.
endCell	The H3 index of the end cell. The data type of this parameter is LONG or STRING. Note The data types of startCell and endCell must be the same.

Examples

Example 1: Input two H3 indexes and return the path between the cells indicated by the two H3 indexes.

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

The following result is returned:

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

Example 2: Input an invalid H3 index. An empty array is returned.

SELECT H3_GridPathCells(587769229395099647, 123) as pathCell;

The following result is returned:

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

Example 3: Input two H3 indexes at different resolutions. The value null is returned.

-- Input two H3 indexes at different resolutions. The H3 index '587769229395099647' is at resolution 2, and the H3 index '599686042433355775' is at resolution 5.
SELECT H3_GridPathCells(587769229395099647, 599686042433355775) as pathCell;

The following result is returned:

+----------+
| pathCell |
+----------+
| null     |
+----------+

H3_GridDisk

This function returns the H3 indexes of all cells whose distance from the specified center cell is equal to or less than the specified distance k at the specified resolution. For example, if you specify a center cell named A and set k to 1, cell A and all cells whose distance from A is 1 are returned. If you set k to 2, cell A and all cells whose distance from A is 2 are returned.

If the input H3 index is invalid or NULL, an empty array is returned. If k is set to 0, the specified center cell is returned.

Syntax

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

Parameters

Parameter	Description
H3Cell	An H3 index of the LONG or STRING data type.
k	The distance between other cells with the center cell.

Examples

Example 1: Return the H3 indexes of all cells whose distance from the center cell is equal to or less than 1.

SELECT H3_GridDisk(599686042433355775, 1) AS grid;

The following result is returned:

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

Example 2: Return the H3 indexes of all cells whose distance from the center cell is equal to 0. The H3 index of the center cell is returned.

SELECT H3_GridDisk(599686042433355775, 0) AS grid;

The following result is returned:

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

Example 3: Input an H3 index that is invalid or NULL, an empty array is returned.

-- Input an H3 index whose value is NULL.
SELECT H3_GridDisk(NULL, 0) AS grid;

-- Input an invalid H3 index.
SELECT H3_GridDisk(123456, 0) AS grid;

The following result is returned:

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

Distance calculation

H3_Distance

This function returns the 2D Euclidean distance between the central points of two specified H3 cells. If one of the specified H3 indexes is invalid or NULL, or the two specified H3 indexes are at different resolutions, the value -1 is returned.

Syntax

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

Parameters

Parameter	Description
startCell	The H3 index of the start cell. The data type of this parameter is LONG or STRING. Note The data types of startCell and endCell must be the same.
endCell	The H3 index of the end cell. The data type of this parameter is LONG or STRING. Note The data types of startCell and endCell must be the same.

Examples

Example 1: Input two H3 indexes of the LONG data type and return the 2D Euclidean distance between the central points of two H3 cells specified by the H3 indexes.
```
SELECT H3_distance(587769229395099647, 587026509290536959) as distance;
```
The following result is returned:
```
+-------------------+
|     distance      |
+-------------------+
| 4.489061432072522 |
+-------------------+
```
Example 2: Input two H3 indexes of the STRING data type and return the 2D Euclidean distance between the central points of two H3 cells specified by the H3 indexes.
```
SELECT H3_distance('825897fffffffff','8282cffffffffff') as distance;
```
The following result is returned:
```
+-------------------+
|     distance      |
+-------------------+
| 4.489061432072522 |
+-------------------+
```

Example 3: Input an H3 index that is invalid or NULL, or specify two H3 indexes at different resolutions. The value -1 is returned.

-- Input an invalid H3 index.
SELECT H3_distance(587769229395099647, 345) AS distance;

-- Input an H3 index whose value is NULL.
SELECT H3_distance(587769229395099647, NULL) AS distance;

-- Input two H3 indexes at different resolutions. The H3 index '587769229395099647' is at resolution 2, and the H3 index '599686042433355775' is at resolution 5.
SELECT H3_distance(587769229395099647, 599686042433355775) AS distance;

The following result is returned:

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

H3_DistanceSphere

This function returns the spherical distance in meters between the central points of two specified H3 cells in WGS84. If one of the input H3 indexes is invalid or NULL, or the resolutions of the specified H3 indexes are different, the value -1 is returned.

Syntax

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

Parameters

Parameter	Description
startCell	The H3 index of the start cell. The data type of this parameter is LONG or STRING. Note The data types of startCell and endCell must be the same.
endCell	The H3 index of the end cell. The data type of this parameter is LONG or STRING. Note The data types of startCell and endCell must be the same.

Examples

Example 1: Input two H3 indexes of the LONG data type and return the spherical distance in WGS84 between the central points of two H3 cells specified by the H3 indexes.
```
SELECT H3_DistanceSphere(587769229395099647, 587026509290536959) as distance;
```
The following result is returned:
```
+--------------------+
|      distance      |
+--------------------+
| 497180.06581361144 |
+--------------------+
```
Example 2: Input two H3 indexes of the STRING data type and return the spherical distance in WGS84 between the central points of two H3 cells specified by the H3 indexes.
```
SELECT H3_DistanceSphere('825897fffffffff','8282cffffffffff') as distance;
```
The following result is returned:
```
+--------------------+
|      distance      |
+--------------------+
| 497180.06581361144 |
+--------------------+
```

Example 3: Input an H3 index that is invalid or NULL, or specify two H3 indexes at different resolutions. The value -1 is returned.

-- Input an invalid H3 index.
SELECT H3_DistanceSphere(587769229395099647, 345) AS distance;

-- Input an H3 index whose value is NULL.
SELECT H3_DistanceSphere(587769229395099647, NULL) AS distance;

-- Input two H3 indexes at different resolutions. The H3 index '587769229395099647' is at resolution 2, and the H3 index '599686042433355775' is at resolution 5.
SELECT H3_DistanceSphere(587769229395099647, 599686042433355775) AS distance;

The following result is returned:

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