sql

lib/sql/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
+```
+
+#### Arguments
+
+CDB_ColumnNames(table_name)
+
+* **table_name** text

lib/sql/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
+```
+
+#### Arguments
+
+CDB_ColumnType(column_name, table_name)
+
+* **column_name** text
+* **table_name** text

lib/sql/doc/CDB_EstimateRowCount.md

@@ -0,0 +1,25 @@
+Estimate the number of rows of a query.
+
+
+#### Using the function
+
+```sql
+SELECT CDB_EstimateRowCount($$
+  UPDATE addresses SET the_geom = cdb_geocode_street_point(addr, city, state, 'US');
+$$) AS row_count;
+```
+
+Result:
+
+```
+ row_count
+-----------
+         5
+(1 row)
+```
+
+#### Arguments
+
+CDB_EstimateRowCount(query)
+
+* **query** text: the SQL query to estimate the row count for.

lib/sql/doc/CDB_GreatCircle.md

@@ -0,0 +1,16 @@
+Based on Paul Ramsey's [blog post](http://blog.cartodb.com/jets-and-datelines/).
+#### Using the function
+
+Creates a great circle line.
+
+```sql
+SELECT CDB_GreatCircle(start_point, end_point) FROM table_name
+-- Results a line reprsenting the great circle between the two points
+```
+
+#### Arguments
+
+CDB_GreatCircle(start_point, end_point)
+
+* **start_point** ST_Point indicating the start of the line.
+* **end_point** ST_point indicating the end of the line.

lib/sql/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.)
+```
+
+#### Arguments
+
+CDB_HeadsTailsBins(in_array, breaks)
+
+* **in_array** numeric[]. A NUMERIC array of values.
+* **breaks** int. The number of categories you want to create

lib/sql/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.

lib/sql/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 >=).

lib/sql/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)
+
+
+#### Arguments
+
+CDB_MakeHexagon(center, radius)
+
+* **center** geometry
+* **radius** float. Radius of hexagon measured in same projection as **center**

lib/sql/doc/CDB_Overviews.md

@@ -0,0 +1,123 @@
+Overviews are tables that represent a *reduced* version of a dataset intended
+for efficient rendering at certain zoom levels while preserving the
+general visual appearance of the complete dataset.
+
+The *reduction* consists in havig a fewer number of records
+(while each overview record may represent an aggregation of multiple records)
+and/or simplified record geometries.
+
+Overviews are created through the `CDB_CreateOverviews` function.
+The statement timeout may need to be adjusted before using this function,
+as overview creation for large tables is a time-consuming operation.
+
+The `CDB_Overviews` function can be used determine what overview tables
+exist for a given dataset table and which zoom levels correspond to it.
+
+The `CDB_DropOverviews` function removes a dataset's existing overviews.
+
+To know if overview tables exist for some base table, and to obtain
+a list of which overview tables are approrpiate for which zoom levels,
+the `CDB_Overviews` functions can be used.
+
+The zoom level we're referring here to are those used
+by the tiler: http://wiki.openstreetmap.org/wiki/Zoom_levels
+
+### CDB_CreateOverviews
+
+Create overviews for vector dataset.
+
+#### Using the function
+
+The table for which overviews will be generated should be
+a Cartodbfied dataset with vector geometry.
+
+```sql
+SELECT CDB_CreateOverviews('table_name');
+--- Generates overview tables for the dataset
+```
+
+#### Arguments
+
+CDB_CreateOverviews(table_name, ref_z_strategy, reduction_strategy)
+
+* **table_name** regclass, table for which overviews will be generated
+* **ref_z_strategy** regproc, optional function that provides
+  the Z-scale strategy.
+  It returns the base Z level for the dataset.
+  It should have these arguments:
+  - **table_name** regclass, table to compute the reference Z scale for
+* **reduction_strategy** regproc, optional function that provides
+  the reduction strategy to generate an overview table from a table
+  for a smaller scale (higher Z number).
+  It returns the name of the generated table.
+  It should have these arguments:
+  - **base_table_name** regclass, base table to be reduced.
+  - **base_z** integer, base Z level assigned to the base table.
+  - **overview_z** integer, Z level for which to generate the overview.
+
+#### Tolerance / level of detail
+
+The level of detail to be representable by each overview layer can
+be specified as a tolerance in pixels (if different from the default of 1 pixel)
+with the function `CDB_CreateOverviewsWithToleranceInPixels`
+which has as a second additional argument the desired tolerance.
+
+This tolerance defines the maximum deviation in pixels of the overviews
+geometries with respect to the original geometries when overview tables
+are used for their intendend zoom level.
+
+### CDB_Overviews
+
+Obtain overview metadata for a given table (existing overviews).
+The returned relation will be empty if the table has no overviews.
+
+The function can be applied to a single table:
+
+```sql
+SELECT CDB_Overviews('table_name');
+--- Return existing overview Z levels and corresponding tables
+```
+
+Or to multiple tables passed as an array; this can be used
+to obtain the overviews that can be applied to a query by
+combining it with `CDB_QueryTablesText`:
+
+```sql
+SELECT CDB_Overviews(CDB_QueryTablesText('SELECT * FROM table1, table2'));
+--- Return existing overview Z levels and corresponding tables
+```
+
+The result of `CDB_Overviews` has three columns:
+
+| base_table | z | overview_table |
+| ---------- | - | -------------- |
+| table1     | 1 | table1_ov1     |
+| table1     | 2 | table1_ov2     |
+| table1     | 4 | table1_ov4     |
+| table2     | 1 | table1_ov1     |
+| table2     | 2 | table1_ov2     |
+
+#### Arguments
+
+CDB_Overviews(table_name)
+
+* **table_name** regclass, oid of table to obtain existing overviews for
+
+CDB_Overviews(table_names)
+
+* **table_names** regclass[], array of table oids
+
+
+### CDB_DropOverviews
+
+Remove the overviews of a table, if present.
+
+```sql
+SELECT CDB_DropOverviews('table_name');
+```
+
+#### Arguments
+
+CDB_Overviews(table_name)
+
+* **table_name** regclass, table for which to drop existing overviews.

lib/sql/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.)
+```
+
+#### Arguments
+
+CDB_QuantileBins(in_array, breaks)
+
+* **in_array** numeric[]. A NUMERIC array of values.
+* **breaks** int. The number of categories you want to create

