carto-explore-datawarehouse

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_data works on any attached MCP session, but not all its methods do on a token: list_connections, list_resources, and search need only the MCP Server scope, while describe additionally needs the Maps API on a token session (it's always available over OAuth). manage_named_sources is an authoring tool, so it needs an OAuth session (it's hidden on token sessions). Use the carto connections / carto named-sources CLI when the server isn't attached, when a token lacks the scope for describe, 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_resources usually saves a five-minute "table not found" loop.
• describe returns column types — use them to write correct SQL (e.g. don't ST_DWithin against a STRING column mistakenly named geom).
• Paginate long lists — CLI browse defaults 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-data is 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.