maps.params isn't documented

[EliRibble]

Seems like maps.params is something that has been referenced in previous issues but is not currently documented anywhere in the documentation on in the examples.

[EliRibble]

Looks like [[maps.params]] has a type property that must be one of config: bool,int,float,string, according to an error I just triggered on startup.

[EliRibble]

Okay, if documentation like this already exists somewhere, this will be quaint and useless, sorry. If not, hopefully it will help someone else who has a similar problem to mine not have to reproduce the searching I did.

Let's say you have a table that contains PostGIS data that you're serving through Tegola, but you want to filter it further within you're query. In my case, I have my data separated by organization, so each row in my table contains a non-NULL organization_id. I could filter this client-side, but that's really wasteful of bandwidth, since I never want to show data from organization 1 to clients of organization 2.

In order to do the filtering server-side I need to pass a parameter through to Tegola. I start by declaring the parameter in the config as follows:

[[maps]]
...
  [[maps.params]]
  name = "organization_id"
  token = "!PARAM!"
  type = "int"
  sql = "AND organization_id = ?"
  default_sql = "1"

[[providers]]
...
  [[providers.layers]]
  ...
  sql = "SELECT ... WHERE ... geometry && !BBOX! !PARAM!""

I've added ellipsis (...) to sections that are necessary, that are documented in other places. The key item here is to modify the providers.layers.sql parameter to include the token value somewhere so that Tegola can replace the token in the larger query. You also must indicate the type of the parameter and the substring that will be replaced in the query.

Once you've done all this you're ready to modify the client to include the new parameter in the URL. In my case I add ?organization_id=1 on the URL. This will get parsed by Tegola and passed through the SQL made to the database.

You can probable have lots of parameters, I haven't tested it myself.

[ARolek]

@EliRibble thanks for spinning up some issues as you have been onboarding to using tegola. I just poked around our documentaiton and you're right, this incredibly useful feature is not documented well at all. There's only a mention of it In the ST_AsMVT example here.

If you would like to send in some readme updates I would gladly accept them. This feature should be added to the Features overview!