Datasets

Datasets describe the data model of a project. Each dataset represents a database table. They also define the constraints and links between all other datasets in a project.

There are three types of datasets:

dwh () type is a data warehouse service dataset type, it references a table in a relational dwh database, which may contain various kinds of data (e.g. orders, customers, administrative units...)
vt () type is a vector tile dataset type, it references a vector tile service, which serves vector tiles that are displayed over the base map (CleverMaps vector tiles are hosted on Mapbox)
h3Grid () type is a H3 grid dataset, it represents a grid visualization, where the geometries are generated on the fly by the application (see Tutorial 8 for more info, and H3 grid spatial index by Uber)

Datasets of dwh type also have a subtype, which defines the type of data they contain. There are five of them:

basic () subtype is used to contain data which are not to be visualized on a map (e.g. orders, clients, or demography)
geometryPolygon () subtype contains data which represent polygons on a map (e.g. administrative units, delivery zones)
geometryPoint () subtype contains data which represent specific points on a map (e.g. shops, postcodes, or POIs)
geometryLine () subtype contains data which represent lines on a map (e.g. routes, pipelines)
date () subtype is a special subtype not to be used in a regular way, it is used to describe datasets the can-dim-dates data dimension

Datasets also subject to various validation checks. Datasets with ref.subtype other than basic - geometryPolygon, geometryPoint, geometryLine and date must also contain properties.featureTitle key, which defines the visualization format of one row of the dataset (used in tooltips or the date picker). Datasets with subtype geometryPolygon, geometryPoint must have a link to a vt type dataset describing that geometry. More about these checks can be found in the examples below.

Datasets are directly referencing other datasets via foreignKey property or geometry key. They are referenced by URL in marker selectors, as some datasets represent a group of points in the map. Dataset properties, declared in dataset.ref.properties are referenced by name in metrics, view filters and indicator drills. Reference integrity of the data model is also enforced. In order not to break this integrity, is not possible to delete a dataset, which is referenced in another dataset, either by foreignKey, or geometry.

Syntax

Example of a dwh dataset with basic subtype. This subtype typically indicates a dataset, which does not have geographical information - so it is not possible to visualize it on the map.

This dataset describes baskets (i.e. orders) from the Retail Solution Demo project. Each basket represents a purchase made by a customer, either offline in one of the shops or online in the e-shop. You can see that it contains various purchase properties like "Date", "Purchase value", "Delivery type", etc.

Dwh dataset with basic subtype syntax

CODE

{
    "name": "baskets",
    "type": "dataset",
    "title": "Baskets",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "basket_id"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "basic",
        "table": "baskets",
        "primaryKey": "basket_id",
        "categorizable": true,
        "fullTextIndex": false,
        "properties": [
            {
                "filterable": true,
                "name": "date_iso",
                "title": "Date ISO",
                "column": "date_iso",
                "type": "string"
            },
            {
            	"filterable": false,
                "name": "shop_id",
                "title": "Shop ID",
                "column": "shop_id",
                "type": "integer"
            },
            {
            	"filterable": false,
                "name": "client_id",
                "title": "Client ID",
                "column": "client_id",
                "type": "integer"
            },
            {
            	"filterable": true,
                "name": "amount",
                "title": "Purchase value",
                "column": "amount",
                "type": "decimal(16,2)"
            },
            {
            	"filterable": true,
                "name": "month",
                "title": "Month",
                "column": "month",
                "type": "integer"
            },
            {
            	"filterable": true,
                "name": "on_off_name",
                "title": "Channel",
                "column": "on_off_name",
                "type": "string"
            },
            {
            	"filterable": true,
                "name": "action_turnover",
                "title": "Action turnover",
                "column": "action_turnover",
                "type": "decimal(16,2)"
            },
            {
            	"filterable": true,
                "name": "courier",
                "title": "Delivery type",
                "column": "courier",
                "type": "string"
            },
            {
            	"filterable": false,
                "name": "value_cat",
                "title": "Item value category",
                "column": "value_cat",
                "type": "integer"
            },
            {
            	"filterable": true,
                "name": "value_name",
                "title": "Item value name",
                "column": "value_name",
                "type": "string"
            },
            {
            	"filterable": false,
                "name": "basket_id",
                "title": "Basket ID",
                "column": "basket_id",
                "type": "integer"
            }
        ]
    }
}

This dataset describes the geometries of UK districts. These geometries are served to the application and visualized as polygons on the map. This geometry is referenced in a dwh dataset district in the examples below.

Example of a Vt dataset

CODE

