MaxCompute AI数据探索客户端

下载与安装

界面概览

客户端采用三栏布局：

• 左侧栏：资源管理区，包含文件管理、Catalog 浏览、数据连接、数据导入、SQL 知识库搜索、查询历史、文件版本历史等面板，通过左侧图标切换。

• 中间区域：SQL 编辑和数据展示区，支持多 Tab 页并行操作。

• 右侧栏：AI 助手面板，可展开或收起。

客户端支持深色和浅色两种主题，可在设置中切换。

配置数据连接

1. 点击左侧栏的连接图标，打开数据连接面板。

2. 点击添加连接按钮。

3. 填写连接信息：

   • 连接名称：为该连接取一个便于识别的名称。

   • 区域：从下拉列表选择 MaxCompute 项目所在的 Region，或选择"自定义 Endpoint"手动输入。

   • 项目名称：填写 MaxCompute 的 Project Name。

   • AccessKey ID 和 AccessKey Secret：填写具有对应项目访问权限的 AccessKey。

4. 点击测试连接验证配置是否正确。

5. 测试通过后，点击保存。

连接成功后，左侧 Catalog 面板会自动加载该项目下的表结构。

执行查询

1. 按快捷键 Option+N 或在文件面板中点击新建，创建一个 SQL 文件。

2. 在编辑器中输入一条查询语句，例如：

   SELECT * FROM your_table_name LIMIT 10;

3. 按 Cmd+Enter（macOS）执行查询。

4. 查询结果将在编辑器下方的结果面板中展示，可以切换表格视图、图表视图或透视表视图对结果进行分析。

配置 AI 服务

1. 点击右上角齿轮图标打开设置。

2. 进入 AI 配置标签页。

3. 填写以下信息：

   • API URL：AI 服务地址，默认为阿里云百炼 https://dashscope.aliyuncs.com/compatible-mode/v1/。

   • API Key：前往阿里云百炼控制台首页，在页面右上角选择华北2（北京）地域，进入API Key页面，单击创建API Key或复制已有API Key。

   • 模型名称：默认qwen3-max-2026-01-23，也可填写其他兼容 OpenAI 接口的模型。

4. 点击保存。

配置完成后，右侧 AI 助手面板即可使用。可以直接输入自然语言问题开始数据探索。

AI 数据探索

完成以上配置后，在 AI 助手面板中尝试以下操作：

1. 输入“查看当前项目有哪些表”，AI 会自动列出当前项目下的表。

2. 选择一张表，输入“查看这张表的结构和前 10 条数据”。

3. 看到结果后，输入一个分析问题，例如“分析这张表中各分区的数据量分布”。

AI 助手会自动规划执行步骤、生成 SQL、执行查询并给出分析结论，全程可在界面上观察执行过程。

新建链接

1. 在左侧栏点击连接图标，打开数据连接面板。

2. 单击添加连接。

3. 填写以下配置项：

   配置项	说明
   连接名称	自定义名称，用于在连接列表中区分不同连接。
   区域	选择 MaxCompute 项目所在的 Region，系统会自动填充对应的 Endpoint。
   项目名称	MaxCompute 的 Project Name。
   AccessKey ID	阿里云账号的 AccessKey ID。
   AccessKey Secret	阿里云账号的 AccessKey Secret。

4. 单击测试连接，确认连接可用。

5. 单击保存完成创建。

连接测试与诊断

点击测试连接后，客户端会尝试连接 MaxCompute 服务并获取项目信息。如果连接失败，请检查以下事项：

• Endpoint 是否与项目所在 Region 匹配。

• AccessKey 是否正确且未过期。

• 当前网络环境是否可以访问对应 Region 的 MaxCompute 服务。

• 使用的 AccessKey 对应的账号是否具有该 Project 的访问权限。

多连接管理

数据连接面板以列表形式展示所有已保存的连接。可以：

• 切换连接：

  点击目标连接即可切换当前活动连接。SQL 执行、Catalog 浏览、数据导入等操作都会在当前活动连接下执行。

• 删除连接：

  点击连接上的删除图标，移除该连接。如需修改连接配置，可删除后重新创建。

支持同时保存多个不同 Region 或不同 Project 的连接，在生产环境、测试环境、不同业务项目之间快速切换。

SQL 编辑器

