carto-explore-datawarehouse

carto-explore-datawarehouse

在编写 SQL 或构建地图之前，Agent 通常需要先了解数据仓库中有什么。本技能涵盖在 MCP 和 CLI 中匹配使用的数据发现方式：

任务	MCP（首选）	CLI（备用）
列出 / 检查连接	explore_data（list_connections、get_connection）	carto connections list / get
浏览层级结构（项目 → 数据集 → 表）	explore_data（list_resources）	carto connections browse
全文搜索资源	explore_data（search）	—
查看表的列和类型	explore_data（describe）	carto connections describe
查找 / 检查已命名数据源	manage_named_sources（list、get）	carto named-sources list / get

访问路径路由。 explore_data 可用于任何已连接的 MCP 会话，但令牌会话无法使用它的所有方法：list_connections、list_resources 和 search 只需要 MCP Server 作用域，而令牌会话中的 describe 还需要 Maps API（OAuth 始终可用）。manage_named_sources 是创作工具，因此需要 OAuth 会话（令牌会话中会隐藏该工具）。当服务未连接、令牌缺少 describe 所需的作用域，或需要以脚本 / 无头方式进行探索时，请使用 carto connections / carto named-sources CLI。检测信号和完整路由表：carto-basics/references/access-paths.md。

何时使用此技能

• 你不知道某个连接中有哪些表 / 架构。
• 编写 SQL 或创作地图之前，需要列出列名和类型。
• 用户提到“X 的已命名数据源”，而你需要找到它。

如果你已经知道表名，只想查询数据，请跳转到 carto-query-datawarehouse。

各引擎的路径语法

传递给 list_resources / describe（或 connections browse / describe）的路径取决于引擎：

引擎	路径格式
BigQuery	project.dataset.table
Snowflake	DATABASE.SCHEMA.TABLE
Postgres / Redshift	schema.table（不带前导项目 / 数据库）
Databricks	catalog.schema.table

CLI 示例：

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"

本技能包含的内容

主题	参考文档
详细浏览和描述连接	references/connection-browse.md
已命名数据源——它们是什么，以及如何列出和检查	references/named-sources.md

始终适用的指导

• 查询前先浏览。 花两秒运行 list_resources，通常就能避免五分钟的“找不到表”循环。
• describe 会返回列类型——用这些信息编写正确的 SQL（例如，不要误把名为 geom 的 STRING 列用于 ST_DWithin）。
• 对长列表进行分页——CLI browse 默认的 --page-size 为 30；对于包含数百个表的数据集，请调大该值。
• 已命名数据源 ≠ 表。 它们是参数化查询——在假设数据源中看到的列以原始形式存在之前，先检查其底层表。
• carto-demo-data 是 CARTO 提供的公共 BigQuery 数据集——只要 BigQuery 连接具备相应的 IAM 权限，就可以浏览该数据集；这是一种快速验证新连接的方式，无需接触客户数据。