diff --git a/docs/how-tos/working-with-postgresql-data-types.rst b/docs/how-tos/working-with-postgresql-data-types.rst index 20c6a8232..ed12ea52b 100644 --- a/docs/how-tos/working-with-postgresql-data-types.rst +++ b/docs/how-tos/working-with-postgresql-data-types.rst @@ -318,144 +318,6 @@ You can insert a new product using a JSON object for the ``extra_info`` column: To query and filter the data see :ref:`json_columns` for a complete reference. -.. _ww_postgis: - -PostGIS -------- - -You can use the string representation for `PostGIS `_ data types such as ``geometry`` or ``geography`` (you need to `install PostGIS `_ first). - -.. code-block:: postgres - - -- Activate the postgis module in the current database - create extension if not exists postgis; - - create table coverage ( - id int primary key, - name text unique, - area geometry - ); - -To add areas in polygon format, you can use string representation: - -.. code-block:: bash - - curl "http://localhost:3000/coverage" \ - -X POST -H "Content-Type: application/json" \ - -d @- << EOF - [ - { "id": 1, "name": "small", "area": "SRID=4326;POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" }, - { "id": 2, "name": "big", "area": "SRID=4326;POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))" } - ] - EOF - -Now, when you request the information, PostgREST will automatically cast the ``area`` column into a ``Polygon`` geometry type. Although this is useful, you may need the whole output to be in `GeoJSON `_ format out of the box, which can be done by including the ``Accept: application/geo+json`` in the request. This will work for PostGIS versions 3.0.0 and up and will return the output as a `FeatureCollection Object `_: - -.. code-block:: bash - - curl "http://localhost:3000/coverage" \ - -H "Accept: application/geo+json" - -.. code-block:: json - - { - "type": "FeatureCollection", - "features": [ - { - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [[0,0],[1,0],[1,1],[0,1],[0,0]] - ] - }, - "properties": { - "id": 1, - "name": "small" - } - }, - { - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [[0,0],[10,0],[10,10],[0,10],[0,0]] - ] - }, - "properties": { - "id": 2, - "name": "big" - } - } - ] - } - -If you need to add an extra property, like the area in square units by using ``st_area(area)``, you could add a generated column to the table and it will appear in the ``properties`` key of each ``Feature``. - -.. code-block:: postgres - - alter table coverage - add square_units double precision generated always as ( st_area(area) ) stored; - -In the case that you are using older PostGIS versions, then creating a function is your best option: - -.. code-block:: postgres - - create or replace function coverage_geo_collection() returns json as $$ - select - json_build_object( - 'type', 'FeatureCollection', - 'features', json_agg( - json_build_object( - 'type', 'Feature', - 'geometry', st_AsGeoJSON(c.area)::json, - 'properties', json_build_object('id', c.id, 'name', c.name) - ) - ) - ) - from coverage c; - $$ language sql; - -Now this query will return the same results: - -.. code-block:: bash - - curl "http://localhost:3000/rpc/coverage_geo_collection" - -.. code-block:: json - - { - "type": "FeatureCollection", - "features": [ - { - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [[0,0],[1,0],[1,1],[0,1],[0,0]] - ] - }, - "properties": { - "id": 1, - "name": "small" - } - }, - { - "type": "Feature", - "geometry": { - "type": "Polygon", - "coordinates": [ - [[0,0],[10,0],[10,10],[0,10],[0,0]] - ] - }, - "properties": { - "id": 2, - "name": "big" - } - } - ] - } - Ranges ------ diff --git a/docs/integrations/postgis.rst b/docs/integrations/postgis.rst new file mode 100644 index 000000000..7696f45bc --- /dev/null +++ b/docs/integrations/postgis.rst @@ -0,0 +1,137 @@ +.. _ww_postgis: + +PostGIS +======= + +You can use the string representation for `PostGIS `_ data types such as ``geometry`` or ``geography`` (you need to `install PostGIS `_ first). + +.. code-block:: postgres + + -- Activate the postgis module in the current database + create extension if not exists postgis; + + create table coverage ( + id int primary key, + name text unique, + area geometry + ); + +To add areas in polygon format, you can use string representation: + +.. code-block:: bash + + curl "http://localhost:3000/coverage" \ + -X POST -H "Content-Type: application/json" \ + -d @- << EOF + [ + { "id": 1, "name": "small", "area": "SRID=4326;POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))" }, + { "id": 2, "name": "big", "area": "SRID=4326;POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))" } + ] + EOF + +Now, when you request the information, PostgREST will automatically cast the ``area`` column into a ``Polygon`` geometry type. Although this is useful, you may need the whole output to be in `GeoJSON `_ format out of the box, which can be done by including the ``Accept: application/geo+json`` in the request. This will work for PostGIS versions 3.0.0 and up and will return the output as a `FeatureCollection Object `_: + +.. code-block:: bash + + curl "http://localhost:3000/coverage" \ + -H "Accept: application/geo+json" + +.. code-block:: json + + { + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[0,0],[1,0],[1,1],[0,1],[0,0]] + ] + }, + "properties": { + "id": 1, + "name": "small" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[0,0],[10,0],[10,10],[0,10],[0,0]] + ] + }, + "properties": { + "id": 2, + "name": "big" + } + } + ] + } + +If you need to add an extra property, like the area in square units by using ``st_area(area)``, you could add a generated column to the table and it will appear in the ``properties`` key of each ``Feature``. + +.. code-block:: postgres + + alter table coverage + add square_units double precision generated always as ( st_area(area) ) stored; + +In the case that you are using older PostGIS versions, then creating a function is your best option: + +.. code-block:: postgres + + create or replace function coverage_geo_collection() returns json as $$ + select + json_build_object( + 'type', 'FeatureCollection', + 'features', json_agg( + json_build_object( + 'type', 'Feature', + 'geometry', st_AsGeoJSON(c.area)::json, + 'properties', json_build_object('id', c.id, 'name', c.name) + ) + ) + ) + from coverage c; + $$ language sql; + +Now this query will return the same results: + +.. code-block:: bash + + curl "http://localhost:3000/rpc/coverage_geo_collection" + +.. code-block:: json + + { + "type": "FeatureCollection", + "features": [ + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[0,0],[1,0],[1,1],[0,1],[0,0]] + ] + }, + "properties": { + "id": 1, + "name": "small" + } + }, + { + "type": "Feature", + "geometry": { + "type": "Polygon", + "coordinates": [ + [[0,0],[10,0],[10,10],[0,10],[0,0]] + ] + }, + "properties": { + "id": 2, + "name": "big" + } + } + ] + }