MaxCompute:CLI MaxCompute

Installation et vérification

maxc est distribué via Alibaba Cloud CLI. Pour utiliser maxc, vous devez installer ou mettre à jour Alibaba Cloud CLI.

• Systèmes d'exploitation pris en charge

  Système d'exploitation	Versions prises en charge	Architectures prises en charge
  Linux	CentOS 8+, RHEL 8+, Ubuntu 16.04+, Debian 9+ et autres distributions majeures. CentOS 7 a atteint sa fin de vie (EOL) et n'est pas recommandé.	x86_64 (64 bits), ARM64
  macOS	macOS 11 (Big Sur) ou version ultérieure	Intel et puces Apple (binaire universel)
  Windows	Windows 10 et versions ultérieures (64 bits)	x86_64 uniquement. Les architectures 32 bits et ARM64 ne sont pas prises en charge.

• Sélectionnez l'onglet correspondant à votre système d'exploitation et suivez les étapes d'installation. Plusieurs méthodes sont disponibles : choisissez celle qui vous convient.

  Linux

  Installer à l'aide d'un script Bash (recommandé)

  Les options suivantes sont prises en charge :

  • Installer la dernière version

    Si vous ne spécifiez pas de version, le script installe automatiquement la dernière version disponible.

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

  • Installer une version antérieure

    Utilisez l'option -V pour spécifier la version à installer. Pour consulter les versions antérieures disponibles, accédez à la page GitHub Releases.

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

  Installer à partir d'un package TGZ (.tar.gz)

  1. Téléchargez le package d'installation.

     • Télécharger la dernière version :

       Remarque

       Exécutez uname -m pour vérifier l'architecture de votre système Linux. Si la sortie du terminal est arm64 ou aarch64, votre système utilise une architecture ARM64. Toute autre sortie indique une architecture AMD64.

       • Pour les systèmes AMD64 :

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

       • Pour les systèmes ARM64 :

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

     • Télécharger une version antérieure : accédez à la page GitHub Releases pour télécharger les packages d'installation des versions précédentes.

       Le format de nom de fichier pour les packages d'installation Linux est aliyun-cli-linux-<version>-<architecture>.tgz. Remplacez <version> par le numéro de version cible, par exemple 3.3.18, et <architecture> par amd64 ou arm64.

  2. Décompressez le package d'installation pour obtenir le fichier exécutable aliyun.

     tar xzvf aliyun-cli-linux-latest.tgz

  3. Déplacez le fichier exécutable vers le répertoire /usr/local/bin. Cela vous permet d'exécuter la commande aliyun depuis n'importe quel chemin d'accès.

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

  macOS

  Installer avec Homebrew (recommandé)

  Remarque

  Avant de continuer, assurez-vous d'avoir installé et configuré Homebrew.

  Installez la dernière version d'Alibaba Cloud CLI :

  brew install aliyun-cli

  Installer via l'interface graphique (PKG)

  Double-cliquez sur le package pour lancer l'installation ; aucun outil en ligne de commande n'est requis.

  1. Téléchargez le package d'installation.

     • Télécharger la dernière version : ouvrez le lien de téléchargement https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg dans votre navigateur pour télécharger le dernier package d'installation.

     • Télécharger une version antérieure : accédez à la page GitHub Releases pour afficher et télécharger les packages d'installation des versions précédentes.

       Le format de nom de fichier pour les packages d'installation macOS PKG (macOS Installer Package, .pkg) est aliyun-cli-<version>.pkg.

  2. Double-cliquez sur le package d'installation téléchargé et suivez les instructions pour terminer l'installation.

  Installer à l'aide d'un script Bash

  Les commandes d'installation sont identiques à celles utilisées pour Linux. Pour plus d'informations sur les paramètres, consultez la section « Installer à l'aide d'un script Bash » pour Linux.

  • Installer la dernière version

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

  • Installer des versions antérieures

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

  Installer à partir d'un package TGZ (.tar.gz)

  1. Téléchargez le package d'installation.

     • Télécharger la dernière version :

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

     • Télécharger une version antérieure : accédez à la page GitHub Releases pour télécharger les packages d'installation des versions précédentes.

       Le format de nom de fichier pour les packages d'installation macOS est aliyun-cli-macosx-<version>-universal.tgz.

  2. Décompressez le package d'installation pour obtenir le fichier exécutable aliyun.

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

  3. Déplacez le fichier exécutable vers le répertoire /usr/local/bin. Cela vous permet d'exécuter la commande aliyun depuis n'importe quel chemin d'accès.

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

  Windows

  Important

  Alibaba Cloud CLI est disponible uniquement pour les systèmes Windows AMD64. Il ne prend pas en charge les architectures 32 bits ni ARM64.

  Installer via l'interface utilisateur graphique (GUI)

  Télécharger et décompresser le package d'installation

  1. Téléchargez le package d'installation.

     • Télécharger la dernière version : ouvrez le lien de téléchargement https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip dans votre navigateur pour télécharger le dernier package d'installation.

     • Télécharger une version antérieure : accédez à la page GitHub Releases pour télécharger les packages d'installation des versions précédentes.

       Le format de nom de fichier pour les packages d'installation Windows est aliyun-cli-windows-<version>-amd64.zip.

  2. Extrayez aliyun.exe du package d'installation vers un répertoire tel que C:\AliyunCLI.

     Remarque

     • Ce fichier doit être exécuté depuis un terminal en ligne de commande. Un double-clic sur le fichier ne fonctionnera pas.

     • Mémorisez ce chemin d'installation. Vous en aurez besoin lors de la configuration de la variable d'environnement PATH.

  Configurer la variable d'environnement PATH

  1. Appuyez sur les touches Windows + S pour ouvrir l'interface de recherche, puis saisissez le mot-clé « variables d'environnement ».

  2. Dans les résultats de recherche, cliquez sur Edit the environment variables for your account pour ouvrir les paramètres Environment Variables.

  3. Dans la section User variables.

  4. Dans la fenêtre d'édition, cliquez sur Edit et saisissez le chemin du répertoire d'installation d'Alibaba Cloud CLI. Par exemple, C:\ExampleDir. Remplacez cette valeur par le chemin réel de votre répertoire d'installation.

  5. Cliquez sur New dans toutes les boîtes de dialogue ouvertes pour enregistrer les modifications.

  6. Redémarrez votre session de terminal pour que les modifications prennent effet.

  Installer à l'aide d'un script PowerShell

  1. Créez un nouveau fichier de script nommé Install-CLI-Windows.ps1. Vous pouvez exécuter New-Item Install-CLI-Windows.ps1 dans PowerShell pour créer le fichier, ou créer un nouveau document texte dans l'Explorateur de fichiers et le renommer.

  2. Copiez le code suivant et enregistrez-le dans le fichier de script.

     Exemple 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. Exécutez le fichier de script pour installer Alibaba Cloud CLI comme indiqué dans les exemples suivants.

     Remarque

     Le chemin d'exemple du script est C:\Example\Install-CLI-Windows.ps1. Avant d'exécuter la commande, remplacez le chemin du script par l'emplacement réel.

     • Si vous ne spécifiez pas de version, le script installe automatiquement la dernière version. Le chemin d'installation par défaut est C:\Users\<USERNAME>\AppData\Local\AliyunCLI.

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

     • Utilisez les options -Version et -InstallDir pour spécifier la version d'installation et le répertoire. Pour consulter les versions antérieures disponibles, accédez à la page GitHub Releases.

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

