MaxCompute:MaxCompute AI data exploration

Download and install

Console overview

The client uses a three-column layout:

• Left Sidebar: Resource Management Area, which contains panels such as File Management, Catalog Browsing, Data Connections, Data Import, SQL Knowledge Base Search, Query History, and File Version History. Use the icons on the left to switch between these panels.

• Middle Area: SQL Editing and Data Display Area, which supports multiple tabs.

• Right Sidebar: AI Assistant Panel, which you can expand or collapse.

The client supports both dark and light themes. You can switch between them in Settings.

Configure data connection

1. In the left sidebar, click the connection icon to open the data connection panel.

2. Click Add Connection.

3. Enter the connection information:

   • Connection Name: Enter a descriptive name for the connection.

   • Region: Select the region where your MaxCompute project is located from the drop-down list, or select "Custom Endpoint" to enter it manually.

   • Project Name: Enter the name of your MaxCompute project.

   • AccessKey ID and AccessKey Secret: Enter the AccessKey ID and AccessKey Secret for project access.

4. Click Test Connection to verify the configuration.

5. Once the test passes, click Save.

Once the connection is successful, the Catalog panel in the left sidebar automatically loads the table structure of the project.

Run query

1. Press Option+N or click New in the file panel to create a new SQL file.

2. In the editor, enter a query, for example:

   SELECT * FROM your_table_name LIMIT 10;

3. Press Cmd+Enter (on macOS) to run the query.

4. Query results appear in the Result Panel below the editor. To analyze the results, you can switch between Table View, Chart View, and Pivot Table View.

Configure AI service

1. Click the gear icon in the upper-right corner to open Settings.

2. Go to the AI Configuration tab.

3. Enter the following information:

   • API URL: The endpoint for the AI service. The default is the endpoint for Alibaba Cloud Model Studio: https://dashscope.aliyuncs.com/compatible-mode/v1/.

   • API Key: Go to the Alibaba Cloud Model Studio console. In the upper-right corner of the page, select the China (Beijing) region. Navigate to the API Key page and click Create API Key or copy an existing one.

   • Model Name: The default is qwen3-max-2026-01-23. You can also enter other models that are compatible with the OpenAI API.

4. Click Save.

After the configuration is complete, the AI Assistant panel on the right is ready to use. You can start exploring your data by asking questions in natural language.

AI data exploration

After completing the configuration, try the following in the AI Assistant panel:

1. Enter "List the tables in the current project." The AI Assistant then lists the tables.

2. Select a table and enter "Show the structure and first 10 rows of this table."

3. After reviewing the results, ask an analytical question, such as "Analyze the data volume distribution across partitions in this table."

The AI Assistant plans the steps, generates SQL, runs the query, and provides an analysis. You can observe this entire process in the interface.

Create a new connection

1. In the left sidebar, click the Connections icon to open the data connections panel.

2. Click Add Connection.

3. Configure the following parameters:

   Parameter	Description
   Connection Name	A custom name to identify the connection.
   Region	Select the region where your MaxCompute project is located. The client automatically populates the corresponding endpoint.
   Project Name	The name of your MaxCompute project.
   AccessKey ID	The AccessKey ID for your Alibaba Cloud account.
   AccessKey Secret	The AccessKey Secret for your Alibaba Cloud account.

4. Click Test Connection to verify the connection.

5. Click Save to create the connection.

Test and troubleshoot connections

When you click Test Connection, the client attempts to connect to the MaxCompute service and retrieve project information. If the connection fails, check the following:

• Ensure the endpoint matches the project's region.

• Verify that your AccessKey is correct and has not expired.

• Confirm that your current network environment can access the MaxCompute service in the specified region.

• Check that the Alibaba Cloud account associated with your AccessKey can access the project.

Manage multiple connections

The data connections panel lists all your saved connections. From here, you can:

• Switch connections:

  Click a connection to make it active. Operations such as SQL execution, Catalog browsing, and data import use the active connection.

