From 1802947c3efe9f2f10b411ac8aa96498358854d0 Mon Sep 17 00:00:00 2001
From: Martin Davis <mtnclimb@gmail.com>
Date: Thu, 27 Feb 2020 11:25:33 -0800
Subject: [PATCH] Add doc feature collection text and examples

---
 hugo/content/usage/collections.md | 11 ++++
 hugo/content/usage/query_data.md  | 99 +++++++++++++++++++++++++++----
 2 files changed, 98 insertions(+), 12 deletions(-)

diff --git a/hugo/content/usage/collections.md b/hugo/content/usage/collections.md
index fd32835a..0733bc9b 100644
--- a/hugo/content/usage/collections.md
+++ b/hugo/content/usage/collections.md
@@ -42,6 +42,11 @@ The metadata includes:
 The path `/collections` returns a list of the feature collections
 available in the service as a JSON document.
 
+#### Example
+```
+http://localhost:9000/collections
+```
+
 Each listed feature collection provides a name, title, description and extent.
 A set of links provide the URLs for accessing:
 
@@ -49,6 +54,7 @@ A set of links provide the URLs for accessing:
 * `alt` - the feature collection metadata as an HTML view
 * `items` - the feature collection items
 
+
 ## Describe Feature Collection metadata
 
 The path `/collections/{coll-name}` returns a JSON object describing
@@ -56,6 +62,11 @@ the metadata for a feature collection.
 The `{coll-name}` is the schema-qualified name of the database table or view
 backing the feature collection.
 
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries
+```
+
 The response is a JSON document ontaining metadata about the collection, including:
 
 * The geometry column name
diff --git a/hugo/content/usage/query_data.md b/hugo/content/usage/query_data.md
index 7517d769..3e280e84 100644
--- a/hugo/content/usage/query_data.md
+++ b/hugo/content/usage/query_data.md
@@ -5,40 +5,115 @@ draft: false
 weight: 150
 ---
 
+Feature collections can be queried to provide sets of features,
+or to return a single feature.
+
 ## Query features
 
-`/collections/{collid}/items`
+The path `/collections/{collid}/items` is the basic query to return
+a set of features from a feature collection.
+
+The response is a GeoJSON feature collection containing the result.
+
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items
+```
+
+Additional query parameters can be appended to the basic query
+to provide control over what sets of features are returned.
 
-- response is GeoJSON for result dataset
+These are analagous to using SQL statement clauses to control
+the results of a query.
+In fact the service
+implements these using exactly that technique.
+This provides maximum performance since it allows
+the Postgres SQL engine to optimize the query execution plan.
 
 ### Limiting and paging results
 
-`limit=N`
+The query parameter `limit=N` can be added to the query to control
+the maximum number of features returned in a response document.
+There is also a server-defined maximum which cannot be exceeded.
+
+The query parameter `offset=N` specifies the offset in the
+actual query result at which the response feature set starts.
+
+Used together these two parameters allow paging through large result
+sets.
+
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items?limit=50&offset=200
+```
 
-`offset=N`
 
 ### Ordering results
 
-`orderBy=PROP`
+The result set can be ordered by any property it contains.
+This allows performing "greatest N" or "smallest N" queries.
 
-`orderBy=PROP:A`
+* `orderBy=PROP` orders results by `PROP` in ascending order
 
-`orderBy=PROP:D`
+The sort order can be specified by appending `:A` (ascending)
+or `:D` (descending) to the ordering property name.
+The default is ascending order.
+
+* `orderBy=PROP:A` orders results by `PROP` in ascending order
+* `orderBy=PROP:D` orders results by `PROP` in descending order
+
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items?orderBy=name
+```
 
 ### Filter by bbox
 
-`bbox=MINX,MINY,MAXX,MAXY`
+The query parameter `bbox=MINX,MINY,MAXX,MAXY`
+can be used
+to limit the features returned to those that intersect
+a specified bounding box.
+The bounding box is specified in geographic coordinates (longitude/latitude).
 
-- extent is in lon/lat (4326)
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items?bbox=10.4,43.3,26.4,47.7
+```
 
 ### Specify result properties
 
-`properties=PROP1,PROP2,PROP3...`
+The query parameter `properties=PROP1,PROP2,PROP3...`
+can be used to restrict the properties which are returned
+in the response.
+This allows reducing the response size of feature collections
+which have a large number of properties.
+
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items?properties=name,abbrev,pop_est
+```
 
 ## Query a single feature
 
-`/collections/{collid}/items/{fid}`
+The path `/collections/{collid}/items/{fid}`
+allows querying a single feature in a feature collection
+by specifying its ID.
+
+The response is a GeoJSON feature containing the result.
+
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items/23
+```
+
 
 ### Specify properties in result
 
-`properties=PROP1,PROP2,PROP3...`
+The query parameter `properties=PROP1,PROP2,PROP3...`
+can be used to restrict the properties which are returned
+in the response.
+
+#### Example
+```
+http://localhost:9000/collections/ne.admin_0_countries/items/23?properties=name,abbrev,pop_est
+```