全部產品
Search

搜尋本產品

    MaxCompute：MaxCompute CLI

    文件中心

    MaxCompute：MaxCompute CLI

    更新時間：Jun 25, 2026

    MaxCompute CLI（命令名 maxc）是 MaxCompute 的命令列工具，通過阿里雲 CLI 以 aliyun maxc 的方式調用。每條命令提供結構化的 JSON 輸出，專為指令碼自動化和 AI Agent 整合設計。

    安裝及驗證

    maxc 通過阿里雲 CLI 分發。安裝/更新 阿里雲CLI 後即可使用。

    • 支援作業系統

      作業系統

      支援版本

      支援架構

      Linux

      主流發行版，如 CentOS 8+/RHEL 8+、Ubuntu 16.04+、Debian 9+ 等（CentOS 7 已 EOL，不建議使用）

      AMD64、ARM64

      macOS

      macOS 11（Big Sur）及以上

      Intel 和 Apple Silicon（Universal）

      Windows

      Windows 10 及以上（64 位元）

      AMD64（不支援 32 位及 ARM64）

    • 根據作業系統選擇對應 Tab，按步驟完成安裝。每種作業系統均提供多種安裝途徑，選擇其中一種即可。

      Linux

      通過 Bash 指令碼安裝（推薦）

      支援以下選項：

      • 安裝最新版本

        若未指定版本，指令碼將自動安裝最新版本。

        /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

      • 安裝歷史版本

        使用 -V 選項可指定安裝版本。訪問 GitHub Releases 頁面可查看歷史可用版本。

        /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)" -- -V 3.3.18

      通過 TGZ 安裝包（.tar.gz）安裝

      1. 下載安裝包。

        • 下載最新版本：

          說明

          執行 uname -m 可查看 Linux 系統架構。終端輸出 arm64 或 aarch64 表示 ARM64 架構，其他輸出表示 AMD64 架構。

          • AMD64 系統：

            curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz -o aliyun-cli-linux-latest.tgz

          • ARM64 系統：

            curl https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz -o aliyun-cli-linux-latest.tgz

        • 下載歷史版本：訪問 GitHub Releases 頁面可下載歷史版本安裝包。

          Linux 適用安裝包包名格式為 aliyun-cli-linux-<version>-<architecture>.tgz（其中 <version> 替換為目標版本號碼，如 3.3.18；<architecture> 替換為 amd64 或 arm64）。

      2. 解壓安裝包以擷取可執行檔 aliyun。

        tar xzvf aliyun-cli-linux-latest.tgz

      3. 將可執行檔移動至 /usr/local/bin 目錄，使 aliyun 命令可在任意路徑下運行。

        sudo mv ./aliyun /usr/local/bin/

      macOS

      通過 Homebrew 安裝（推薦）

      說明

      繼續操作前，請確保已安裝並配置 Homebrew。

      安裝最新版本的阿里雲 CLI：

      brew install aliyun-cli

      通過圖形介面（PKG）安裝

      雙擊安裝，無需命令列工具。

      1. 下載安裝包。

        • 下載最新版本：在瀏覽器中開啟下載連結 https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg，下載最新版本安裝包。

        • 下載歷史版本：訪問 GitHub Releases 頁面可查看並下載歷史版本安裝包。

          macOS 適用的 PKG（macOS Installer Package，.pkg）安裝包包名格式為 aliyun-cli-<version>.pkg。

      2. 雙擊下載好的安裝包，按照說明指引完成安裝。

      通過 Bash 指令碼安裝

      安裝命令與 Linux 相同，參數說明請參見 Linux 的「通過 Bash 指令碼安裝」方式。

      • 安裝最新版本

        /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

      • 安裝歷史版本

        /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)" -- -V 3.3.5

      通過 TGZ 安裝包（.tar.gz）安裝

      1. 下載安裝包。

        • 下載最新版本：

          curl https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-universal.tgz -o aliyun-cli-macosx-latest-universal.tgz

        • 下載歷史版本：訪問 GitHub Releases 頁面可下載歷史版本安裝包。

          macOS 適用安裝包包名格式為 aliyun-cli-macosx-<version>-universal.tgz。

      2. 解壓安裝包以擷取可執行檔 aliyun。

        tar xzvf aliyun-cli-macosx-latest-universal.tgz

      3. 將可執行檔移動至 /usr/local/bin 目錄，使 aliyun 命令可在任意路徑下運行。

        sudo mv ./aliyun /usr/local/bin/

      Windows

      重要

      阿里雲 CLI 當前僅適用於 Windows AMD64 架構系統，暫不支援 32 位及其他非 AMD64 架構（如 ARM64）的 Windows 系統。

      通過圖形介面（GUI）安裝

      下載並解壓安裝包

      1. 下載安裝包。

      2. 將安裝包中的可執行檔 aliyun.exe 解壓至目標目錄（建議 C:\AliyunCLI），該目錄將作為阿里雲 CLI 的安裝目錄。

        說明

        • 該檔案需要通過命令列終端運行，雙擊檔案無法正常工作。

        • 請記住此安裝路徑，後續配置 PATH 時需要使用。

      配置 PATH 環境變數

      1. 按下 Windows 鍵 + S 鍵開啟搜尋介面，輸入搜尋關鍵詞"環境變數"。

      2. 在搜尋結果中單擊 編輯賬戶的環境變數，開啟 環境變數 設定介面。

      3. 在 使用者變數 中選擇鍵為 Path 的環境變數，單擊 編輯。

      4. 在編輯介面中單擊 建立，輸入阿里雲 CLI 安裝目錄路徑。樣本目錄：C:\ExampleDir（請替換為實際安裝目錄路徑）。

        image

      5. 在所有開啟的對話方塊中依次單擊 確定 以儲存更改。

      6. 重新啟動終端會話以使更改生效。

      通過 PowerShell 指令碼安裝

      1. 建立指令檔 Install-CLI-Windows.ps1。可在 PowerShell 中執行 New-Item Install-CLI-Windows.ps1 建立，或在檔案總管中建立文字文件後重新命名。

      2. 將以下代碼複製並儲存到指令檔中。

        指令碼樣本

        # Install-CLI-Windows.ps1
