Move doc from wiki to repo, closes #85

doc/CDB_ColumnNames.md

@@ -0,0 +1,14 @@
+Retrieve all column names in a particular table
+
+#### Using the function
+
+```sql
+SELECT CDB_ColumnNames('table_name')
+--- Returns a set of rows with column names
+```
+
+#### Arguements
+
+CDB_ColumnNames(table_name)
+
+* **table_name** text

doc/CDB_ColumnType.md

@@ -0,0 +1,15 @@
+Returns a column type for any column in a table
+
+#### Using the function
+
+```sql
+SELECT CDB_ColumnType('column_name','table_name')
+--- Returns a set of rows with column types
+```
+
+#### Arguements
+
+CDB_ColumnType(column_name, table_name)
+
+* **column_name** text
+* **table_name** text

doc/CDB_HeadsTailsBins.md

@@ -0,0 +1,21 @@
+Find the breaks for N categories in a numerical column based on the [Heads/Tails optimization](http://arxiv.org/pdf/1209.2801v1.pdf). Below, Heads/Tails used to color based on the area of the polygons.
+
+![headtails](https://f.cloud.github.com/assets/370259/140655/6eebb918-7228-11e2-89fa-149745f25d34.png)
+
+#### Using the function
+
+We can determine the 7 most optimal breaks in a column of numerical data as follows, 
+
+```sql
+SELECT CDB_HeadsTailsBins(array_agg(numeric_column), 7) FROM table_name
+-- Results in an ordered array like, {7824,23492,52696,233857,666089,1001709,1638094}
+-- Each break happens up to, and equal, to a number: 
+-- (bin1 is less than or equal to 7824, bin2 is less than or equal to 23492, etc.)
+```
+
+#### Arguements
+
+CDB_HeadsTailsBins(in_array, breaks)
+
+* **in_array** numeric[]. A NUMERIC array of values.
+* **breaks** int. The number of categories you want to create

doc/CDB_HexagonGrid.md

@@ -0,0 +1,43 @@
+Fill given extent with an hexagonal coverage
+
+#### Using the function
+
+Create a hexagonal grid from a polygon geometry. For example, take the geometry
+
+```sql
+  ST_SetSRID(
+    ST_Envelope(
+      ST_Collect(
+        ST_MakePoint(10000000,-10000000),
+        ST_MakePoint(-10000000,10000000)
+      )
+     ),
+     3857)
+```
+
+We can create a grid as follows, 
+
+```sql
+SELECT CDB_HexagonGrid(
+  ST_SetSRID(
+    ST_Envelope(
+      ST_Collect(
+        ST_MakePoint(10000000,-10000000),
+        ST_MakePoint(-10000000,10000000)
+      )
+     ),
+     3857),
+   1000000) the_geom_webmercator
+```
+
+Which will look something like this,
+
+![grid tile](http://i.imgur.com/4rZXGMb.png)
+
+#### Arguments
+
+CDB_HexagonGrid(ext, side, origin)
+
+* **ext** geometry. Extent to fill. Only hexagons with center point falling inside the extent (or at the lower or leftmost edge) will be emitted. The returned hexagons will have the same SRID as this extent.
+* **side** float. Side measure for the hexagon. Maximum diameter will be 2 * side. Measure is in the same projection as **ext**
+* **origin** OPTIONAL geometry. Optional origin to allow for exact tiling. If omitted the origin will be 0,0. The parameter is checked for having the same SRID as the extent.

doc/CDB_JenksBins.md

@@ -0,0 +1,23 @@
+Find the breaks for N categories in a numerical column based on the [Jenks optimization](http://en.wikipedia.org/wiki/Jenks_natural_breaks_optimization). Below, Jenks used to color based on the area of the polygons.
+
+![Jenks](https://f.cloud.github.com/assets/370259/140093/b64a9382-7210-11e2-81a4-c65cce3c885e.png)
+
+#### Using the function
+
+We can determine the 7 most optimal breaks in a column of numerical data as follows, 
+
+```sql
+SELECT CDB_JenksBins(array_agg(numeric_column), 7) FROM table_name
+-- Results in an ordered array like, {0,73,2568,9408,29411,768230,1638094}
+-- Each break happens up to, and equal, to a number: 
+-- (bin1 is less than or equal to 0, bin2 is less than or equal to 73, etc.)
+```
+
+#### Arguments
+
+CDB_JenksBins(in_array, breaks, invert)
+
+* **in_array** numeric[]. A NUMERIC array of values.
+* **breaks** int. The number of categories you want to create
+* **iterations** OPTIONAL int. The number of iterations used for calculating breaks.
+* **invert** OPTIONAL boolean. Flips whether you receive top down breaks or bottom up breaks. Default is top down (so, <=). Bottom up would give you values that define the lower-end start of a bin (so >=).

doc/CDB_MakeHexagon.md

@@ -0,0 +1,21 @@
+Return an Hexagon with given center and side (or maximal radius)
+
+#### Using the function
+
+Running the following SQL
+
+```sql
+SELECT CDB_MakeHexagon(ST_MakePoint(0,0),10000000)
+```
+
+Would give you back a single hexagon geometry, 
+
+![hexagon](http://i.imgur.com/6jeGStb.png)
+
+
+#### Arguements
+
+CDB_MakeHexagon(center, radius)
+
+* **center** geometry
+* **radius** float. Radius of hexagon measured in same projection as **center**

doc/CDB_QuantileBins.md

@@ -0,0 +1,21 @@
+Find the breaks for N categories in a numerical column based on the [Quantile bins]. Below, the quantile method is used to determine color based on the area of the polygons.
+
+![qunatile](https://f.cloud.github.com/assets/370259/140714/932ed0e6-722b-11e2-9807-ffbd0fddb9ac.png)
+
+#### Using the function
+
+We can determine the 7 most optimal breaks in a column of numerical data as follows, 
+
+```sql
+SELECT CDB_QuantileBins(array_agg(numeric_column), 7) FROM table_name
+-- Results in an ordered array like, {80,2281,7162,17652,39730,91077,1638094}
+-- Each break happens up to, and equal, to a number: 
+-- (bin1 is less than or equal to 80, bin2 is less than or equal to 2281, etc.)
+```
+
+#### Arguements
+
+CDB_QuantileBins(in_array, breaks)
+
+* **in_array** numeric[]. A NUMERIC array of values.
+* **breaks** int. The number of categories you want to create

doc/CDB_RectangleGrid.md

@@ -0,0 +1,46 @@
+Fill given extent with a rectangular coverage
+
+#### Using the function
+
+Create a rectangular grid from a polygon geometry. For example, take the geometry
+
+```sql
+  ST_SetSRID(
+    ST_Envelope(
+      ST_Collect(
+        ST_MakePoint(10000000,-10000000),
+        ST_MakePoint(-10000000,10000000)
+      )
+     ),
+     3857)
+```
+
+We can create a grid as follows, 
+
+```sql
+SELECT CDB_RectangleGrid(
+  ST_SetSRID(
+    ST_Envelope(
+      ST_Collect(
+        ST_MakePoint(10000000,-10000000),
+        ST_MakePoint(-10000000,10000000)
+      )
+     ),
+     3857),
+   1000000,
+   1000000
+) the_geom_webmercator
+```
+
+Which will look something like this,
+
+![rect grid](http://i.imgur.com/HuhOJRs.png)
+
+#### Arguements
+
+CDB_RectangleGrid(ext, width, height, origin)
+
+* **ext** geometry. Extent to fill. Only rectangles with center point falling inside the extent (or at the lower or leftmost edge) will be emitted. The returned hexagons will have the same SRID as this extent.
+* **width** float. Width of each rectangle. Measure is in the same projection as **ext**
+* **height** float. Height of each rectangle. Measure is in the same projection as **ext**
+* **origin** OPTIONAL geometry. Optional origin to allow for exact tiling. If omitted the origin will be 0,0. The parameter is checked for having the same SRID as the extent.

doc/CDB_SetUserQuotaInBytes.md

@@ -0,0 +1,11 @@
+Sets user quota in bytes (superuser only)
+
+#### Using the function
+
+```sql
+SELECT CDB_SetUserQuotaInBytes(10485760);
+--- Returns the previously set quota.
+--- Use 0 to disable quota.
+```
+
+REF: https://github.com/CartoDB/cartodb-postgresql/blob/master/scripts-available/CDB_Quota.sql

doc/CDB_TransformToWebmercator.md

@@ -0,0 +1,44 @@
+Function to "safely" transform to webmercator. This function is most useful for rendering custom geometries using the CartoDB tiler. Often, transforming a projection like WGS84 can cause issues with extents beyond what are actually valid in webmercator, this attempts to fix those issues.
+
+#### Using the function
+
+Using a box that is nearly the full globe,
+
+```sql
+ST_SetSRID(
+  ST_Envelope(
+    ST_Collect(
+      ST_MakePoint(-180,60),
+      ST_MakePoint(180,-60)
+    )
+   ),
+   4326
+)
+```
+
+We can then convert it to a renderable webmercator geometry.
+
+```sql
+SELECT CDB_TransformToWebmercator(
+ ST_SetSRID(
+  ST_Envelope(
+    ST_Collect(
+      ST_MakePoint(-10,60),
+      ST_MakePoint(300,-60)
+    )
+   ),
+   4326
+ )
+)
+```
+
+Would give you back a single valid rectangle in webmercator. Since a longitude of 300 would convert to an unallowed webmercator coordinate, it gets clipped first. Valid extent is WGS84 (-180, -89, 180, 89)
+
+![valid geom](http://i.imgur.com/EFdXiqt.png)
+
+
+#### Arguements
+
+CDB_TransformToWebmercator(geom)
+
+* **geom** geometry

doc/CDB_UserTables.md

@@ -0,0 +1,11 @@
+List the name of available tables (only the usable ones)
+
+#### Using the function
+
+```sql
+--- Returns a row for each table having given permission with the table name
+--- Currently accepted permissions are: 'public', 'private' or 'all'
+SELECT CDB_UserTables(perms)
+```
+
+REF: https://github.com/CartoDB/cartodb-postgresql/blob/master/scripts-available/CDB_UserTables.sql

doc/CDB_XYZ_Extent.md

@@ -0,0 +1,22 @@
+Determine the spatial extent of a tile based on the tile's XYZ coordinate.
+
+#### Using the function
+
+Take a common tile with coordinates x=3, y=2, z=2,
+
+![2/3/2](https://viz2.cartodb.com/tiles/quantile_breaks/2/3/2.png)
+
+To determine its extent you would run,
+
+```sql
+SELECT CDB_XYZ_Extent(3,2,2)
+--- Returns a WKB polygon in Webmercator (SRID 3857)
+```
+
+#### Arguements
+
+CDB_XYZ_Extent(x,y,z)
+
+* **x** integer
+* **y** integer
+* **z** integer

doc/CDB_XYZ_Resolution.md

@@ -0,0 +1,20 @@
+Return pixel resolution of tiles at a given zoom level
+
+#### Using the function
+
+Take a common tile with zoom, z=2,
+
+![2/3/2](https://viz2.cartodb.com/tiles/quantile_breaks/2/3/2.png)
+
+To determine the resolution of these pixels,
+
+```sql
+SELECT CDB_XYZ_Resolution(2)
+--- Returns a float, 39135.7587890625
+```
+
+#### Arguements
+
+CDB_XYZ_Resolution(z)
+
+* **z** integer

doc/CartoDB-PLpgSQL.md

@@ -0,0 +1,38 @@
+INTRODUCTION
+============
+
+CartoDB uses a number of custom [PLpgSQL](http://www.postgresql.org/docs/8.3/static/plpgsql.html) functions to perform a few magical things. Those functions are accessible to users on CartoDB as well, so we would like to document what they are and what they do here.
+
+## Spatial functions
+
+[CDB_HexagonGrid](CDB_HexagonGrid) - create hexagonal grid from extent and size
+
+[CDB_MakeHexagon](CDB_MakeHexagon) - make a hexagon with given center and side
+
+[CDB_RectangleGrid](CDB_RectangleGrid) - fill given extent with a rectangular coverage
+
+##### Tile based
+
+[CDB_XYZ_Extent](CDB_XYZ_Extent) - Find the extent of a tile by XYZ
+
+[CDB_XYZ_Resolution](CDB_XYZ_Resolution) - Find the pixel resolution of tiles
+
+[CDB_TransformToWebmercator](CDB_TransformToWebmercator) - Convert a geometry to valid webmercator
+
+## Statistical functions
+
+[CDB_JenksBins](CDB_JenksBins) - Find breaks in an array of numbers using Jenks method
+
+[CDB_HeadsTailsBins](CDB_HeadsTailsBins) - Find breaks in an array of numbers using Heads/Tails method
+
+[CDB_QuantileBins](CDB_QuantileBins) - Find quantile breaks in an array of numbers
+
+## System functions
+
+[CDB_UserTables](CDB_UserTables) - Get a list of all tables in your account
+
+[[CDB_SetUserQuotaInBytes]] - Set maximum user quota in bytes
+
+column names - now returned in JSON response
+
+column types - now returned in JSON response

doc/CartoDB-user-table.md

@@ -0,0 +1,29 @@
+A "cartodb" user table is a table with a well-known set of fields and a well-known set of triggers attached on. 
+
+The fields are:
+
+ - `cartodb_id`, a numerical primary key of serial type
+ - `created_at`, timestamp with timezone not null default now()
+ - `updated_at`, timestamp with timezone not null default now()
+ - `the_geom`, geometry, GiST indexed, constrained (see below)
+ - `the_geom_webmercator`, geometry, GiST indexed, constrained (see below)
+
+The values of "the_geom" and "the_geom_webmercator" must match these constraints:
+
+ - Only POINT, MULTILINE, MULTIPOLYGON types ? Maybe UNCONSTRAINED
+ - Only 2 dimensions ? Maybe UNCONSTRAINED
+ - SRID=4326 for the_geom and SRID=3857 for the_geom_webmercator
+
+The triggers are:
+
+ - `track_updates` after modifying statement updates cdb_tablemetadata
+ - `test_quota` before changing statement to forbid if overquota
+ - `test_quota_per_row` before changing row to forbod if overquota (checked on a probabilistic basis)
+ - `update_the_geom_webmercator` before insert or update row to maintain the_geom_webmercator
+ - `update_updated_at_trigger` before update row to maintain updated_at
+
+Some conversions will be attempted to perform upon cartodbfication when certain fields appear:
+
+ - `cartodb_id`: If found type TEXT will be attempted to cast
+ - `created_at`: If found type TEXT will be attempted to cast
+ - `updated_at`: If found type TEXT will be attempted to cast

doc/README.md

@@ -0,0 +1,48 @@
+# Contents
+
+* [CartoDB-user-table](CartoDB-user-table.md)
+* [CartoDB-PLpgSQL](CartoDB-PLpgSQL.md)
+* [CDB_ColumnNames](CDB_ColumnNames.md)
+* [CDB_ColumnType](CDB_ColumnType.md)
+* [CDB_HeadsTailsBins](CDB_HeadsTailsBins.md)
+* [CDB_HexagonGrid](CDB_HexagonGrid.md)
+* [CDB_JenksBins](CDB_JenksBins.md)
+* [CDB_MakeHexagon](CDB_MakeHexagon.md)
+* [CDB_QuantileBins](CDB_QuantileBins.md)
+* [CDB_RectangleGrid](CDB_RectangleGrid.md)
+* [CDB_SetUserQuotaInBytes](CDB_SetUserQuotaInBytes.md)
+* [CDB_TransformToWebmercator](CDB_TransformToWebmercator.md)
+* [CDB_UserTables](CDB_UserTables.md)
+* [CDB_XYZ_Extent](CDB_XYZ_Extent.md)
+* [CDB_XYZ_Resolution](CDB_XYZ_Resolution.md)
+
+The CartoDB PostgreSQL extension is a module to load into each CartoDB user database to perform cartodb-specific security and functionality checks.
+
+# Checks
+
+No user other than the superuser should be allowed to change `statement_timeout` for the session (SET statement_timeout disallowed).
+
+User tables need to match certain structure criteria (See [[CartoDB-user-table]]) so the extension should provide a mean to enforce such structure everytime an attempt to change structure is encountered. 
+
+# Events
+
+The events we want some function to be called upon are:
+
+| event                  | arguments to handler function        | function duty                    | OK* |
+|------------------------|--------------------------------------|----------------------------------|-----|
+| SET variable           | name of variable                     | forbid changing some vars        |     |
+| RENAME table           | old and new name + oid of the table  | flush cache                      |     |
+| ADD/DROP/ALTER column  | oid of the table                     | flush cache, cartodbfy, upd meta |  Y  |
+| DISABLE/DROP trigger   | oid of table, name of trigger        | cartodbfy or forbid              |     |
+| DROP table             | oid of the table                     | flush cache and metadata         |  Y  |
+| CREATE table           | oid of the table                     | cartodby, upd metadata           |  Y  |
+| GRANT                  | oid of table, privilege, role        | flush cache, upd metadata        |
+| REVOKE                 | oid of table, privilege, role        | flush cache, upd metadata        |
+
+
+* event available by installing https://github.com/CartoDB/pg_schema_triggers
+
+At this stage we don't need more than this, but the number of events and the number of arguments passed to the handler function may expand in the future, so the extension should be written in a way to easily allow that.
+
+Some of the handler will need to act _after_ the statement is completed (CREATE TABLE, for example).
+