Hologres:Use Hologres AI Plugins

Scenarios

• Manage tables, dynamic tables, schemas, and permissions in bulk from the terminal or a shell script, instead of clicking through the console.

• Run data imports, dynamic table refreshes, and schema changes inside CI/CD pipelines, and feed the JSON output into your monitoring stack.

• Drive Hologres from natural language inside Claude Code, Cursor, or another AI coding tool to optimize SQL, analyze slow queries, or design UV deduplication solutions.

• Generate text, images, and video through Hologres AI functions and write the output directly to an Object Storage Service (OSS) bucket through a Hologres Volume.

Comparison with other tools

Method 1: One-click install script (recommended)

Run the following command to install the CLI:

curl -sSf https://raw.githubusercontent.com/aliyun/hologres-ai-plugins/master/hologres-cli/install.sh | sh

After installation, reload the shell so that the updated PATH takes effect:

source ~/.bashrc   # bash users
source ~/.zshrc    # zsh users

Method 2: pip install

In a Python 3.11 or later environment, run:

pip install hologres-cli

Method 3: uv install

Use uv tool to install the CLI globally, isolated from any project's dependencies:

uv tool install hologres-cli

Verify the installation

Print the CLI version. A version string indicates that the installation succeeded.

hologres --version

Run the interactive configuration wizard

For first-time setup, start the wizard:

hologres config

The wizard prompts for the following nine fields in order:

1. Profile name: An identifier for this connection set, such as default, dev, or prod. Allowed characters are letters, digits, underscores, and hyphens. Names are case-sensitive, and a duplicate name overwrites the existing profile.

2. Region: The region ID of the instance, such as cn-hangzhou, cn-shanghai, or cn-beijing.

3. Instance ID: The Hologres instance ID, formatted as hgprecn-cn-xxx. You can find it on the instance details page in the Hologres console.

4. Network type: internet (public network), intranet (classic network), or vpc (VPC). For details, see the network type selection table later in this section.

5. Authentication method: basic (database username and password) or ram (RAM user AccessKey pair).

6. Database name: The database to connect to inside the instance.

7. Warehouse: The compute warehouse to use.

8. Endpoint: Optional. If you leave it empty, the CLI builds the endpoint from the instance ID, region, and network type. For details, see Endpoint format later in this section.

9. Port: Defaults to 80, which is the PG Wire protocol port for Hologres. The same port applies in both VPC and public network deployments. To use SSL or TLS, declare it explicitly in the endpoint or in a dedicated parameter, as described in the Hologres connection documentation.

The wizard saves the profile to ~/.hologres/config.json. Run a status check to confirm the configuration:

hologres status

Choose a network type

The network type determines how the CLI builds the endpoint and routes traffic. Choosing the wrong type results in connection timeouts or DNS failures. Use the following table to make the correct choice:

Manage profiles

Use the following commands to view, switch, and update profiles:

# List all profiles
hologres config list

# Show details of the current profile
hologres config show

# Switch to another profile
hologres config switch prod

# Set a configuration value directly
hologres config set database my_new_db
hologres config set warehouse my_warehouse

# Read a single configuration value
hologres config get database

# Delete a profile
hologres config delete old_profile --confirm

Switch environments per command

To run a single command against a different environment without changing the default profile, pass the --profile flag. This is useful in scripts that operate on multiple environments side by side:

hologres --profile dev status
hologres --profile staging sql run "SELECT 1"
hologres --profile prod schema tables

Endpoint format

When the endpoint field is empty, the CLI assembles the host from instance_id, region_id, and the network type:

Check the connection status

Verify that the current profile can reach Hologres:

hologres status

A successful response looks similar to:

{
  "ok": true,
  "data": {
    "connected": true,
    "version": "Hologres 2.2.0.x",
    "database": "my_db"
  }
}

When the connection fails, ok is false, and the response carries the CONNECTION_ERROR error code along with a description. Use the description to troubleshoot network, allowlist, or authentication issues.

Choose an output format

The CLI supports four output formats. Use the global -f flag to pick one. The default is JSON:

hologres -f json  schema tables    # JSON, the default, ideal for agents and scripts
hologres -f table schema tables    # Terminal table, ideal for human review
hologres -f csv   schema tables    # CSV, ideal for downstream processing
hologres -f jsonl schema tables    # JSON Lines, ideal for stream processing

Inspect the instance and warehouses

hologres instance                     # Show the version and max connections of the instance bound to the current profile
hologres warehouse                    # List all warehouses
hologres warehouse default_warehouse  # Show details of a specific warehouse

View command history

hologres history          # Show recent commands
hologres history -n 50    # Show the last 50 commands

List tables

hologres table list                    # List all tables in the current database
hologres table list --schema public    # List tables under a specific schema
hologres table list -f table           # Output as a terminal table

A typical JSON response:

{
  "ok": true,
  "data": [
    {"schema": "public", "name": "orders", "type": "table"},
    {"schema": "public", "name": "users",  "type": "table"}
  ]
}

Inspect a table

hologres table show public.orders        # Columns, types, primary key, and comments
hologres table properties public.orders  # Storage format, distribution key, TTL
hologres table dump public.orders        # Full DDL
hologres table size public.orders        # Storage size

Create a table

Create a column-oriented table:

hologres table create --name public.orders \
  --columns "order_id BIGINT NOT NULL, user_id INT, amount DECIMAL(10,2), created_at TIMESTAMPTZ" \
  --primary-key order_id \
  --orientation column \
  --distribution-key order_id \
  --clustering-key "created_at:asc" \
  --ttl 7776000 \
  --dry-run

Create a logical partitioned table (V3.1 or later):

hologres table create --name public.logs \
  --columns "a TEXT, b INT, ds DATE NOT NULL" \
  --primary-key "b,ds" \
  --partition-by ds \
  --partition-mode logical \
  --orientation column \
  --distribution-key b \
  --partition-expiration-time "30 day" \
  --dry-run

Alter a table

hologres table alter my_table --add-column "age INT"
hologres table alter my_table --rename-column "old_col:new_col"
hologres table alter my_table --ttl 3600
hologres table alter my_table --dictionary-encoding-columns "a:on,b:auto"
hologres table alter my_table --partition-expiration-time "60 day"
hologres table alter my_table --ttl 3600 --dry-run   # Preview the generated SQL

Drop or truncate a table

hologres table drop my_table              # Preview only (default dry-run)
hologres table drop my_table --confirm    # Actually drop the table
hologres table truncate my_table --confirm # Empty the table but keep its schema

Manage partitions

hologres partition list --table my_table
hologres partition drop --table my_table --partition "2025-04-01" --confirm
hologres partition alter -t my_table --partition "ds=2025-03-16" --set "keep_alive=TRUE"

Manage views

hologres view list
hologres view show analytics.daily_stats

Create a dynamic table

Basic example:

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

Use incremental refresh and serverless compute:

hologres dt create -t ads_report \
  --freshness "5 minutes" \
  --refresh-mode incremental \
  --computing-resource serverless \
  -q "SELECT region, SUM(amount) FROM orders GROUP BY region"

Preview the generated SQL only:

hologres dt create -t my_dt --freshness "10 minutes" -q "SELECT 1" --dry-run

Inspect dynamic tables

hologres dt list                    # List all dynamic tables
hologres dt show public.my_dt       # Properties and refresh status
hologres dt ddl public.my_dt        # Export the DDL
hologres dt lineage public.my_dt    # Show lineage dependencies
hologres dt storage public.my_dt    # Storage size
hologres dt state-size public.my_dt # State table size

Alter, refresh, or drop a dynamic table

hologres dt alter my_dt --freshness "30 minutes"
hologres dt refresh my_dt
hologres dt drop my_dt               # Preview only
hologres dt drop my_dt --confirm     # Actually drop

Upgrade from V3.0 to V3.1

Convert dynamic tables that were created on V3.0 to the V3.1 format:

hologres dt convert my_old_dt   # Convert a single dynamic table
hologres dt convert --all       # Batch-convert every V3.0 dynamic table in the current database

Read-only queries

hologres sql run "SELECT * FROM orders LIMIT 10"
hologres sql run --with-schema "SELECT * FROM orders LIMIT 10"   # Include column names and types
hologres sql run --no-limit-check "SELECT * FROM large_table"    # Disable the row count check

By default, a SELECT statement without a LIMIT clause is blocked when it returns more than 100 rows. For details, see the row count limit description in the Security guardrails section. To bypass this check, pass --no-limit-check.

Write operations

Write SQL statements require the explicit --write flag:

hologres sql run --write "INSERT INTO logs VALUES (1, 'test')"
hologres sql run --write "DELETE FROM logs WHERE created_at < '2024-01-01'"

View the execution plan

hologres sql explain "SELECT * FROM orders WHERE status = 'active'"

Prerequisites for AI features

Complete both of the following steps before you call any AI command:

1. Register a foundation model: Use hologres model create to register the model you plan to use (such as Tongyi Qianwen or Tongyi Wanxiang) in the Hologres instance, providing the model type, name, and API key. For details, see the Manage foundation models section.

2. Configure a Volume: Use hologres volume create to register a Volume in Hologres that maps to an OSS bucket. The Volume becomes the storage destination for generated content. For details, see Manage Volume storage.

When you create a Volume, we recommend using a RAM role (RoleArn) to authorize OSS access. If you must use an AccessKey pair, pass it through environment variables instead of writing it on the command line:

# Authorize through a RAM role (recommended)
hologres volume create my_vol \
  --endpoint oss-cn-hangzhou-internal.aliyuncs.com \
  --root oss://my-bucket/ai-output/ \
  --rolearn acs:ram::123456:role/AliyunHologresDefaultRole

# Or, if you must use an AccessKey pair, pass it via environment variables
export HOLO_AK="$(security find-generic-password -s holo_ak -w)"
export HOLO_SK="$(security find-generic-password -s holo_sk -w)"
hologres volume create my_vol \
  --endpoint oss-cn-hangzhou-internal.aliyuncs.com \
  --root oss://my-bucket/ai-output/ \
  --access-key "$HOLO_AK" \
  --access-secret "$HOLO_SK"

Generate text

hologres ai gen "Introduce the core advantages of Hologres"
hologres ai gen "Write a poem about data" --model qwen-max

Generate images

hologres ai image-gen "Tech-style data warehouse concept art" -o volume://my_vol/images
hologres ai image-gen "Product showcase" --size "1280*720" -n 2 -o volume://my_vol/output
hologres ai image-gen "Q-style cartoon" --reference-url volume://my_vol/ref.png -o volume://my_vol/output

Generate and edit video

# Text to video
hologres ai t2v "A cat running across a meadow" -o volume://my_vol/output

# Image to video
hologres ai i2v "Animate this image" --img-url volume://my_vol/frame.png -o volume://my_vol/output

# Reference image to video
hologres ai r2v "A woman strolling through a garden" --reference-url volume://my_vol/girl.png -o volume://my_vol/output

# Edit video
hologres ai video-edit "Convert to anime style" --video volume://my_vol/input.mp4 -o volume://my_vol/output

Common commands

hologres volume list                                    # List all Volumes
hologres volume list-files --volume my_vol              # List files in a Volume
hologres volume list-files --volume my_vol --prefix images/ --max-count 50
hologres volume upload-file --volume my_vol --local-file ./data.csv --target-file data/data.csv
hologres volume download-file --volume my_vol --file report.csv -d ./output
hologres volume view volume://my_vol/images/photo.png   # Preview a file in the terminal
hologres volume delete-file --volume my_vol --file old.csv --confirm
hologres volume delete my_vol                           # Delete the Volume registration (does not delete OSS data)

Network type for Volume traffic

Volume operations run over either the public network or the private network. Use the --net flag to choose:

hologres volume list-files --volume my_vol --net internet   # Public network (default)
hologres volume list-files --volume my_vol --net intranet   # Private network (recommended for ECS and VPC clients)

Layer 1: Row count limit

A SELECT statement without a LIMIT clause returns at most 100 rows by default. Anything beyond that triggers the LIMIT_REQUIRED error. The limit prevents accidental retrieval of huge result sets.