# Purpose: Install Alibaba Cloud CLI on Windows AMD64 systems.
# Supports custom version and install directory. Only modifies User-level and Process-level PATH.

[CmdletBinding()]
param (
    [string]$Version = "latest",
    [string]$InstallDir = "$env:LOCALAPPDATA",
    [switch]$Help
)

function Show-Usage {
    Write-Output @"

      Alibaba Cloud Command Line Interface Installer

    -Help                 Display this help and exit

    -Version VERSION      Custom CLI version. Default is 'latest'

    -InstallDir PATH      Custom installation directory. Default is:
                          $InstallDir\AliyunCLI

"@
}

function Write-ErrorExit {
    param([string]$Message)
    Write-Error $Message
    exit 1
}

if ($PSBoundParameters['Help']) {
    Show-Usage
    exit 0
}

Write-Output @"
..............888888888888888888888 ........=8888888888888888888D=..............
...........88888888888888888888888 ..........D8888888888888888888888I...........
.........,8888888888888ZI: ...........................=Z88D8888888888D..........
.........+88888888 ..........................................88888888D..........
.........+88888888 .......Welcome to use Alibaba Cloud.......O8888888D..........
.........+88888888 ............. ************* ..............O8888888D..........
.........+88888888 .... Command Line Interface(Reloaded) ....O8888888D..........
.........+88888888...........................................88888888D..........
..........D888888888888DO+. ..........................?ND888888888888D..........
...........O8888888888888888888888...........D8888888888888888888888=...........
............ .:D8888888888888888888.........78888888888888888888O ..............
"@

$OSArchitecture = (Get-WmiObject -Class Win32_OperatingSystem).OSArchitecture

$ProcessorArchitecture = [int](Get-WmiObject -Class Win32_Processor).Architecture

