Data tools
Data tools cover everything between your agent and the data: exploring connections and tables, running SQL, geocoding and routing, importing and exporting, moving data between warehouses, working with named sources, and enriching from the Data Observatory.
Explore and query
explore_data
Title: Explore Data
Explores connections and their data, read-only. Lists connections, inspects one, browses databases/schemas/tables, searches tables by name, and describes a table's or query's columns with per-column statistics.
Method: list_connections · get_connection · list_resources · search · describe
connection_name
string
For list_resources, search, describe
The connection to work in.
fqn
string
No
A fully-qualified name to browse (for list_resources).
query
string
For search; optional for describe
The search string, or the SQL query to describe.
table_fqn
string
For describe
The table to describe (alternative to query).
column
string
No
Return per-column stats instead of the schema (for describe).
Read-only.
execute_query
Title: Execute SQL Query
Runs a SQL query synchronously and returns rows. Best for quick SELECTs (about a one-minute timeout). For longer queries or DDL/DML, the agent uses execute_async_query.
connection_name
string
Yes
The connection to run against.
sql
string
Yes
The SQL to execute.
queryParameters
any
No
Named or positional query parameters.
Can modify data: runs arbitrary SQL.
execute_async_query
Title: Execute Async SQL Query
Runs SQL too slow or large for execute_query, or that changes data. Submits a job, reports status, and cancels.
Method: submit · status · cancel
connection
string
Yes
The connection to run against.
body
object
For submit
The query and any parameters.
jobId
string
For status, cancel
The job to check or cancel.
Can modify data.
Move data
Each of these submits a job and tracks it to completion via a submit / status method.
import_data
Title: Import Data
Loads a file into the warehouse from a URL, then tracks the job. body carries the connection, source URL, destination, and options. For the supported formats and the size limit, see:
CARTO supports importing CSV, GeoJSON, GeoPackage, KML, KMZ, TAB, Shapefiles (in a .zip package), and GeoParquet files. These formats can be imported into any connected data warehouse.
GeoTIFF raster files are also supported when importing into BigQuery, Snowflake, and Databricks connections. The resulting table follows the Raquet specification.
The size limit for file imports is 5 GB for all formats.
export_data
Title: Export Data
Exports a table or query result to a downloadable file (GeoParquet, GeoJSON, Shapefile, GeoPackage, CSV, and more). body carries the connection, source (table or SQL), and format.
transfer_data
Title: Transfer Data
Copies a table from one connection to another, with optional reprojection. body carries the source and destination connections and tables.
All three can modify data: they write to the warehouse or produce exports.
Location Data Services
These call CARTO's Location Data Services, and are read-only. Each takes an operation that includes a capabilities value to discover provider support.
geocode
Title: Geocode
Geocodes addresses to coordinates, or reverse-geocodes coordinates to addresses. operation: geocode · reverse · capabilities. Geocoding takes an addresses array (batched in one call); reverse takes lat/lon.
route
Title: Compute Route
Computes a route between an origin and destination with optional waypoints, returning geometry plus time and distance. operation: route · capabilities. Takes origin, destination, and travel mode.
calculate_isolines
Title: Calculate Isolines
Computes an isoline (catchment area) around an origin. operation: isolines · capabilities. Takes origin, mode, range, and range_type (time or distance).
calculate_od_matrix
Title: Calculate OD Matrix
Computes an origin-destination time/distance matrix. operation: od_matrix · capabilities. Takes origins and destinations arrays of [lon, lat] points.
All four are read-only.
Named sources and Data Observatory
manage_named_sources
Title: Manage Named Sources
Lists, inspects, creates, and updates named sources — reusable SQL or table references under a stable name. To remove one, the agent uses delete.
Method: list · get · create · update
name
string
For get, create, update
The named source's name.
source
string
For create, update
A SQL query or a fully-qualified table reference.
Can modify data.
search_data_observatory
Title: Search Data Observatory
Searches and browses the CARTO Data Observatory catalog of public and premium datasets.
Method: list_datasets · list_filters · search_variables · get_dataset · sample
searchText
string
No
Free-text catalog search (for list_datasets).
id
string
For get_dataset, sample
The dataset to inspect or sample.
Read-only.
manage_data_observatory_subscriptions
Title: Manage Data Observatory Subscriptions
Lists your Data Observatory subscriptions, subscribes to a dataset, or unsubscribes.
Method: list · subscribe · unsubscribe
Can modify data: subscribe and unsubscribe change your subscriptions.
Connections
manage_connections
Title: Manage Connections
Creates or updates a data warehouse connection (BigQuery, Snowflake, Databricks, Postgres, Redshift, Oracle). To list or inspect connections, the agent uses explore_data; to remove one, delete.
Method: create · update
body
object
Yes
The connection payload — full for create, partial for update.
id
string
For update
The connection to update (id or name).
Can modify data.
Last updated
Was this helpful?