客户端内置基于 Monaco 的 SQL 编辑器，提供接近 IDE 的编辑体验。

• 语法高亮与智能补全

  编辑器对 MaxCompute SQL 语法进行高亮着色，并在输入过程中提供上下文感知的智能补全，包括 SQL 关键词、MaxCompute 内置函数、当前连接下的表名和列名。补全列表会根据光标位置自动过滤，输入表名后紧跟. 会自动弹出该表的列名补全。

• 代码编辑

  编辑器支持代码折叠、括号配对着色、自动换行、Minimap 代码缩略图等常用编辑功能。按 Shift+Option+F 可对当前 SQL 进行自动格式化。

SQL 脚本管理

左侧栏的文件面板映射本地文件系统中的 SQL 文件。

• 新建文件

  按 Option+N（Mac OS） 创建新的 SQL 文件。

• 打开文件

  在文件面板中点击已有 SQL 文件，在编辑器中打开。

• 保存文件

  按 Option+S（Mac OS） 保存当前编辑内容。

• 多 Tab 操作

  同时打开多个 SQL 文件，通过 Tab 页切换。

SQL 文件版本管理

客户端为每个 SQL 文件维护版本历史。点击左侧栏的版本历史图标，可以查看当前文件的历史版本列表。

每个版本记录包括版本号、保存时间和版本类型。版本类型分为两种：手动保存（主动保存时创建）和执行前快照（执行 SQL 前自动创建的备份）。

对版本可执行以下操作：

• 对比差异：双击某个版本，打开 Diff 视图，对比该版本与当前内容的差异。

• 恢复版本：将文件内容恢复到指定版本。

• 删除版本：清理不再需要的历史版本。

SQL 执行

客户端提供三种执行方式：

• 全文执行：按 Cmd+Enter，依次执行编辑器中的所有 SQL 语句。

• 选中执行：选中一段 SQL 文本后按 Shift+Enter，仅执行选中部分。

• 单句执行：编辑器在每条 SQL 语句的行间显示运行按钮，点击即可执行该条语句。

如果 SQL 文件中包含 SET 语句（如 SET odps.sql.type.system.odps2=true;），客户端会自动将 SET 配置合并到后续 SQL 语句中一起执行。

执行过程中，编辑器下方会展示进度条和运行状态。执行完成后，DQL（查询语句）结果以表格形式展示，DDL / DML 等语句展示执行状态。

查询结果分析

查询返回结果后，可通过以下方式深入分析。

查询历史

点击左侧栏的历史图标，可以浏览所有已执行查询的记录。每条记录展示执行时间、耗时（毫秒）、SQL 语句预览、执行状态（成功 / 失败）和返回行数。点击某条记录，可将该 SQL 回填到编辑器中。

查询历史支持分页加载，便于回顾和复用历史查询。

Catalog 浏览

在左侧栏点击 Catalog 图标，以树形结构展示当前连接项目下的所有表。展开任意一张表，可以查看该表的列定义（列名、数据类型、注释）。

右键点击表名，可快速执行以下操作：

• 数据预览：查看该表的前几条数据。

• 查看表结构：展示完整的列信息、分区键、表属性等。

• 查看表信息：展示表容量、记录数、最近修改时间、权限等元数据。

如果保存了多个连接，Catalog 会展示所有已连接项目的表结构，便于在多项目之间对照浏览。

数据预览

在 Catalog 中选择一张表，可直接预览表中的数据。系统会自动执行一条带 LIMIT 的查询语句，将结果以表格形式展示在中间区域。

分区管理

支持在 Catalog 中查看已有的分区列表，同时也支持为分区表添加新分区。

数据导入

客户端支持将本地文件导入 MaxCompute 表。点击左侧栏的数据导入图标，进入导入面板。

数据导出

查询结果支持导出为以下格式：

• CSV：以逗号分隔的文本文件，兼容 Excel 等工具。

• JSON：结构化 JSON 格式。

• Parquet：列式存储格式，适合大数据场景下的二次处理。

在查询结果面板中，点击导出按钮并选择目标格式即可。

对话模式与 Agent 模式

AI 助手提供两种工作模式：

对话模式适合快速问答和轻量级操作，例如解释 SQL 含义、优化 SQL 写法、对当前查询结果给出洞察建议。您的问题会直接由 AI 生成回复，不涉及多步执行。

