All Products
Search

This Product

    MaxCompute:MaxCompute CLI

    Document Center

    MaxCompute:MaxCompute CLI

    Last Updated:Sep 15, 2026

    MaxCompute CLI (maxc) adalah alat command-line yang dipanggil melalui Alibaba Cloud CLI sebagai aliyun maxc. Semua perintah menghasilkan output JSON terstruktur untuk otomatisasi skrip dan integrasi AI Agent.

    Instalasi dan verifikasi

    maxc didistribusikan melalui Alibaba Cloud CLI. Untuk menggunakan maxc, Anda harus menginstal atau memperbarui Alibaba Cloud CLI.

    • Sistem operasi yang didukung

      Sistem operasi

      Versi yang didukung

      Arsitektur yang didukung

      Linux

      CentOS 8+, RHEL 8+, Ubuntu 16.04+, Debian 9+, dan distribusi utama lainnya. CentOS 7 telah mencapai EOL dan tidak direkomendasikan.

      x86_64 (64-bit), ARM64

      macOS

      macOS 11 (Big Sur) atau lebih baru

      Intel dan Apple silicon (Universal binary)

      Windows

      Windows 10 dan lebih baru (64-bit)

      Hanya x86_64. Arsitektur 32-bit dan ARM64 tidak didukung.

    • Pilih tab sesuai sistem operasi Anda dan ikuti langkah-langkah instalasi. Beberapa metode tersedia—pilih salah satu.

      Linux

      Instal menggunakan skrip Bash (Direkomendasikan)

      Opsi berikut didukung:

      • Instal versi terbaru

        Jika Anda tidak menentukan versi, skrip secara otomatis menginstal versi terbaru.

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

      • Instal versi sebelumnya

        Gunakan opsi -V untuk menentukan versi yang akan diinstal. Untuk melihat versi sebelumnya yang tersedia, kunjungi halaman GitHub Releases.

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

      Instal dari paket TGZ (.tar.gz)

      1. Unduh paket instalasi.

        • Unduh versi terbaru:

          Catatan

          Jalankan uname -m untuk memeriksa arsitektur sistem Linux Anda. Jika output terminal adalah arm64 atau aarch64, sistem Anda memiliki arsitektur ARM64. Output lainnya menunjukkan arsitektur AMD64.

          • Untuk sistem AMD64:

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

          • Untuk sistem ARM64:

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

        • Unduh versi sebelumnya: Kunjungi halaman GitHub Releases untuk mengunduh paket instalasi versi sebelumnya.

          Format nama file untuk paket instalasi Linux adalah aliyun-cli-linux-<version>-<architecture>.tgz. Ganti <version> dengan nomor versi target, seperti 3.3.18, dan <architecture> dengan `amd64` atau `arm64`.

      2. Ekstrak paket instalasi untuk mendapatkan file yang dapat dieksekusi aliyun.

        tar xzvf aliyun-cli-linux-latest.tgz

      3. Pindahkan file yang dapat dieksekusi ke direktori /usr/local/bin. Hal ini memungkinkan Anda menjalankan perintah aliyun dari path mana pun.

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

      macOS

      Instal menggunakan Homebrew (Direkomendasikan)

      Catatan

      Sebelum melanjutkan, pastikan Anda telah menginstal dan mengonfigurasi Homebrew.

      Instal versi terbaru Alibaba Cloud CLI:

      brew install aliyun-cli

      Instal menggunakan antarmuka grafis (PKG)

      Klik ganda paket untuk menginstal—tidak diperlukan alat command-line.

      1. Unduh paket instalasi.

        • Unduh versi terbaru: Buka tautan unduhan https://aliyuncli.alicdn.com/aliyun-cli-latest.pkg di browser Anda untuk mengunduh paket instalasi terbaru.

        • Unduh versi sebelumnya: Kunjungi halaman GitHub Releases untuk melihat dan mengunduh paket instalasi versi sebelumnya.

          Format nama file untuk paket instalasi macOS PKG (macOS Installer Package, .pkg) adalah aliyun-cli-<version>.pkg.

      2. Klik ganda paket instalasi yang telah diunduh dan ikuti petunjuk untuk menyelesaikan instalasi.

      Instal menggunakan skrip Bash

      Perintah instalasi sama dengan yang digunakan untuk Linux. Untuk informasi lebih lanjut tentang deskripsi parameter, lihat bagian "Instal menggunakan skrip Bash" untuk Linux.

      • Instal versi terbaru

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

      • Instal versi sebelumnya

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

      Instal dari paket TGZ (.tar.gz)

      1. Unduh paket instalasi.

        • Unduh versi terbaru:

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

        • Unduh versi sebelumnya: Kunjungi halaman GitHub Releases untuk mengunduh paket instalasi versi sebelumnya.

          Format nama file untuk paket instalasi macOS adalah aliyun-cli-macosx-<version>-universal.tgz.

      2. Ekstrak paket instalasi untuk mendapatkan file yang dapat dieksekusi aliyun.

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

      3. Pindahkan file yang dapat dieksekusi ke direktori /usr/local/bin. Hal ini memungkinkan Anda menjalankan perintah aliyun dari path mana pun.

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

      Windows

      Penting

      Alibaba Cloud CLI hanya tersedia untuk sistem Windows AMD64. Tidak mendukung arsitektur 32-bit atau ARM64.

      Instal menggunakan antarmuka pengguna grafis (GUI)

      Unduh dan ekstrak paket instalasi

      1. Unduh paket instalasi.

      2. Ekstrak aliyun.exe dari paket instalasi ke direktori seperti C:\AliyunCLI.

        Catatan

        • File ini harus dijalankan dari terminal command-line. Mengklik ganda file tidak akan berfungsi.

        • Ingat path instalasi ini. Anda akan membutuhkannya saat mengonfigurasi variabel lingkungan PATH.

      Konfigurasi variabel lingkungan PATH

      1. Tekan tombol Windows + S untuk membuka antarmuka pencarian, lalu masukkan kata kunci "environment variables".

      2. Pada hasil pencarian, klik Edit the environment variables for your account untuk membuka pengaturan Environment Variables.

      3. Pada bagian User variables, pilih variabel lingkungan dengan kunci Path dan klik Edit.

      4. Pada jendela edit, klik New dan masukkan path direktori instalasi Alibaba Cloud CLI. Misalnya, C:\ExampleDir. Ganti ini dengan path direktori instalasi aktual Anda.

      5. Klik OK pada semua kotak dialog yang terbuka untuk menyimpan perubahan.

      6. Mulai ulang sesi terminal Anda agar perubahan diterapkan.

      Instal menggunakan skrip PowerShell

      1. Buat file skrip baru bernama Install-CLI-Windows.ps1. Anda dapat menjalankan New-Item Install-CLI-Windows.ps1 di PowerShell untuk membuat file, atau buat dokumen teks baru di File Explorer dan ubah namanya.

      2. Salin kode berikut dan simpan ke file skrip.

        Contoh skrip

        # 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. Jalankan file skrip untuk menginstal Alibaba Cloud CLI seperti pada contoh berikut.

        Catatan

        Path contoh skrip adalah C:\Example\Install-CLI-Windows.ps1. Sebelum menjalankan perintah, ganti path skrip dengan lokasi aktual.

        • Jika Anda tidak menentukan versi, skrip secara otomatis menginstal versi terbaru. Path instalasi default adalah C:\Users\<USERNAME>\AppData\Local\AliyunCLI.

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

        • Gunakan opsi -Version dan -InstallDir untuk menentukan versi dan direktori instalasi. Untuk melihat versi sebelumnya yang tersedia, kunjungi halaman GitHub Releases.

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

    • Verifikasi instalasi

      Jalankan perintah berikut untuk memverifikasi instalasi.

      aliyun maxc --version

      Jika nomor versi muncul, instalasi berhasil. Jika terjadi kesalahan, periksa versi CLI. Untuk informasi lebih lanjut, lihat Instal atau perbarui Alibaba Cloud CLI.

    Otentikasi

    aliyun maxc menggunakan kembali sistem kredensial Alibaba Cloud CLI. Semua metode autentikasi yang dikonfigurasi dengan aliyun configure (kecuali OAuth) berfungsi langsung—maxc mewarisi kredensial dari profil saat ini.

    # Konfigurasikan autentikasi menggunakan Alibaba Cloud CLI (jika belum dilakukan)
