Data sources & map layers

When you begin a new map in CARTO Builder, the left panel is your starting point, providing the tools to add data sources that will be visualized as layers on your map. In Builder, each data source creates a direct connection to your data warehouse, allowing you to access your data without the need to move or copy it. This cloud-native approach ensures efficient and seamless integration of large datasets.

Once a data source is added, CARTO's advanced technology renders a map layer that visually represents your data, offering smooth and scalable visualization, even with extensive datasets.

In this section, we'll take you through the various data source formats that CARTO Builder supports. We'll also explore the different types of map layers that can be rendered in Builder, enhancing your understanding of how to effectively visualize and interact with your geospatial data.

Data sources

Builder data sources can be differentiated in the following geospatial data types:

• Simple features: These are unaggregated features using standard geometry (point, line or polygon) and attributes, ready for use in Builder. These spatial and non-spatial attributes are ready to be used in Builder.

• Aggregated features based on Spatial Indexes: These data sources are aggregated for improved performance or specific use cases. The properties of these features are aggregated according to the chosen aggregation type in Builder. CARTO currently supports two different types of utilize a spatial indexes, Quadbin and H3.

• Pre-generated tilesets: These are tilesets that have been previously pre-generated using CARTO Analytics Toolbox procedure and stored directly in your data warehouse. Ideal for handling very large, static datasets, these tilesets ensure efficient and high-performance visualizations.

Spatial Data Column Naming Convention

When working with data sources in Builder, there is a column name convention that should be followed to ensure that CARTO can fully support it.

• Simple features: CARTO expects to find a column named geom that will be used to render standard geometry (point, line, polygon) in the map.

• Aggregated features: When loading a table that contains aggregated features using spatial indexes, CARTO expects the following column name convention:

  • H3 ids: The column should be named h3

  • Quadbin ids: Name the column quadbin

Adding sources to Builder

In Builder, you can add data sources either as table sources, by connecting to a materialized table in your data warehouse, or through custom SQL queries. These queries execute directly in your data warehouse, fetching the necessary properties for your map.

Table sources

You can directly connect to your data warehouse table by navigating through the mini data explorer. Once your connection is set, the data source is added as a map layer to your map.

SQL query sources

You can perform a custom SQL query source that will act as your input source. Here you can select the precise columns for better performance and customize your analyses according to your need.

Best practices for SQL Query sources

• Ensure you use the appropriate alias for the Spatial Data Column in your query, in line with the Spatial Data Column Naming Convention outlined earlier.

• SQL Editor is not designed for conducting complex analysis or detailed step-by-step geospatial analytics directly, as Builder executes a separate query for each map tiles. For analysis requiring high computational power, we recommend two approaches:

  • Materialization: Consider materializing the output result of your analysis. This involves saving the query result as a table in your data warehouse and use that output table as the data source in Builder.

  • Workflows: Utilize CARTO Workflows for conducting step-by-step analysis. This allows you to process the data in stages and visualize the output results in Builder effectively.

Map layers

Depending on the type and size of data source, different layer types will be available:

• For small tables, you have different styling options depending on your geometry type:

  • Point: You can either visualize your point geometry without aggregation or you can apply aggregated styles such as Grid, Hexbins, Cluster or Heatmap

  • Line or Polygon: You can visualize your line or polygon geometry without aggregation once the full dataset has been loaded in Builder

Note that Grid, Hexbins, Cluster or Heatmap aggregated styles are not based on Spatial Indexes, the aggregation is performed visually, at rendering time. Due to that, they offer limited analytical capabilities.

• For SQL Queries and larger tables, regardless of the type of geometry, data will be loaded progressively as tiles. For this type of source, you have the following options:

  • Point: You can either visualize your point geometry loaded as tiles or dynamically aggregate point into a grid.

  • Line or Polygon: You can visualize line or polygon geometry loaded as tiles.

• Grid layers based on Spatial Indexes (H3 and Quadbin) are always loaded progressively. Working with an aggregated grid requires that the properties used for styling, widgets and pop-ups are also aggregated. Because of this, all property selectors will let you select an aggregation operation for each property.

• When using pre-generated Tilesets the data will be loaded progressively according to the configuration of your tileset. For more info about how to create pre-generated tilesets check this guide.