Agent 模式适合需要多步骤完成的数据分析任务。AI 会先制定执行计划（Plan），经您确认后逐步执行，包括查询元数据、生成 SQL、执行查询、分析结果并输出结论。

对话模式

在 AI 面板的输入框中直接输入问题即可进入对话模式。常用场景包括：

• SQL 生成：描述查询需求，AI 生成对应的 MaxCompute SQL。

• SQL 优化：在编辑器中打开一段 SQL，请求 AI 给出优化建议，优化后的 SQL 可一键插入编辑器。

• SQL 解释：选中一段复杂 SQL，让 AI 逐段解释逻辑含义。

• 结果洞察：执行查询后，针对结果数据请求 AI 提供趋势分析、异常发现等洞察。

Agent 模式

当您提出一个涉及多步操作的分析问题时，AI 自动进入 Agent 模式。

AI 工作区

AI 工作区是 Agent 执行产物的本地持久化空间。每次 AI 分析任务执行过程中产生的中间结果和最终产物，都会自动保存到工作区中。

应用场景

SQL 片段知识库

SQL 片段知识库用于管理可复用的 SQL 模板，适合管理周期性的取数脚本。将标准化的业务 SQL 维护在知识库中，配合 AI 的日期改写能力，可以快速获取不同时间段的报表数据。将日常使用的 SQL 文件导入知识库，系统会自动从文件中识别和抽取独立的 SQL 片段，并为每个片段提取表名、关键词、分区字段和日期字面量，建立全文索引。

在左侧栏点击搜索图标，可以按关键词搜索知识库中的 SQL 片段。找到后可以将片段插入编辑器执行，也可以通过 AI 助手调用“执行 SQL 片段”能力，让 AI 自动匹配和改写日期后执行。

语义层

语义层是 MaxCompute 客户端与通用 AI 工具的关键差异。它将数据库中的表和列，映射为业务可理解的术语、指标和关联关系。AI 在生成 SQL 时会参考语义层信息，从而产出更准确的查询。

语义层包含以下组成部分：

• 业务术语：定义业务领域的专有名词及其含义，例如DAU表示日活跃用户数。

• 实体定义：描述核心业务对象及其对应的表和关键字段。

• 指标定义：定义业务指标的计算公式和口径，例如转化率 = 下单用户数 / 访问用户数。

• 表关联关系：描述表之间的 JOIN 关系和关联键。

• 已验证查询：经过确认的标准查询模板，AI 在遇到相似问题时可直接复用。

• 分析剧本（Playbook）：预设的分析场景和步骤模板，指导 AI 按照标准流程完成分析。

内置语义包

客户端内置了 Information Schema 语义包，覆盖 MaxCompute 租户级元仓的常用分析场景，包括存储压力诊断、成本压力诊断、作业性能分析、任务失败激增分析、用户角色审计、权限暴露审计、热点表观测和资源配额监控。

启用该语义包后，直接向 AI 提出元仓分析问题（例如“分析当前项目的存储 Top 10 表”），AI 会基于语义包中的指标定义和参考查询生成准确的分析 SQL。

自定义语义包

针对个人业务场景创建自定义语义包。在语义层管理面板中，选择目标域后，可以逐项编辑术语、实体、指标、关联关系、已验证查询和分析剧本。也可以使用 AI 辅助功能，基于当前连接的表结构自动生成语义包初稿，再手动调整优化。

Blob 文件浏览器

MaxCompute 支持 Blob 类型列存储二进制文件数据。客户端提供文件浏览器界面（需启用文件浏览器 Beta 开关），以类似文件管理器的方式浏览 MaxCompute 中存储 Blob 数据的表。

文件浏览器支持网格视图和列表视图切换、面包屑导航、文件夹创建和文件上传下载。

Blob 文件导入

在数据导入面板中，切换到 Blob 导入模式，可以通过拖拽方式批量上传文件到 MaxCompute 的 Blob 表中。系统会自动提取文件路径、名称、类型等元信息写入表的对应列。

如果目标表尚不存在，客户端会辅助生成包含 Blob 列的建表语句。

多模态文件预览

客户端内置多模态文件预览能力，支持以下格式：

系统根据文件的 MIME 类型自动匹配预览方式，也支持手动切换。

WebDAV 挂载

