Document aggregation filters

Note that dimension filters remain undocumented
2018-03-21 17:21:05 +01:00 · 2018-03-21 17:21:05 +01:00 · ead6fa5f1f
commit ead6fa5f1f
parent 6ada8ba6a2
1 changed files with 77 additions and 0 deletions
--- a/docs/aggregation.md
+++ b/docs/aggregation.md
@ -185,3 +185,80 @@ This is the minimum number of (estimated) rows in the dataset (query results) fo
    ]
 }
 ```
+
+### `filters`
+
+Aggregated data can be filtered by imposing filtering conditions on the aggregated columns.
+
+Each condition is represented by one or more parameters:
+
+* `{ "equal": V }` selects an specific value of the aggregated column.
+* `{ "not_equal": V }` selects values different from the one specified.
+* `{ "in": [v1, v2, v3] }` selects any value from a list.
+* `{ "not_in": [v1, v2, v3] }` selects any value not in a list.
+* `{ "less_than": v }` selects values strictly less than the one given.
+* `{ "less_than_or_equal_to": v }` selects values less than or equal to the one given.
+* `{ "greater_than": v }` selects values strictly greater than the one given.
+* `{ "greater_than_or_equal_to": v }` selects values  greater than or equal to the one given.
+
+One of the *less* conditions can be combined with one of the *greater* conditions to select a range of values, for example:
+* `{ "greater_than": v1, "less_than": v2 }`
+* `{ "greater_than_or_equal_to": v1, "less_than": v2 }`
+* `{ "greater_than": v1, "less_than_or_equal_to": v2 }`
+* `{ "greater_than_or_equal_to": v1, "less_than_or_equal_to": v2 }`
+
+For a given column, multiple conditions can be passed in an array; the conditions will logically ORed (any of the conditions have to be verifid for the value to be selected):
+
+* `"myvalue": [ { "equal": 10 }, { "less_than": 0 }]` will select values of the column `myvalue` which are equal to 10 **or** less than 0.
+
+In addition, the filters applied to different columns are logically combined with AND (all the conditions have to be satisfied for an element to be selected); for example with the following `filters` parameter we'll select aggregated records which have a `total_value` > 100 **and** a category equal to "a".
+
+```json
+{
+    "total_value": { "greater_than": 100 },
+    "category":    { "equal": "a" }
+}
+```
+
+Note that the filtered columns have to be defined with the `columns` parameter, except for `_cdb_features_count`, which is always implicitly defined and can be filtered too.
+
+#### Example
+
+```json
+{
+    "version": "1.7.0",
+    "extent": [-20037508.5, -20037508.5, 20037508.5, 20037508.5],
+    "srid": 3857,
+    "maxzoom": 18,
+    "minzoom": 3,
+    "layers": [
+        {
+            "type": "mapnik",
+            "options": {
+                "sql": "select * from table",
+                "cartocss": "#table { marker-width: [total]; marker-fill: ramp(value, (red, green, blue), jenks); }",
+                "cartocss_version": "2.3.0",
+                "aggregation": {
+                    "placement": "centroid",
+                    "columns": {
+                        "total_value": {
+                            "aggregate_function": "sum",
+                            "aggregated_column": "value"
+                        },
+                        "category": {
+                            "aggregate_function": "mode",
+                            "aggregated_column": "category"
+                        }
+                    },
+                    "filters" : {
+                        "total_value": { "greater_than": 100 },
+                        "category":   { "equal": "a" }
+                    },
+                    "resolution": 2,
+                    "threshold": 500000
+                }
+            }
+        }
+    ]
+}
+```