MaxCompute:MaxCompute CLI

Instalação e verificação

O maxc é distribuído pela Alibaba Cloud CLI. Para usar o maxc, você deve instalar ou atualizar a Alibaba Cloud CLI.

• Sistemas operacionais compatíveis

  Sistema operacional	Versões compatíveis	Arquiteturas compatíveis
  Linux	CentOS 8+, RHEL 8+, Ubuntu 16.04+, Debian 9+ e outras distribuições principais. O CentOS 7 atingiu o fim do suporte (EOL) e não é recomendado.	x86_64 (64 bits), ARM64
  macOS	macOS 11 (Big Sur) ou posterior	Intel e Apple silicon (binário universal)
  Windows	Windows 10 e posteriores (64 bits)	Apenas x86_64. Não há suporte para 32 bits e ARM64.

• Selecione a aba correspondente ao seu sistema operacional e siga as etapas de instalação. Há vários métodos disponíveis — escolha um.

  Linux

  Install using a bash script (Recommended)

  As seguintes opções são compatíveis:

  • Instalar a versão mais recente

    Se nenhuma versão for especificada, o script instalará automaticamente a versão mais recente.

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

  • Instalar uma versão anterior

    Use a opção -V para especificar a versão a instalar. Para visualizar versões anteriores disponíveis, acesse a página de GitHub Releases.

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

  Install from a TGZ package (.tar.gz)

  1. Baixe o pacote de instalação.

     • Baixar a versão mais recente:

       Nota

       Execute uname -m para verificar a arquitetura do seu sistema Linux. Se a saída do terminal for arm64 ou aarch64, seu sistema possui arquitetura ARM64. Outras saídas indicam arquitetura AMD64.

       • Para sistemas AMD64:

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

       • Para sistemas ARM64:

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

     • Baixar uma versão anterior: Acesse a página de GitHub Releases para baixar pacotes de instalação de versões anteriores.

       O formato do nome de arquivo para pacotes de instalação Linux é aliyun-cli-linux-<version>-<architecture>.tgz. Substitua <version> pelo número da versão desejada, como 3.3.18, e <architecture> por amd64 ou arm64.

  2. Descompacte o pacote de instalação para obter o arquivo executável aliyun.

     tar xzvf aliyun-cli-linux-latest.tgz

  3. Mova o arquivo executável para o diretório /usr/local/bin. Isso permite executar o comando aliyun de qualquer caminho.

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

  macOS

  Install using Homebrew (Recommended)

  Nota

  Antes de continuar, certifique-se de ter instalado e configurado o Homebrew.

  Instale a versão mais recente da Alibaba Cloud CLI:

  brew install aliyun-cli

  Install using the graphical interface (PKG)

  Clique duas vezes no pacote para instalar — nenhuma ferramenta de linha de comando é necessária.

  1. Baixe o pacote de instalação.

     • Baixar a versão mais recente: Abra o link de download https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg no navegador para baixar o pacote de instalação mais recente.

     • Baixar uma versão anterior: Acesse a página de GitHub Releases para visualizar e baixar pacotes de instalação de versões anteriores.

       O formato do nome de arquivo para pacotes de instalação PKG do macOS (Pacote de Instalação do macOS, .pkg) é aliyun-cli-<version>.pkg.

  2. Clique duas vezes no pacote de instalação baixado e siga as instruções para concluir a instalação.

  Install using a bash script

  Os comandos de instalação são os mesmos do Linux. Para mais informações sobre as descrições dos parâmetros, consulte a seção "Install using a bash script" para Linux.

  • Instalar a versão mais recente

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

  • Instalando versões anteriores

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

  Install from a TGZ package (.tar.gz)

  1. Baixe o pacote de instalação.

     • Baixar a versão mais recente:

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

     • Baixar uma versão anterior: Acesse a página de GitHub Releases para baixar pacotes de instalação de versões anteriores.

       O formato do nome de arquivo para pacotes de instalação do macOS é aliyun-cli-macosx-<version>-universal.tgz.

  2. Descompacte o pacote de instalação para obter o arquivo executável aliyun.

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

  3. Mova o arquivo executável para o diretório /usr/local/bin. Isso permite executar o comando aliyun de qualquer caminho.

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

  Windows

  Importante

  A Alibaba Cloud CLI está disponível apenas para sistemas Windows AMD64. Não há suporte para arquiteturas de 32 bits ou ARM64.

  Install using the graphical user interface (GUI)

  Baixar e descompactar o pacote de instalação

  1. Baixe o pacote de instalação.

     • Baixar a versão mais recente: Abra o link de download https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip no navegador para baixar o pacote de instalação mais recente.

     • Baixar uma versão anterior: Acesse a página de GitHub Releases para baixar pacotes de instalação de versões anteriores.

       O formato do nome de arquivo para pacotes de instalação Windows é aliyun-cli-windows-<version>-amd64.zip.

  2. Extraia o aliyun.exe do pacote de instalação para um diretório como C:\AliyunCLI.

     Nota

     • Este arquivo deve ser executado em um terminal de linha de comando. Clicar duas vezes no arquivo não funciona.

     • Anote este caminho de instalação. Ele será necessário ao configurar a variável de ambiente PATH.

  Configurar a variável de ambiente PATH

  1. Pressione as teclas Windows + S para abrir a interface de pesquisa e insira a palavra-chave "environment variables".

  2. Nos resultados da pesquisa, clique em Edit the environment variables for your account para abrir as configurações de Environment Variables.

  3. Na seção User variables, selecione a variável de ambiente com a chave Path e clique em Edit.

     

  4. Na janela de edição, clique em New e insira o caminho do diretório de instalação da Alibaba Cloud CLI. Por exemplo, C:\ExampleDir. Substitua este valor pelo caminho real do seu diretório de instalação.

     

  5. Clique em OK em todas as caixas de diálogo abertas para salvar as alterações.

  6. Reinicie a sessão de terminal para que as alterações entrem em vigor.

  Install using a PowerShell script

  1. Crie um novo arquivo de script chamado Install-CLI-Windows.ps1. Execute New-Item Install-CLI-Windows.ps1 no PowerShell para criar o arquivo ou crie um novo documento de texto no Explorador de Arquivos e renomeie-o.

  2. Copie o código a seguir e salve-o no arquivo de script.

     Exemplo de script

     # 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. Execute o arquivo de script para instalar a Alibaba Cloud CLI conforme mostrado nos exemplos a seguir.

     Nota

     O caminho de exemplo do script é C:\Example\Install-CLI-Windows.ps1. Antes de executar o comando, substitua o caminho do script pela localização real.

     • Se nenhuma versão for especificada, o script instalará automaticamente a versão mais recente. O caminho de instalação padrão é C:\Users\<USERNAME>\AppData\Local\AliyunCLI.

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

     • Use as opções -Version e -InstallDir para especificar a versão e o diretório de instalação. Para visualizar versões anteriores disponíveis, acesse a página de GitHub Releases.

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