if (-not ($OSArchitecture -match "64") -or $ProcessorArchitecture -ne 9) {
    Write-ErrorExit "Alibaba Cloud CLI only supports Windows AMD64 systems. Please run on a compatible system."
}

$DownloadUrl = "https://aliyuncli.alicdn.com/aliyun-cli-windows-$Version-amd64.zip"

$tempPath = $env:TEMP
$randomName = -join ((65..90) + (97..122) + (48..57) | Get-Random -Count 8)
$DownloadDir = Join-Path -Path $tempPath -ChildPath $randomName
New-Item -ItemType Directory -Path $DownloadDir | Out-Null

try {
    $InstallDir = Join-Path $InstallDir "AliyunCLI"
    if (-not (Test-Path $InstallDir)) {
        New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
    }

    $ZipPath = Join-Path $DownloadDir "aliyun-cli.zip"
    Start-BitsTransfer -Source $DownloadUrl -Destination $ZipPath

    Expand-Archive -Path $ZipPath -DestinationPath $DownloadDir -Force

    Move-Item -Path "$DownloadDir\aliyun.exe" -Destination "$InstallDir\" -Force

    $Key = 'HKCU:\Environment'
    $CurrentPath = (Get-ItemProperty -Path $Key -Name PATH).PATH

    if ([string]::IsNullOrEmpty($CurrentPath)) {
        $NewPath = $InstallDir
    } else {
        if ($CurrentPath -notlike "*$InstallDir*") {
            $NewPath = "$CurrentPath;$InstallDir"
        } else {
            $NewPath = $CurrentPath
        }
    }

    if ($NewPath -ne $CurrentPath) {
        Set-ItemProperty -Path $Key -Name PATH -Value $NewPath
        $env:PATH += ";$InstallDir"
    }
} catch {
    Write-ErrorExit "Failed to install Alibaba Cloud CLI: $_"
} finally {
    Remove-Item -Path $DownloadDir -Recurse -Force | Out-Null
}

      3. 參考以下樣本，運行指令檔安裝阿里雲 CLI。

        說明

        樣本指令碼路徑為 C:\Example\Install-CLI-Windows.ps1，請將指令碼路徑替換為實際位置後運行命令。

        • 若未指定版本，指令碼將自動安裝最新版本。預設安裝路徑為：C:\Users\<USERNAME>\AppData\Local\AliyunCLI。

          powershell.exe -ExecutionPolicy Bypass -File C:\Example\Install-CLI-Windows.ps1

        • 使用 -Version 和 -InstallDir 選項可指定安裝版本和安裝目錄。訪問 GitHub Releases 頁面可查看歷史可用版本。

          powershell.exe -ExecutionPolicy Bypass -File C:\Example\Install-CLI-Windows.ps1 -Version 3.3.15 -InstallDir "C:\ExampleDir\AliyunCLI"

    • 驗證安裝結果

      安裝完成後，在終端中執行以下命令確認阿里雲 CLI 已安裝成功。

      aliyun maxc --version

      如顯示版本號碼，則安裝成功。如提示錯誤，建議檢查 CLI 版本，詳情參考安裝/更新 阿里雲CLI 。

    認證

    aliyun maxc 直接複用阿里雲 CLI 的憑證體系。通過 aliyun configure 配置的認證方式（除 OAuth 認證）均可直接使用，maxc 會自動繼承當前 Profile 的憑證。

    # 使用阿里雲 CLI 配置認證（如果尚未配置）
aliyun configure --mode AK

# 驗證 maxc 可以訪問 MaxCompute
aliyun maxc auth whoami --json

    認證方式詳情參考配置與管理身份憑證。

    配置 MaxCompute 專案

    首次使用時需要指定 MaxCompute 專案和端點：

    aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

    省略 --project 時會彈出互動式專案選取器。CI 情境需顯式指定：

    aliyun maxc auth login \
  --project my_project_dev \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api \
  --no-picker

    MaxCompute 專案配置儲存在 ~/.maxc/config.yaml。

    查看與驗證

    # 查看當前身份和專案
