dot

dot — AI 数据分析师 CLI

dot 可让你通过 Dot（一位 AI 数据分析师）查询公司的数据库。 Dot 会编写 SQL、运行查询、生成图表并解释结果。

设置

如果未安装 dot 或无法在 PATH 中找到：

• macOS/Linux： curl -fsSL https://app.getdot.ai/install.sh | sh
• Windows： irm https://app.getdot.ai/install.ps1 | iex

安装后，使用 dot login 进行身份验证（会打开浏览器）。

适用场景

当用户询问以下内容时，使用 dot：

• 数据问题：“上个月的销售额是多少？”、“展示一下排名靠前的客户”
• 指标和 KPI：“我们的客户流失率是多少？”、“按地区划分的收入”
• SQL 查询：“编写一个查询来查找……”、“检查一下数据库……”
• 报告：“生成一份……的摘要”、“细分……”
• 用户说“问问 dot”、“查一下数字”或“查询数据”时

决策：目录还是提问

• 如果用户询问有哪些数据可用，运行 dot catalog
• 如果问题比较模糊（没有指定指标、表或时间段），先运行 dot catalog 了解可用内容，再提出有针对性的问题
• 如果用户提出了具体的数据问题，直接运行 dot "..."

使用方法

先发现可用数据

提问前，运行 dot catalog 查看可用数据：

dot catalog

此命令会立即返回（不会调用大模型），并显示：

• 可用功能（SQL、可视化、定时报告、文本分析）
• 为组织配置的自定义技能
• 数据源连接及其表数量
• 按使用情况排序的前 50 张表，以及描述和列数／行数
• 外部资源（Looker 仪表板等）

提出问题

通过 Bash 运行 dot，并将问题放在引号内。设置较长的超时时间——Dot 会运行完整的 AI 分析流程（生成 SQL、执行查询、生成可视化），耗时 15-60 秒；复杂查询有时最多需要 2 分钟：

dot "What were total sales last month?"

后续问题

每次回复都会包含一个聊天 ID。使用 --chat 继续对话：

dot "Now break down by region" --chat cli-m1abc2d-x4y5z6

何时绕过缓存

响应会被永久缓存。遇到以下情况时使用 --no-cache：

• 问题涉及“今天”、“现在”、“最新”或“当前”
• 用户说“刷新”、“更新”或“重新运行”
• 用户似乎对之前的回答不满意

dot "What are today's sales numbers?" --no-cache

收到响应后

1. 解析输出文本，并向用户展示解释
2. 如果显示了图表 PNG 路径（“Chart saved to: /tmp/dot/...png”），请读取 PNG 文件——你具备多模态能力，可以描述图表内容
3. 如果显示了 CSV 路径，且用户需要详细分析，请读取并分析 CSV 数据
4. 如果与用户的目标相关，请提供建议的后续问题
5. 如果用户想继续对话，请使用输出中的聊天 ID 和 --chat

输出格式

输出包括：

• 文本解释——对问题的自然语言回答
• SQL 查询——实际执行的 SQL
• 数据预览——以类似 CSV 的文本展示前几行及列统计信息
• 图表——以 PNG 格式保存到 /tmp/dot/<chat-id>/（请读取——你具备多模态能力）
• CSV 数据——保存在本地，以便进一步分析
• Dot URL——在浏览器中打开完整交互式分析的链接
• 建议的后续问题——相关时主动使用

多步分析

你可以编排多步数据分析：

1. 运行 dot catalog 了解可用数据
2. 使用 dot "..." 提出初始问题
3. 读取 CSV 输出，进行更深入的分析或自定义计算
4. 使用 --chat 提出后续问题，以完善结果
5. 比较多个查询的结果

缓存

• dot "question"——缓存永久有效，直到运行 --clear-cache
• 使用 --chat 提出的后续问题不会缓存（始终获取最新结果）
• dot catalog 不会缓存（本身速度很快，也不会调用大模型）

使用 --no-cache 强制发起新请求，或使用 --clear-cache 清除所有缓存数据。

提出好问题的技巧

• 从 dot catalog 开始，了解有哪些表和数据可用
• 尽量具体：包含指标名称、时间范围和筛选条件
• 一次只问一个问题效果最好
• 使用后续提问（--chat）进行细化，而不是提出复合问题
• 如果需要图表，请说“给我展示一张……图表”或“可视化……”

错误：找不到命令

如果找不到 dot，请告知用户安装它：

curl -fsSL https://app.getdot.ai/install.sh | sh
dot login

错误：未通过身份验证

如果收到“未通过身份验证”的提示，用户需要登录：

dot login

如果 dot login 无法正常工作（例如，没有可用的浏览器或 SSO 出现问题），用户可以手动创建 API 令牌：

1. 在浏览器中打开 Dot 仪表板（例如，https://app.getdot.ai 或贵公司的 Dot URL）
2. 前往 设置 > 用户 > API 令牌
3. 创建一个限定为该用户的令牌
4. 使用以下命令：dot login --token <TOKEN> --server <SERVER_URL>

错误：身份验证失败

如果收到“身份验证失败”的提示，令牌可能已过期。用户需要重新登录：

dot login

错误：连接失败

如果 dot 无法连接到服务，请告知用户检查互联网连接。 如果使用自定义服务，请通过 dot status 验证 URL。

调试

运行 dot status，检查当前登录用户、已配置的服务以及令牌是否过期。

示例

# See what data is available
dot catalog

# Simple question
dot "What were total sales last month?"

# With follow-up
dot "Compare to the same period last year" --chat cli-m1abc2d-x4y5z6

# Chart request
dot "Show me a chart of monthly revenue trend for the past 12 months"

# Specific filters
dot "Top 10 customers by order count in Q4 2025, US only"

# Force fresh answer (bypass cache)
dot "What were total sales last month?" --no-cache