14.16.11 Spatial GeoJSON Functions — MySQL 9.2

14.16.11 Функции пространственных GeoJSON

В данном разделе описаны функции преобразования между документами GeoJSON и пространственными значениями. GeoJSON — это открытый стандарт кодирования геометрических/географических объектов. Дополнительную информацию можно найти на странице http://geojson.org. Рассматриваемые здесь функции соответствуют спецификации GeoJSON версии 1.0.

GeoJSON поддерживает те же типы геометрических/географических данных, что и MySQL. Объекты Feature и FeatureCollection не поддерживаются, за исключением извлечения геометрических объектов из них. Поддержка CRS ограничена значениями, идентифицирующими SRID.

MySQL также поддерживает собственный тип данных JSON и набор SQL-функций для работы со значениями JSON. Дополнительную информацию можно найти в разделе 13.5, «Тип данных JSON» и разделе 14.17, «Функции JSON».

ST_AsGeoJSON(g [, max_dec_digits [, options]])

Генерирует объект GeoJSON из геометрии g. Строка объекта имеет кодировку и сортировку соединения.

Если какой-либо аргумент является NULL, возвращаемое значение равно NULL. Если любой не-NULL аргумент некорректен, возникает ошибка.

max_dec_digits, если указано, ограничивает количество десятичных знаков для координат и приводит к округлению выходных данных. Если не указано, этот аргумент по умолчанию принимает максимальное значение 2³² − 1. Минимальное значение — 0.

options, если указано, — это битовая маска. В следующей таблице показаны разрешённые значения флагов. Если у аргумента geometry SRID равен 0, объект CRS не создаётся, даже для тех значений флагов, которые его запрашивают.

Значение флага	Описание
0	Нет опций. Это значение по умолчанию, если `options` не указано.
1	Добавить прямоугольник обрамления в выходные данные.
2	Добавить сокращённую URN CRS в выходные данные. Формат по умолчанию — короткий формат (`EPSG:srid`).
4	Добавить URN CRS в длинном формате (`urn:ogc:def:crs:EPSG::srid`). Этот флаг переопределяет флаг 2. Например, значения опций 5 и 7 означают то же самое (добавить прямоугольник обрамления и URN CRS в длинном формате).

mysql> SELECT ST_AsGeoJSON(ST_GeomFromText('POINT(11.11111 12.22222)'),2);
+-------------------------------------------------------------+
| ST_AsGeoJSON(ST_GeomFromText('POINT(11.11111 12.22222)'),2) |
+-------------------------------------------------------------+
| {"type": "Point", "coordinates": [11.11, 12.22]}            |
+-------------------------------------------------------------+

ST_GeomFromGeoJSON(str [, options [, srid]])

Парсит строку str, представляющую объект GeoJSON, и возвращает геометрию.

options, если задан, описывает, как обрабатывать документы GeoJSON, содержащие геометрии с размерностью координат выше 2. В следующей таблице показаны разрешённые значения options.

Значение опции	Описание
1	Отклонить документ и сгенерировать ошибку. Это значение по умолчанию, если `options` не указано.
2, 3, 4	Принять документ и удалить координаты для размерности координат выше 2.

Значения options 2, 3 и 4 в настоящее время дают одинаковый результат. Если в будущем будут поддерживаться геометрии с размерностью координат выше 2, ожидается, что эти значения будут давать разные результаты.

Аргумент srid, если задан, должен быть 32-битным беззнаковым целым числом. Если не задан, возвращаемая геометрия имеет SRID 4326.

Если srid ссылается на неопределённую систему пространственной ссылки (SRS), возникает ошибка.

Для геометрических аргументов географических SRS, если у любого аргумента долгота или широта выходят за пределы диапазона, возникает ошибка:

Если значение долготы не находится в диапазоне (−180, 180], возникает ошибка.
Если значение широты не находится в диапазоне [−90, 90], возникает ошибка.

Указанные диапазоны приведены в градусах. Если SRS использует другую единицу измерения, диапазон использует соответствующие значения в этой единице. Точные пределы диапазона незначительно отличаются из-за арифметики с плавающей запятой.

Объекты GeoJSON геометрии, признака и коллекции признаков могут иметь свойство crs. Функция парсинга анализирует URN CRS с именами в пространствах имён urn:ogc:def:crs:EPSG::srid и EPSG:srid, но не CRS, заданные как объекты ссылок. Кроме того, urn:ogc:def:crs:OGC:1.3:CRS84 распознаётся как SRID 4326. Если объект имеет не распознаваемый CRS, возникает ошибка, за исключением случая, когда указан необязательный аргумент srid, в этом случае любой CRS игнорируется, даже если он некорректен.

Если член crs, который указывает на SRID, отличающийся от SRID верхнего уровня объекта, найден на более низком уровне документа GeoJSON, возникает ошибка.

Согласно спецификации GeoJSON, парсинг для члена type входных данных GeoJSON (Point, LineString и так далее) является регистрозависимым. Спецификация ничего не говорит о регистрозависимости для других операций парсинга, которые в MySQL не регистрозависимы.

В этом примере показан результат парсинга для простого объекта GeoJSON. Обратите внимание, что порядок координат зависит от используемого SRID.

mysql> SET @json = '{ "type": "Point", "coordinates": [102.0, 0.0]}';
mysql> SELECT ST_AsText(ST_GeomFromGeoJSON(@json));
+--------------------------------------+
| ST_AsText(ST_GeomFromGeoJSON(@json)) |
+--------------------------------------+
| POINT(0 102)                         |
+--------------------------------------+
mysql> SELECT ST_SRID(ST_GeomFromGeoJSON(@json));
+------------------------------------+
| ST_SRID(ST_GeomFromGeoJSON(@json)) |
+------------------------------------+
|                               4326 |
+------------------------------------+
mysql> SELECT ST_AsText(ST_SRID(ST_GeomFromGeoJSON(@json),0));
+-------------------------------------------------+
| ST_AsText(ST_SRID(ST_GeomFromGeoJSON(@json),0)) |
+-------------------------------------------------+
| POINT(102 0)                                    |
+-------------------------------------------------+