• Vérifier l'installation

  Exécutez la commande suivante pour vérifier l'installation.

  aliyun maxc --version

  Si le numéro de version s'affiche, l'installation a réussi. En cas d'erreur, vérifiez la version de la CLI. Pour plus d'informations, consultez Installer ou mettre à jour Alibaba Cloud CLI.

Authentification

aliyun maxc réutilise le système d'identification d'Alibaba Cloud CLI. Toutes les méthodes d'authentification configurées avec aliyun configure (à l'exception d'OAuth) fonctionnent directement : maxc hérite des identifiants du profil actuel.

# 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

Pour plus d'informations sur les méthodes d'authentification, consultez Configurer et gérer les identifiants d'identité.

Configurer un projet MaxCompute

Lors de la première utilisation de maxc, vous devez spécifier le projet MaxCompute et l'endpoint :

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

Si vous omettez --project, un sélecteur de projet interactif s'affiche. Pour les scénarios d'intégration continue (CI), vous devez spécifier explicitement le projet :

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

La configuration du projet MaxCompute est enregistrée dans ~/.maxc/config.yaml.

Consultation et vérification

# 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

Démarrage rapide

# 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

Options globales

Les options suivantes peuvent être placées n'importe où dans la ligne de commande et s'appliquent à toutes les commandes :

Utilisez --project et --schema pour accéder temporairement à d'autres projets ou schemas sans modifier la configuration de session. Les noms de table prennent également en charge le format schema.table.

Référence des commandes

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

Format de sortie

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

Intégration avec les Agents IA

maxc est conçu spécifiquement pour s'intégrer aux Agents IA. Les sections suivantes détaillent sa conception fondamentale et ses modèles d'utilisation.

# 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