数据目录与 SQL

打开 数据 → 数据目录.

本地表

1. 1

   上传

   拖入一个 .csv 或 .xlsx，或直接粘贴数据行。第一行会被当作表头。
2. 2

   核对推断出的列类型

   一列 2024-03-01 必须是 日期类型，而不是文本，否则日期筛选和时序图表后面都用不了。现在就改掉——等仪表板搭好之后再改要麻烦得多。
3. 3

   取名要考虑模型

   monthly_revenue 被智能体选对的概率远高于 sheet1。小写、下划线、不要空格。

外部连接——逐个字段说明

在这里配置： 集成 → 数据源 → 添加连接。每个连接器都有一个 名称 （你自己的标签）和一个 测试连接 按钮；最近一次测试的结果与报错会保存在该连接上，方便你看出它是从什么时候开始失败的。所有密钥都加密存储，绝不回传给浏览器。

PostgreSQL

MySQL / MariaDB

Microsoft SQL Server / Azure SQL

通过 tedious 驱动使用 TDS 协议，因此需要 Node 或 Docker 部署 ——没有 REST SQL API 可以退而求其次。

ClickHouse

使用 HTTP 接口，因此任何部署方式都可用。

Snowflake

使用 编程访问令牌（PAT），而不是密码——在 Snowflake 的用户设置中生成。

Databricks SQL

该 warehouse_id 取自该 SQL 数仓的 连接详情 页签中。

Google BigQuery

Amazon Redshift

两种形态： Serverless （设置 workgroup_name）或 预置型 （设置 cluster_identifier 和 db_user）。只填其中一组，不要都填。

Azure Synapse（专用 SQL 池）

Trino / Starburst / Presto

Amazon Athena

Oracle Database / Autonomous DB

通过 ORDS 连接——纯 HTTPS，因此不需要 wallet，也不需要 Instant Client。Autonomous Database 默认已启用 ORDS。

对象存储与湖仓目录

S3、GCS 及兼容端点是作为 数据目录数据源 添加的，而不是查询连接——它们会被抓取，文件被登记为数据集。Iceberg REST 与 Unity Catalog 接入的是元数据。两者都在这里配置： 数据目录 → 添加数据源.

直接查询与导入的取舍

把连接共享给团队

连接归创建者所有。与其让每个分析师各建一个（同一份凭据存了好几份，各自轮换，每一份都是一个泄漏点），超级管理员可以在这里共享它： 管理 → IAM → 访问控制，共享给某个用户或用户组，形式可以是 数据库 / 数据仓库连接 或 应用数据源.

共享连接以其所有者的身份运行。 凭据 就是 这个连接本身——被授权者并没有自己的凭据——所以所有者的凭据在服务端解密，查询打到所有者的数仓上。被授权者可以查询、测试、查看健康状况；但看不到凭据，也不能修改或删除它。 {{secret:NAME}} 引用是按所有者身份解析的，绝不会用被授权者自己的密钥库。

共享的 应用数据源 以所有者身份同步，写入所有者的数据集——这样发现数据过期的同事可以直接重跑并刷新真实数据集，而不是在自己账号下再建一份平行副本。审计记录会同时记下是谁触发的、动的是谁的数据。共享数据源让人能维护它；若还要让对方读取同步出来的数据，那些数据集也要一并共享。

应用——SaaS 数据源

数据库是 就地查询的。应用没有查询语言，所以它们是被 拉取成数据集 ： 集成 → 应用 → 连接、发现里面有什么、选择要同步的内容。每条数据流各成一个数据集，之后与上传的 CSV 无从区分——同样的类型推断、同样的版本历史，在 BI、数据准备流程和语义层里同样可用。

认证一律是粘贴凭据，而不是 OAuth：重定向流程需要一个公网可达的回调 URL，而防火墙后的自托管部署可能没有，所以每个连接器都改用厂商的服务端到服务端凭据。

保持连接可用

每个连接底下都有三件事在自动运行，无需你操心。运维实例的人都可以调整——参见 自托管.

数据目录

查询数据 任意数据集上的这个操作都会在工作台中打开它，并已载入该表。

SQL 工作台

对任何已连接的数据写 SQL。结果可以作图、加入 仪表板，或导出为 CSV / Excel。

-- Monthly revenue and order count for the last 12 months
SELECT date_trunc('month', o.created_at) AS month,
       COUNT(*)                          AS orders,
       SUM(o.amount)                     AS revenue
FROM   orders o
WHERE  o.status = 'settled'
  AND  o.created_at >= current_date - INTERVAL '12 months'
GROUP  BY 1
ORDER  BY 1;

• 用自然语言提问 ——描述你的问题，助手来写 SQL。运行前先读一遍：它会明确告诉你这个答案依赖哪个联接和哪个筛选条件。
• 结果有条数上限 仅用于展示，同时会显示真实的匹配总数，因此失控的查询不会把页面卡死。

你的 SQL 由哪个引擎执行

针对 已连接数据仓库 的查询在该数仓上执行。针对 上传的表与已准备数据集 的查询运行在 DuckDB 上——工作台和“问 AI”在你的浏览器里跑，定时刷新、数据准备流程和智能体工具在服务端跑。

一次会话中的第一条查询会慢一些

该引擎是 WebAssembly，大约 8 MB，只下载一次，之后由浏览器缓存供后续访问使用。期间你会看到 “正在启动 SQL 引擎…” 以及一个进度条。

• 它的启动时机是 你一打开数据类页面，而不是等你按“运行”，所以通常在你还在选表的时候就已就绪。
• 它的下载频率是 每个浏览器一次，而不是每次查询、每个数据集或每个标签页一次。
• 它的来源是 你自己的部署，而不是 CDN——所以离网安装也能用，且没有第三方知道你加载过它。

把数据权限授予智能体

1. 1

   打开该智能体 → 工具

   启用 sql_query。同时启用 calculator ——参见下面的提醒。
2. 2

   设置允许访问的表

   只有列在这里的表智能体才看得到。留空意味着 sql_query 无表可查。
3. 3

   在系统提示词里提到这些数据

   e.g. “凡涉及计数、汇总或日期的问题都用 sql_query。能算出来的数字，绝不估算。”
4. 4

   用一个计数问题测试

   让它算一个总数。检查答案下方的来源是否指向那张表——如果指向的是文档，说明它是从文字里编出来的。

运行时智能体能看到每张表的名称、列和少量样本行，据此写出一条 SELECT，然后拿回真实数据行。

问题排查