{
    "name": "districtgeojson",
    "type": "dataset",
    "title": "Vector tiles for UK district polygons",
    "ref": {
        "type": "vt",
        "urlTemplate": "https://a.tiles.mapbox.com/v4/cleveranalytics.dia058st/{z}/{x}/{y}.vector.pbf?access_token={token}",
        "zoom": {
            "min": 8,
            "optimal": 10,
            "max": 15
        }
    },
    "dataSources": [
        {
            "licenceHolder": "Office for National Statistics",
            "licenceHolderUrl": "https://www.ons.gov.uk/",
            "licenceUrl": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
        }
    ]
}

This dataset represents H3 grid visualization on resolution 8. It's very similar to vt dataset, apart from resolution you only need to define the appropriate zoom. See Example to see how to link this dataset to a geometryPoint dwh dataset.

Example of a h3Grid dataset

CODE

{
    "name": "h3_grid_8",
    "type": "dataset",
    "title": "H3 grid resolution 8",
    "ref": {
        "type": "h3Grid",
        "resolution": 8,
        "zoom": {
            "min": 2,
            "optimal": 10,
            "max": 18
        }
    }
}

Additional syntax examples

Important - to properly understand datasets, please see the examples below.

Example of a dwh dataset type with geometryPoint subtype

CODE

{
    "name": "shops",
    "type": "dataset",
    "title": "Shops",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "name"
        },
        "featureSubtitle": {
            "type": "property",
            "value": "address"
        },
        "featureAttributes": [
            {
                "type": "property",
                "value": "manager_name"
            },
            {
                "type": "property",
                "value": "opening_hours"
            },
            {
                "type": "property",
                "value": "opening_hours_sun"
            },
            {
                "type": "property",
                "value": "contact_phone"
            },
            {
                "type": "property",
                "value": "contact_mail",
                "format": {
                    "type": "email"
                }
            },
            {
                "type": "property",
                "value": "employees"
            },
            {
                "type": "property",
                "value": "monthly_expenses",
                "format": {
                    "type": "number",
                    "fraction": 0,
                    "symbol": "£"
                }
            },
            {
                "type": "property",
                "value": "monthly_rent",
                "format": {
                    "type": "number",
                    "fraction": 0,
                    "symbol": "£"
                }
            }
        ]
    },
    "ref": {
        "type": "dwh",
        "subtype": "geometryPoint",
        "visualizations": [
            {
                "type": "dotmap"
            }
        ],
        "table": "shops",
        "primaryKey": "shop_id",
        "categorizable": true,
        "fullTextIndex": true,
        "spatialIndex": true,
        "properties": [
            {
                "filterable": false,
                "name": "shop_id",
                "title": "Shop ID",
                "column": "shop_id",
                "type": "integer"
            },
            {
                "filterable": true,
                "name": "name",
                "title": "Name",
                "column": "name",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "address",
                "title": "Address",
                "column": "address",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "opening_hours",
                "title": "Opening hours",
                "column": "opening_hours",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "opening_hours_sun",
                "title": "Opening hours (Sun)",
                "column": "opening_hours_sun",
                "type": "string"
            },
            {
                "filterable": true,
                "name": "manager_name",
                "title": "Manager",
                "column": "manager_name",
                "type": "string"
            },
            {
                "filterable": true,
                "name": "partner",
                "title": "Partner",
                "column": "partner",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "lat",
                "column": "lat",
                "type": "latitude"
            },
            {
                "filterable": false,
                "name": "lng",
                "column": "lng",
                "type": "longitude"
            },
            {
                "filterable": false,
                "name": "contact_phone",
                "title": "Phone",
                "column": "contact_phone",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "contact_mail",
                "title": "E-mail",
                "column": "contact_mail",
                "type": "string"
            },
            {
                "filterable": true,
                "name": "employees",
                "title": "Employees",
                "column": "employees",
                "type": "integer"
            },
            {
                "filterable": true,
                "name": "monthly_expenses",
                "title": "Monthly expenses",
                "column": "monthly_expenses",
                "type": "integer"
            },
            {
                "filterable": true,
                "name": "monthly_rent",
                "title": "Monthly rent",
                "column": "monthly_rent",
                "type": "integer"
            }
        ]
    }
}

This dwh dataset represents locations of stores. Each store has a location (lat and lon properties), and is visualized by a marker. So, in this case the subtype is geometryPoint.

In geometryPoint subtype, the presence of ref.properties called lng of longitude and lat of latitude type is enforced.

Example of a dwh dataset type with geometryPolygon subtype

CODE