aliyun maxc auth whoami --json

# 檢查對特定表的許可權
aliyun maxc auth can-i --table my_table --operation SELECT --json

    快速入門

    # 1. 設定項目（認證已通過 aliyun configure 完成）
aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

# 2. 瀏覽表
aliyun maxc meta list-tables --json
aliyun maxc meta describe my_table --json

# 3. 執行查詢
aliyun maxc query "SELECT * FROM my_table LIMIT 10" --json

# 4. 預估成本
aliyun maxc query cost "SELECT * FROM my_table" --json

# 5. 採樣資料
aliyun maxc data sample my_table --rows 5 --json

    全域選項

    以下選項可放在命令列任意位置，對所有命令生效：

    選項

    說明

    --json

    輸出 JSON Envelope 格式（等同於 --format json）

    --format

    輸出格式：json、table、csv、ndjson、markdown、brief

    --config

    指定設定檔路徑

    --project

    目標 MaxCompute 專案（臨時覆蓋會話設定）

    --schema

    目標 Schema（臨時覆蓋會話設定）

    --project 和 --schema 用於臨時訪問其他專案或 Schema，不影響當前會話配置。表名也支援 schema.table 格式。

    命令參考

    SQL 查詢（Query）

    • query查詢模式

      支援三種模式，通過第一個關鍵詞指定：

      aliyun maxc query <sql>             # 執行查詢（預設）
aliyun maxc query cost <sql>        # 預估成本
aliyun maxc query explain <sql>     # 查看執行計畫

      預設唯讀模式，DDL/DML 會被用戶端攔截（--force 可繞過）。

      aliyun maxc query "SELECT * FROM my_table LIMIT 10" --json

    • 參數說明

      參數

      說明

      預設值

      <sql>

      SQL 文本

      —

      --file

      從檔案讀取 SQL

      —

      --stdin

      從標準輸入讀取 SQL

      —

      --max-rows

      最大返回行數

      100

      --page-size

      分頁大小

      —

      --cursor

      分頁遊標（上次傳回值）

      —

      --wait

      同步等待秒數，逾時後返回 job_id

      10

      --dry-run

      僅顯示查詢計劃，不執行

      —

      --cost-check

      預估成本超過閾值（CU）時中止

      —

      --output

      將結果寫入檔案

      —

      --output-format

      輸出檔案格式：table、json、csv、ndjson

      —

      --idempotency-key

      去重鍵，用於重試等冪

      —

      --retry-on

      逗號分隔的可重試錯誤碼

      —

      --max-retries

      最大重試次數

      0

      --retry-backoff

      退避策略：fixed、exponential

      fixed

      --force

      繞過唯讀模式，允許 DDL/DML

      —

    • --wait 行為

      • --wait 10（預設）：同步輪詢 10 秒，完成則返回結果；逾時則返回 job_id。

      • --wait 0：立即提交並返回 job_id。

      • --wait 300：最多等待 5 分鐘。

      逾時後可用 job wait <job_id> 繼續等待。

    • 使用樣本

      # 從檔案執行
aliyun maxc query --file my_query.sql --json

# 成本保護：預估超過 100 CU 自動中止
aliyun maxc query "SELECT * FROM orders" --cost-check 100 --json

# 分頁
aliyun maxc query "SELECT * FROM orders" --page-size 50 --json
aliyun maxc query "SELECT * FROM orders" --page-size 50 --cursor <next_cursor> --json

# 結果寫入 CSV 檔案
aliyun maxc query "SELECT * FROM orders LIMIT 1000" --output result.csv --output-format csv --json

