14.16.10 Spatial Geohash Functions — MySQL 8.4

14.16.10 Функции пространственных геохешей

Геохеш — это система кодирования координат широты и долготы произвольной точности в строку текста. Значения геохешей — это строки, содержащие только символы, выбранные из "0123456789bcdefghjkmnpqrstuvwxyz".

Функции в этом разделе позволяют манипулировать значениями геохешей, предоставляя приложениям возможности импорта и экспорта данных геохешей, а также индексирования и поиска значений геохешей.

Если не указано иное, функции в этом разделе обрабатывают свои аргументы геометрии следующим образом:

Если какой-либо аргумент равен NULL, возвращаемое значение равно NULL.
Если какой-либо аргумент является недопустимым, возникает ошибка.
Если какой-либо аргумент имеет долготу или широту, выходящие за пределы диапазона, возникает ошибка:
- Если значение долготы не находится в диапазоне (−180, 180], возникает ошибка.
- Если значение широты не находится в диапазоне [−90, 90], возникает ошибка.
Указанные диапазоны приведены в градусах. Точные пределы диапазона немного отличаются из-за арифметики с плавающей запятой.
Если какой-либо аргумент точки не имеет SRID 0 или 4326, возникает ошибка. point аргумент SRID проверки не выполняется.
Если какой-либо аргумент SRID ссылается на неопределённую пространственную систему координат (SRS), возникает ошибка.
Если какой-либо аргумент SRID не находится в диапазоне 32-битного беззнакового целого числа, возникает ошибка.
В противном случае возвращаемое значение является не-NULL.

Доступны следующие функции геохешей:

ST_GeoHash(longitude, latitude, max_length), ST_GeoHash(point, max_length)

Возвращает строку геохеша в наборе символов и сортировке соединения.

Для первого синтаксиса longitude должно быть числом в диапазоне [−180, 180], а latitude должно быть числом в диапазоне [−90, 90]. Для второго синтаксиса требуется значение POINT, где координаты X и Y находятся в допустимых диапазонах для долготы и широты соответственно.

Результирующая строка не длиннее, чем max_length символов, что имеет верхнюю границу 100. Строка может быть короче, чем max_length символов, поскольку алгоритм, создающий значение геохеша, продолжает работу до тех пор, пока не создаст строку, которая либо является точным представлением местоположения, либо max_length символов, в зависимости от того, что произойдёт раньше.

ST_GeoHash() обрабатывает свои аргументы, как описано во введении к этому разделу.
```
mysql> SELECT ST_GeoHash(180,0,10), ST_GeoHash(-180,-90,15);
+----------------------+-------------------------+
| ST_GeoHash(180,0,10) | ST_GeoHash(-180,-90,15) |
+----------------------+-------------------------+
| xbpbpbpbpb           | 000000000000000         |
+----------------------+-------------------------+
```
ST_LatFromGeoHash(geohash_str)

Возвращает широту из значения строки геохеша в виде числа двойной точности в диапазоне [−90, 90].

Функция декодирования ST_LatFromGeoHash() считывает не более 433 символов из аргумента geohash_str. Это представляет собой верхний предел информации во внутреннем представлении значений координат. Символы после 433-го игнорируются, даже если они являются недопустимыми и вызывают ошибку.

ST_LatFromGeoHash() обрабатывает свои аргументы, как описано во введении к этому разделу.
```
mysql> SELECT ST_LatFromGeoHash(ST_GeoHash(45,-20,10));
+------------------------------------------+
| ST_LatFromGeoHash(ST_GeoHash(45,-20,10)) |
+------------------------------------------+
|                                      -20 |
+------------------------------------------+
```
ST_LongFromGeoHash(geohash_str)

Возвращает долготу из значения строки геохеша в виде числа двойной точности в диапазоне [−180, 180].

Замечания в описании ST_LatFromGeoHash() относительно максимального числа обработанных символов из аргумента geohash_str также относятся к ST_LongFromGeoHash().

ST_LongFromGeoHash() обрабатывает свои аргументы, как описано во введении к этому разделу.
```
mysql> SELECT ST_LongFromGeoHash(ST_GeoHash(45,-20,10));
+-------------------------------------------+
| ST_LongFromGeoHash(ST_GeoHash(45,-20,10)) |
+-------------------------------------------+
|                                        45 |
+-------------------------------------------+
```
ST_PointFromGeoHash(geohash_str, srid)

Возвращает значение POINT, содержащее декодированное значение геохеша, заданное строковым значением геохеша.

Координаты X и Y точки — это долгота в диапазоне [−180, 180] и широта в диапазоне [−90, 90] соответственно.

Аргумент srid — это 32-битное беззнаковое целое число.

Замечания в описании ST_LatFromGeoHash() относительно максимального числа обработанных символов из аргумента geohash_str также относятся к ST_PointFromGeoHash().

ST_PointFromGeoHash() обрабатывает свои аргументы, как описано во введении к этому разделу.
```
mysql> SET @gh = ST_GeoHash(45,-20,10);
mysql> SELECT ST_AsText(ST_PointFromGeoHash(@gh,0));
+---------------------------------------+
| ST_AsText(ST_PointFromGeoHash(@gh,0)) |
+---------------------------------------+
| POINT(45 -20)                         |
+---------------------------------------+
```