aliyun configure --mode AK

# Verifikasi bahwa maxc dapat mengakses MaxCompute
aliyun maxc auth whoami --json

    Untuk informasi lebih lanjut tentang metode autentikasi, lihat Konfigurasi dan kelola kredensial identitas.

    Konfigurasi proyek MaxCompute

    Saat pertama kali menggunakan maxc, Anda harus menentukan proyek dan titik akhir MaxCompute:

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

    Jika Anda menghilangkan --project, pemilih proyek interaktif akan muncul. Untuk skenario continuous integration (CI), Anda harus secara eksplisit menentukan proyek:

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

    Konfigurasi proyek MaxCompute disimpan di ~/.maxc/config.yaml.

    Lihat dan verifikasi

    # Lihat identitas dan proyek saat ini
aliyun maxc auth whoami --json

# Periksa izin untuk tabel tertentu
aliyun maxc auth can-i --table my_table --operation SELECT --json

    Memulai Cepat

    # 1. Konfigurasikan proyek (otentikasi sudah diselesaikan dengan aliyun configure)
aliyun maxc auth login \
  --endpoint http://service.cn-hangzhou.maxcompute.aliyun.com/api

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

# 3. Jalankan kueri
aliyun maxc query "SELECT * FROM my_table LIMIT 10" --json