# 等冪重試
aliyun maxc query "INSERT INTO target SELECT * FROM source WHERE ds='20260601'" \
  --force --idempotency-key "daily-etl-20260601" \
  --retry-on "QUOTA_EXCEEDED" --max-retries 3 --retry-backoff exponential --json

    作業管理（Job）

    管理非同步 SQL 作業的生命週期。

    job submit

    提交 SQL 作業，立即返回job_id。

    aliyun maxc job submit "SELECT * FROM large_table" --json

    參數

    說明

    預設值

    <sql>

    SQL 文本

    —

    --file

    從檔案讀取 SQL

    —

    --stdin

    從標準輸入讀取 SQL

    —

    --max-rows

    最大返回行數

    100

    --cost-check

    成本閾值（CU）

    —

    --idempotency-key

    去重鍵

    —

    --force

    允許 DDL/DML

    —

    job status / wait / result / cancel / diagnose

    aliyun maxc job status <job_id> --json       # 查詢狀態
aliyun maxc job wait <job_id> --json         # 等待完成並返回結果
aliyun maxc job result <job_id> --json       # 擷取已完成作業的結果
aliyun maxc job cancel <job_id> --json       # 取消運行中的作業
aliyun maxc job diagnose <job_id> --json     # 診斷失敗原因

    • job wait 額外參數

      參數

      說明

      預設值

      --timeout

      逾時秒數

      300

      --stream

      以 NDJSON 流式輸出進度

      —

    • job result 額外參數

      參數

      說明

      預設值

      --max-rows

      最大返回行數

      100

      --cursor

      分頁遊標

      —

    job list

    aliyun maxc job list --json                  # 列出最近作業（預設 20 條）
aliyun maxc job list --limit 50 --json       # 指定數量

    非同步查詢完整流程

    # 1. 提交
JOB_ID=$(aliyun maxc query "SELECT * FROM large_table" --wait 0 --json \
  | jq -r '.metadata.job_id')

# 2. 等待
aliyun maxc job wait "$JOB_ID" --timeout 600 --json

# 3. 擷取結果（可分頁）
aliyun maxc job result "$JOB_ID" --max-rows 1000 --json

    中繼資料瀏覽（Meta）

    表操作

    # 列出表
aliyun maxc meta list-tables --json

# 查看錶結構（--full 顯示完整列列表，預設摘要模式）
aliyun maxc meta describe my_table --json
aliyun maxc meta describe my_table --full --json

# 搜尋表
aliyun maxc meta search "order" --json

# 搜尋列
aliyun maxc meta search-columns "user_id" --json

    list-tables 和 search 支援 --limit 和 --cursor 分頁。search 預設返回 20 條。

    分區操作

    # 列出分區（預設最多 100 個）
aliyun maxc meta partitions my_table --json
aliyun maxc meta partitions my_table --limit 500 --json

# 查看最新分區
aliyun maxc meta latest-partition my_table --json

# 查看資料新鮮度
aliyun maxc meta freshness my_table --json

    專案與 Schema

    # 列出可訪問的專案
aliyun maxc meta list-projects --json

# 列出專案下的 Schema
aliyun maxc meta list-schemas --json

    語義中繼資料

    為 AI Agent 提供表的業務語義資訊，詳見 AI Agent 整合。

    # 設定語義資訊
aliyun maxc meta semantic set my_table \
  --desc "訂單明細表" \
  --use-cases "分析每日訂單量" "計算使用者複購率" \
  --json

# 擷取語義資訊
aliyun maxc meta semantic get my_table --json

# 列出缺少語義資訊的表
aliyun maxc meta semantic list-missing --json

    semantic set 還支援 --sample-questions、--column-semantics（JSON）、--relations（JSON）、--stats（JSON）。

    資料操作（Data）

    Data sample

    從表中採樣資料。分區表不指定分區時自動選取最新分區。不支援視圖。

    aliyun maxc data sample my_table --json
aliyun maxc data sample my_table --rows 20 --partition "ds=20260601" --columns "user_id,amount" --json

    參數

    說明

    預設值

    <table_name>

    表名

    —

    --rows

    採樣行數

    5

    --partition

    分區規格

    自動選最新

    --columns

    指定列（逗號分隔）

    全部

    Data profile

    分析表的列統計資訊（空值率、唯一值數、最大最小值等）。基於 20 行採樣的啟發學習法結果。

    aliyun maxc data profile my_table --json
