How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/cartodb/agent-skills --skill carto-explore-datawarehouseBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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, while `describe` additionally 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:
bash
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. - `describe` returns column types — use them to write correct SQL (e.g. don't
ST_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-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.