• Verificar a instalação

  Execute o seguinte comando para verificar a instalação.

  aliyun maxc --version

  Se o número da versão aparecer, a instalação foi bem-sucedida. Se ocorrer um erro, verifique a versão da CLI. Para mais informações, consulte Instalar ou atualizar a Alibaba Cloud CLI.

Autenticação

O aliyun maxc reutiliza o sistema de credenciais da Alibaba Cloud CLI. Todos os métodos de autenticação configurados com aliyun configure (exceto OAuth) funcionam diretamente — o maxc herda as credenciais do perfil atual.

# Configure authentication using the Alibaba Cloud CLI (if you have not already done so)
aliyun configure --mode AK

# Verify that maxc can access MaxCompute
aliyun maxc auth whoami --json

Para mais informações sobre métodos de autenticação, consulte Configurar e gerenciar credenciais de identidade.

Configurar um projeto MaxCompute

Ao usar o maxc pela primeira vez, especifique o projeto e o endpoint do MaxCompute:

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

Se você omitir --project, um seletor interativo de projetos será exibido. Para cenários de integração contínua (CI), especifique explicitamente o projeto:

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

A configuração do projeto MaxCompute é salva em ~/.maxc/config.yaml.

Visualizar e verificar

# View the current identity and project
aliyun maxc auth whoami --json

# Check permissions for a specific table
aliyun maxc auth can-i --table my_table --operation SELECT --json

Início rápido

# 1. Configure the project (authentication is already completed with aliyun configure)
aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