{
    "name": "district",
    "type": "dataset",
    "title": "Districts",
    "origin": "https://secure.clevermaps.io/rest/projects/mxl3pmyqc7kz04hl/md/datasets?name=district",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "districtname"
        },
        "featureSubtitle": {
            "type": "property",
            "value": "upper_admin_name"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "geometryPolygon",
        "geometry": "districtgeojson",
        "visualizations": [
            {
                "type": "areas"
            }
        ],
        "table": "district_dwh",
        "primaryKey": "districtcode",
        "categorizable": false,
        "fullTextIndex": true,
        "properties": [
            {
                "filterable": false,
                "name": "districtcode",
                "title": "districtcode",
                "column": "districtcode",
                "type": "string"
            },
            {
                "filterable": true,
                "name": "districtname",
                "title": "districtname",
                "column": "districtname",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "y_min",
                "title": "y_min",
                "column": "y_min",
                "type": "decimal(19,16)"
            },
            {
                "filterable": false,
                "name": "y_max",
                "title": "y_max",
                "column": "y_max",
                "type": "decimal(19,16)"
            },
            {
                "filterable": false,
                "name": "x_min",
                "title": "x_min",
                "column": "x_min",
                "type": "decimal(19,16)"
            },
            {
                "filterable": false,
                "name": "x_max",
                "title": "x_max",
                "column": "x_max",
                "type": "decimal(19,16)"
            },
            {
                "filterable": true,
                "name": "upper_admin_name",
                "title": "upper_admin_name",
                "column": "upper_admin_name",
                "type": "string"
            }
        ]
    },
    "dataSources": [
        {
            "licenceHolder": "Office for National Statistics",
            "licenceHolderUrl": "https://www.ons.gov.uk/",
            "licenceUrl": "http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
        }
    ]
}

This dataset represents dwh data of the districts of the United Kingdom. Districts have a geometry, so they can be visualised as polygons on the map. Thus, subtype is geometryPolygon.

The dataset also contains information about its data sources. The source data for UK districts was provided by Office for National Statistics under the Open Government license. For more info, see the syntax below.

Note the reference to a vt dataset named districtgeojson in ref.properties.geometry key. This dataset must exist in the project before we add the geometryPolygon one.

Example of a dwh dataset type with geometryLine subtype

CODE

{
    "name": "pipelines",
    "type": "dataset",
    "title": "Gas pipelines",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "type"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "geometryLine",
        "geometry": "pipelines_geojson",
        "visualizations": [
            {
                "type": "line"
            }
        ],
        "table": "pipelines",
        "primaryKey": "id",
        "categorizable": true,
        "fullTextIndex": true,
        "properties": [
            {
                "filterable": false,
                "name": "id",
                "title": "ID",
                "column": "id",
                "type": "integer"
            },
            {
                "filterable": true,
                "name": "source",
                "title": "Source",
                "column": "source",
                "type": "string"
            },
            {
                "filterable": true,
                "name": "type",
                "title": "Type",
                "column": "type",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "x_min",
                "title": "x_min",
                "column": "x_min",
                "type": "decimal(19,16)"
            },
            {
                "filterable": false,
                "name": "x_max",
                "title": "x_max",
                "column": "x_max",
                "type": "decimal(19,16)"
            },
            {
                "filterable": false,
                "name": "y_min",
                "title": "y_min",
                "column": "y_min",
                "type": "decimal(19,16)"
            },
            {
                "filterable": false,
                "name": "y_max",
                "title": "y_max",
                "column": "y_max",
                "type": "decimal(19,16)"
            }
        ]
    }
}

This dataset represents a gas pipeline network. The pipelines are visualized by lines, so subtype is geometryLine. However, remember that the actual geometries are described by the pipelines_geojson vt dataset.

Example of a dwh dataset type with date subtype

CODE

{
    "name": "dim_dates",
    "type": "dataset",
    "title": "dates",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "date_en"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "date",
        "table": "dim_dates",
        "primaryKey": "date_iso",
        "categorizable": false,
        "fullTextIndex": false,
        "properties": [
            {
                "filterable": false,
                "name": "date_iso",
                "title": "date_iso",
                "column": "date_iso",
                "type": "date"
            },
            {
                "filterable": false,
                "name": "date_kat",
                "title": "date_kat",
                "column": "date_kat",
                "type": "integer"
            },
            {
                "filterable": false,
                "name": "date_cz",
                "title": "date_cz",
                "column": "date_cz",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "date_en",
                "title": "date_en",
                "column": "date_en",
                "type": "string"
            },
            {
                "filterable": false,
                "name": "day_of_month",
                "title": "day_of_month",
                "column": "day_of_month",
                "type": "integer"
            },
            {
                "filterable": false,
                "name": "day_of_quarter",
                "title": "day_of_quarter",
                "column": "day_of_quarter",
                "type": "integer"
            },
            {
                "filterable": false,
                "name": "day_of_year",
                "title": "day_of_year",
                "column": "day_of_year",
                "type": "integer"
            },
            {
                "filterable": false,
                "name": "day_of_week_id",
                "title": "day_of_week_id",
                "column": "day_of_week_id",
                "type": "integer",
                "foreignKey": "dim_dates_day_of_week"
            },
            {
                "filterable": false,
                "name": "week_id",
                "title": "week_id",
                "column": "week_id",
                "type": "integer",
                "foreignKey": "dim_dates_week"
            },
            {
                "filterable": false,
                "name": "month_id",
                "title": "month_id",
                "column": "month_id",
                "type": "integer",
                "foreignKey": "dim_dates_month"
            },
            {
                "filterable": false,
                "name": "quarter_id",
                "title": "quarter_id",
                "column": "quarter_id",
                "type": "integer",
                "foreignKey": "dim_dates_quarter"
            },
            {
                "filterable": false,
                "name": "year_id",
                "title": "year_id",
                "column": "year_id",
                "type": "integer",
                "foreignKey": "dim_dates_year"
            }
        ]
    }
}

