Skip to content

Commit

Permalink
Merge pull request #1 from kbatuigas/pg_tileserv
Browse files Browse the repository at this point in the history
pg_tileserv edits and fix a couple of typos in pg_featureserv
  • Loading branch information
adamtimm authored Jul 10, 2020
2 parents d2400c4 + 62f6176 commit 19d7cbd
Show file tree
Hide file tree
Showing 9 changed files with 42 additions and 34 deletions.
4 changes: 1 addition & 3 deletions postgis/pg_featureserv/04-user_defined_functions.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
All of the commands on this page should be run within Terminal 2.
All of the commands on this page should be run within **Terminal 2**.

## `postgisftw` schema

Expand Down Expand Up @@ -63,5 +63,3 @@ To show that it's live, go back to **Terminal 2** and let's get some station nam
ORDER BY name ASC LIMIT 30;```{{execute}}
Try grabbing one of these names (e.g. `14th St`), and in the pg_featureserv UI, enter that name in the ```stop_name``` Function Args field on the `nyc_katacoda` function view. (Click `Requery` to view the output geometries.)
2 changes: 2 additions & 0 deletions postgis/pg_featureserv/finish.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
We put together this exercise to give you a taste of how easily and quickly you can add pg_featureserv to your existing PostGIS implementation and easily expose your spatial data via an API. We also showed you an example of adding a user-defined function and accessing it through the pg_featureserv generated API.

From here you can now add these features as layers to your web maps. Common implementations use [OpenLayers](https://openlayers.org/) or [Leaflet](https://leafletjs.com/). You can also add functions that do more complex geospatial analysis in the database and then expose them as web features. We encourage you to check out our [PostGIS exercises](https://learn.crunchydata.com/postgis) for further information on the different types of analysis and functions you can create.

Don't forget to also check out the [official pg_featureserv documentation](https://access.crunchydata.com/documentation/pg_featureserv/latest/).
2 changes: 1 addition & 1 deletion postgis/pg_featureserv/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ This scenario gives you an introduction to pg_featureserv.

To use pg_featureserv, you need to have a PostGIS database with spatial data loaded in it. The database has already been started in this learning environment and the spatial data has already been loaded. This scenario will use data from census data from New York City (NYC).

This exercise shows how to connect pg_featureserv to your database and shows the resulting features. We also demonstrate an example of using user-defined functions through pg_featureserv. If you would like to learn more about creating functions in PostgreSQL, please review our [Basics on Writing Functions](https://learn.crunchydata.com/postgresql-devel/courses/beyond-basics/basicfunctions) scenario. Data from this scenario is used in our other exercises as well, but the environements don't persist between scenarios.
This exercise shows how to connect pg_featureserv to your database and shows the resulting features. We also demonstrate an example of using user-defined functions through pg_featureserv. If you would like to learn more about creating functions in PostgreSQL, please review our [Basics on Writing Functions](https://learn.crunchydata.com/postgresql-devel/courses/beyond-basics/basicfunctions) scenario. Data from this scenario is used in our other exercises as well, but the environments don't persist between scenarios.

Here are the details on the database we are connecting to:

Expand Down
12 changes: 7 additions & 5 deletions postgis/pg_tileserv/01-pg_tileserv.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,17 @@
This exercise will show you the steps to take to add pg_tileserv to your PostGIS implementation.
This exercise shows you the steps to add pg_tileserv to your PostGIS implementation.

First, take a look at the tab to the right called "pg_tileserv". You'll see that it's still waiting for an available conneciton on port 7800, the port that pg_tileserv serves data on. That's because we haven't added pg_tileserv to our PostGIS implementation yet. Let's do that now (click back to ```Terminal```)
First, take a look at the tab in the terminal to the right called "pg_tileserv". You'll see that it's still waiting for an available conneciton on port 7800, the port that pg_tileserv serves data on. That's because we haven't added pg_tileserv to our PostGIS implementation yet. Let's do that now.

## Add pg_tileserv

To add pg_tileserv to your PostGIS database, you need to either download the [source code](https://github.com/CrunchyData/pg_tileserv), the binaries, or one of our supported containers. We'll use the container version of pg_tileserv for this scenario.

To add the container to your postgis implentation, you'll need the connection info and username and password (from the first screen).
The code block below allows you to click on it to have the code execute in the terminal. Be sure to click on the ```Terminal``` tab before click on the box to make sure the code executes in the correct tab. You also have the option of copying and pasting the code, or typing it yourself in the ```Terminal``` tab.

```docker run -p 7800:7800 --env=DATABASE_URL=postgres://groot:[email protected]/nyc timmam/pg_tileserv:Katacoda```{{execute}}

You'll see that the connection info we provided in the intro (database name: `nyc`, username: `groot`, and password: `password`) is used in the statement above.

You should see lines of output like this in the terminal:

```sh
Expand All @@ -23,6 +25,6 @@ time="2020-07-02T14:06:47Z" level=info msg="HEAD /" method=HEAD url=/
time="2020-07-02T14:06:50Z" level=info msg="GET /" method=GET url=/
```