# 4. Perkirakan biaya
aliyun maxc query cost "SELECT * FROM my_table" --json

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

    Opsi global

    Opsi berikut dapat ditempatkan di mana saja dalam baris perintah dan berlaku untuk semua perintah:

    Opsi

    Deskripsi

    --json

    Output dalam format JSON Envelope (setara dengan --format json)

    --format

    Format output: json, table, csv, ndjson, markdown, atau brief

    --config

    Menentukan path file konfigurasi

    --project

    Proyek MaxCompute target (menimpa sementara pengaturan sesi)

    --schema

    Skema target (menimpa sementara pengaturan sesi)

    Gunakan --project dan --schema untuk mengakses sementara proyek atau skema lain tanpa mengubah konfigurasi sesi. Nama tabel juga mendukung format schema.table.

    Referensi perintah

    Kueri SQL (Query)

    • mode kueri

      Tiga mode tersedia, dipilih berdasarkan kata kunci pertama:

      aliyun maxc query <sql>             # Jalankan kueri (default)
aliyun maxc query cost <sql>        # Perkirakan biaya
aliyun maxc query explain <sql>     # Lihat rencana eksekusi

      Mode default bersifat read-only—pernyataan DDL dan DML diblokir di sisi klien. Gunakan --force untuk melewati pembatasan ini.

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

    • Deskripsi parameter

      Parameter

      Deskripsi

      Nilai default

      <sql>

      Teks SQL

      —

      --file

      Membaca SQL dari file

      —

      --stdin

      Membaca SQL dari input standar

      —

      --max-rows

      Jumlah maksimum baris yang dikembalikan

      100

      --page-size

      Ukuran halaman

      —

      --cursor

      Kursor paginasi (nilai kembali dari pemanggilan terakhir)

      —

      --wait

      Jumlah detik untuk menunggu sinkronisasi. Jika terjadi timeout, job_id dikembalikan.

      10

      --dry-run

      Hanya menampilkan rencana kueri tanpa menjalankannya

      —

      --cost-check

      Membatalkan kueri jika perkiraan biaya melebihi ambang batas (dalam CUs)

      —

      --output

      Menulis hasil ke file

      —

      --output-format

      Format file output: table, json, csv, atau ndjson

      —

      --idempotency-key

      Kunci deduplikasi, digunakan untuk retry idempoten

      —

      --retry-on

      Daftar kode kesalahan yang dapat diulang, dipisahkan koma

      —

      --max-retries

      Jumlah maksimum percobaan ulang

      0

      --retry-backoff

      Kebijakan backoff: fixed atau exponential

      fixed

      --force

      Melewati mode read-only dan mengizinkan pernyataan DDL/DML

      —

    • --wait perilaku

      • --wait 10 (Default): Melakukan polling secara sinkron selama 10 detik. Jika pekerjaan selesai, hasil dikembalikan. Jika terjadi timeout, job_id dikembalikan.

      • --wait 0: Mengirimkan pekerjaan dan segera mengembalikan job_id.

      • --wait 300: Menunggu maksimal 5 menit.

      Setelah timeout, Anda dapat menggunakan job wait <job_id> untuk melanjutkan menunggu.

    • Contoh

      # Jalankan dari file
aliyun maxc query --file my_query.sql --json

# Perlindungan biaya: Secara otomatis membatalkan jika perkiraan biaya melebihi 100 CUs
aliyun maxc query "SELECT * FROM orders" --cost-check 100 --json

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