aliyun maxc data profile my_table --partition "ds=20260601" --json
    aliyun maxc data profile <table_name> --json

    Data upload

    將本地 CSV/TSV 檔案上傳到表。分區表必須指定 --partition。不支援視圖和複雜類型（array/map/struct）。

    aliyun maxc data upload my_table --file data.csv --json
aliyun maxc data upload my_table --file data.csv --partition "ds=20260601" --overwrite --json

    參數

    說明

    預設值

    <table_name>

    目標表名

    —

    --file

    本地檔案路徑（必填）

    —

    --partition

    分區規格（分區表必填）

    —

    --overwrite

    INSERT OVERWRITE 語義

    —

    --delimiter

    欄位分隔符號

    ,

    --no-header

    首行為資料而非表頭

    —

    --null-marker

    NULL 標記

    \N

    --block-size

    每批上傳行數

    10000

    Data download

    將表資料下載為本地 CSV/TSV 檔案。分區表必須指定 --partition。不支援視圖。

    aliyun maxc data download my_table --output data.csv --json
aliyun maxc data download my_table --output data.csv --partition "ds=20260601" --limit 100000 --json

    參數

    說明

    預設值

    <table_name>

    源表名

    —

    --output

    輸出檔案路徑（必填）

    —

    --partition

    分區規格（分區表必填）

    —

    --columns

    指定列（逗號分隔）

    全部

    --limit

    最大下載行數

    不限

    --delimiter

    欄位分隔符號

    ,

    --no-header

    不寫入表頭行

    —

    --null-marker

    NULL 輸出標記

    Null 字元串

    會話管理（Session）

    管理當前會話的預設專案和 Schema。本地操作，不需要後端串連。

    # 設定預設專案（至少指定 --project 或 --schema 之一）
aliyun maxc session set --project my_project_dev --json

# 設定預設 Schema
aliyun maxc session set --schema my_schema --json

# 查看當前會話
aliyun maxc session show --json

# 清除會話設定
aliyun maxc session unset --json

    跨專案訪問時，使用全域 --project 參數臨時切換，不修改會話配置：

    aliyun maxc meta list-tables --project other_project --json
