cartodb carto-explore-datawarehouse
Before writing SQL or building maps, an agent usually needs to know what's in the warehouse. This skill covers discovery, matched across MCP and CLI:
| Task | MCP (primary) | CLI (fallback) |
|---|---|---|
| List / inspect connections | explore_data (list_connections, get_connection) |
carto connections list / get |
| Walk the hierarchy (project → dataset → table) | explore_data (list_resources) |
carto connections browse |
| Full-text find a resource | explore_data (search) |
— |
| Columns + types for a table | explore_data (describe) |
carto connections describe |
| Find / inspect a named source | manage_named_sources (list, get) |
carto named-sources list / get |
Access-path routing.
explore_dataworks on any attached MCP session, but not all its methods do on a token:list_connections,list_resources, andsearchneed only the MCP Server scope, whiledescribeadditionally needs the Maps API on a token session (it's always available over OAuth).manage_named_sourcesis an authoring tool, so it needs an OAuth session (it's hidden on token sessions). Use thecarto connections/carto named-sourcesCLI when the server isn't attached, when a token lacks the scope fordescribe, or when the exploration is scripted/headless. Detection signals and the full routing table:carto-basics/references/access-paths.md.
When to use this skill
- You don't know which tables / schemas exist in a connection.
- You need a column list and types before writing SQL or authoring a map.
- The user references "the named source for X" and you need to find it.
If you already know the table and just want to query it, jump to carto-query-datawarehouse.
Path syntax by engine
The path passed to list_resources / describe (or connections browse / describe) depends on the engine:
| Engine | Path shape |
|---|---|
| BigQuery | project.dataset.table |
| Snowflake | DATABASE.SCHEMA.TABLE |
| Postgres / Redshift | schema.table (no leading project/database) |
| Databricks | catalog.schema.table |
CLI examples:
carto connections browse <name> # top level
carto connections browse <name> "carto-demo-data.demo_tables" # drill in
carto connections describe <name> "carto-demo-data.demo_tables.nyc_collisions"
What's in this skill
| Topic | Reference |
|---|---|
| Browsing and describing a connection in detail | references/connection-browse.md |
| Named sources — what they are, how to list and inspect them | references/named-sources.md |
Always-on guidance
- Browse before you query. A two-second
list_resourcesusually saves a five-minute "table not found" loop. describereturns column types — use them to write correct SQL (e.g. don'tST_DWithinagainst aSTRINGcolumn mistakenly namedgeom).- Paginate long lists — CLI
browsedefaults to--page-size 30; bump it for datasets with hundreds of tables. - Named sources ≠ tables. They're parameterized queries — inspect the underlying tables before assuming a column you see in the source exists in raw form.
carto-demo-datais a public BigQuery dataset CARTO ships — browsing it works on any BigQuery connection with the right IAM, a fast way to validate a fresh connection without touching customer data.