Hologres CLI#

AI-agent-friendly command-line interface for Hologres with safety guardrails and structured JSON output.

Installation#

bash

# Requires Python 3.11+
pip install hologres-cli

# Or install a specific version
pip install hologres-cli==0.2.0

Configuration#

Profile-based configuration stored in ~/.hologres/config.json.

bash

# Interactive setup wizard
hologres config

# Or set values directly
hologres config set region_id cn-hangzhou
hologres config set instance_id hgprecn-cn-xxx
hologres config set database mydb

Profile resolution priority: --profile <name> flag > current profile > error (prompts to run hologres config).

Quick Start#

bash

pip install hologres-cli
hologres config                                   # Interactive setup
hologres status                                    # Check connection
hologres schema tables                             # List tables
hologres sql run "SELECT * FROM orders LIMIT 10"   # Query data
hologres --profile prod status                     # Use specific profile
hologres dt list                                   # List Dynamic Tables

Core Commands#

CommandDescriptionhologres statusCheck connection statushologres instance <name>Query instance version/connectionshologres warehouse [name]List or query warehouseshologres schema tablesList all tableshologres schema describe <table>Show table structurehologres schema dump <schema.table>Export DDLhologres schema size <schema.table>Get table storage sizehologres table list [--schema S]List all tableshologres table create -n TABLE -c COLS [options] [--dry-run]Create a table (supports logical partition V3.1+)hologres table dump <schema.table>Export DDL for a tablehologres table show <table>Show table structure (columns, types, nullable, defaults, primary key, comments)hologres table size <schema.table>Get table storage sizehologres table properties <table>Show Hologres-specific table properties (orientation, distribution_key, clustering_key, TTL, etc.)hologres table drop <table> [--if-exists] [--cascade] --confirmDrop a table (dry-run by default)hologres table truncate <table> --confirmTruncate (empty) a table (dry-run by default)hologres table alter TABLE [options] [--dry-run]Alter table properties (add column, rename, TTL, etc.)hologres partition list --table <table>List partitions of a logical partition tablehologres partition create --table <table>Create partition (no-op for logical tables, returns notice)hologres partition drop --table <table> --partition VALUE --confirmDrop partition (deletes partition data)hologres partition alter --table <table> --partition <value> --set <key=value> [--dry-run]Alter partition properties (keep_alive, storage_mode, generate_binlog)hologres partition alter --table <table> --partition <value> --set <key=value> [--dry-run]Alter partition properties (keep_alive, storage_mode, generate_binlog)hologres view list [--schema S]List all viewshologres view show <view>Show view definition and structurehologres extension listList installed extensionshologres extension create <name> [--if-not-exists]Create (install) a database extensionhologres guc show <param>Show current value of a GUC parameterhologres guc set <param> <value>Set GUC parameter at database level (persistent)hologres sql run "<query>"Execute read-only SQLhologres sql run --write "<dml>"Execute write SQLhologres sql explain "<query>"Show SQL execution planhologres data export <table> -f out.csv [-q <query>] [-d <delimiter>]Export to CSVhologres data import <table> -f in.csv [-d <delimiter>] [--truncate]Import from CSVhologres data count <table> [-w <where>]Count rowshologres history [-n <count>]Show command historyhologres ai-guideGenerate AI agent guidehologres ai gen "<prompt>" [--model]Generate text using AI functionhologres ai image-gen "<prompt>" -o volume://vol/path [options]Generate images to OSS volume using AI functionhologres ai t2v "<prompt>" -o volume://vol/path [options]Generate video from text (text-to-video)hologres ai i2v "<prompt>" --img-url <url|local_file> -o volume://vol/path [options]Generate video from first-frame image (image-to-video)hologres ai r2v "<prompt>" --reference-url <url|local_file> -o volume://vol/path [options]Generate video from reference images (reference-to-video)hologres ai video-edit "<prompt>" --video <url|local_file> -o volume://vol/path [options]Edit video with text instructionshologres volume create <name> --endpoint <ep> --root <root> --rolearn <arn> --access-key <ak> --access-secret <sk>Create a local volume config (also creates OSS directory placeholder)hologres volume listList all volumes in current profilehologres volume delete <name>Delete a volume confighologres volume list-files --volume <name> [--prefix P] [--max-count N] [--net internet|intranet]List files in volumehologres volume delete-file --volume <name> --file <path> [--confirm] [--net internet|intranet]Delete file from volume (dry-run by default)hologres volume download-file --volume <name> --file <path> -d <dir> [--net internet|intranet]Download file from volumehologres volume upload-file --volume <name> --local-file <path> --target-file <path> [--net internet|intranet]Upload file to volumehologres volume view volume://<name>/path/file [--net internet|intranet]Download file to temp dir and open with system viewerhologres model list [--task T] [--model-type T] [--search S]List registered external AI modelshologres model catalog [--task T] [--search S]List supported AI model types from the bundled catalog (no DB connection)hologres model create --name N --type T --api-key K [--config J] [--dry-run]Register an external AI model via add_external_model()``hologres model delete <model_name> [--confirm]Delete a registered external AI model (dry-run by default)