The 100-row cap is the CLI's built-in default. To bypass it, pass --no-limit-check. Bulk commands such as data export and data import are exempt from this check.

Layer 2: Read-only connections

Every connection runs SET default_transaction_read_only = ON by default, so the database engine rejects writes at the transaction level. Even if a SQL statement carries write semantics by mistake, it cannot reach storage.

Layer 3: Explicit authorization for write operations

Write operations require explicit authorization:

A write that is not explicitly authorized fails with WRITE_GUARD_ERROR.

Layer 4: Block dangerous operations

A DELETE or UPDATE without a WHERE clause is rejected with DANGEROUS_WRITE_BLOCKED. --write does not bypass this guard. Add an explicit filter and rerun the statement.

Layer 5: Serverless compute isolation

SQL submitted by an agent is routed to a dedicated serverless compute pool, isolated from the dedicated compute resources that serve production. Exploratory AI queries cannot interfere with online workloads.

Layer 6: Adaptive execution

Complex SQL is scheduled in stages by the adaptive execution engine, which scales compute resources on demand and prevents a single query from triggering an out-of-memory (OOM) failure.

Automatic masking for sensitive data

The CLI masks columns whose names match the following sensitive fields in the result set:

To disable masking, for example during compliance-approved operational tasks that require the raw values, add --no-mask:

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

Credential encryption

The CLI encrypts the database password and any AccessKey with the Fernet algorithm before writing them to ~/.hologres/config.json. The encryption key is stored in ~/.hologres/.cipher_key with file permissions 0600. Older plaintext configurations remain readable, and the CLI rewrites them in the encrypted format on the next save.

Error codes

Installation methods

The recommended path is the one-click install script, which downloads the packages, installs the dependencies, and starts the interactive selector:

curl -sSf https://raw.githubusercontent.com/aliyun/hologres-ai-plugins/master/agent-skills/install.sh | sh

Alternatively, run the installer directly with uvx (no prior installation required):

uvx hologres-agent-skills

Interactive installation flow

After the install script starts, the interactive selector walks you through three steps:

1. Choose the AI tool: Select your tool from the list of Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Qoder, Trae, OpenClaw, and OpenCode. Use the up and down arrow keys to move the cursor, then press Enter to confirm.

2. Choose the skill packages: A multi-select prompt opens. Press Space to toggle a package, use the arrow keys to move, and press Enter to continue. To go back, press Esc.

3. Deploy: The script copies the selected packages into the AI tool's local directory. Once deployment finishes, the script prints the install path and version of every skill.

Sample interactive flow:

? Choose an AI tool (use ↑/↓ keys, press Enter to confirm):
  ❯ Claude Code
    Cursor
    OpenAI Codex
    GitHub Copilot
    Qoder
    Trae
    OpenClaw
    OpenCode

? Choose the skills to install (Space to toggle, Enter to confirm):
  [x] hologres-cli
  [x] hologres-query-optimizer
  [ ] hologres-slow-query-analysis
  [x] hologres-schema-generator
  [ ] hologres-privileges
  [ ] hologres-uv-compute
  [ ] hologres-bsi-profile-analysis
  [ ] hologres-ad-campaign

✔ Deployment complete
  hologres-cli                 → ~/project/.claude/skills/hologres-cli
  hologres-query-optimizer     → ~/project/.claude/skills/hologres-query-optimizer
  hologres-schema-generator    → ~/project/.claude/skills/hologres-schema-generator

Install paths

Default skill install paths for each AI tool:

Built-in skill packages

Scenario 1: Optimize a slow query

Send a natural language request to Claude Code. The agent calls the query-optimizer skill, runs the execution plan, and returns optimization advice:

User: This SQL ran for 30 seconds. Help me optimize it:
        SELECT region, SUM(amount)
        FROM orders
        WHERE created_at > '2025-01-01'
        GROUP BY region;

Agent runs:
  $ hologres sql explain "SELECT region, SUM(amount) FROM orders \
      WHERE created_at > '2025-01-01' GROUP BY region"

CLI returns (excerpt):
  Seq Scan on orders  (cost=0..120000 rows=10000000)
    Filter: (created_at > '2025-01-01')
  Redistribution: HashRedistribution by region