客户端内置 WebDAV 服务，可以将 MaxCompute 中存储 Blob 文件的表挂载为操作系统的本地文件夹。挂载后，可以直接在 Finder 中预览和下载文件，无需通过客户端界面操作。

macOS 挂载方式：

在 Finder 中按 Cmd+K，输入 http://localhost:8899/dav/，即可以网络文件夹形式浏览 Blob 表中的文件数据。

OpenClaw Sub-Agent

MaxCompute 客户端可以作为 OpenClaw 的 Sub-Agent 接入，承接 OpenClaw 下发的数据分析任务。

在这种模式下，OpenClaw 负责总控和任务编排，MaxCompute 客户端负责专业的数据分析执行。两者的协作优势在于：

• 安全隔离：MaxCompute 的连接认证信息保留在客户端本地管理，OpenClaw 侧不需要配置 AccessKey。

• 证据链完整：OpenClaw 侧保持简洁的对话体验，详细的执行过程（Plan、SQL、中间结果、诊断信息）沉淀在客户端中，可随时回溯。

• 扩展分析：OpenClaw 得到的分析结论，可以继续在客户端的 Studio 模式下深入分析和导出。

# 安装 MaxCompute 插件
openclaw plugins install @maxcompute/openclaw-maxquery --pin

# 启用插件并配置连接地址
openclaw plugins enable maxquery
openclaw config set plugins.entries.maxquery.enabled true
openclaw config set plugins.entries.maxquery.config.baseUrl http://127.0.0.1:8899

编辑器设置

AI 配置

AI 高级配置

主题切换

客户端支持深色和浅色两种主题，可在设置中切换。

版本更新

客户端支持自动检查更新。当有新版本可用时，会在应用内提示您下载安装。

MacOS 安装时提示“应用已损坏”或“无法验证开发者”

这是 macOS Gatekeeper 安全机制导致的，不影响应用安全性。打开终端执行以下命令后重新启动应用：

sudo xattr -rd com.apple.quarantine "/Applications/MaxCompute.app"

连接问题

• 连接测试失败

  请依次排查以下事项：

  1. 确认 Endpoint 与 MaxCompute 项目所在 Region 匹配。如果不确定，可以在 MaxCompute 控制台查看项目详情。

  2. 确认 AccessKey ID 和 Secret 填写正确，且 AccessKey 未被禁用或过期。

  3. 确认当前网络可以访问对应 Region 的 MaxCompute 公网 Endpoint。如果处于 VPN 或代理环境，确认网络策略允许出站连接。

  4. 确认 AccessKey 对应的账号已被授权访问目标 Project。

• 连接超时

  通常由网络原因导致。如果使用的是跨境 Region（例如从中国内地访问海外 Region），可能因网络延迟较高导致超时。建议检查网络连通性或联系网络管理员。

SQL 执行问题

• SQL 执行报语法错误

  MaxCompute SQL 与标准 SQL 存在部分差异。客户端内置了 MaxCompute SQL 兼容性规则，会在执行前自动进行部分语法转写（例如将 NOW() 转为 GETDATE()），但不覆盖所有情况。建议参阅 MaxCompute SQL 官方文档确认语法。

• 查询返回数据量过大

  客户端默认对查询结果进行行数限制以保证响应速度。如果需要获取更多数据，建议在 SQL 中显式使用 LIMIT 控制返回量，或通过数据导出功能获取完整结果。

AI 配置问题

• AI 助手无法使用

  请确认已在设置中正确配置 AI 服务的 API URL、API Key 和模型名称。默认配置使用阿里云百炼（DashScope），您需要先在百炼控制台创建 API Key。

• AI 响应速度慢

  AI 响应速度受模型服务负载和网络状况影响。如果希望更快的响应，可以在 AI 高级配置中将推理档位切换为 fast，或更换响应更快的模型。

导入导出问题

• Excel 文件导入后列类型不正确

  客户端在解析 Excel 时会自动推断列类型。如果推断结果不符合预期，可以在新建表模式下手动修改 DDL 中的列类型定义，或使用 AI 生成 DDL 功能获取更准确的类型推断。

• Parquet 文件导出后无法打开

  导出的 Parquet 文件遵循 Apache Parquet 标准格式，可使用 Python（pandas / pyarrow）、Spark 或其他支持 Parquet 的工具读取。