This is an example of the date subtype dataset. This subtype is almost exclusively used in the can-dim-dates dimension, used for date management and filtering in a project.

This subtype also enforces the presence of the featureTitle property. The property selected as a featureTitle defines what date will be show in the date picker, or the time series indicator drill block. This is useful in cases when you want to use the date names in different language. The can-dim-dates dimension currently offers either English (date_en) or Czech (date_cz).

Example of a dataset with displayOptions

CODE

{
    "name": "baskets",
    "type": "dataset",
    "title": "Baskets",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "basket_id"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "basic",
        "table": "baskets",
        "primaryKey": "basket_id",
        "categorizable": true,
        "fullTextIndex": false,
        "properties": [
            {
                "filterable": true,
                "name": "date_iso",
                "title": "Date ISO",
                "column": "date_iso",
                "type": "string"
            },
            {
            	"filterable": false,
                "name": "shop_id",
                "title": "Shop ID",
                "column": "shop_id",
                "type": "integer"
            },
            {
            	"filterable": false,
                "name": "client_id",
                "title": "Client ID",
                "column": "client_id",
                "type": "integer"
            },
            {
            	"filterable": true,
                "name": "amount",
                "title": "Purchase value",
                "column": "amount",
                "type": "decimal(16,2)"
            },
            {
            	"filterable": true,
                "name": "month",
                "title": "Month",
                "column": "month",
                "type": "integer"
            },
            {
            	"filterable": true,
                "name": "on_off_name",
                "title": "Channel",
                "column": "on_off_name",
                "type": "string",
                "displayOptions": {
                    "valueOptions": [
                        {
                            "value": "Online",
                            "color": "green"
                        },
                        {
                            "value": "Offline",
                            "color": "red"
                        }
                    ]
                }
            },
            {
            	"filterable": true,
                "name": "action_turnover",
                "title": "Action turnover",
                "column": "action_turnover",
                "type": "decimal(16,2)"
            },
            {
            	"filterable": true,
                "name": "courier",
                "title": "Delivery type",
                "column": "courier",
                "type": "string",
                "displayOptions": {
                    "valueOptions": [
                        {
                            "value": "Picked up",
                            "color": "blue"
                        },
                        {
                            "value": "Delivered",
                            "color": "pink"
                        }
                    ]
                }
            },
            {
            	"filterable": false,
                "name": "value_cat",
                "title": "Item value category",
                "column": "value_cat",
                "type": "integer",
                "displayOptions": {
                    "valueOptions": [
                        {
                            "value": "Up to £ 20",
                            "color": "blue"
                        },
                        {
                            "value": "£ 20 - 50",
                            "color": "purple"
                        },
                        {
                            "value": "£ 50 - 100",
                            "color": "red"
                        },
                        {
                            "value": "£ 100 - 250",
                            "color": "orange"
                        },
                        {
                            "value": "More than £ 250",
                            "color": "green"
                        }
                    ]
                }
            },
            {
            	"filterable": true,
                "name": "value_name",
                "title": "Item value name",
                "column": "value_name",
                "type": "string"
            },
            {
            	"filterable": false,
                "name": "basket_id",
                "title": "Basket ID",
                "column": "basket_id",
                "type": "integer"
            }
        ]
    }
}

This dataset has the displayOptions.valueOptions object set on some properties. These are the properties that are also used in a categories block in any linked indicator drill. This gives you the ability to use the qualitative visualization (more info in Tutorial 5: Drilling down on the data).

For example, the baskets.on_off_name property has two possible values: "Online" and "Offline". So the objects with prevailing "Online" value will become green, and objects with prevailing "Offline" will become red.

Example of a geometryPoint dataset with h3Geometries

CODE