aliyun maxc query "SELECT * FROM t LIMIT 5" --project other_project --json

    輸出格式

    JSON Envelope

    所有命令添加 --json 後輸出統一的 JSON Envelope（v2.0）：

    {
  "version": "2.0",
  "command": "query",
  "status": "success",
  "data": { ... },
  "metadata": { ... },
  "error": null,
  "agent_hints": null
}

    欄位

    類型

    說明

    version

    string

    固定 "2.0"

    command

    string

    執行的命令，如 "query"、"meta describe"

    status

    string

    "success" 或 "failure"

    data

    object

    命令返回的業務資料

    metadata

    object

    執行元資訊（專案名、耗時、job_id 等）

    error

    object/null

    失敗時的錯誤詳情

    agent_hints

    object/null

    AI Agent 的下一步操作建議

    Data 欄位

    不同命令返回的 data 結構不同：

    命令

    data 頂層鍵

    query / job wait / job result

    result（含 rows、schema、row_count、returned_rows）、pagination

    query cost / query explain

    analysis

    meta list-tables

    tables、pagination

    meta describe

    table

    meta search / meta search-columns

    search（含 keyword、matches）、pagination

    meta partitions

    table、partitions

    meta latest-partition

    partition

    meta freshness

    freshness

    data sample

    sample

    data profile

    profile

    job list

    jobs、pagination

    job status / job cancel

    job

    job diagnose

    diagnosis

    auth whoami

    identity

    auth login

    identity、persistence

    auth can-i

    authorization

    error 欄位

    失敗時 error 包含以下欄位：

    {
  "code": "TABLE_NOT_FOUND",
  "message": "Table 'orders' does not exist in project 'my_project'",
  "suggestion": "Use 'aliyun maxc meta search orders --json' to find similar tables",
  "recoverable": false
}

    欄位

    說明

    code

    錯誤碼（見下表）

    message

    錯誤描述

    suggestion

    修複建議（可選）

    recoverable

    是否可重試

    instance_id

    ODPS Instance ID（僅查詢錯誤，可選）

    logview

    LogView 連結（僅查詢錯誤，可選）

    context

    結構化上下文（可選）

    錯誤碼

    錯誤碼

    說明

    可重試

    EXECUTION_FAILED

    執行失敗

    是

    PERMISSION_DENIED

    許可權不足

    否

    QUOTA_EXCEEDED

    配額超限

    是

    SQL_ERROR

    SQL 文法或執行錯誤

    否

    COST_LIMIT_EXCEEDED

    成本超過閾值

    否

    NOT_FOUND

    資源不存在

    否

    TABLE_NOT_FOUND

    表不存在

    否

    SCHEMA_NOT_FOUND

    Schema 不存在

    否

    COLUMN_NOT_FOUND

    列不存在

    否

    VALIDATION_ERROR

    輸入校正失敗

    否

    BACKEND_CONNECTION_ERROR

    無法串連後端

    是

    JOB_TIMEOUT

    作業輪詢逾時

    是

    READ_ONLY_VIOLATION

    唯讀模式攔截寫操作

    否

    WRITE_OPERATION_REQUIRES_FORCE

    寫操作需要 --force

    是

    CSV_PARSE_ERROR

    CSV 解析失敗

    否

    INTERNAL_ERROR

    內部錯誤

    否

    其他格式

    格式

    說明

    table

    可讀表格（預設）

    markdown

    Markdown 格式

    brief

    單行摘要

    csv

    CSV（僅資料行）

    ndjson

    換行分隔 JSON，每行一條記錄

    AI Agent 整合

    maxc 是面向 AI Agent 構建的工具層。以下是核心設計理念和使用方式。

    統一 JSON 協議

    每條命令的 --json 輸出遵循固定的 Envelope 協議。Agent 通過結構化欄位擷取資訊，從而得到明確的結構化反饋。

    • status ：成功還是失敗

    • data：業務資料，結構按命令類型固定

    • error.code + error.suggestion ：錯誤碼和可執行檔修複建議

    • agent_hints.next_actions ：CLI 推薦的下一步命令（完整可執行檔命令列）

    • agent_hints.warnings： 需要注意的風險（如成本過高、自動選取了分區等）

    錯誤自修複

    每個錯誤響應都包含 suggestion 欄位和對應的 agent_hints.next_actions，告訴 Agent 接下來應該執行什麼命令。例如：

    錯誤情境

    Agent 收到的引導

    表不存在

    建議執行 meta search 尋找相似表名

    列不存在

    建議執行 meta describe 查看錶結構

    許可權不足

    建議切換到 _dev 專案或檢查身份

    SQL 語法錯誤

    建議執行 query cost 或 query explain 驗證

    配額超限

    建議執行 query cost 評估查詢成本

    作業逾時

    建議執行 job wait 或 job status 繼續跟蹤

    Agent 只需讀取 error.suggestion，按提示重新執行，即可自動從錯誤中恢複，無需寫入程式碼錯誤處理邏輯。

    唯讀安全

    maxc 在用戶端攔截所有 DDL/DML 語句（CREATE、DROP、INSERT、UPDATE、DELETE 等），確保 Agent 不會意外修改或刪除資料。這是在 SQL 提交到服務端之前的本地檢查，零延遲、無成本。

    需要執行寫操作時，必須由使用者顯式添加 --force 參數——Agent 不應自行添加此參數。資料上傳（data upload）通過 Tunnel API 走獨立寫入通道，不受此限制。

    成本感知

    Agent 可以在執行查詢前通過 query cost 預估成本，或使用 --cost-check 設定成本上限：

    # 預估成本
aliyun maxc query cost "SELECT * FROM large_table" --json