Now, if you look at the pg_tileserv tab again, you'll see the default UI and all of the nyc data being delivered as vector tiles (under ```Table Layers```).
Now, if you look at the pg_tileserv tab again, you'll see the default UI as well as all of the NYC data being delivered as vector tiles (under ```Table Layers```).

Next, we'll go over the default UI and then show you how you can add a simple user defined function and have it available via pg_tileserv.
Next, we'll go over the default UI and then show you how to add a user-defined function and have it available via pg_tileserv.
4 changes: 2 additions & 2 deletions postgis/pg_tileserv/02-pg_tileserv-ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ The service metadata provides basic information in JSON format to make it discov

## Table Layers

Table layers will list all of the tables that it has access to that contain a valid geometry column (```geom```). If a table is missing from this view that you were expecting to see, you can try the following troubleshooting steps:
Table Layers will list all tables that it has access to that contain a valid geometry column (```geom```). If a table is missing from this view that you were expecting to see, you can try the following troubleshooting steps:

1. Verify user roles/permissions for the service account.
2. Verify the table has a geometry column and the geometry is valid.

## Function Layers

Functions is where you will find any user-defined functions made available to pg_tileserv. Note that we haven't added any functions yet, so this section should be empty. We'll go into user-defined functions in more detail on the next page.
Function Layers is where you will find any user-defined functions made available to pg_tileserv. Note that we haven't added any functions yet, so this section should be empty. We'll go into user-defined functions in more detail on the next page.
23 changes: 11 additions & 12 deletions postgis/pg_tileserv/03-user_defined_functions.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@
>**WAIT!** Before you execute the code block below, make sure you've navigated back to ```Terminal 2```.
## Create a user-defined function

