From 0cfb204c04e9ee2eda8b7bcd7ba3bd9fb5bbc1e3 Mon Sep 17 00:00:00 2001
From: Javier Goizueta <jgoizueta@gmail.com>
Date: Tue, 9 Jan 2018 14:49:33 +0100
Subject: [PATCH] Add MapConfig extension for aggregation

---
 docs/MapConfig-Aggregation-extension.md | 59 +++++++++++++++++++++++++
 1 file changed, 59 insertions(+)
 create mode 100644 docs/MapConfig-Aggregation-extension.md

diff --git a/docs/MapConfig-Aggregation-extension.md b/docs/MapConfig-Aggregation-extension.md
new file mode 100644
index 00000000..ffcd5144
--- /dev/null
+++ b/docs/MapConfig-Aggregation-extension.md
@@ -0,0 +1,59 @@
+# 1. Purpose
+
+This specification describes an extension for
+[MapConfig 1.7.0](https://github.com/CartoDB/Windshaft/blob/master/doc/MapConfig-1.7.0.md) version.
+
+
+# 2. Changes over specification
+
+This extension introduces a new layer options for aggregated data tile generation.
+
+## 2.1 Aggregation options
+
+The layer options attribute is extended with a new optional `aggregation` attribute.
+The value of this attribute can be `false` to explicitly disable aggregation for the layer.
+
+```javascript
+{
+    aggregation: {
+
+        // OPTIONAL
+        // string, defines the placement of aggregated geometries. Can be one of:
+        // * "point-sample", the default places geometries at a sample point (one of the aggregated geometries)
+        // * "point-grid" places geometries at the center of the aggregation grid cells
+        // * "centroid" places geometriea at the average position of the aggregated points
+        // See https://github.com/CartoDB/Windshaft-cartodb/blob/master/docs/... for more details
+        placement: "point-sample",
+
+        // OPTIONAL
+        // object, defines the columns of the aggregated datasets. Each property corresponds to a columns name and
+        // should contain an object with two properties: "aggregate_function" (one of "sum", "max", "min", "avg", "mode" or "count"),
+        // and "aggregated_column" (the name of a column of the original layer query or "*")
+        // A column defined as `"_cdb_features_count": {"aggregate_function": "count", aggregated_column: "*"}`
+        // is always generated in addition to the defined columns.
+        // The column names `cartodb_id`, `the_geom`, `the_geom_webmercator` and `_cdb_feature_count` cannot be used
+        // for aggregated columns, as they correspond to columns always present in the result.
+        columns: {
+            "aggregated_column_1": {
+                "aggregate_function": "sum",
+                "aggregated_column": "original_column_1"
+            }
+        },
+
+        // OPTIONAL
+        // Number, defines the cell-size of the spatial aggregation grid as a pixel resolution power of two (1/4, 1/2,... 2, 4, 16)
+        // to scale from 256x256 pixels; the default is 1 corresponding to 256x256 cells per tile.
+        resolution: 1,
+
+        // OPTIONAL
+        // Number, the minimum number of (estimated) rows in the dataset (query results) for aggregation to be applied.
+        threshold: 500000
+    }
+}
+```
+
+# History
+
+## 1.0.0
+
+ - Initial version