# Tulis hasil ke file CSV
aliyun maxc query "SELECT * FROM orders LIMIT 1000" --output result.csv --output-format csv --json

# Retry idempoten
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

    Manajemen pekerjaan (Job)

    Mengelola siklus hidup pekerjaan SQL asinkron.

    job submit

    Mengirimkan pekerjaan SQL dan segera mengembalikan job_id.

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

    Parameter

    Deskripsi

    Nilai default

    <sql>

    Teks SQL

    —

    --file

    Membaca SQL dari file

    —

    --stdin

    Membaca SQL dari input standar

    —

    --max-rows

    Jumlah maksimum baris yang dikembalikan

    100

    --cost-check

    Ambang batas biaya (dalam CUs)

    —

    --idempotency-key

    Kunci deduplikasi

    —

    --force

    Mengizinkan pernyataan DDL/DML

    —

    job status / wait / result / cancel / diagnose

    aliyun maxc job status <job_id> --json       # Memeriksa status
aliyun maxc job wait <job_id> --json         # Menunggu hingga selesai dan mengembalikan hasil
aliyun maxc job result <job_id> --json       # Mendapatkan hasil pekerjaan yang telah selesai
aliyun maxc job cancel <job_id> --json       # Membatalkan pekerjaan yang sedang berjalan
aliyun maxc job diagnose <job_id> --json     # Mendiagnosis penyebab kegagalan

    • Parameter tambahan untuk job wait

      Parameter

      Deskripsi

      Nilai default

      --timeout

      Timeout dalam detik

      300

      --stream

      Streaming output progres dalam format NDJSON

      —

    • Parameter tambahan untuk job result

      Parameter

      Deskripsi

      Nilai default

      --max-rows

      Jumlah maksimum baris yang dikembalikan

      100

      --cursor

      Kursor paginasi

      —

    job list

    aliyun maxc job list --json                  # Menampilkan pekerjaan terbaru (20 secara default)
aliyun maxc job list --limit 50 --json       # Tentukan jumlah pekerjaan

    Alur lengkap untuk kueri asinkron

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

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

# 3. Dapatkan hasil (mendukung paging)
aliyun maxc job result "$JOB_ID" --max-rows 1000 --json

    Penelusuran metadata (Meta)

    Operasi tabel

    # Daftar tabel
aliyun maxc meta list-tables --json

# Lihat skema tabel (--full menampilkan daftar kolom lengkap; mode ringkasan adalah default)
aliyun maxc meta describe my_table --json
aliyun maxc meta describe my_table --full --json

# Cari tabel
aliyun maxc meta search "order" --json

# Cari kolom
aliyun maxc meta search-columns "user_id" --json

    list-tables dan search mendukung paging dengan --limit dan --cursor. Secara default, search mengembalikan 20 item.

    Operasi partisi

    # Daftar partisi (maksimal 100 secara default)
aliyun maxc meta partitions my_table --json
aliyun maxc meta partitions my_table --limit 500 --json

# Lihat partisi terbaru
aliyun maxc meta latest-partition my_table --json

# Lihat kesegaran data
aliyun maxc meta freshness my_table --json

    Proyek dan skema

    # Daftar proyek yang dapat diakses
aliyun maxc meta list-projects --json

# Daftar skema dalam proyek
aliyun maxc meta list-schemas --json

    Metadata semantik

    Menyediakan informasi semantik bisnis tentang tabel untuk AI Agent. Untuk informasi lebih lanjut, lihat Integrasi AI Agent.

    # Tetapkan informasi semantik
aliyun maxc meta semantic set my_table \
  --desc "Tabel detail pesanan" \
  --use-cases "Analisis volume pesanan harian" "Hitung tingkat pembelian ulang pengguna" \
  --json

# Dapatkan informasi semantik
aliyun maxc meta semantic get my_table --json