Agent summary:
  Bottleneck 1: Seq Scan over the full table; no efficient filter on created_at
  Bottleneck 2: Heavy data redistribution by region
  Recommendations:
    1. Set created_at as the clustering key:
       ALTER TABLE orders SET clustering_key='created_at:asc'
    2. Set region as the distribution key to remove the GROUP BY redistribution:
       ALTER TABLE orders SET distribution_key='region'
    3. Enable result cache: hologres guc set hg_cache_enable on

Scenario 2: Investigate slow queries

User: Production looks slow. Please investigate.

Agent runs (slow-query-analysis skill):
  1. hologres sql run "SELECT query, duration, start_time FROM hg_query_log
       WHERE start_time > NOW() - INTERVAL '10 minutes'
       ORDER BY duration DESC LIMIT 10"
  2. Identify the slowest SQL.
  3. hologres sql explain "<slowest SQL>"
  4. Output the execution plan analysis and an optimization plan.

Scenario 3: Design a schema

User: Design a table for orders that grows by 100 million rows per day.

Agent runs (schema-generator skill):
  1. Asks about query patterns: high-frequency lookups by user_id and daily aggregates.
  2. Recommends columnar storage, daily logical partitioning, user_id as the distribution key, and created_at as the clustering key.
  3. hologres table create --name public.orders \
       --columns "order_id BIGINT NOT NULL, user_id INT, amount DECIMAL(10,2), created_at TIMESTAMPTZ, ds DATE NOT NULL" \
       --primary-key "order_id,ds" \
       --partition-by ds --partition-mode logical \
       --orientation column \
       --distribution-key user_id \
       --clustering-key "created_at:asc" \
       --partition-expiration-time "180 day" \
       --dry-run
  4. Outputs the DDL with reasoning. After you confirm, drop --dry-run to actually create the table.

Scenario 4: Real-time UV deduplication

User: We have 500 million users. Design a real-time UV count per channel.

Agent runs (uv-compute skill):
  1. Recommends a RoaringBitmap and dynamic table architecture.
  2. Creates a user dictionary encoding table and a per-channel bitmap table.
  3. Uses a dynamic table to incrementally refresh the bitmaps per channel.
  4. Queries with RB_CARDINALITY to return UV counts in subseconds.

The shell reports "command not found" when I run hologres. How do I fix it?

The CLI install directory is not in PATH. Reload the shell configuration:

source ~/.bashrc   # or source ~/.zshrc

If the command is still missing, add the default uv install directory to PATH manually:

export PATH="$HOME/.local/bin:$PATH"

The connection fails. How do I troubleshoot?

Inspect the current configuration and connection state first:

hologres config show    # Show details of the current profile
hologres status         # Test the connection and show the error message
hologres config         # Restart the wizard to update the configuration

Then verify the four most common culprits:

• The network type matches the runtime environment (internet for local hosts, vpc for hosts inside an Alibaba Cloud VPC).

• The instance ID and region are correct.

• The credentials (username and password, or the AccessKey pair) have access to the target instance.

• For public network access, the client IP address is on the instance allowlist.

The CLI rejects my write operation. How do I unblock it?

Handle the error code based on which guard fired:

# WRITE_GUARD_ERROR: write not authorized; add --write
hologres sql run --write "INSERT INTO logs VALUES (1, 'test')"

# DANGEROUS_WRITE_BLOCKED: DELETE or UPDATE without WHERE; add a filter
hologres sql run --write "DELETE FROM users WHERE id = 1"

A SELECT statement returns LIMIT_REQUIRED. What should I do?

A SELECT without a LIMIT clause returns at most 100 rows. Choose one of the following:

hologres sql run "SELECT * FROM table LIMIT 100"          # Add an explicit LIMIT
hologres sql run --no-limit-check "SELECT * FROM table"   # Disable the row count check

I forgot the database password. What now?

The CLI does not store the password in plaintext. Run the wizard again and enter the new value:

hologres config

How do I upgrade the CLI and Skills to the latest version?

pip install --upgrade hologres-cli       # Upgrade the CLI
uvx hologres-agent-skills                # Restart the Skills installer to overwrite