aliyun hologres-mcp-server CLI
Tool Commands
execute_hg_select_sql
Execute SELECT SQL to query data from Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool execute_hg_select_sql --query <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The (SELECT) SQL query to execute in Hologres database. |
execute_hg_select_sql_with_serverless
Use Serverless Computing resources to execute SELECT SQL to query data in Hologres database. When the error like 'Total memory used by all existing queries exceeded memory limitation' occurs during execute_hg_select_sql execution, you can re-execute the SQL with this tool.
uv run --with fastmcp python hologres_mcp_cli.py call-tool execute_hg_select_sql_with_serverless --query <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The (SELECT) SQL query to execute with serverless computing in Hologres database |
execute_hg_dml_sql
Execute (INSERT, UPDATE, DELETE, REFRESH DYNAMIC TABLE) SQL to insert, update, delete data, and refresh dynamic tables in Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool execute_hg_dml_sql --query <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The DML SQL query to execute in Hologres database |
execute_hg_ddl_sql
Execute (CREATE, ALTER, DROP) SQL statements to CREATE, ALTER, or DROP tables, views, procedures, GUCs etc. in Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool execute_hg_ddl_sql --query <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The DDL SQL query to execute in Hologres database |
gather_hg_table_statistics
Execute the ANALYZE TABLE command to have Hologres collect table statistics, enabling QO to generate better query plans.
uv run --with fastmcp python hologres_mcp_cli.py call-tool gather_hg_table_statistics --schema-name <value> --table <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name in Hologres database |
--table |
string | yes | Table name in Hologres database |
get_hg_query_plan
Get query plan for a SQL query in Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_query_plan --query <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The SQL query to analyze in Hologres database |
get_hg_execution_plan
Get actual execution plan with runtime statistics for a SQL query in Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_execution_plan --query <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The SQL query to analyze in Hologres database |
call_hg_procedure
Call a stored procedure in Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool call_hg_procedure --procedure-name <value> --procedure-args <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--procedure-name |
string | yes | The name of the stored procedure to call in Hologres database |
--procedure-args |
string | no | The arguments to pass to the stored procedure in Hologres database (JSON string) |
create_hg_maxcompute_foreign_table
Create a MaxCompute foreign table in Hologres database to accelerate queries on MaxCompute data.
uv run --with fastmcp python hologres_mcp_cli.py call-tool create_hg_maxcompute_foreign_table --maxcompute-project <value> --maxcompute-tables <value> --maxcompute-schema <value> --local-schema <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--maxcompute-project |
string | yes | The MaxCompute project name (required) |
--maxcompute-tables |
array[string] | yes | The MaxCompute table names (required) |
--maxcompute-schema |
string | no | The MaxCompute schema name (optional, default: 'default') |
--local-schema |
string | no | The local schema name in Hologres (optional, default: 'public') |
list_hg_schemas
List all schemas in the current Hologres database, excluding system schemas.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_schemas
list_hg_tables_in_a_schema
List all tables in a specific schema in the current Hologres database, including their types (table, view, foreign table, partitioned table).
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_tables_in_a_schema --schema-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name to list tables from in Hologres database |
show_hg_table_ddl
Show DDL script for a table, view, or foreign table in Hologres database.
uv run --with fastmcp python hologres_mcp_cli.py call-tool show_hg_table_ddl --schema-name <value> --table <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name in Hologres database |
--table |
string | yes | Table name in Hologres database |
query_and_plotly_chart
Execute a SELECT SQL query and generate a chart from the results. Returns both the query result data and a base64-encoded PNG image of the chart.
uv run --with fastmcp python hologres_mcp_cli.py call-tool query_and_plotly_chart --query <value> --chart-type <value> --x-column <value> --y-column <value> --title <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query |
string | yes | The SELECT SQL query to execute |
--chart-type |
string | no | Chart type: 'bar', 'line', 'scatter', 'pie', 'histogram', 'area' |
--x-column |
string | no | Column name for X axis (uses first column if not specified) |
--y-column |
string | no | Column name for Y axis (uses second column if not specified) |
--title |
string | no | Chart title |
analyze_hg_query_by_id
Analyze a specific query's performance profile by its query_id from hg_query_log. Returns detailed metrics including duration, memory usage, CPU time, read/write stats, and execution plan.
uv run --with fastmcp python hologres_mcp_cli.py call-tool analyze_hg_query_by_id --query-id <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--query-id |
string | yes | The query_id from hg_query_log to analyze |
get_hg_slow_queries
Get slow queries from hg_query_log ordered by duration. Useful for identifying performance bottlenecks.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_slow_queries --min-duration-ms <value> --limit <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--min-duration-ms |
integer | no | Minimum query duration in milliseconds to filter (default 1000) |
--limit |
integer | no | Maximum number of queries to return (default 20) |
list_hg_dynamic_tables
List all Dynamic Tables with their status, freshness settings, and last refresh info.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_dynamic_tables --schema-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | no | Schema name to filter (empty for all schemas) |
get_hg_dynamic_table_refresh_history
Get refresh history for a specific Dynamic Table, including duration, status, and latency.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_dynamic_table_refresh_history --schema-name <value> --table-name <value> --limit <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name of the dynamic table |
--table-name |
string | yes | Dynamic table name |
--limit |
integer | no | Maximum number of history records (default 10) |
list_hg_recyclebin
List all tables in the Hologres recycle bin (dropped tables that can be restored).
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_recyclebin
restore_hg_table_from_recyclebin
Restore a dropped table from the Hologres recycle bin. Only works if the table is still in the recycle bin.
uv run --with fastmcp python hologres_mcp_cli.py call-tool restore_hg_table_from_recyclebin --table-name <value> --schema-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--table-name |
string | yes | The original table name to restore from recycle bin |
--schema-name |
string | no | Schema name of the table (default 'public') |
list_hg_warehouses
List all computing groups (warehouses) in the Hologres instance, including their CPU, memory, cluster count, and status.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_warehouses
switch_hg_warehouse
Switch the current session's computing resource to a specified warehouse (computing group). Use 'local' for the default computing group.
uv run --with fastmcp python hologres_mcp_cli.py call-tool switch_hg_warehouse --warehouse-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--warehouse-name |
string | yes | The warehouse (computing group) name to switch to |
get_hg_table_storage_size
Get storage size details of a table, including total size, data, index, and metadata breakdown.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_table_storage_size --schema-name <value> --table <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name in Hologres database |
--table |
string | yes | Table name in Hologres database |
cancel_hg_query
Cancel or terminate a running query by its process ID. Use list_hg_active_queries to find the pid first.
uv run --with fastmcp python hologres_mcp_cli.py call-tool cancel_hg_query --pid <value> --terminate
| Flag | Type | Required | Description |
|---|---|---|---|
--pid |
integer | yes | The process ID (pid) of the query to cancel |
--terminate |
boolean | no | If True, forcefully terminate the backend process (default False, just cancel the query) |
list_hg_active_queries
List currently active queries and connections from pg_stat_activity. Useful for monitoring running queries and finding PIDs to cancel.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_active_queries --state <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--state |
string | no | Filter by state: 'active', 'idle', 'all' (default 'active') |
list_hg_query_queues
List all Query Queues and their classifiers, showing concurrency limits, queue sizes, and routing rules. Requires Hologres V3.0+.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_query_queues
get_hg_table_properties
Get table properties including distribution_key, clustering_key, segment_key, bitmap_columns, dictionary_columns, binlog settings, etc.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_table_properties --schema-name <value> --table <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name in Hologres database |
--table |
string | yes | Table name in Hologres database |
get_hg_table_shard_info
Get table's Table Group and shard count info. Useful for diagnosing data skew and shard configuration.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_table_shard_info --schema-name <value> --table <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name in Hologres database |
--table |
string | yes | Table name in Hologres database |
list_hg_external_databases
List all External Databases (federated databases for Lakehouse acceleration). Requires Hologres V3.0+.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_external_databases
get_hg_lock_diagnostics
Diagnose lock contention by showing blocking and waiting queries. Useful for identifying lock waits that cause query hangs.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_lock_diagnostics
get_hg_table_info_trend
Get table storage trend from hg_table_info, showing daily storage size, file count, and row count changes. Data is T+1, retained for 30 days.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_table_info_trend --schema-name <value> --table <value> --days <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--schema-name |
string | yes | Schema name in Hologres database |
--table |
string | yes | Table name in Hologres database |
--days |
integer | no | Number of days to look back (default 7) |
manage_hg_query_queue
Create, drop, or clear a Query Queue. Requires Hologres V3.0+ and superuser privileges.
uv run --with fastmcp python hologres_mcp_cli.py call-tool manage_hg_query_queue --action <value> --queue-name <value> --max-concurrency <value> --max-queue-size <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--action |
string | yes | Action: 'create', 'drop', or 'clear' |
--queue-name |
string | yes | Name of the query queue |
--max-concurrency |
integer | no | Max concurrency for the queue (required for 'create') |
--max-queue-size |
integer | no | Max queue size (required for 'create') |
manage_hg_classifier
Create or drop a classifier for a Query Queue. Use set_hg_query_queue_property to configure classifier rules after creation. Requires Hologres V3.0+.
uv run --with fastmcp python hologres_mcp_cli.py call-tool manage_hg_classifier --action <value> --queue-name <value> --classifier-name <value> --priority <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--action |
string | yes | Action: 'create' or 'drop' |
--queue-name |
string | yes | Name of the query queue the classifier belongs to |
--classifier-name |
string | yes | Name of the classifier |
--priority |
integer | no | Priority for the classifier (required for 'create', higher = matched first) |
set_hg_query_queue_property
Set or remove properties on a Query Queue or classifier. For classifier rules, use property_key as condition_name and property_value as condition_value. Requires Hologres V3.0+.
uv run --with fastmcp python hologres_mcp_cli.py call-tool set_hg_query_queue_property --target <value> --queue-name <value> --property-key <value> --property-value <value> --classifier-name <value> --action <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--target |
string | yes | Target type: 'queue' or 'classifier' |
--queue-name |
string | yes | Name of the query queue |
--property-key |
string | yes | Property key to set (e.g. 'max_concurrency', 'query_timeout_ms' for queue; 'condition_name' for classifier rule) |
--property-value |
string | yes | Property value to set |
--classifier-name |
string | no | Classifier name (required when target='classifier') |
--action |
string | no | Action: 'set' to add/update, 'remove' to delete the property (default 'set') |
manage_hg_warehouse
Manage a computing group (warehouse): suspend, resume, restart, rename, or resize. Requires superuser privileges.
uv run --with fastmcp python hologres_mcp_cli.py call-tool manage_hg_warehouse --action <value> --warehouse-name <value> --cu <value> --new-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--action |
string | yes | Action: 'suspend', 'resume', 'restart', 'rename', or 'resize' |
--warehouse-name |
string | yes | Name of the warehouse (computing group) |
--cu |
integer | no | CU count for resize action |
--new-name |
string | no | New name for rename action |
get_hg_warehouse_status
Get detailed running status and scaling progress of a computing group (warehouse).
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_warehouse_status --warehouse-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--warehouse-name |
string | yes | Name of the warehouse (computing group) |
rebalance_hg_warehouse
Trigger shard rebalancing for a computing group to eliminate data skew across nodes.
uv run --with fastmcp python hologres_mcp_cli.py call-tool rebalance_hg_warehouse --warehouse-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--warehouse-name |
string | yes | Name of the warehouse (computing group) to rebalance |
list_hg_data_masking_rules
List all data masking rules configured via hg_anon extension, including column-level and user-level masking labels.
uv run --with fastmcp python hologres_mcp_cli.py call-tool list_hg_data_masking_rules
query_hg_external_files
Query files directly from OSS using EXTERNAL_FILES function without creating foreign tables. Requires Hologres V4.1+. Supports CSV, Parquet, ORC formats.
uv run --with fastmcp python hologres_mcp_cli.py call-tool query_hg_external_files --path <value> --format <value> --columns <value> --oss-endpoint <value> --role-arn <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--path |
string | yes | OSS path, e.g. 'oss://bucket/path/to/files' |
--format |
string | yes | File format: 'csv', 'parquet', or 'orc' |
--columns |
string | no | Optional column definitions for AS clause, e.g. 'id int, name text'. Leave empty for auto schema inference. |
--oss-endpoint |
string | no | OSS endpoint (internal), e.g. 'oss-cn-hangzhou-internal.aliyuncs.com'. Leave empty if already configured. |
--role-arn |
string | no | RAM role ARN for accessing OSS. Leave empty if already configured. |
get_hg_guc_config
Get the current value of a GUC (Grand Unified Configuration) parameter.
uv run --with fastmcp python hologres_mcp_cli.py call-tool get_hg_guc_config --guc-name <value>
| Flag | Type | Required | Description |
|---|---|---|---|
--guc-name |
string | yes | The GUC parameter name to query, e.g. 'hg_computing_resource', 'statement_timeout', 'hg_experimental_enable_fixed_dispatcher' |
Utility Commands
uv run --with fastmcp python hologres_mcp_cli.py list-tools
uv run --with fastmcp python hologres_mcp_cli.py list-resources
uv run --with fastmcp python hologres_mcp_cli.py read-resource <uri>
uv run --with fastmcp python hologres_mcp_cli.py list-prompts
uv run --with fastmcp python hologres_mcp_cli.py get-prompt <name> [key=value ...]