# Daftar tabel yang tidak memiliki informasi semantik
aliyun maxc meta semantic list-missing --json

    semantic set juga mendukung --sample-questions, --column-semantics (JSON), --relations (JSON), dan --stats (JSON).

    Operasi data (Data)

    Contoh data

    Mengambil sampel data dari tabel. Untuk tabel partisi, partisi terbaru dipilih secara default. View tidak didukung.

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

    Parameter

    Deskripsi

    Nilai default

    <table_name>

    Nama tabel

    —

    --rows

    Jumlah baris yang diambil sebagai sampel

    5

    --partition

    Spesifikasi partisi

    Terbaru dipilih secara otomatis

    --columns

    Kolom yang disertakan (dipisahkan koma)

    Semua

    Profil data

    Menganalisis statistik kolom seperti persentase null, jumlah nilai unik, dan nilai min/maks. Hasil bersifat heuristik, berdasarkan sampel 20 baris.

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

    Unggah data

    Mengunggah file CSV atau TSV lokal ke tabel. Untuk tabel partisi, --partition wajib diisi. View dan tipe kompleks (array, map, struct) tidak didukung.

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

    Parameter

    Deskripsi

    Nilai default

    <table_name>

    Nama tabel tujuan

    —

    --file

    Path file lokal (wajib)

    —

    --partition

    Spesifikasi partisi (wajib untuk tabel partisi)

    —

    --overwrite

    Menggunakan semantik INSERT OVERWRITE

    —

    --delimiter

    Pemisah field

    ,

    --no-header

    Menunjukkan bahwa baris pertama adalah data, bukan header

    —

    --null-marker

    Penanda NULL

    \N

    --block-size

    Jumlah baris yang diunggah per batch

    10000

    Unduh data

    Mengunduh data tabel ke file CSV atau TSV lokal. Untuk tabel partisi, --partition wajib diisi. View tidak didukung.

    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

    Parameter

    Deskripsi

    Nilai default

    <table_name>

    Nama tabel sumber

    —

    --output

    Path file output (wajib)

    —

    --partition

    Spesifikasi partisi (wajib untuk tabel partisi)

    —

    --columns

    Kolom yang disertakan (dipisahkan koma)

    Semua

    --limit

    Jumlah maksimum baris yang diunduh

    Tanpa Batas

    --delimiter

    Pemisah field

    ,

    --no-header

    Tidak menulis baris header

    —

    --null-marker

    Penanda output NULL

    String kosong

    Manajemen sesi (Session)

    Mengelola proyek dan skema default untuk sesi saat ini. Ini adalah operasi lokal yang tidak memerlukan koneksi backend.

    # Tetapkan proyek default (tentukan minimal --project atau --schema)
aliyun maxc session set --project my_project_dev --json

# Tetapkan skema default
aliyun maxc session set --schema my_schema --json

# Lihat sesi saat ini
aliyun maxc session show --json