Dynamic Table Commands (V3.1+)#

Full lifecycle management for Hologres Dynamic Tables.

CommandDescriptionhologres dt createCreate a Dynamic Tablehologres dt listList all Dynamic Tableshologres dt show <table>Show Dynamic Table propertieshologres dt ddl <table>Show DDL (CREATE statement)hologres dt lineage <table>Show dependency lineagehologres dt lineage --allShow lineage for all DTshologres dt storage <table>Show storage detailshologres dt state-size <table>Show state table size (incremental)hologres dt refresh <table>Trigger manual refreshhologres dt alter <table>Alter DT propertieshologres dt drop <table>Drop DT (dry-run by default)hologres dt convert [table]Convert V3.0 → V3.1 syntax

dt create#

bash

# Minimal
hologres dt create -t my_dt --freshness "10 minutes" \
  -q "SELECT col1, SUM(col2) FROM src GROUP BY col1"

# With partitioning and serverless
hologres dt create -t ads_report --freshness "5 minutes" --refresh-mode auto \
  --logical-partition-key ds --partition-active-time "2 days" \
  --partition-time-format YYYY-MM-DD \
  --computing-resource serverless --serverless-cores 32 \
  -q "SELECT repo_name, COUNT(*) AS events, ds FROM src GROUP BY repo_name, ds"

# Incremental refresh
hologres dt create -t tpch_q1 --freshness "3 minutes" --refresh-mode incremental \
  -q "SELECT l_returnflag, l_linestatus, COUNT(*) FROM lineitem GROUP BY 1,2"

# Dry-run (preview SQL without executing)
hologres dt create -t my_dt --freshness "10 minutes" -q "SELECT 1" --dry-run

Key create options:

OptionDescription-t, --tableTable name [schema.]table (required)-q, --querySQL query for data definition (required)--freshnessData freshness target, e.g. "10 minutes" (required)--refresh-mode``auto / full / incremental``--auto-refresh/--no-auto-refreshEnable/disable auto refresh--cdc-format``stream (default) / binlog``--computing-resource``local / serverless / <warehouse>``--serverless-coresServerless computing cores--logical-partition-keyPartition column for logical partition--partition-active-timeActive partition window, e.g. "2 days"``--partition-time-formatPartition key format, e.g. YYYY-MM-DD``--orientation``column / row / row,column``--distribution-keyDistribution key columns--clustering-keyClustering key with sort order--event-time-columnEvent time column (Segment Key)--ttlData TTL in seconds--refresh-gucGUC params for refresh (repeatable)--dry-runPreview SQL without executing

dt list / show / ddl#

bash

hologres dt list                     # List all DTs with refresh info
hologres dt show public.my_dt        # Show all properties
hologres dt ddl public.my_dt         # Show CREATE statement
hologres dt list -f table            # Table format output

dt lineage#

bash

hologres dt lineage public.my_dt     # Single table lineage
hologres dt lineage --all            # All DTs lineage
hologres dt lineage my_dt -f table   # Table format

base_table_type: r =table, v =view, m =materialized view, f =foreign table, d =Dynamic Table.

dt storage / state-size#

bash

hologres dt storage public.my_dt      # Storage breakdown
hologres dt state-size public.my_dt   # State table size (incremental DTs)

dt refresh#

bash

hologres dt refresh my_dt
hologres dt refresh my_dt --overwrite --partition "ds = '2025-04-01'" --mode full
hologres dt refresh my_dt --dry-run

dt alter#

bash

hologres dt alter my_dt --freshness "30 minutes"
hologres dt alter my_dt --no-auto-refresh
hologres dt alter my_dt --refresh-mode full --computing-resource serverless
hologres dt alter my_dt --refresh-guc timezone=GMT-8:00 --dry-run

dt drop#

bash

hologres dt drop my_dt               # Dry-run by default (safety)
hologres dt drop my_dt --confirm     # Actually drop
hologres dt drop my_dt --if-exists --confirm

dt convert (V3.0 → V3.1)#

bash

hologres dt convert my_old_dt          # Convert single table
hologres dt convert --all              # Convert all V3.0 tables
hologres dt convert my_old_dt --dry-run

Output Formats#

Partition Management#

bash

# List partitions
hologres partition list -t public.logs

# Drop a partition
hologres partition drop -t my_table --partition "2025-04-01" --confirm

# Alter partition properties
hologres partition alter -t public.logs --partition "ds=2025-03-16" --set "keep_alive=TRUE"
hologres partition alter -t my_table --partition "ds=2025-03-16" --set "keep_alive=TRUE" --set "storage_mode=hot" --dry-run

Output Formats#

bash

hologres -f json schema tables    # JSON (default)
hologres -f table schema tables   # Human-readable table
hologres -f csv schema tables     # CSV
hologres -f jsonl schema tables   # JSON Lines

Response Structure#

json

// Success
{"ok": true, "data": {"rows": [...], "count": 10}}

// Error
{"ok": false, "error": {"code": "ERROR_CODE", "message": "..."}}

Safety Features#

0. Default Session GUC Protection#

All connections automatically set safety GUCs upon creation:

• SET hg_experimental_enable_adaptive_execution = on — Enables adaptive execution to prevent OOM
• SET hg_computing_resource = 'serverless' — Routes queries to the serverless computing pool

These are applied transparently at the connection layer; no user action needed.

1. Row Limit Protection#

Queries without LIMIT returning >100 rows fail with LIMIT_REQUIRED.

bash

# Will fail if >100 rows
hologres sql run "SELECT * FROM large_table"

# Fix: add LIMIT
hologres sql run "SELECT * FROM large_table LIMIT 50"

# Or disable check
hologres sql run --no-limit-check "SELECT * FROM large_table"

2. Write Protection#

Write operations (INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE) require --write flag.

bash

hologres sql run --write "INSERT INTO logs VALUES (1, 'test')"

3. Dangerous Write Blocking#

DELETE/UPDATE without WHERE clause are blocked.

bash

# Blocked
hologres sql run --write "DELETE FROM users"

# Must have WHERE
hologres sql run --write "DELETE FROM users WHERE status='inactive'"

Error Codes#

CodeDescriptionCONNECTION_ERRORFailed to connectQUERY_ERRORSQL execution errorLIMIT_REQUIREDNeed LIMIT clauseWRITE_GUARD_ERRORWrite operation without --write flagDANGEROUS_WRITE_BLOCKEDDELETE/UPDATE without WHERE clauseWRITE_BLOCKEDWrite operation not allowedNOT_FOUNDTable or resource not foundINVALID_INPUTInvalid identifier or input validation failedINVALID_ARGSInvalid or missing argumentsNO_CHANGESNo properties specified to alterEXPORT_ERRORData export failedIMPORT_ERRORData import failedVIEW_NOT_FOUNDView not foundOSS_ERROROSS operation failed (e.g. directory placeholder creation on volume create)

Sensitive Data Masking#

Auto-masks by column name pattern:

• phone/mobile/tel → 138****5678
• email → j***@example.com
• password/secret/token → ********

Disable: hologres sql run --no-mask "SELECT * FROM users LIMIT 10"

References#

DocumentContentcommands.mdComplete command reference with DT commandsai-volume-model.mdAI generation, volume storage, and model commandssafety-features.mdSafety guardrails details

Best Practices#

1. Always use LIMIT for large result sets
2. Use --dry-run to preview DT SQL before executing
3. Use --confirm explicitly for destructive operations (table drop, table truncate, dt drop)
4. Include WHERE clause in DELETE/UPDATE
5. Use JSON output for automation/scripting
6. Check hologres status before batch operations
7. Use hologres dt lineage to understand DT dependencies before altering

SQL Tracking#

Set HOLOGRES_SKILL environment variable before calling CLI to tag queries with skill origin:

bash

export HOLOGRES_SKILL=hologres-query-optimizer
hologres sql run "SELECT * FROM orders LIMIT 10"

Queries will appear in hg_query_log with application_name = "hologres-cli/hologres-query-optimizer".

This enables per-skill SQL statistics on the Hologres server:

sql

SELECT
  split_part(application_name, '/', 2) AS skill,
  COUNT(*) AS query_count,
  AVG(duration) AS avg_duration_ms
FROM hologres.hg_query_log
WHERE query_start > now() - interval '1 hour'
  AND application_name LIKE 'hologres-cli/%'
GROUP BY 1
ORDER BY 2 DESC;