hologres-cli

name	hologres-cli
description	AI-agent-friendly Hologres CLI with safety guardrails and structured JSON output. Use for database operations, schema inspection, SQL execution, data import/export, Dynamic Table lifecycle management (V3.1+ syntax), and GUC parameter management. Triggers: "hologres cli", "hologres command", "hologres database", "dynamic table", "hologres查询", "hologres guc", "GUC parameter"

Hologres CLI

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

Installation

# 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.

# 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

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

Command	Description
hologres status	Check connection status
hologres instance <name>	Query instance version/connections
hologres warehouse [name]	List or query warehouses
hologres schema tables	List all tables
hologres schema describe <table>	Show table structure
hologres schema dump <schema.table>	Export DDL
hologres schema size <schema.table>	Get table storage size
hologres table list [--schema S]	List all tables
hologres 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 table
hologres table show <table>	Show table structure (columns, types, nullable, defaults, primary key, comments)
hologres table size <schema.table>	Get table storage size
hologres table properties <table>	Show Hologres-specific table properties (orientation, distribution_key, clustering_key, TTL, etc.)
hologres table drop <table> [--if-exists] [--cascade] --confirm	Drop a table (dry-run by default)
hologres table truncate <table> --confirm	Truncate (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 table
hologres partition create --table <table>	Create partition (no-op for logical tables, returns notice)
hologres partition drop --table <table> --partition VALUE --confirm	Drop 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 views
hologres view show <view>	Show view definition and structure
hologres extension list	List installed extensions
hologres extension create <name> [--if-not-exists]	Create (install) a database extension
hologres guc show <param>	Show current value of a GUC parameter
hologres guc set <param> <value>	Set GUC parameter at database level (persistent)
hologres sql run "<query>"	Execute read-only SQL
hologres sql run --write "<dml>"	Execute write SQL
hologres sql explain "<query>"	Show SQL execution plan
hologres data export <table> -f out.csv [-q <query>] [-d <delimiter>]	Export to CSV
hologres data import <table> -f in.csv [-d <delimiter>] [--truncate]	Import from CSV
hologres data count <table> [-w <where>]	Count rows
hologres history [-n <count>]	Show command history
hologres ai-guide	Generate AI agent guide
hologres ai gen "<prompt>" [--model]	Generate text using AI function
hologres ai image-gen "<prompt>" -o volume://vol/path [options]	Generate images to OSS volume using AI function
hologres 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 instructions
hologres 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 list	List all volumes in current profile
hologres volume delete <name>	Delete a volume config
hologres volume list-files --volume <name> [--prefix P] [--max-count N] [--net internet|intranet]	List files in volume
hologres 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 volume
hologres volume upload-file --volume <name> --local-file <path> --target-file <path> [--net internet|intranet]	Upload file to volume
hologres volume view volume://<name>/path/file [--net internet|intranet]	Download file to temp dir and open with system viewer
hologres model list [--task T] [--model-type T] [--search S]	List registered external AI models
hologres 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
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.

Command	Description
hologres dt create	Create a Dynamic Table
hologres dt list	List all Dynamic Tables
hologres dt show <table>	Show Dynamic Table properties
hologres dt ddl <table>	Show DDL (CREATE statement)
hologres dt lineage <table>	Show dependency lineage
hologres dt lineage --all	Show lineage for all DTs
hologres dt storage <table>	Show storage details
hologres dt state-size <table>	Show state table size (incremental)
hologres dt refresh <table>	Trigger manual refresh
hologres dt alter <table>	Alter DT properties
hologres dt drop <table>	Drop DT (dry-run by default)
hologres dt convert [table]	Convert V3.0 → V3.1 syntax

dt create

# 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:

Option	Description
-t, --table	Table name [schema.]table (required)
-q, --query	SQL query for data definition (required)
--freshness	Data freshness target, e.g. "10 minutes" (required)
--refresh-mode	auto / full / incremental
--auto-refresh/--no-auto-refresh	Enable/disable auto refresh
--cdc-format	stream (default) / binlog
--computing-resource	local / serverless / <warehouse>
--serverless-cores	Serverless computing cores
--logical-partition-key	Partition column for logical partition
--partition-active-time	Active partition window, e.g. "2 days"
--partition-time-format	Partition key format, e.g. YYYY-MM-DD
--orientation	column / row / row,column
--distribution-key	Distribution key columns
--clustering-key	Clustering key with sort order
--event-time-column	Event time column (Segment Key)
--ttl	Data TTL in seconds
--refresh-guc	GUC params for refresh (repeatable)
--dry-run	Preview SQL without executing

dt list / show / ddl

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

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

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

dt refresh

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

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

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)

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

# 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

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

// 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.

# 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.

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

3. Dangerous Write Blocking

DELETE/UPDATE without WHERE clause are blocked.

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

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

Error Codes

Code	Description
CONNECTION_ERROR	Failed to connect
QUERY_ERROR	SQL execution error
LIMIT_REQUIRED	Need LIMIT clause
WRITE_GUARD_ERROR	Write operation without --write flag
DANGEROUS_WRITE_BLOCKED	DELETE/UPDATE without WHERE clause
WRITE_BLOCKED	Write operation not allowed
NOT_FOUND	Table or resource not found
INVALID_INPUT	Invalid identifier or input validation failed
INVALID_ARGS	Invalid or missing arguments
NO_CHANGES	No properties specified to alter
EXPORT_ERROR	Data export failed
IMPORT_ERROR	Data import failed
VIEW_NOT_FOUND	View not found
OSS_ERROR	OSS 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

Document	Content
commands.md	Complete command reference with DT commands
ai-volume-model.md	AI generation, volume storage, and model commands
safety-features.md	Safety 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:

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:

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;

Error Codes Reference

All CLI errors return structured JSON with retryable and hint fields for automatic retry decisions:

{"ok": false, "error": {"code": "...", "message": "...", "retryable": true/false, "hint": "..."}}

Code	Retryable	When	Agent Action
CONNECTION_ERROR	Yes	Network/auth failure	Check config, retry after delay
CONNECTION_TIMEOUT	Yes	Server busy	Retry after short delay
CONFIG_ERROR	No	Invalid config	Run hologres config
PROFILE_NOT_FOUND	No	Profile missing	Use hologres config list
INVALID_INPUT	No	Bad parameters	Fix input and retry
INVALID_ARGS	No	Wrong arguments	Check --help
WRITE_GUARD_ERROR	No	Write without flag	Add --write flag
DANGEROUS_WRITE_BLOCKED	No	DELETE/UPDATE no WHERE	Add WHERE clause
LIMIT_REQUIRED	No	SELECT >100 rows	Add LIMIT or --no-limit-check
QUERY_ERROR	Yes	SQL execution failed	Check syntax, retry once
QUERY_TIMEOUT	Yes	Query too slow	Simplify query or add filters
TABLE_NOT_FOUND	No	Table doesn't exist	Verify with hologres table list
NOT_FOUND	No	Resource missing	Run corresponding list command
FILE_NOT_FOUND	No	Path invalid	Verify file path
OSS_ERROR	Yes	Storage failure	Check credentials, retry
NO_CHANGES	No	Nothing to alter	Specify properties to change
INTERNAL_ERROR	Yes	Unexpected failure	Retry once, then report bug
MODEL_TYPE_NOT_SUPPORTED	No	Wrong model type	Use hologres model list