Data sources

CARTO Builder allows you to add sources by connecting directly with your data warehouses, ensuring security and data governance. Once a source is added, the related layer associated with the source is also rendered on the map. From this point, you can start styling your layer, adding widgets, and creating your interactive application.

Data sources types

Builder currently support the following data sources types:

• Simple features: Unaggregated features using standard geometry (point, line or polygon) and attributes, ready to use in Builder.

• Spatial Indexes: Aggregated data sources for improved performance or specific use cases, including Quadbin and H3 spatial indexes.

• Pre-generated tilesets: Tilesets pre-generated using CARTO Analytics Toolbox procedures or Workflows and stored directly in your data warehouse, ideal for handling very large, static datasets.

• Raster: A raster source is composed of grids of pixels, where each pixel contains a value representing specific information

Methods for adding sources

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: Connect directly to your data warehouse table through the data explorer dialog. Once connected, the data source is added including its related layer.

• SQL query sources: Perform a custom SQL qeury that will act as your input source. Once you execute it, if valid, a new data source and its linked layer will be added to the Builder.

Best practices for SQL Query sources

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: Use 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.

Adding data sources

To add sources in Builder, click on "Add source from" and choose from the following options:

• Data Explorer: Browse and add tables as sources from your existing connections or from CARTO Data Observatory.
• Custom Query (SQL): Write your own SQL query using the connection of your choice.
• Import file: Start the process of importing a file to a CARTO connection.

Partitioned BigQuery tables require a WHERE clause in the query filtering by the column used for the partition. If you need to load a BigQuery partitioned table in Builder, add it as a SQL Query source like:

SELECT *
FROM project.dataset.my_partitioned_table
WHERE partition_column = 'value'

Adding a source from Data Explorer

When adding a source from Data Explorer, you have the option to add a source from your existing connection or by adding data from the Data Observatory.

To add a source, navigate to the desired location, select your table and click 'Add Source'. The source and its associated layer will be added to the map.

Subscriptions are only available from CARTO Data Warehouse, BigQuery and Snowflake connections, while samples are only available from CARTO Data Warehouse and BigQuery connections.

Adding a source from a Custom Query (SQL)

Use the SQL Editor panel in Biulder to add a source by selecting a specific connection. Create your own SQL queries to perform simple analysis, create WHERE statements to pre-filter your data, or use SQL Parameters. You can also leverage CARTO Analytics Toolbox directly from this interface.

Adding source by importing a file

CARTO allows creating tables in your connectiosn by importing files from your computer or via URL. Once a file is imported, the resulting table can be previewed in Data Explorer and used in Builder and external applications.

Find more information about compatible data warehouses, supported formats, column names, and delimiters in our Importing Data documentation.