carto-connect-datawarehouse

carto-connect-datawarehouse

CARTO 在用户自己的数据仓库中运行空间分析。连接是 CARTO 与该数据仓库之间的桥梁：它承载凭据、目标项目／数据库范围设置，有时还包括服务账号或 PAT。大多数其他 CARTO 操作（查询、导入、构建地图、运行工作流）都需要已有连接。

任务	MCP	CLI（备用）
列出／检查连接	explore_data（任何会话均可使用 list_connections；get_connection 仅限 OAuth）	carto connections list / get
创建／更新连接	manage_connections（create、update）——仅限 OAuth 会话	carto connections create / update
删除连接	delete（kind=connection）——仅限 OAuth 会话	carto connections delete

访问路径路由。 使用已连接的 MCP 服务时，通过 explore_data（list_connections）列出连接；通过 manage_connections 创建／更新连接；通过 delete 删除连接。Token 会话仅支持 list_connections——get_connection 和写入工具（manage_connections、delete）需要 OAuth，因此请改用 carto connections CLI。服务器未连接或需要脚本化设置时，也请使用 CLI。以下关于引擎选择的指南和注意事项适用于两种路径。检测信号：carto-basics/references/access-paths.md。

何时使用此技能

• 用户想将新的数据仓库连接到 CARTO。
• 用户正在排查连接问题（身份验证失败、缺少表、权限错误）。
• 下游技能需要连接名称，但你还不知道用户使用的是哪个引擎。
• 用户正在轮换凭据，或从一个项目／数据库迁移到另一个项目／数据库。

连接建立后，如果你想检查其中的内容，请使用 carto-explore-datawarehouse。

快速生命周期（CLI）

carto connections list --json             # what's already connected? (--all, --search "prod")
carto connections get <id>                # detailed view of one connection
carto connections create                  # interactive create
carto connections update <id>             # rotate credentials, change scoping
carto connections delete <id>             # remove (irreversible)

列出／检查连接不会产生破坏性影响——在决定下一步操作前，可以随时执行。如果用户已有连接，请勿强行创建新连接——使用现有连接。

选择引擎

引擎	选择时机	参考
BigQuery	Google Cloud 用户；CARTO 的旗舰级集成；原生 GIS 函数丰富。	references/bigquery.md
Snowflake	使用 Snowflake 的客户；通过 SQL 函数和原生类型支持地理空间数据。	references/snowflake.md
Redshift	使用 AWS 的客户，采用 Redshift Serverless 或 RA3 集群。	references/redshift.md
Postgres	自托管或 RDS Postgres 搭配 PostGIS；常用于中小型部署。	references/postgres.md
Databricks	Lakehouse / Unity Catalog 用户；使用 SQL Warehouses 处理交互式工作负载。	references/databricks.md
Oracle	配备 Spatial 的 Oracle Database；可部署在本地或 OCI / Autonomous Database。	references/oracle.md

常见注意事项

• 身份验证模式不匹配：BigQuery 支持 OAuth（交互式）和服务账号 JSON（CI）。请在每个环境中始终使用同一种模式；混用会导致共享连接失效。
• 区域与项目：有些引擎既需要账号／项目，也需要区域（Snowflake、Redshift）。未指定区域通常会导致“找不到端点”，而不是权限错误。
• 默认数据库／架构范围设置：CARTO 会将瓦片集、命名数据源和分析输出写回数据仓库。创建连接前，请确认 CARTO 可以写入哪个数据集／架构。
• 描述和读取表格所需的权限来自 CARTO 持有的凭据，而非用户的 CARTO 角色。即使 CARTO Admin 使用的是权限较低的服务账号，也仍会从数据仓库收到“权限被拒绝”错误。

此技能不涵盖的内容

• 浏览现有连接中的表/架构 — carto-explore-datawarehouse。
• 在数据仓库中运行 SQL — carto-query-datawarehouse。
• 将文件导入数据仓库 — carto-import-export-data。