# Hapus pengaturan sesi
aliyun maxc session unset --json

    Untuk beralih sementara ke proyek lain tanpa mengubah konfigurasi sesi, gunakan parameter global --project:

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

    Format output

    JSON Envelope

    Menambahkan --json ke perintah apa pun menghasilkan JSON Envelope terpadu (v2.0):

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

    Field

    Tipe

    Deskripsi

    version

    string

    Tetap pada "2.0"

    command

    string

    Perintah yang dijalankan, seperti "query" atau "meta describe"

    status

    string

    "success" atau "failure"

    data

    object

    Data bisnis yang dikembalikan oleh perintah

    metadata

    object

    Metadata eksekusi (seperti nama proyek, waktu yang dikonsumsi, dan job_id)

    error

    object/null

    Detail kesalahan jika perintah gagal

    agent_hints

    object/null

    Aksi berikutnya yang direkomendasikan untuk AI Agent

    Field data

    Struktur field data bervariasi berdasarkan perintah:

    Perintah

    Kunci tingkat atas dalam data

    query / job wait / job result

    result (berisi 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 (berisi 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

    field error

    Jika perintah gagal, field error berisi field-field berikut:

    {
  "code": "TABLE_NOT_FOUND",
  "message": "Tabel 'orders' tidak ada di proyek 'my_project'",
  "suggestion": "Gunakan 'aliyun maxc meta search orders --json' untuk menemukan tabel serupa",
  "recoverable": false
}

    Field

    Deskripsi

    code

    Kode kesalahan (lihat tabel di bawah)

    message

    Deskripsi kesalahan

    suggestion

    Perbaikan yang direkomendasikan (opsional)

    recoverable

    Menunjukkan apakah operasi dapat diulang

    instance_id

    ID instans ODPS (hanya untuk kesalahan kueri, opsional)

    logview

    Tautan LogView (hanya untuk kesalahan kueri, opsional)

    context

    Konteks terstruktur (opsional)

    Kode kesalahan

    Kode kesalahan

    Deskripsi

    Dapat Dicoba Ulang

    EXECUTION_FAILED

    Eksekusi gagal

    Ya

    PERMISSION_DENIED

    Izin ditolak

    Tidak

    QUOTA_EXCEEDED

    Kuota terlampaui

    Ya

    SQL_ERROR

    Kesalahan sintaksis atau eksekusi SQL

    Tidak

    COST_LIMIT_EXCEEDED

    Batas biaya terlampaui

    Tidak

    NOT_FOUND

    Sumber daya tidak ditemukan

    Tidak

    TABLE_NOT_FOUND

    Tabel tidak ditemukan

    Tidak

    SCHEMA_NOT_FOUND

    Skema tidak ditemukan

    Tidak

    COLUMN_NOT_FOUND

    Kolom tidak ditemukan

    Tidak

    VALIDATION_ERROR

    Validasi input gagal

    Tidak

    BACKEND_CONNECTION_ERROR

    Tidak dapat terhubung ke backend

    Ya

    JOB_TIMEOUT

    Waktu tunggu polling pekerjaan habis

    Ya

    READ_ONLY_VIOLATION

    Operasi tulis diblokir oleh mode read-only

    Tidak

    WRITE_OPERATION_REQUIRES_FORCE

    Operasi tulis memerlukan --force

    Ya

    CSV_PARSE_ERROR

    Penguraian CSV gagal

    Tidak

    INTERNAL_ERROR

    Kesalahan internal

    Tidak

    Format lainnya

    Format

    Deskripsi

    table

    Tabel yang mudah dibaca (default)

    markdown

    Format Markdown

    brief

    Rangkuman satu baris

    csv

    CSV (hanya baris data)

    ndjson

    JSON yang dipisahkan baris baru, dengan satu record per baris

    Integrasi AI Agent

    maxc dirancang khusus untuk integrasi AI Agent. Bagian berikut mencakup desain inti dan pola penggunaannya.

    Protokol JSON terpadu

    Output --json dari setiap perintah mengikuti protokol Envelope tetap. Agent mengurai field terstruktur untuk umpan balik yang andal dan dapat diprediksi.

    • status: Menunjukkan keberhasilan atau kegagalan.

    • data: Data bisnis. Strukturnya tetap berdasarkan jenis perintah.

    • error.code + error.suggestion: Kode kesalahan dan saran yang dapat dieksekusi untuk perbaikan.

    • agent_hints.next_actions: Perintah berikutnya yang direkomendasikan oleh CLI. Ini adalah baris perintah lengkap dan dapat dieksekusi.

    • agent_hints.warnings: Risiko yang perlu diperhatikan, seperti biaya tinggi atau pemilihan partisi otomatis.

    Self-healing kesalahan

    Setiap respons kesalahan mencakup field suggestion dan agent_hints.next_actions yang memberi tahu Agent perintah apa yang harus dijalankan selanjutnya:

    Skenario kesalahan

    Panduan yang diterima Agent

    Tabel tidak ditemukan

    Menyarankan menjalankan meta search untuk menemukan tabel dengan nama serupa

    Kolom tidak ditemukan

    Menyarankan menjalankan meta describe untuk melihat skema tabel

    Izin tidak mencukupi

    Menyarankan beralih ke proyek _dev atau memeriksa identitas

    Kesalahan sintaksis SQL

    Menyarankan menjalankan query cost atau query explain untuk validasi

    Kuota terlampaui

    Menyarankan menjalankan query cost untuk mengevaluasi biaya kueri

    Waktu tunggu pekerjaan habis

    Menyarankan menjalankan job wait atau job status untuk melanjutkan pelacakan

    Agent membaca error.suggestion dan menjalankan kembali perintah yang disarankan untuk pulih secara otomatis—tidak diperlukan penanganan kesalahan yang dikodekan secara keras.

    Keamanan read-only

    maxc memblokir semua pernyataan DDL dan DML (CREATE, DROP, INSERT, UPDATE, DELETE) di sisi klien, mencegah modifikasi data yang tidak disengaja. Pemeriksaan lokal ini dijalankan sebelum SQL dikirim ke server, tanpa latensi dan tanpa biaya.

    Operasi tulis memerlukan pengguna untuk secara eksplisit memberikan --force—Agent tidak boleh menambahkan ini sendiri. Unggahan data melalui data upload menggunakan saluran Tunnel API terpisah dan tidak tunduk pada pembatasan ini.

    Kesadaran biaya

    Sebelum Agent menjalankan kueri, ia dapat memperkirakan biaya menggunakan query cost atau menetapkan batas biaya menggunakan --cost-check:

    # Perkirakan biaya
aliyun maxc query cost "SELECT * FROM large_table" --json

# Tetapkan ambang batas biaya
aliyun maxc query "SELECT * FROM large_table" --cost-check 100 --json

    Menanyakan tabel partisi tanpa filter partisi dapat memicu pemindaian tabel penuh dengan biaya tinggi. Agent harus menentukan rentang partisi dengan meta partitions atau meta latest-partition sebelum menjalankan kueri.

    Arsitektur pengetahuan berlapis SKILL

    SKILL adalah seperangkat dokumen panduan terstruktur yang diinstal pada platform Agent yang mengajarkan Agent cara menggunakan maxc untuk tugas data MaxCompute.

    # Instalasi satu klik ke Claude Code
aliyun maxc agent skill install --json

# Instal di platform lain
aliyun maxc agent skill install cursor --json
aliyun maxc agent skill install windsurf --json

    SKILL menggunakan pemuatan berlapis untuk mengoptimalkan efisiensi jendela konteks LLM:

    Lapisan

    Konten

    Waktu pemuatan

    Main file SKILL.md

    Tabel pemetaan intent-to-command, prinsip inti, alur kerja, tabel keputusan

    Dimuat otomatis saat tugas dipicu

    Dokumen referensi

    Panduan dialek SQL, templat kueri, strategi partisi, manual pemulihan kesalahan, dll.

    Dimuat sesuai permintaan (hanya saat Agent membutuhkannya)

    Kueri metadata sederhana hanya memerlukan file utama 270 baris. Pembuatan SQL kompleks atau pemulihan kesalahan memicu pemuatan dokumen referensi sesuai permintaan.

    Platform Agent yang didukung:

    Platform

    Path instalasi

    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 lainnya

    Tentukan --dir untuk menginstal ke direktori apa pun

    Manajemen SKILL

    # Lihat status instalasi di semua platform
aliyun maxc agent skill list --json

# Perbarui SKILL yang telah diinstal (setelah rilis versi baru)
aliyun maxc agent skill update --all --json

# Lihat perbedaan antara versi yang diinstal dan versi terbaru
aliyun maxc agent skill diff claude-code --json

# Uninstal
aliyun maxc agent skill uninstall cursor --json

    Alur kerja NL2SQL

    SKILL memandu Agent untuk mengonversi pertanyaan bahasa alami menjadi kueri SQL menggunakan alur berikut:

    Pertanyaan pengguna
  ↓
1. meta search / meta list-tables     → Temukan tabel yang relevan
  ↓
2. meta describe                      → Pahami skema tabel dan makna kolom
  ↓
3. data sample                        → Lihat data aktual untuk mengonfirmasi format nilai kolom
  ↓
4. meta partitions / latest-partition → Tentukan rentang partisi
  ↓
5. query cost                         → Perkirakan biaya
  ↓
6. query                              → Jalankan kueri dan kembalikan hasil

    Dokumen referensi SKILL mencakup panduan dialek SQL MaxCompute lebih dari 700 baris yang mencakup perbedaan fungsi, jebakan tipe, templat kueri, dan perbaikan kesalahan umum.

    Metadata semantik

    Perintah meta semantic melampirkan semantik bisnis ke tabel—deskripsi, kasus penggunaan, pertanyaan contoh, dan semantik kolom. Saat meta describe mengungkapkan semantik yang hilang, Agent dapat menghasilkan dan menyimpannya:

    aliyun maxc meta semantic set my_table \
  --description "Tabel log perilaku pengguna, mencatat event klik dan tampilan dalam aplikasi" \
  --usage-scenario "Analisis perilaku pengguna, statistik konversi funnel" \
  --sample-questions '["Berapa DAU dalam 7 hari terakhir?", "Apa tren tingkat konversi pendaftaran?"]' \
  --json

    Sesi Agent berikutnya membaca informasi ini, menciptakan siklus penggunaan, akumulasi, dan penggunaan ulang.

    Konteks Agent

    Agent dapat mengambil konteks saat ini secara lengkap sekaligus menggunakan agent context:

    aliyun maxc agent context --json

    Perintah ini mengembalikan status autentikasi, proyek, skema, dan path konfigurasi saat ini, membantu Agent memutuskan apakah akan memandu pengguna melalui autentikasi atau pergantian proyek.