• Delete a connection:

  Click the delete icon on a connection to remove it. To modify a connection, delete the existing one and create a new one.

You can save multiple connections for different regions or projects and quickly switch between production, testing, and various business environments or projects.

SQL editor

The client includes a built-in, Monaco-based SQL editor for an IDE-like experience.

• Syntax highlighting and intelligent completion

  The editor highlights syntax for MaxCompute SQL and provides context-aware intelligent completion as you type. Suggestions include SQL keywords, MaxCompute built-in functions, and table and column names from the current connection. The completion list filters automatically based on the cursor's position. Typing a table name followed by a. automatically suggests column names for that table.

• Code editing

  The editor includes code folding, bracket pair colorization, word wrap, and a code minimap. Press Shift+Option+F to automatically format the current SQL script.

SQL script management

The File Panel in the left sidebar displays the SQL files in your local file system.

• New file

  Press Option+N (macOS) to create a new SQL file.

• Open file

  In the File Panel, click an existing SQL file to open it in the editor.

• Save file

  Press Option+S (macOS) to save your current changes.

• Multi-tab operations

  You can open multiple SQL files at once and switch between them using tabs.

SQL file version management

The client maintains a version history for each SQL file. Click the Version History icon in the left sidebar to view a list of historical versions for the current file.

Each version record includes a version number, save time, and version type. There are two version types: manual saves (created when you explicitly save a file) and pre-execution snapshots (backups created automatically before you run a SQL query).

You can perform the following operations on a version:

• Compare differences: Double-click a version to open a diff view that shows the changes between that version and the current content.

• Restore version: Restore the file content to a specific version.

• Delete version: Remove historical versions you no longer need.

SQL execution

There are three ways to execute SQL:

• Execute All: Press Cmd+Enter to execute all SQL statements in the editor.

• Execute Selected: Select a portion of SQL text and press Shift+Enter to execute only the selection.

• Single-Statement Execution: The editor displays a Run button between each SQL statement. Click it to execute that specific statement.

If a SQL file contains SET statements, such asSET odps.sql.type.system.odps2=true;, the client automatically merges this configuration with subsequent SQL statements and executes them together.

During execution, the editor displays a progress bar and run status below. When complete, query results appear in a table, while an execution status appears for DDL/DML statements.

Query result analysis

After a query returns results, you can use the following views for in-depth analysis.

Query history

Click the History icon in the left sidebar to browse your query history. Each record shows the execution time, duration (in milliseconds), a preview of the SQL statement, the execution status (success or failure), and the number of rows returned. You can click a record to load that SQL statement back into the editor.

The query history supports pagination, making it easy to review and reuse past queries.

Browse Catalog

In the left sidebar, click the Catalog icon to view all tables in the current project, displayed as a tree structure. Expand any table to view its column definitions, including the column name, data type, and comment.

Right-click a table name to perform the following actions:

• Data Preview: View the first few rows of data in the table.

• View table schema: Displays the complete column information, partition key, and table properties.

• View table information: Displays metadata such as the table size, record count, last modified time, and permissions.

If you have multiple connections saved, the Catalog displays the table schemas for all connected projects, making it easy to browse and compare them.

Data preview

Select a table in the Catalog to preview its data. The system automatically runs a query with a LIMIT clause and displays the results as a table in the central pane.

Partition management

You can view the list of existing partitions in the Catalog and add new partitions to a partitioned table.

Data import

The client supports importing local files into MaxCompute tables. To open the import panel, click the Data Import icon in the left sidebar.

Data export

You can export query results in the following formats:

• CSV: A comma-separated text file compatible with tools like Excel.

• JSON: Data in JSON format.

• Parquet: A columnar storage format suitable for further processing in big data scenarios.

In the query result panel, click the Export button and select a format.

Chat mode and agent mode

The AI assistant provides two working modes:

Chat mode is ideal for quick Q&A and lightweight operations, such as explaining the meaning of a SQL statement, optimizing SQL code, or suggesting insights based on your current query results. Your questions are answered directly by the AI without requiring a multi-step process.