{
    "name": "buildings",
    "type": "dataset",
    "title": "Customer address ID",
    "properties": {
        "featureTitle": {
            "type": "function",
            "value": "concat",
            "content": [
                {
                    "type": "text",
                    "value": "ID: "
                },
                {
                    "type": "property",
                    "value": "id"
                }
            ]
        },
        "featureSubtitle": {
            "type": "property",
            "value": "ward"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "geometryPoint",
        "h3Geometries": [
            "h3_grid_6",
            "h3_grid_7",
            "h3_grid_8",
            "h3_grid_9"
        ],
        "visualizations": [
            {
                "type": "heatmap"
            },
            {
                "type": "dotmap"
            }
        ],
        "table": "buildings",
        "primaryKey": "id",
        "categorizable": true,
        "fullTextIndex": true,
        "spatialIndex": true,
        "properties": [
            {
                "name": "id",
                "title": "id",
                "column": "id",
                "type": "integer",
                "filterable": false
            },
            {
                "name": "lat",
                "column": "lat",
                "type": "latitude",
                "filterable": true
            },
            {
                "name": "lng",
                "column": "lng",
                "type": "longitude",
                "filterable": true
            },
            {
                "name": "ward",
                "title": "ward",
                "column": "ward",
                "type": "string",
                "filterable": false
            },
            {
                "name": "name",
                "title": "name",
                "column": "name",
                "type": "string",
                "filterable": false
            }
        ]
    },
    "dataSources": [
        {
            "licenceHolder": "© OpenStreetMap",
            "licenceHolderUrl": "https://www.openstreetmap.org/",
            "licenceUrl": "https://www.openstreetmap.org/copyright/en"
        }
    ]
}

This is a simple dwh geometryPoint dataset which contains addresses with latitude and longitude. To visualize it using H3 grid, simply add some h3Grid datasets and specify them in the ref.h3Geometries array.

Notice the concat function in featureTitle. This function allows you to concat multiple properties and text to be displayed in the dataset's features tooltip and headers.

Example of a geometryPoint dataset with calculated dwh property

CODE

{
    "name": "ami_dwh",
    "type": "dataset",
    "title": "Adresní místa",
    "properties": {
        "featureTitle": {
            "type": "property",
            "value": "address_1"
        },
        "featureSubtitle": {
            "type": "property",
            "value": "address_2"
        }
    },
    "ref": {
        "type": "dwh",
        "subtype": "geometryPoint",
        "visualizations": [
            {
                "type": "heatmap"
            },
            {
                "type": "dotmap"
            }
        ],
        "primaryKey": "id",
        "categorizable": false,
        "fullTextIndex": true,
        "spatialIndex": true,
        "properties": [
            {
                "name": "id",
                "title": "id",
                "column": "id",
                "type": "integer",
                "filterable": false
            },
            {
                "name": "obec",
                "title": "obec",
                "column": "obec",
                "type": "string",
                "filterable": false
            },
            {
                "name": "momc",
                "title": "momc",
                "column": "momc",
                "type": "string",
                "filterable": false
            },
            {
                "name": "mop",
                "title": "mop",
                "column": "mop",
                "type": "string",
                "filterable": false
            },
            {
                "name": "cast_obec",
                "title": "cast_obec",
                "column": "cast_obec",
                "type": "string",
                "filterable": false
            },
            {
                "name": "ulice",
                "title": "ulice",
                "column": "ulice",
                "type": "string",
                "filterable": false
            },
            {
                "name": "typ_cisla",
                "title": "typ_cisla",
                "column": "typ_cisla",
                "type": "string",
                "filterable": false
            },
            {
                "name": "cislo_domovni",
                "title": "cislo_domovni",
                "column": "cislo_domovni",
                "type": "string",
                "filterable": false
            },
            {
                "name": "cislo_orientacni",
                "title": "cislo_orientacni",
                "column": "cislo_orientacni",
                "type": "string",
                "filterable": false
            },
            {
                "name": "psc",
                "title": "psc",
                "column": "psc",
                "type": "string",
                "filterable": false
            },
            {
                "name": "lat",
                "column": "lat",
                "type": "latitude",
                "filterable": true
            },
            {
                "name": "lng",
                "column": "lng",
                "type": "longitude",
                "filterable": true
            },
            {
                "name": "address_1",
                "title": "address_1",
                "column": "address_1",
                "type": "string",
                "filterable": false
            },
            {
                "name": "address_2",
                "title": "address_2",
                "column": "address_2",
                "type": "string",
                "filterable": false
            },
            {
                "foreignKey": "zsj_d_dwh",
                "name": "zsjd_geom",
                "title": "zsjd_geom",
                "column": "zsjd_geom",
                "type": "string",
                "filterable": false,
                "calculated": true
            }
        ],
        "zoom": {
            "min": 11,
            "optimal": 11,
            "max": 18
        }
    },
    "dataSources": [
        {
            "licenceHolder": "RUIAN - ČÚZK",
            "licenceHolderUrl": "http://vdp.cuzk.cz/",
            "licenceUrl": "https://www.cuzk.cz/Uvod/Produkty-a-sluzby/RUIAN/RUIAN-(1).aspx"
        }
    ]
}

The dataset has one dwh property with "calculated": true. The dwh property references other dataset (zsj_d_dwh) which must be dwh dataset of subtype geometryPolygon and must have one dwh property with "type": "geometry". When uploading data this property is calculated as an intersect between point and polygon and ID of the polygon is written to the row.

Key description

`properties`

These properties define the content of a tool-tip shown on marker/area hover (example), and the details of a dataset (example).

The properties can be found on the common syntax level. The syntax example can be found in the "Example of a dwh dataset type with geometryPoint subtype" above.

Do not confuse these properties with dataset (dwh) properties - dwhDataset.ref.properties array.

Key	Type	Optionality	Description
`featureTitle`	object	VARIES	defines the tooltip title shown on hover, required for datasets of subtype `geometryPolygon` and `geometryPoint`
`featureSubtitle`	object	OPTIONAL	defines the tooltip subtitle shown on hover
`featureAttributes`	array	OPTIONAL	defines the properties which will be displayed in the details

`properties.featureTitle & properties.featureSubtitle`

The syntax of featureTitle and featureSubtitle is identical.

Key

Type

Optionality

Description

Constraints

type

object

REQUIRED

property - a dataset property

function - function to apply to a dataset property (currently only concat)

[property, function]

value

object

REQUIRED

name of the dataset property, or the function (currently only concat)

content

array

OPTIONAL

allows you to nest properties in functions

`properties.featureAttributes`

The definition of the dataset details. Allows you to display properties of a dataset itself. These can be properties which are not explicitly to be used in a metric (e.g. store owner, opening hours, area, etc.).

Key	Type	Optionality	Description	Constraints
`type`	object	REQUIRED	`property` - a dataset property `expression` - expression to format multiple properties (e.g. `lat` and `lon`)	`[property, expression]`
`value`	object	REQUIRED	name of the dataset property
`format`	object	OPTIONAL	object specifying formatting of the attribute value
`layout`	string	OPTIONAL	attribute layout size	`[primary, secondary]`

`properties.featureAttributes.format`

Key	Type	Optionality	Description	Constraints
`type`	string	REQUIRED	formatting type	`[text, number, percentage, email, link]`
`fraction`	integer	OPTIONAL	the number of places after the decimal point (for `number` type only)	x => 0
`symbol`	string	OPTIONAL	custom symbol to display with the attribute (e.g. `"m2"`, `"$"`, etc.)	`(*)`

`dataSources`

In this array, you can specify a list of data sources / licences for each dataset. This includes the licence holder's name, webpage, logo and the link to the licence itself. The unique list of data sources for each project can be displayed by clicking on:

the Menu button in the top left corner (☰) and selecting "Data sources"
selecting "Data sources" in the bottom right corner of the map window

Key	Type	Optionality	Description	Constraints
`licenceHolder`	string	REQUIRED	Name of the licence holder	`(*)`
`licenceHolderUrl`	string	REQUIRED	URL link to the licence holder's website	`(*)`
`licenceHolderLogo`	string	OPTIONAL	URL link to the licence holder's logo preferably `.png`, will be downsized automatically	`(*)`
`licenceUrl`	string	OPTIONAL	URL link to the licence itself	`(*)`

`dwh.ref`

A reference of a dataset dwh type.

Key	Type	Optionality	Description	Constraints
`type`	string	REQUIRED	type identifier, always `dwh`	`[dwh]`
`subtype`	string	REQUIRED	`dwh` subtype identifier	`[basic, geometryPoint, geometryPolygon, geometryLine, date]`
`geometry`	string	VARIES	geometry reference to a vector tile dataset required only for `geometryPolygon` `and` `geometryLine` subtypes	`{datasetName}`
`h3Geometries`	array	OPTIONAL	array of references to `h3Grid` dataset names (see example above) enables the grid visualization
`visualizations`	array	VARIES	array of objects specifying the allowed visualizations of the dataset required only for `geometryPoint`, `geometryPolygon` and `geometryLine` subtypes
`zoom`	object	OPTIONAL	map zoom object
`table`	string	READ-ONLY	name of the actual `dwh` table this dataset represents it's derived from the name of the dataset, and _X postfix is added for each full load, where X is the number of the load	`(a-z0-9_-)`
`primaryKey`	string	REQUIRED	primary key of the table - must be one of the dataset properties should be unique	`{datasetProperty}`
`categorizable`	boolean	OPTIONAL	indicates if the dataset is capable of being categorized in the Filters tool () default = `true` should be `true` for fact datasets like "orders", "shops" or "clients", `false` for additional datasets like "postcodes", "dim_dates" or "price_categories"	`[true, false]`
`fullTextIndex`	boolean	OPTIONAL	indicates if the dataset data will be indexed for full text search in Search tool () default = `true` for `geometry*` subtypes, false for `basic` and `date` subtypes	`[true, false]`
`spatialIndex`	boolean	OPTIONAL	indicates if the dataset data will be indexed with spatial index applicable only for `geometryPoint` subtypes default = `false`	`[true, false]`
`properties`	array	REQUIRED	array of `properties` - database table column descriptions dataset property order must be identical to the order of the data columns size must be at least 1

`dwh.ref.zoom`

Set desired zoom levels for the dwh datasets.

Key	Type	Optionality	Description	Constraints
`min`	integer	REQUIRED	minimal available zoom level	`2 .. 18`
`max`	integer	REQUIRED	maximal available zoom level	`2 .. 18`
`optimal`	integer	REQUIRED	optimal zoom level	`2 .. 18`
`visibleFrom`	integer	OPTIONAL	zoom level from which the dataset's feature will be visible this property works only for `dwh` datasets	`2 .. 18`

`dwh.ref.visualizations`

Array of objects specifying the allowed visualizations of the dataset. The available visualizations are derived from the subtype of the dataset:

geometryPolygon subtype can be visualized by areas, grid or zones visualizations
geometryPoint subtype can be visualized by dotmap or heatmap visualizations
geometryLine subtype can be visualized by line visualization

For more info, see the additional syntax examples above.

Key	Type	Optionality	Description	Constraints
`type`	string	REQUIRED	type of the visualization	`[areas, grid, zones, dotmap, heatmap, line]`
`zoom`	object	OPTIONAL	map zoom object

`dwh.ref.properties`

Array of properties describing database table of a dwh dataset.

Key	Type	Optionality	Description	Constraints
`name`	string	REQUIRED	name of the column as it will be referenced in other objects	`(a-z0-9_-)`
`title`	string	REQUIRED	human-readable title of the column	`(*)`
`column`	string	REQUIRED	name of the column as it is in the database table	`(a-z0-9_-)`
`type`	string	REQUIRED	column data type detailed description in the table below	`[integer, bigint, decimal, string, boolean, date, latitude, longitude, h3_grid, geometry]`
`foreignKey`	string	VARIES	name of the dataset, whose `primaryKey` is referenced by this `foreignKey`
`calculated`	boolean	VARIES	indicated if the property is calculated during data upload must be used with `foreignKey` (see example above)	`[true, false]`
`filterable`	boolean	OPTIONAL	indicates whether it's possible for this property to be added to a filter default = `true`	`[true, false]`
`description`	string	OPTIONAL	description of the property which appears in Filters ()	`(*)`
`displayOptions`	object	OPTIONAL	options that specify how the property will be displayed

`dwh.ref.properties.displayOptions`

The displayOptions object allows you to specify how the property will be displayed. See the example above.

Key	Type	Optionality	Description	Constraints
`valueOptions`	array	OPTIONAL	assigns colors to values of the property

`dwh.ref.properties.displayOptions.valueOptions`

In this array, we can assign colors to specific values of the property. The valueOptions array allows you to set your own colors for the qualitative visualization. See Tutorial 5: Drilling down on the data for more info.

Key	Type	Optionality	Description	Constraints
`value`	string	REQUIRED	value of the property	`(*)`
`color`	string	VARIES	predefined color of the property either `color` or `hexColor` can be specified	`[purple, green, orange, blue, turquoise, pink, red, lime, brown, yellow]`
`hexColor`	string	VARIES	hex color code of the property (e.g. `#E8493F`), see more about hex color codes either `color` or `hexColor` can be specified	`(#[a-fA-F0-9]{6})`
`weight`	number	OPTIONAL	weight (or "width") of the property for `lines` visualization only, see the example	`x => 0`
`pattern`	string	OPTIONAL	pattern of the property for `lines` visualization only, see the example	`[solid, dot, dash, longdash, dotdash]`

Dataset property data types

Identifier	Description	Examples
`integer`	a whole number 4-byte signed number, range: 2^-31 .. 2⁺³¹	`-1000000, -120, 0, 1, 2, 42, 2147483648`
`bigint`	large range integer 8-byte signed number, range: 2^-63 .. 2⁺⁶³	`-1000000, -120, 0, 1, 2, 42, 2147483648, 9223372036854775807`
`decimal`	decimal number with precision and scale parameters: `decimal(precision,scale) ~ decimal(10,2)`	`-1215.0146, 1.02, 4.57, 9546.4164563`
`string`	a sequence of characters variable size, limit: 255 characters	`"banana", "CleverMaps", "E=mc2", "!@#$%^&"`
`boolean`	Boolean data type, has two values only 1-byte size	`true, false`
`date`	ISO 8601 date format (preferred), more available formats can be found here 4-byte size, range: 4713 BC .. 5874897 AD	`1997-01-30, 2015-01-05, 2018-03-19`
`latitude`	a geographic coordinate specifying the north-south position of a point on Earth	`49.1872206`
`longitude`	a geographic coordinate specifying the east-west position of a point on Earth	`16.6057850`
`geometry`	WKT or WKB representation of vector geometry object type can only be used in datasets of subtype `geometryPoint` and `geometryPolygon`, with a limit of 1 per dataset	`POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))`

Additional decimal type info

Numeric precision refers to the maximum number of digits that are present in the number (i.e. 1234567.89 has a precision of 9).

Numeric scale refers to the maximum number of decimal places (i.e. 123456.789 has a scale of 3).

scale must not be higher than precision, and the default value is decimal(19,6).

`vt.ref`

A reference of a dataset vt type.

Key	Type	Optionality	Description	Constraints
`type`	string	REQUIRED	type identifier, always `vt`	`[vt]`
`urlTemplate`	string	REQUIRED	absolute URL link to the location of the vector tiles	`(*)`
`zoom`	object	REQUIRED	map zoom object

`vt.ref.zoom`

Set desired zoom levels for the vector tile datasets.

Key	Type	Optionality	Description	Constraints
`min`	integer	REQUIRED	minimal available zoom level	`2 .. 18`
`max`	integer	REQUIRED	maximal available zoom level	`2 .. 18`
`optimal`	integer	REQUIRED	optimal zoom level	`2 .. 18`
`visibleFrom`	integer	OPTIONAL	zoom level from which the dataset's feature will be visible this property works only for `dwh` datasets	`2 .. 18`

`h3Grid.ref`

A reference of a dataset h3Grid type.

Key	Type	Optionality	Description	Constraints
`type`	string	REQUIRED	type identifier, always `h3Grid`	`[h3Grid]`
`resolution`	string	REQUIRED	resolution of the grid	`2 .. 11`
`zoom`	object	REQUIRED	map zoom object

`h3Grid.ref.zoom`

Set desired zoom levels for the h3Grid datasets.

Key	Type	Optionality	Description	Constraints
`min`	integer	REQUIRED	minimal available zoom level	`2 .. 18`
`max`	integer	REQUIRED	maximal available zoom level	`2 .. 18`
`optimal`	integer	REQUIRED	optimal zoom level	`2 .. 18`
`visibleFrom`	integer	OPTIONAL	zoom level from which the dataset's feature will be visible this property works only for `dwh` datasets	`2 .. 18`

Visual representation

The data model the datasets describe can be considered their visualization. It can be viewed in the application by clicking the Account button on the bottom left of a Project page, and selecting Data model. However, this functionality is available only to users with the Admin user role.

Example of a project's data model

This is the visualization of the data model from the Retail Solution Demo project.

Native datasets in this project are baskets, shops and clients. The other datasets were imported from different data dimensions. The datasets in orange were imported from the can-dim-dates dimension. Brown datasets are from a dimension of UK administrative units. The dataset demography_postcode comes from a UK demography dimension. The h3Grid datasets are pink.

Detail of a dataset in the data model

If you click on any dataset a detail will be displayed.

The detail of a dwh dataset contains 3 blocks - Overview, Properties and Data load history. Please note that Data load history is displayed only to administrators of a project. It's also possible to see the Data preview, where you can check if your data has loaded properly, and sort or filter by the value of any column.

The detail of a vt dataset contains only the Overview block. It is possible to click the link to Mapbox to see a geometry preview.

`dwh` dataset detail	`vt` dataset detail	`h3Grid` dataset detail

Dataset data preview

Data preview with applied filters to some shop_id, month and on_off_name dataset properties.

Tooltip shown on hover

For geometryPoint and geometryPolygon datasets, a tooltip is shown on hover. The content is defined in dataset.properties.

"My Store: Grand Central" is the featureTitle.

"Virgin Trains, 6b 7b, Digbeth, B15" is the featureSubtitle.

Dataset details

The content of dataset details is defined in dataset.properties.featureAttributes. The details are shown on the dashboard, right under the indicator list.