lib/sql/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)
+
+#### Arguments
+
+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.

lib/sql/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

lib/sql/doc/CDB_SyncTable.md

@@ -0,0 +1,56 @@
+Synchronize two tables. This function will synchronize a *destination* table with a *source* table.
+The idea is that the *destination* is a replica of *source* and *source* has been subject to
+modifications that are to be applied to *destination*.
+
+This will be achieved by deleting the rows in the destination not present
+in the source, inserting rows of the source not in the destination and updating modified rows.
+If the destination table does not exist it will be created and all the rows of the source inserted into it.
+
+Both tables must have a consistent `cartodb_id` primary key column which will be used to match
+the source and destination rows.
+
+Note that both tables do not necessarily become identical after the synchronization, since additional columns
+may have been added to the destination; those columns will not be altered by the synchronization.
+
+In addition some source columns may be skipped by listing them in the optional last argument; such columns
+will not be updated in the destination, so if they are present in it their values won't be altered.
+
+
+#### Using the function
+
+Import some data using COPY FROM into a temporary table, then synchronize a table with the data and
+finally delete the temporary table. This could be used import and update some data periodically while
+allowing to add columns to the data that will be preserved across updates.
+
+```sql
+CREATE tmp_pois(cartodb_id int, name text, type text, longitude double precision, latitude double precision, rank int);
+COPY tmp_pois FROM '/tmp/pois.csv';
+SELECT CDB_SyncTable('tmp_pois', 'public', 'pois');
+DROP TABLE tmp_pois;
+```
+
+Now we could perform some changes to the `pois` to maintain our own ranking:
+
+```sql
+UPDATE pois SET rank = random()*4 + 1;
+```
+
+Then, if the source were updated at `/tmp/pois.csv` we could synchronize with it while preserving our `rank` values with:
+
+```sql
+CREATE tmp_pois(cartodb_id int, name text, type text, longitude double precision, latitude double precision, rank int);
+COPY tmp_pois FROM '/tmp/pois.csv';
+SELECT CDB_SyncTable('tmp_pois', 'public', 'pois', '{rank}');
+DROP TABLE tmp_pois;
+```
+
+#### Arguments
+
+```
+CDB_SyncTable(src_table, dst_schema, dst_table, skip_cols)
+```
+
+* **src_table** REGCLASS the source data for the synchronization
+* **dst_scgena** REGNAMESPACE the destination schema
+* **dst_table** NAME the destination table to be updated
+* **skip_cols** NAME[] an array of column names, empty by default, which will be skipped

