From fc0e883c202fedc6a29e6ea31ced446f45ae822c Mon Sep 17 00:00:00 2001 From: Rafa de la Torre Date: Tue, 15 Sep 2015 11:51:27 +0200 Subject: [PATCH 1/3] First version of the cartodbfy requirements --- doc/cartodbfy-requirements.rst | 59 ++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 doc/cartodbfy-requirements.rst diff --git a/doc/cartodbfy-requirements.rst b/doc/cartodbfy-requirements.rst new file mode 100644 index 0000000..4492a23 --- /dev/null +++ b/doc/cartodbfy-requirements.rst @@ -0,0 +1,59 @@ +Introduction +============ + +This document aims at describing what cartodbfy 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. + + + +Valid CartoDB tables +==================== + +A valid CartoDB table shall meet the following conditions: + +- Have a ``cartodb_id`` column as primary key with a sequence +- 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 + +Additionally, a CartoDB table can contain other columns. + + + +High level requirements +======================= + +Here is a list of high level requirments for the public function ``CDB_CartodbfyTable()``: + +- A call to ``CDB_CartodbfyTable()`` shall modify/rewrite the table and produce a valid CartoDB table with the same name. +- A call to ``CDB_CartodbfyTable()`` shall cause the registration of the table into the platform +- It shall be idempotent, meaning that successive calls to ``CDB_CartodbfyTable()`` 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 feature 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 ``cartodb_id`` column, it shall be used +- If the original table contains a valid ``the_geom`` or ``the_geom_webmercator`` it 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 + + From 333a40819958f71ab4650a3c279a2cd1f35be850 Mon Sep 17 00:00:00 2001 From: Carla Iriberri Date: Fri, 20 Nov 2015 17:15:37 +0100 Subject: [PATCH 2/3] Add Paul and Rafa feedback --- doc/cartodbfy-requirements.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/cartodbfy-requirements.rst b/doc/cartodbfy-requirements.rst index 4492a23..e3fa3a5 100644 --- a/doc/cartodbfy-requirements.rst +++ b/doc/cartodbfy-requirements.rst @@ -22,7 +22,7 @@ Valid CartoDB tables A valid CartoDB table shall meet the following conditions: -- Have a ``cartodb_id`` column as primary key with a sequence +- Have a ``cartodb_id`` integer column 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 @@ -49,8 +49,8 @@ Note that there should be only one feature per row in the source table. If there Low-level requirements ====================== -- If the original table contains a valid ``cartodb_id`` column, it shall be used -- If the original table contains a valid ``the_geom`` or ``the_geom_webmercator`` it shall be used. +- If the original table contains a valid (unique) ``cartodb_id`` column, it shall be used +- If the original table contains a ``the_geom`` column or a ``the_geom_webmercator`` 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`` From bcfe8d8f3b7e9470190a5871f555fe7ca90ad088 Mon Sep 17 00:00:00 2001 From: Carla Iriberri Date: Fri, 20 Nov 2015 17:24:01 +0100 Subject: [PATCH 3/3] Adds not null constraint for cartodb_id --- doc/cartodbfy-requirements.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/cartodbfy-requirements.rst b/doc/cartodbfy-requirements.rst index e3fa3a5..0743699 100644 --- a/doc/cartodbfy-requirements.rst +++ b/doc/cartodbfy-requirements.rst @@ -49,7 +49,7 @@ Note that there should be only one feature per row in the source table. If there Low-level requirements ====================== -- If the original table contains a valid (unique) ``cartodb_id`` column, it shall be used +- If the original table contains a valid (unique and not null) ``cartodb_id`` column, it shall be used - If the original table contains a ``the_geom`` column or a ``the_geom_webmercator`` 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``