Agent mode is designed for data analysis tasks that require multiple steps. The AI first creates an execution plan. After you approve the plan, the AI executes it step by step. This process can include querying metadata, generating SQL, running queries, and analyzing results to provide a conclusion.

Chat mode

Enter a question directly into the input box in the AI panel to use chat mode. Common use cases include:

• SQL generation: Describe your query requirements, and the AI generates the corresponding MaxCompute SQL.

• SQL optimization: Open a SQL script in the editor and ask the AI for optimization suggestions. You can then insert the optimized SQL into the editor with a single click.

• SQL explanation: Select a complex SQL statement and ask the AI to explain its logic section by section.

• Result insights: After running a query, ask the AI for insights on the results, such as trend analysis or anomaly detection.

Agent mode

When you ask an analytical question that involves multiple steps, the AI automatically enters agent mode.

AI workspace

The AI Workspace is a persistent local directory that stores output from agent mode. Intermediate results and final outputs from each AI analysis task are automatically saved to the workspace.

Use cases

SQL snippet knowledge base

The sql snippet knowledge base stores reusable SQL templates for periodic data retrieval. Maintaining standardized business SQL in the knowledge base lets you use the AI's date rewriting to quickly retrieve report data for different time periods. When you import frequently used SQL files into the knowledge base, the system automatically extracts individual sql snippets. For each snippet, it then extracts table names, keywords, partition fields, and date literals to build a full-text index.

Click the search icon in the left sidebar to search the knowledge base for sql snippets by keyword. After finding a snippet, you can insert it into the editor for execution. Alternatively, you can use the AI assistant's "Execute SQL Snippet" feature to automatically match a snippet, rewrite its date, and execute it.

Semantic layer

The semantic layer is a key feature that distinguishes the MaxCompute client from general-purpose AI tools. It maps tables and columns from your database to business-friendly terms, metrics, and relationships. When generating SQL, the AI consults the semantic layer to produce more accurate queries.

The semantic layer consists of the following components:

• Business term: Defines a specialized term in your business domain, such as 'DAU' for 'Daily Active Users'.

• Entity definition: Describes core business objects and their corresponding tables and key fields.

• Metric definition: Defines the calculation formulas and scope for business metrics, such as Conversion Rate = Number of users who placed an order / Number of visiting users.

• Table relationship: Describes the JOIN relationships and join keys between tables.

• Validated query: A standard, validated query template that the AI can reuse for similar questions.

• Analysis playbook: A predefined template for analysis scenarios and steps that guides the AI to complete an analysis following a standard workflow.

Built-in semantic package

The client includes a built-in semantic package for Information Schema that covers common analysis scenarios for the MaxCompute tenant-level meta-warehouse. These scenarios include storage pressure diagnosis, cost pressure diagnosis, job performance analysis, task failure surge analysis, user role audits, permission exposure audits, hot table observation, and resource quota monitoring.

After you enable this semantic package, you can ask the AI meta-warehouse analysis questions directly, such as "Analyze the top 10 tables by storage in the current project." The AI then uses the metric definitions and reference queries from the semantic package to generate accurate analysis SQL.

Custom semantic package

Create a custom semantic package for your specific business scenarios. In the Semantic Layer Management panel, after selecting a target domain, you can edit business terms, entity definitions, metric definitions, table relationships, validated queries, and analysis playbooks individually. You can also use AI assistance to automatically generate a draft semantic package from the current connection's table structure. You can then manually adjust and optimize this draft.

Blob file browser

MaxCompute lets you store binary file data in columns of the blob type. The client provides a blob file browser that works like a file manager, allowing you to browse tables that store blob data in MaxCompute. To use this feature, enable the file browser Beta switch.

The blob file browser supports switching between grid view and list view, breadcrumb navigation, folder creation, and file upload/download.

Blob file import