# 2. Browse tables
aliyun maxc meta list-tables --json
aliyun maxc meta describe my_table --json

# 3. Run a query
aliyun maxc query "SELECT * FROM my_table LIMIT 10" --json

# 4. Estimate the cost
aliyun maxc query cost "SELECT * FROM my_table" --json

# 5. Sample data
aliyun maxc data sample my_table --rows 5 --json

Opções globais

As opções a seguir podem ser inseridas em qualquer lugar na linha de comando e aplicam-se a todos os comandos:

Use --project e --schema para acessar temporariamente outros projetos ou schemas sem alterar a configuração da sessão. Os nomes das tabelas também aceitam o formato schema.table.

Referência de comandos

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

aliyun maxc job status <job_id> --json       # Query the status
aliyun maxc job wait <job_id> --json         # Wait for completion and return the result
aliyun maxc job result <job_id> --json       # Get the result of a completed job
aliyun maxc job cancel <job_id> --json       # Cancel a running job
aliyun maxc job diagnose <job_id> --json     # Diagnose the cause of a failure

aliyun maxc job list --json                  # Lists recent jobs (20 by default)
aliyun maxc job list --limit 50 --json       # Specify the number of jobs

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

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

# 3. Get the result (supports paging)
aliyun maxc job result "$JOB_ID" --max-rows 1000 --json

# List tables
aliyun maxc meta list-tables --json

# View the table schema (--full displays the complete column list; summary mode is the default)
aliyun maxc meta describe my_table --json
aliyun maxc meta describe my_table --full --json

# Search for tables
aliyun maxc meta search "order" --json

# Search for columns
aliyun maxc meta search-columns "user_id" --json

# List partitions (up to 100 by default)
aliyun maxc meta partitions my_table --json
aliyun maxc meta partitions my_table --limit 500 --json

# View the latest partition
aliyun maxc meta latest-partition my_table --json

# View data freshness
aliyun maxc meta freshness my_table --json

# List accessible projects
aliyun maxc meta list-projects --json

# List schemas in a project
aliyun maxc meta list-schemas --json

# Set semantic information
aliyun maxc meta semantic set my_table \
  --desc "Order details table" \
  --use-cases "Analyze daily order volume" "Calculate user repurchase rate" \
  --json

# Get semantic information
aliyun maxc meta semantic get my_table --json

# List tables that are missing semantic information
aliyun maxc meta semantic list-missing --json

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

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

aliyun maxc data profile <table_name> --json

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

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

# Set the default project (specify at least --project or --schema)
aliyun maxc session set --project my_project_dev --json

# Set the default schema
aliyun maxc session set --schema my_schema --json

# View the current session
aliyun maxc session show --json

# Clear session settings
aliyun maxc session unset --json

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

Formato de saída

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

{
  "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
}

Integração com AI Agent

O maxc foi projetado especificamente para integração com AI Agent. As seções a seguir abordam seu design principal e padrões de uso.

# Estimate the cost
aliyun maxc query cost "SELECT * FROM large_table" --json

# Set a cost threshold
aliyun maxc query "SELECT * FROM large_table" --cost-check 100 --json

# One-click installation to Claude Code
aliyun maxc agent skill install --json

# Install on other platforms
aliyun maxc agent skill install cursor --json
aliyun maxc agent skill install windsurf --json

# View the installation status on all platforms
aliyun maxc agent skill list --json

# Update installed SKILLs (after a new version is released)
aliyun maxc agent skill update --all --json

# View the differences between the installed version and the latest version
aliyun maxc agent skill diff claude-code --json

# Uninstall
aliyun maxc agent skill uninstall cursor --json

User question
  ↓
1. meta search / meta list-tables     → Find relevant tables
  ↓
2. meta describe                      → Understand table schema and column meanings
  ↓
3. data sample                        → View actual data to confirm column value formats
  ↓
4. meta partitions / latest-partition → Determine the partition range
  ↓
5. query cost                         → Estimate the cost
  ↓
6. query                              → Run the query and return the result

aliyun maxc meta semantic set my_table \
  --description "User behavior log table, recording click and view events within the app" \
  --usage-scenario "User behavior analysis, funnel conversion statistics" \
  --sample-questions '["What was the DAU for the last 7 days?", "What is the registration conversion rate trend?"]' \
  --json

aliyun maxc agent context --json