Merge pull request #828 from metamx/fix-query-docs

Fix query docs

docs/content/SelectQuery.md

@@ -26,9 +26,9 @@ There are several main parts to a select query:
 |dataSource|A String defining the data source to query, very similar to a table in a relational database|yes|
 |intervals|A JSON Object representing ISO-8601 Intervals. This defines the time ranges to run the query over.|yes|
 |filter|See [Filters](Filters.html)|no|
-|dimensions|The list of dimensions to select. If left empty, all dimensions are returned.|no|
+|dimensions|A String array of dimensions to select. If left empty, all dimensions are returned.|no|
-|metrics|The list of metrics to select. If left empty, all metrics are returned.|no|
+|metrics|A String array of metrics to select. If left empty, all metrics are returned.|no|
-|pagingSpec|A JSON object indicating offsets into different scanned segments. Select query results will return a pagingSpec that can be reused for pagination.|yes|
+|pagingSpec|A JSON object indicating offsets into different scanned segments. Query results will return a `pagingIdentifiers` value that can be reused in the next query for pagination.|yes|
 |context|An additional JSON Object which can be used to specify certain flags.|no|
 
 The format of the result is:
@@ -140,4 +140,30 @@ The format of the result is:
 } ]
 ```
 
-The result returns a global pagingSpec that can be reused for the next select query. The offset will need to be increased by 1 on the client side.
+The `threshold` determines how many hits are returned, with each hit indexed by an offset.
+
+The results above include:
+
+```json 
+    "pagingIdentifiers" : {
+      "wikipedia_2012-12-29T00:00:00.000Z_2013-01-10T08:00:00.000Z_2013-01-10T08:13:47.830Z_v9" : 4
+    },
+```
+
+This can be used with the next query's pagingSpec:
+
+```json
+ {
+   "queryType": "select",
+   "dataSource": "wikipedia",
+   "dimensions":[],
+   "metrics":[],
+   "granularity": "all",
+   "intervals": [
+     "2013-01-01/2013-01-02"
+   ],
+   "pagingSpec":{"pagingIdentifiers": {"wikipedia_2012-12-29T00:00:00.000Z_2013-01-10T08:00:00.000Z_2013-01-10T08:13:47.830Z_v9" : 5}, "threshold":5}
+      
+ }
+
+Note that in the second query, an offset is specified and that it is 1 greater than the largest offset found in the initial results. To return the next "page", this offset must be incremented by 1 with each new query. When an empty results set is recieved, the very last page has been returned.

docs/content/TopNMetricSpec.md

@@ -11,7 +11,7 @@ The topN metric spec specifies how topN values should be sorted.
 The simplest metric specification is a String value indicating the metric to sort topN results by. They are included in a topN query with:
 
 ```json
-"metric": <metric_value_string>
+"metric": "<metric_name>"
 ```
 
 The metric field can also be given as a JSON object. The grammar for dimension values sorted by numeric value is shown below:
@@ -19,7 +19,7 @@ The metric field can also be given as a JSON object. The grammar for dimension v
 ```json
 "metric": {
     "type": "numeric",
-    "metric": "<metric_value>"
+    "metric": "<metric_name>"
 }
 ```
 

docs/content/TopNQuery.md

@@ -72,9 +72,9 @@ There are 10 parts to a topN query, but 7 of them are shared with [TimeseriesQue
 
 |property|description|required?|
 |--------|-----------|---------|
-|dimension|A JSON object defining the dimension that you want the top taken for. For more info, see [DimensionSpecs](DimensionSpecs.html)|yes|
+|dimension|A String or JSON object defining the dimension that you want the top taken for. For more info, see [DimensionSpecs](DimensionSpecs.html)|yes|
 |threshold|An integer defining the N in the topN (i.e. how many you want in the top list)|yes|
-|metric|A JSON object specifying the metric to sort by for the top list. For more info, see [TopNMetricSpec](TopNMetricSpec.html).|yes|
+|metric|A String or JSON object specifying the metric to sort by for the top list. For more info, see [TopNMetricSpec](TopNMetricSpec.html).|yes|
 
 Please note the context JSON object is also available for topN queries and should be used with the same caution as the timeseries case.
 The format of the results would look like so: