-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Add new Examples sections * Updated Crunchy Hugo theme * Flesh out examples, some light edits * Added Spatial logo and edited screenshots
- Loading branch information
Showing
17 changed files
with
349 additions
and
33 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
101 changes: 101 additions & 0 deletions
101
hugo/content/examples/ex_query_functions_countries_name.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| --- | ||
| title: "Example: Query Countries by Name" | ||
| date: | ||
| draft: false | ||
| weight: 210 | ||
| --- | ||
|
|
||
| This is the same spatial function example shown in the [Usage](/usage/functions/) section, but we'll include a sample GeoJSON response, as well as the web UI preview. | ||
|
|
||
| ## Create a spatial function that returns a filtered set of countries | ||
|
|
||
| ```sql | ||
| CREATE OR REPLACE FUNCTION postgisftw.countries_name( | ||
| name_prefix text DEFAULT 'A') | ||
| RETURNS TABLE(name text, abbrev text, continent text, geom geometry) | ||
| AS $$ | ||
| BEGIN | ||
| RETURN QUERY | ||
| SELECT t.name::text, | ||
| t.abbrev::text, | ||
| t.continent::text, | ||
| t.geom | ||
| FROM ne.admin_0_countries t | ||
| WHERE t.name ILIKE name_prefix || '%'; | ||
| END; | ||
| $$ | ||
| LANGUAGE 'plpgsql' STABLE PARALLEL SAFE; | ||
|
|
||
| COMMENT ON FUNCTION postgisftw.countries_name IS 'Filters the countries table by the initial letters of the name using the "name_prefix" parameter.'; | ||
| ``` | ||
|
|
||
| ## Example of API query | ||
|
|
||
| The function can be called via the API by providing a value for the `name_prefix` parameter. | ||
|
|
||
| `http://localhost:9000/functions/countries_name/items?name_prefix=Mo` | ||
|
|
||
| Since a default value is included in the function declaration, you could omit the parameter in the call -- a random sample of features will be returned. | ||
|
|
||
| ## Sample GeoJSON response | ||
|
|
||
| The response is a GeoJSON document containing the 7 countries starting with the letters 'Mo'. | ||
|
|
||
| ```json | ||
| { | ||
| "type":"FeatureCollection", | ||
| "features":[ | ||
| { | ||
| "type":"Feature", | ||
| "geometry":{ | ||
| "type":"MultiPolygon", | ||
| "coordinates":[ | ||
| [ | ||
| [ | ||
| [ | ||
| -62.1484375, | ||
| 16.74033203125 | ||
| ], | ||
| [ | ||
| -62.154248046875, | ||
| 16.681201171875 | ||
| ], | ||
| ... | ||
| [ | ||
| -62.1484375, | ||
| 16.74033203125 | ||
| ] | ||
| ] | ||
| ] | ||
| ] | ||
| }, | ||
| "properties":{ | ||
| "abbrev":"Monts.", | ||
| "continent":"North America", | ||
| "name":"Montserrat" | ||
| } | ||
| }, | ||
| ... | ||
| ], | ||
| "numberReturned":7, | ||
| "timeStamp":"2020-03-18T03:15:15Z", | ||
| "links":[ | ||
| { | ||
| "href":"http://localhost:9000/collections/countries_name/items.json", | ||
| "rel":"self", | ||
| "type":"application/json", | ||
| "title":"This document as JSON" | ||
| }, | ||
| { | ||
| "href":"http://localhost:9000/collections/countries_name/items.html", | ||
| "rel":"alternate", | ||
| "type":"text/html", | ||
| "title":"This document as HTML" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Web preview | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,151 @@ | ||
| --- | ||
| title: "Example: Generate a Geographic Grid" | ||
| date: | ||
| draft: false | ||
| weight: 220 | ||
| --- | ||
|
|
||
| This example shows how to generate geometry data from a function, controlled by some input parameters. | ||
|
|
||
| This particular function does not query an existing table in the database; rather, it uses PostGIS functions to generate spatial data. Grids generated in this way could be used for data visualization, analysis, or clustering. | ||
|
|
||
| ## Create a spatial function that generates a grid over a desired area | ||
|
|
||
| ```sql | ||
| CREATE OR REPLACE FUNCTION postgisftw.geo_grid( | ||
| num_x integer DEFAULT 10, | ||
| num_y integer DEFAULT 10, | ||
| lon_min numeric DEFAULT -180.0, | ||
| lat_min numeric DEFAULT -90.0, | ||
| lon_max numeric DEFAULT 180.0, | ||
| lat_max numeric DEFAULT 90.0) | ||
| RETURNS TABLE(id text, geom geometry) | ||
| AS $$ | ||
| DECLARE | ||
| dlon numeric; | ||
| dlat numeric; | ||
| BEGIN | ||
| dlon := (lon_max - lon_min) / num_x; | ||
| dlat := (lat_max - lat_min) / num_y; | ||
| RETURN QUERY | ||
| SELECT | ||
| x.x::text || '_' || y.y::text AS id, | ||
| ST_MakeEnvelope( | ||
| lon_min + (x.x - 1) * dlon, lat_min + (y.y - 1) * dlat, | ||
| lon_min + x.x * dlon, lat_min + y.y * dlat, 4326 | ||
| ) AS geom | ||
| FROM generate_series(1, num_x) AS x(x) | ||
| CROSS JOIN generate_series(1, num_y) AS y(y); | ||
| END; | ||
| $$ | ||
| LANGUAGE 'plpgsql' | ||
| STABLE | ||
| STRICT; | ||
| ``` | ||
|
|
||
| Notes: | ||
|
|
||
| * The `geo_grid` function accepts a num_x and a num_y value to define the number of grid cells along the longitudinal (X) and latitudinal (Y) axes respectively. It also takes in minimum and maximum longitude and latitude values for the map area we want covered. | ||
| * The function first calculates the lengths of the sides of the grid (dlon and dlat). | ||
| * A CROSS JOIN on two generate_series() functions produces X and Y indices for each grid cell. | ||
| * The PostGIS function [ST_MakeEnvelope()](https://postgis.net/docs/ST_MakeEnvelope.html) contructs a rectangular polygon for each cell. An `id` value is also returned that encodes the grid index. | ||
|
|
||
| ## Example of API query | ||
|
|
||
| `http://localhost:9000/functions/geo_grid/items?num_x=5&num_y=5&lon_min=-128&lat_min=25&lon_max=-65&lat_max=49&limit=50` | ||
|
|
||
| This generates a 5x5 grid over the United States. | ||
|
|
||
| The server returns a limited number of features by default, so we add a `limit` parameter in the call to ensure that we get all the grid cells. See _Limiting and Paging_ in [Executing Functions](/usage/query_function/) for more details on the `limit` parameter. | ||
|
|
||
| ## Sample GeoJSON response | ||
|
|
||
| The function returns a feature collection of Polygons. | ||
|
|
||
| ```json | ||
| { | ||
| "type": "FeatureCollection", | ||
| "features": [ | ||
| { | ||
| "type": "Feature", | ||
| "id": "1_1", | ||
| "geometry": { | ||
| "type": "Polygon", | ||
| "coordinates": [ | ||
| [ | ||
| [ | ||
| -128, | ||
| 25 | ||
| ], | ||
| [ | ||
| -128, | ||
| 29.8 | ||
| ], | ||
| [ | ||
| -115.4, | ||
| 29.8 | ||
| ], | ||
| [ | ||
| -115.4, | ||
| 25 | ||
| ], | ||
| [ | ||
| -128, | ||
| 25 | ||
| ] | ||
| ] | ||
| ] | ||
| }, | ||
| "properties": { | ||
| "id": "1_1" | ||
| } | ||
| }, | ||
| ... | ||
| { | ||
| "type": "Feature", | ||
| "id": "5_5", | ||
| "geometry": { | ||
| "type": "Polygon", | ||
| "coordinates": [ | ||
| [ | ||
| [ | ||
| -77.6, | ||
| 44.2 | ||
| ], | ||
| ... | ||
| [ | ||
| -77.6, | ||
| 44.2 | ||
| ] | ||
| ] | ||
| ] | ||
| }, | ||
| "properties": { | ||
| "id": "5_5" | ||
| } | ||
| } | ||
| ], | ||
| "numberReturned": 25, | ||
| "timeStamp": "2020-04-05T19:54:17Z", | ||
| "links": [ | ||
| { | ||
| "href": "http://localhost:9000/collections/geo_grid/items.json", | ||
| "rel": "self", | ||
| "type": "application/json", | ||
| "title": "This document as JSON" | ||
| }, | ||
| { | ||
| "href": "http://localhost:9000/collections/geo_grid/items.html", | ||
| "rel": "alternate", | ||
| "type": "text/html", | ||
| "title": "This document as HTML" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Each cell has an `id` value that also indicates where it is on the grid. Since longitude and latitude values increase as you move east and north respectively, the cell with `id` 1_1 is the most southwestern corner of the grid, while cell 1_2 is immediately east and cell 2_1 immediately north. | ||
|
|
||
| ## Web preview | ||
|
|
||
|  |
Oops, something went wrong.