In the Data Import panel, you can switch to blob import mode to upload files in bulk to a MaxCompute blob table with drag-and-drop. The client automatically extracts metadata, such as file path, name, and type, and writes it to the corresponding columns in the table.

If the target table does not exist, the client helps generate a table creation statement that includes a blob type column.

Multimodal file preview

The client provides built-in multimodal file preview for the following formats:

The client automatically matches the preview method based on the file's MIME type, but you can also switch it manually.

WebDAV mount

The client includes a built-in WebDAV service that lets you mount a MaxCompute table containing blob files as a local folder. After you mount the table, you can preview and download files directly in Finder without using the client interface.

How to mount on macOS:

In Finder, press Cmd+K and enter http://localhost:8899/dav/ to browse the files in the blob table as a network folder.

OpenClaw sub-agent

The MaxCompute client integrates as an OpenClaw Sub-Agent to handle data analysis tasks delegated by OpenClaw.

In this mode, OpenClaw controls and orchestrates tasks, while the MaxCompute client handles data analysis. The advantages of this collaboration include:

• Security isolation: MaxCompute connection credentials are managed locally on the client. You do not need to configure an AccessKey in OpenClaw.

• Complete audit trail: OpenClaw maintains a simple conversational experience, while the client stores the detailed execution process, including the plan, SQL, intermediate results, and diagnostic information, for tracking and review.

• Extended analysis: You can further analyze and export results from OpenClaw in the client's Studio mode.

# Install the MaxCompute plugin
openclaw plugins install @maxcompute/openclaw-maxquery --pin

# Enable the plugin and configure the connection address
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

Editor settings

AI settings

Advanced AI settings

Theme settings

Switch between Dark and Light themes.

Version update

The application automatically checks for updates and prompts you to install new versions when available.

macOS installation verification error

The macOS Gatekeeper security feature causes this error but does not compromise the application's security. To fix this, open Terminal, run the following command, and restart the application:

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

Connection issues

• Connection test fails

  Check the following items in order:

  1. Ensure the endpoint matches the region of your MaxCompute project. You can verify the correct region on the project details page in the MaxCompute console.

  2. Verify that the AccessKey ID and AccessKey Secret are correct and have not been disabled or expired.

  3. Confirm that your network can access the MaxCompute public endpoint for the specified region. If you are behind a VPN or proxy, ensure that your network policy allows outbound connections.

  4. Ensure that the account associated with the AccessKey ID is authorized to access the target project.

• Connection times out

  Network issues typically cause this timeout. High latency, especially when connecting to a cross-border region, such as accessing an overseas region from the Chinese mainland, can lead to timeouts. Check your network connectivity or contact your network administrator.

SQL execution issues

• SQL execution returns a syntax error

  MaxCompute SQL differs from standard SQL. The client has built-in compatibility rules to automatically rewrite some syntax before execution (for example, converting NOW() to GETDATE()), but this does not cover all cases. Refer to the official MaxCompute SQL documentation to confirm the correct syntax.

• Query returns a large volume of data

  By default, the client limits the number of rows in query results to ensure responsiveness. To retrieve more data, add a LIMIT clause to your SQL statement or use the data export feature to obtain the complete result set.

AI configuration issues

• AI assistant is not working

  Ensure you have correctly configured the API URL, API key, and Model Name in the settings. The default configuration uses Model Studio (DashScope); to use it, you must first create an API key in the Model Studio console.

• AI responses are slow

  Model service load and network conditions affect the AI assistant's response speed. For faster responses, switch the inference service tier to fast in the advanced AI settings or choose a more responsive model.

Import and export issues

• Incorrect column types after importing an Excel file

  The client automatically infers column types when parsing an Excel file. If the inferred types are incorrect, manually modify the column type definitions in the DDL in Create New Table mode, or use the AI Generate DDL feature for more accurate type inference.

• Cannot open an exported Parquet file

  Exported Parquet files adhere to the Apache Parquet format and can be read by tools that support Parquet, such as Python (pandas/pyarrow) and Spark.