For this part of the exercise, we'll be using the functions from Paul Ramsey's blog post on [Serving Tiles with Dynamic Geometry](https://info.crunchydata.com/blog/tile-serving-with-dynamic-geometry). This post creates four internal funcitons first and then pulls them all together in one public facing function that can be exposed through pg_tileserv. This is also a good example of showing how not everything will be exposed if managed properly. At the end, you'll only see one function exposed through pg_tileserv.
All of the commands on this page should be run within **Terminal 2**.

To create a user-defined function, first we must log into the running database.

>**WAIT!** Before you execute the code block below, make sure you've navigated back to ```Terminal 2```.
```PGPASSWORD="password" psql -h localhost -U groot nyc```{{execute}}

## Create a user-defined function

For this part of the exercise, we'll use a couple of the functions from Paul Ramsey's blog post on [Serving Tiles with Dynamic Geometry](https://info.crunchydata.com/blog/tile-serving-with-dynamic-geometry). We create four internal functions first and then pull them all together in one public-facing function that can be exposed through pg_tileserv.

Next, we'll create a function that makes hexagons.
First we need to create the hexagons.

```
CREATE OR REPLACE
Expand Down Expand Up @@ -39,7 +40,7 @@ STRICT
PARALLEL SAFE;
```{{execute}}
Then we'll fill tiles with those Hexagons.
Then we'll fill tiles with those hexagons.
```
CREATE OR REPLACE
Expand Down Expand Up @@ -69,8 +70,7 @@ STRICT
PARALLEL SAFE;
```{{execute}}
Now we need to create the ```ST_TileEnvelope``` Function (we have to create it here since the version of PostGIS we're using in this container is Postgis 2.4. This function is included in Postgis 3.0+)
Now we need to create the ```ST_TileEnvelope``` function. While this function is actually included in PostGIS 3.0+, we have to create it here since the version of PostGIS in this container is PostGIS 2.4.
```
CREATE OR REPLACE
Expand Down Expand Up @@ -129,7 +129,7 @@ STRICT
PARALLEL SAFE;
```{{execute}}
And finally we can pull them all together in a function that allows us to have dynamic hexagons as vector tiles.
Finally, we can pull them all together in a function that allows us to have dynamic hexagons as vector tiles.
```
CREATE OR REPLACE
Expand Down Expand Up @@ -163,7 +163,6 @@ PARALLEL SAFE;
COMMENT ON FUNCTION public.hexagons IS 'Hex coverage dynamically generated. Step parameter determines how approximately many hexes (2^step) to generate per tile.';
```{{execute}}
Now, go back to the pg_tileserv tab and you should now see the new dynamic hexagon tile function. (You may need to hit the refresh symbol in the pg_tileserv tab.) If you click on the ```preview``` link, you'll see the hexagons getting tiled in. And you can change the number int he top left corner of the preview to change the size of the hexagons.
Now, go back to the pg_tileserv tab and you should now see the new `public.hexagons` function. (You may need to hit the refresh symbol in the pg_tileserv tab.) Despite having created a few intermediary functions, we only see the final function since it has the form `function(z integer, x integer, y integer, ...)` that returns an MVT `bytea`, so pg_tileserv knows to expose it as a function layer.
Now that you have these tiles, you could use them to do real-time filtering and analysis of data in your database. That is a more advanced use case that goes beyond the scope of this exercise.
8 changes: 6 additions & 2 deletions postgis/pg_tileserv/finish.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
You've completed this exercise. Seemed short right? That's because it is. This exercise is meant to show you how easily and quickly you can add pg_tileserv to your exisitng PostGIS implementation to service enable your spatial data.
This scenario was meant to show you how easily and quickly you can add pg_tileserv to your exisitng PostGIS implementation to service enable your spatial data.

From here you can now add these vector tiles as layers to your web-map. Common implementations are OpenLayers or Leaflet. That get's into topics that are beyond the scope of this exercise. You can also add functions to your database to do more complex geospatial analysis in the database and have them exposed as vector tiles as we also showed in this scenario. We encourage you to check out our other PostGIS exercises for further information on the different type of analysis and functions you can create.
From here you can now add these vector tiles as layers to your web map. Common implementations use [OpenLayers](https://openlayers.org/) or [Leaflet](https://leafletjs.com/) (a topic beyond the scope of this scenario).

You also saw in this scenario that you can also add functions to your database to do more complex geospatial analysis in the database and have them exposed as vector tiles. We encourage you to check out our [PostGIS exercises](https://learn.crunchydata.com/postgis) for further information on the different types of analysis and functions you can create.

Don't forget to also check out the [official pg_tileserv documentation](https://access.crunchydata.com/documentation/pg_tileserv/latest/).
8 changes: 4 additions & 4 deletions postgis/pg_tileserv/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
"title": "pg_tileserv",
"description": "Service enabling your spatial data with pg_tileserv.",
"difficulty": "beginner",
"time": "15 minutes",
"time": "10 minutes",
"details": {
"steps": [
{"title": "Vector Tiles", "text": "01-pg_tileserv.md"},
{"title": "pg_tileserv", "text": "02-pg_tileserv-ui.md"},
{"title": "user defined functions", "text": "03-user_defined_functions.md"}
{"title": "Vector Tiles and pg_tileserv", "text": "01-pg_tileserv.md"},
{"title": "The pg_tileserv UI", "text": "02-pg_tileserv-ui.md"},
{"title": "Adding User-defined Functions", "text": "03-user_defined_functions.md"}
],
"intro": {
"courseData": "env-init.sh",
Expand Down
13 changes: 8 additions & 5 deletions postgis/pg_tileserv/intro.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,20 @@
# Introduction to Vector Tiles and pg_tileserv

This scenario gives you an introduction to vector tiles and pg_tileserv.
This scenario gives you a hands-on introduction to vector tiles and [pg_tileserv](https://access.crunchydata.com/documentation/pg_tileserv/latest/).

Vector tiles are a bandwidth efficient method of transferring spatial data over the web for display in webmaps. For a brief history of webmaps and vector tiles, watch [Paul Ramsey's presentation at PostGIS Day 2019](https://youtu.be/t8eVmNwqh7M "PostGIS Day 2019 Vector Tiles").
Vector tiles are a bandwidth-efficient method of transferring spatial data over the web for display in web maps. For a brief history of web maps and vector tiles, watch [Paul Ramsey's presentation at PostGIS Day 2019](https://youtu.be/t8eVmNwqh7M "PostGIS Day 2019 Vector Tiles").

With the release of PostGIS 2.4, PostGIS introduced the ability to generate vector tiles directly from the database. This provided developers with the ability to have constantly up-to-date vector tiles in their webmap. However, it required the developers to write their own API to leverage this functionality. Pg_tileserv was created to make it easy to service enable your spatial data and integrate it into your web application.
With the release of PostGIS 2.4, [PostGIS](https://postgis.net/) introduced the ability to generate vector tiles directly from the database. This provided developers with the ability to have constantly up-to-date vector tiles in their web maps. However, it also required developers to write their own API to leverage this functionality. Pg_tileserv was created to make it easy to service enable your spatial data and integrate it into your web application.

To use pg_tileserv, you need to have a PostGIS database with spatial data loaded in it. The database has already been started and the spatial data has already been loaded. This scenario will use data from New York City (NYC). This exercise shows how to connect pg_tileserv to your database and shows the resulting vector tiles. We also show an example of using user defined function through pg_tileserv. If you would like to learn more about creating funcitons, please review some of our other exercies. Data from this scenario is used in our other exercises as well, but the environements don't persist between scenarios.
To use pg_tileserv, you need to have a PostGIS database with spatial data loaded in it. The database has already been started and the spatial data has already been loaded. This scenario will use data from New York City (NYC).

We have already logged you into the PostgreSQL command line but, if you get disconnected here are the details on the database we are connecting to:
This exercise demonstrates how to connect pg_tileserv to your database and shows the resulting vector tiles. We also provide an example of how pg_tileserv works with user-defined functions. If you would like to learn more about creating funcitons, please review our [Basics on Writing Functions](https://learn.crunchydata.com/postgresql-devel/courses/beyond-basics/basicfunctions) scenario. Data from this scenario is used in our other exercises as well, but the environments don't persist between scenarios.

Here are the details on the database we are connecting to:

1. Username: groot
2. Password: password (same password for the postgres user as well)
3. A database named: nyc

And with that, let's dig in.

0 comments on commit 19d7cbd

Please sign in to comment.