# 設定成本閾值
aliyun maxc query "SELECT * FROM large_table" --cost-check 100 --json

    分區表不加分區過濾可能掃描全表，導致成本飆升。建議 Agent 在查詢前先通過 meta partitions 或 meta latest-partition 確定分區範圍。

    SKILL分層知識架構

    SKILL 是一套安裝到 Agent 平台的結構化指導文檔，教會 Agent 如何使用 maxc 完成 MaxCompute 資料任務。

    # 一鍵安裝到 Claude Code
aliyun maxc agent skill install --json

# 安裝到其他平台
aliyun maxc agent skill install cursor --json
aliyun maxc agent skill install windsurf --json

    SKILL 採用分層載入設計，最佳化 LLM 上下文視窗的使用效率：

    層級

    內容

    載入時機

    主檔案 SKILL.md

    意圖→命令映射表、核心原則、工作流程、決策表

    任務觸發時自動載入

    參考文檔

    SQL 方言指南、查詢範本、分區策略、錯誤恢複手冊等

    按需載入（僅當 Agent 需要時）

    Agent 處理簡單的中繼資料查詢時只需主檔案的 270 行指導；遇到複雜的 SQL 產生或錯誤恢複時，才按需載入對應的參考文檔。

    支援的 Agent 平台：

    平台

    安裝路徑

    claude-code

    ~/.claude/skills/maxc-cli/

    cursor

    ~/.cursor/skills/maxc-cli/

    windsurf

    ~/.codeium/windsurf/skills/maxc-cli/

    codex

    ~/.codex/skills/maxc-cli/

    qwen

    ~/.qwen/skills/maxc-cli/

    qoder

    ~/.qoder/skills/maxc-cli/

    qoderwork

    ~/.qoderwork/skills/maxc-cli/

    openclaw

    ~/.openclaw/workspace/skills/maxc-cli/

    hermes

    ~/.hermes/skills/maxc-cli/

    其他 Agent

    指定 --dir 來安裝到任意目錄

    SKILL 管理

    # 查看所有平台的安裝狀態
aliyun maxc agent skill list --json

# 更新已安裝的 SKILL（新版本發布後）
aliyun maxc agent skill update --all --json

# 查看已安裝版本與最新版本的差異
aliyun maxc agent skill diff claude-code --json

# 卸載
aliyun maxc agent skill uninstall cursor --json

    NL2SQL 工作流程

    SKILL 引導 Agent 按以下流程將自然語言問題轉化為 SQL 查詢：

    使用者提問
  ↓
1. meta search / meta list-tables     → 找到相關表
  ↓
2. meta describe                      → 瞭解表結構和列含義
  ↓
3. data sample                        → 查看實際資料，確認列值格式
  ↓
4. meta partitions / latest-partition → 確定分區範圍
  ↓
5. query cost                         → 預估成本
  ↓
6. query                              → 執行查詢並返回結果

    SKILL 中的參考文檔提供了 MaxCompute SQL 方言的完整指南（700+ 行），覆蓋函數差異、類型陷阱、查詢範本和常見錯誤修複，協助 Agent 產生正確的 SQL。

    語義中繼資料

    meta semantic 命令允許為表附加業務語義資訊（描述、使用情境、樣本問題、列語義等）。當 Agent 通過 meta describe 發現表缺少語義資訊時，可以根據自身理解產生並儲存：

    aliyun maxc meta semantic set my_table \
  --description "使用者行為日誌表，記錄 App 內的點擊和瀏覽事件" \
  --usage-scenario "使用者行為分析、漏鬥轉化統計" \
  --sample-questions '["過去7天的DAU是多少", "註冊轉化率趨勢"]' \
  --json

    這些語義資訊會被後續的 Agent 會話讀取，形成「使用→沉澱→複用」的正向迴圈。

    Agent 上下文

    Agent 可通過 agent context 一次性擷取當前的完整上下文：

    aliyun maxc agent context --json

    返回當前認證狀態、專案、Schema、配置路徑等資訊，Agent 據此判斷是否需要引導使用者完成認證或專案切換。