Back to Details

carto-connect-datawarehouse

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

carto-connect-datawarehouse

carto-connect-datawarehouse

CARTO runs spatial analytics in the user's own data warehouse. A connection is the bridge between CARTO and that warehouse: it carries credentials, target project/database scoping, and sometimes a service account or PAT. Most other CARTO operations (querying, importing, building maps, running workflows) require an existing connection.
CARTO在用户自有数据仓库中运行空间分析。连接是CARTO与该仓库之间的桥梁：它承载凭证、目标项目/数据库范围设定，有时还包含服务账户或PAT。CARTO的大多数其他操作（查询、导入、构建地图、运行工作流）都需要已建立的连接。

When to use this skill

何时使用此技能

  • The user wants to connect a new warehouse to CARTO.
  • The user is debugging a connection (auth failures, missing tables, permission errors).
  • A downstream skill needs a connection name and you don't yet know which engine the user has.
  • The user is rotating credentials or moving from one project/database to another.
Use 
carto-explore-datawarehouse
 once a connection exists and you want to inspect what's inside it.
  • 用户想要将新仓库连接到CARTO。
  • 用户正在调试连接问题（认证失败、表缺失、权限错误）。
  • 下游技能需要连接名称，但你还不知道用户使用的是哪种引擎。
  • 用户正在轮换凭证，或从一个项目/数据库迁移到另一个。
当连接已建立且你想要查看仓库内的内容时，请使用
carto-explore-datawarehouse
。

Quick lifecycle

快速生命周期

bash
carto connections list --json             # what's already connected?
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)
connections list
and 
connections get
are non-destructive — agents should run them freely before deciding what to do.
bash
carto connections list --json             # what's already connected?
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)
connections list
和
connections get
是无破坏性操作——Agent可以在决定下一步操作前自由运行这些命令。

Choosing an engine

选择引擎

EngineWhen to choose itReference
BigQueryGoogle Cloud users; CARTO's flagship integration; rich GIS functions native.references/bigquery.md
SnowflakeSnowflake-shop customers; geospatial via SQL functions and Snowflake-native types.references/snowflake.md
RedshiftAWS-shop customers on Redshift Serverless or RA3 clusters.references/redshift.md
PostgresSelf-hosted or RDS Postgres with PostGIS; common for small/medium deployments.references/postgres.md
DatabricksLakehouse / Unity Catalog users; SQL Warehouses recommended for interactive workloads.references/databricks.md
OracleOracle Database with Spatial; on-prem or OCI / Autonomous Database deployments.references/oracle.md
If the user already has a connection (
connections list
returns at least one), don't push a new one — use the existing one.
引擎适用场景参考文档
BigQueryGoogle Cloud用户；CARTO的旗舰集成；原生支持丰富的GIS功能。references/bigquery.md
SnowflakeSnowflake客户；通过SQL函数和Snowflake原生类型实现地理空间分析。references/snowflake.md
Redshift使用Redshift Serverless或RA3集群的AWS客户。references/redshift.md
Postgres搭载PostGIS的自托管或RDS Postgres；适用于中小型部署。references/postgres.md
DatabricksLakehouse / Unity Catalog用户；交互式工作负载推荐使用SQL Warehouses。references/databricks.md
Oracle搭载Spatial的Oracle数据库；支持本地部署或OCI / 自治数据库部署。references/oracle.md
如果用户已有连接（
connections list
返回至少一个结果），请勿创建新连接——使用现有连接即可。

Listing options

列出选项

bash
carto connections list                    # default page (10)
carto connections list --all              # all pages
carto connections list --search "prod"    # filter by name
carto connections list --json             # machine-readable
bash
carto connections list                    # default page (10)
carto connections list --all              # all pages
carto connections list --search "prod"    # filter by name
carto connections list --json             # machine-readable

Common pitfalls

常见陷阱

  • Auth-mode mismatch: BigQuery supports OAuth (interactive) and service-account JSON (CI). Pick one consistently per environment; mixing the two breaks shared connections.
  • Region vs project: Some engines need both an account/project and a region (Snowflake, Redshift). Skipping the region typically yields "endpoint not found" rather than a permissions error.
  • Default database/schema scoping: CARTO can write tilesets, named sources, and analytics output back into the warehouse. Confirm with the user which dataset/schema CARTO is allowed to write to before creating the connection.
  • Permissions for 
    connections describe
    and table reads come from the credential CARTO holds, not from the user's CARTO role. A CARTO Admin with a low-privilege service account will still see "permission denied" from the warehouse.
  • 认证模式不匹配：BigQuery支持OAuth（交互式）和服务账户JSON（CI）。每个环境需一致选择其中一种模式；混合使用会导致共享连接失效。
  • 区域与项目混淆：部分引擎同时需要账户/项目和区域（Snowflake、Redshift）。跳过区域通常会导致“端点未找到”错误，而非权限错误。
  • 默认数据库/模式范围设定：CARTO可以将瓦片集、命名数据源和分析结果写回仓库。创建连接前，请与用户确认CARTO被允许写入的数据集/模式。
  • 权限：
    connections describe
    和表读取的权限来自CARTO持有的凭证，而非用户的CARTO角色。即使是CARTO管理员，如果使用低权限服务账户，仍会收到仓库返回的“权限被拒绝”错误。

What this skill doesn't cover

本技能不涵盖的内容

  • Browsing tables/schemas of an existing connection — that's 
    carto-explore-datawarehouse
    .
  • Running SQL against the warehouse — that's 
    carto-query-datawarehouse
    .
  • Importing files into the warehouse — that's 
    carto-import-export-data
    .
  • 浏览现有连接的表/模式——这属于
    carto-explore-datawarehouse
    的功能范围。
  • 在仓库上运行SQL——这属于
    carto-query-datawarehouse
    的功能范围。
  • 将文件导入仓库——这属于
    carto-import-export-data
    的功能范围。