lib/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)
+
+
+#### Arguments
+
+CDB_TransformToWebmercator(geom)
+
+* **geom** geometry

lib/sql/doc/CDB_UserTables.md

@@ -0,0 +1,15 @@
+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.
+--- It also returns tables from others users if you've permission to see them. For example, consider the following scenario:
+--- User X and User Y at account C.
+--- User X has a public table T.
+--- User Y will see table T. 
+--- 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

lib/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)
+```
+
+#### Arguments
+
+CDB_XYZ_Extent(x,y,z)
+
+* **x** integer
+* **y** integer
+* **z** integer

lib/sql/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
+```
+
+#### Arguments
+
+CDB_XYZ_Resolution(z)
+
+* **z** integer

lib/sql/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

lib/sql/doc/CartoDB-user-table.rst

@@ -0,0 +1,68 @@
+CartoDB User Table
+==================
+
+Introduction
+----------
+A CartoDB user table is a table with a well-known set of columns and a well-known set of triggers attached on.
+
+Columns
+----------
+The required columns of a CartoDB table are:
+
+-  ``cartodb_id``
+  - This column will be used as the primary key of the table and it has a sequence as default value
+  - Its values must be integer, non-zero, non-null and unique
+  -  B-Tree indexed
+-  ``the_geom``
+  - This column stores the main geometric features of a table
+  - The type of the column in the Postgres database is ``geometry(Geometry,4326)```
+  - GiST indexed
+  -  geometry, GiST indexed, constrained (see below)
+-  ``the_geom_webmercator``
+  - This column stores the geometries used for rendering purposes
+  - The type of the column in the Postgres database is ``geometry(Geometry,3857)``
+  - GiST indexed
+  - This column is automatically updated by the system when the ``the_geom`` column is updated or when there is an insertion of a new row into the table (See triggers below)
+
+The values of ``the_geom`` and ``the_geom_webmercator`` must be two-dimensional Points, MultiLineStrings or MultiPolygons. Different geometric types in a CartoDB table are not supported.
+
+Described table example
+^^^^^^^^^^
+::
+
+        Column        |          Type           |                       Modifiers                        
+  ----------------------+-------------------------+--------------------------------------------------------
+   cartodb_id           | bigint                  | not null default nextval('t_cartodb_id_seq'::regclass)
+   the_geom             | geometry(Geometry,4326) | 
+   the_geom_webmercator | geometry(Geometry,3857) | 
+  Indexes:
+      "table_name_pkey" PRIMARY KEY, btree (cartodb_id)
+      "table_name_the_geom_idx" gist (the_geom)
+      "table_name_the_geom_webmercator_idx" gist (the_geom_webmercator)
+
+Triggers
+----------
+The triggers generated in each CartoDB table are:
+
+-  ``track_updates`` after modifying statement updates ``cdb_tablemetadata``
+-  ``test_quota`` before changing statement to forbid if overquota
+-  ``test_quota_per_row`` before insert ot update row to forbid if overquota (checked on a probabilistic basis)
+-  ``update_the_geom_webmercator`` before insert or update row to maintain the ``the_geom_webmercator`` updated with the contents in ``the_geom``
+
+Described triggers example
+^^^^^^^^^^
+::
+
+  test_quota BEFORE INSERT OR UPDATE ON t FOR EACH STATEMENT EXECUTE PROCEDURE cdb_checkquota('0.1', '-1', 'public')
+  test_quota_per_row BEFORE INSERT OR UPDATE ON t FOR EACH ROW EXECUTE PROCEDURE cdb_checkquota('0.001', '-1', 'public')
+  track_updates AFTER INSERT OR DELETE OR UPDATE OR TRUNCATE ON t FOR EACH STATEMENT EXECUTE PROCEDURE cdb_tablemetadata_trigger()
+  update_the_geom_webmercator_trigger BEFORE INSERT OR UPDATE OF the_geom ON t FOR EACH ROW EXECUTE PROCEDURE _cdb_update_the_geom_webmercator()
+
+
+Further details
+----------
+
+Some conversions will be attempted to perform upon cartodbfication when certain fields appear:
+
+-  ``cartodb_id``: If found type TEXT will be attempted to cast to integer. If not casteable, an eror will be raised.
+-  ``the_geom``: If found type TEXT will be attempted to cast to geometry(Geometry,4326).

lib/sql/doc/README.md

@@ -0,0 +1,23 @@
+# 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
+
+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. 

lib/sql/doc/cartodbfy-requirements.rst

@@ -0,0 +1,63 @@
+CartoDBfy Requirements
+======================
+
+Introduction
+------------
+
+This document aims at describing what the CartoDBfication is and what its formal requirements are, with the following goals in mind:
+
+- Clarify what are the expectations of the "cartodbfycation process".
+- Define an important part of what should be a stable, public API
+- Allow for better testing, which should in turn...
+- ...ease modifications and increase quality of the code
+
+
+What is the CartoDBfycation
+---------------------------
+
+The CartoDBfycation is the process of converting an arbitrary postgres table into a valid CartoDB table, and register it in the system so that it can be used in the CartoDB editor and platform to generate maps and analysis.
+
+It is performed by running the function ``CDB_CartodbfyTable(reloid REGCLASS)`` over a target table.
+
+Valid CartoDB tables
+--------------------
+
+A valid CartoDB table shall meet the following conditions:
+
+- Have a ``cartodb_id`` column with integer, unique, non-zero and non-null values as primary key with a sequence as default value
+- Have a ``the_geom`` column of type ``Geometry`` with SRID 4326
+- Have a ``the_geom_webmercator`` column of type ``Geometry`` with SRID 3857
+- The columns ``the_geom`` and ``the_geom_webmercator`` shall be in sync (task of the ``update_the_geom_webmercator`` trigger)
+
+Additionally, a CartoDB table can contain other columns.
+
+See the `CartoDB User Table documentation`_
+
+.. _CartoDB User Table documentation: https://github.com/CartoDB/cartodb-postgresql/blob/master/doc/CartoDB-user-table.rst 
+for further information.
+
+High level requirements
+-----------------------
+
+Here is a list of high level requirments for the public function ``CDB_CartodbfyTable()``:
+
+- A call to the function shall modify/rewrite the table and produce a valid CartoDB table with the same name.
+- A call to the function shall cause the registration of the table into the platform.
+- It shall be idempotent, meaning that successive calls to the function shall not produce any visible effect in the system.
+- If there's a column containing a geometry, it shall be used to generate ``the_geom`` and the ``the_geom_webmercator`` columns.
+- Exporting and re-importing the same table in CartoDB shall produce equivalent tables, with the same features associated to the same ``cartodb_id``'s.
+
+
+Note that there should be only one geometry per row in the source table. If there's more than one, then which one is used for ``the_geom`` and ``the_geom_webmercator`` fields is not determined.
+
+
+Low-level requirements
+----------------------
+
+- If the original table contains a valid (integer, unique, non-zero and not null) ``cartodb_id`` column, it shall be used
+- If the original table contains a ``the_geom`` column or a ``the_geom_webmercator`` geometric column in the expected projection (EPSG 4326 and EPSG 3857, respectively) they shall be used.
+- A modification of a cartodbfy'ed table shall insert or update a row in ``CDB_TableMetadata``
+- A cartodbfy'ed table shall have a ``btree`` index on ``cartodb_id``
+- A cartodbfy'ed table shall have ``gist`` indices on ``the_geom`` and ``the_geom_webmercator``
+- Cartodbfy shall deal with text columns for imports, regarding CartoDB columns (``cartodb_id``, ``the_geom``, ``the_geom_webmercator``)
+