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.
LABSCO SUMMARY
It carries the diagnosis tools, not only the query tools.
Most database servers stop at running SQL. This one continues into the part where a query is slow: slow queries ordered by duration out of hg_query_log, one of them opened by query_id with memory, CPU time and read/write statistics attached, the actual execution plan rather than the estimated one, lock contention showing who is blocking whom, and a cancel by PID when the right answer is to stop it outright. Administration goes further still, down to resizing a computing group and rebalancing its shards. Two things bound what you can actually use: several tools name a Hologres version floor in their own descriptions, and the warehouse and queue tools need superuser.
What it is
A Hologres server covering query execution, schema inspection, performance diagnosis and instance administration down to computing groups and query queues.
What you get
- SQL split by kind: SELECT, a serverless SELECT for re-running a query that exceeded the memory limit, DML including dynamic-table refresh, and DDL
- Schema reading: schemas, tables in a schema with their types, a table's DDL script, its properties (distribution key, clustering key, segment key, bitmap and dictionary columns, binlog settings), its Table Group and shard count, and its storage size split into data, index and metadata
- Planning: the query plan, the actual execution plan with runtime statistics, and ANALYZE TABLE so the optimiser has current statistics to work from
- Diagnosis: slow queries from hg_query_log ordered by duration, one query analysed by query_id for duration, memory, CPU time and read/write statistics, active queries and connections from pg_stat_activity, a query cancelled or terminated by PID, and lock contention showing blocking and waiting queries together
- Dynamic tables listed with their status, freshness settings and last refresh, and their refresh history with duration, status and latency
- Warehouses listed with CPU, memory, cluster count and status; the session switched to one; suspended, resumed, restarted, renamed or resized; scaling progress read; and shard rebalancing triggered
- Query queues and their classifiers created, dropped, cleared and configured, listed alongside their concurrency limits, queue sizes and routing rules
- Recovery and external data: the recycle bin listed and a dropped table restored, MaxCompute foreign tables created for query acceleration, external databases listed, and OSS files queried directly through EXTERNAL_FILES in CSV, Parquet or ORC
- query_and_plotly_chart, returning both the result rows and a base64-encoded PNG of the chart
Requirements
A Hologres instance and a database user, supplied as HOLOGRES_HOST, HOLOGRES_PORT, HOLOGRES_USER, HOLOGRES_PASSWORD and HOLOGRES_DATABASE. Several tools state their own version floor — query queues, classifiers and external databases need Hologres V3.0 or later and query_hg_external_files needs V4.1 or later — and the warehouse and queue management tools need superuser privileges.
Setup effort
One command plus credentials — pip install hologres-mcp-server, then supply credentials
USE CASES
01
Chasing a query that got slower this month
Pull the slowest queries out of hg_query_log, profile the one that matters by its query_id, and compare the planner's intent against what actually ran before deciding whether the fix is statistics or the query itself.
02
Clearing a session that has stopped responding
Read the active queries and connections, check whether something is blocking rather than merely slow, and end the offending process by its pid.
03
Working out why one shard is doing all the work
Shard count and Table Group explain how rows were spread; the table's distribution and clustering keys explain why. Rebalancing is the fix at the compute end once the layout question is settled.
04
Getting a chart out of a question without leaving the chat
Run the SELECT, and when the answer is a shape rather than a number, have the same query return a chart image alongside its rows. A query too large for the default resources can be re-run on serverless resources.
05
Recovering a table someone dropped this morning
Check the recycle bin, restore the table while it is still there, and read its DDL back to confirm the definition matches what was lost.
06
Querying data that never landed in Hologres
MaxCompute tables can be mounted as foreign tables to speed queries over them, OSS files can be read in place as CSV, Parquet or ORC, and federated databases show what else is already attached.
39 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
call_hg_procedure
Call a stored procedure 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.
create_hg_maxcompute_foreign_table
Create a MaxCompute foreign table in Hologres database to accelerate queries on MaxCompute data.
execute_hg_ddl_sql
Execute (CREATE, ALTER, DROP) SQL statements to CREATE, ALTER, or DROP tables, views, procedures, GUCs etc. 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.
execute_hg_select_sql
Execute SELECT SQL to query data from 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.
gather_hg_table_statistics
Execute the ANALYZE TABLE command to have Hologres collect table statistics, enabling QO to generate better query plans.
get_hg_dynamic_table_refresh_history
Get refresh history for a specific Dynamic Table, including duration, status, and latency.
get_hg_execution_plan
Get actual execution plan with runtime statistics for a SQL query in Hologres database.
get_hg_guc_config
Get the current value of a GUC (Grand Unified Configuration) parameter.
get_hg_lock_diagnostics
Diagnose lock contention by showing blocking and waiting queries. Useful for identifying lock waits that cause query hangs.
get_hg_query_plan
Get query plan for a SQL query in Hologres database.
get_hg_slow_queries
Get slow queries from hg_query_log ordered by duration. Useful for identifying performance bottlenecks.
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.
get_hg_table_properties
Get table properties including distribution_key, clustering_key, segment_key, bitmap_columns, dictionary_columns, binlog settings, etc.
get_hg_table_shard_info
Get table's Table Group and shard count info. Useful for diagnosing data skew and shard configuration.
get_hg_table_storage_size
Get storage size details of a table, including total size, data, index, and metadata breakdown.
get_hg_warehouse_status
Get detailed running status and scaling progress of a computing group (warehouse).
list_hg_active_queries
List currently active queries and connections from pg_stat_activity. Useful for monitoring running queries and finding PIDs to cancel.
list_hg_data_masking_rules
List all data masking rules configured via hg_anon extension, including column-level and user-level masking labels.
list_hg_dynamic_tables
List all Dynamic Tables with their status, freshness settings, and last refresh info.
list_hg_external_databases
List all External Databases (federated databases for Lakehouse acceleration). Requires Hologres V3.0+.
list_hg_query_queues
List all Query Queues and their classifiers, showing concurrency limits, queue sizes, and routing rules. Requires Hologres V3.0+.
list_hg_recyclebin
List all tables in the Hologres recycle bin (dropped tables that can be restored).
list_hg_schemas
List all schemas in the current Hologres database, excluding system 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).
list_hg_warehouses
List all computing groups (warehouses) in the Hologres instance, including their CPU, memory, cluster count, and status.
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+.
manage_hg_query_queue
Create, drop, or clear a Query Queue. Requires Hologres V3.0+ and superuser privileges.
manage_hg_warehouse
Manage a computing group (warehouse): suspend, resume, restart, rename, or resize. Requires superuser privileges.
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.
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.
rebalance_hg_warehouse
Trigger shard rebalancing for a computing group to eliminate data skew across nodes.
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.
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+.
show_hg_table_ddl
Show DDL script for a table, view, or foreign table in Hologres database.
switch_hg_warehouse
Switch the current session's computing resource to a specified warehouse (computing group). Use 'local' for the default computing group.
BEFORE YOU INSTALL
What to know first
Tools you get
39 tools when we connected. Up to seven tools fail on older or non-privileged instances: queue, classifier and external-database tools need V3.0+, query_hg_external_files needs V4.1+, and manage_hg_query_queue and manage_hg_warehouse need superuser.
Requires
- uvx on PATH
- HOLOGRES_USER in your environment
- HOLOGRES_PASSWORD in your environment
CONTEXT COST
Moderate Standing cost
Rated by the size of the 39 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install hologres-mcp-serverMCP Clients
Any MCP client — local build
Download from GitHub
ANY MCP CLIENT — LOCAL BUILD · TERMINAL
git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.gitAdd this to your MCP client. <YOUR_PATH_TO_ALIBABACLOUD_HOLOGRES_MCP_SERVER> is the full path of the alibabacloud-hologres-mcp-server folder you cloned.
ANY MCP CLIENT — LOCAL BUILD · JSON
{
"mcpServers": {
"hologres-mcp-server": {
"command": "uv",
"args": [
"--directory",
"<YOUR_PATH_TO_ALIBABACLOUD_HOLOGRES_MCP_SERVER>",
"run",
"hologres-mcp-server"
],
"env": {
"HOLOGRES_HOST": "<YOUR_HOLOGRES_HOST>",
"HOLOGRES_PORT": "<YOUR_HOLOGRES_PORT>",
"HOLOGRES_USER": "<YOUR_HOLOGRES_USER>",
"HOLOGRES_PASSWORD": "<YOUR_HOLOGRES_PASSWORD>",
"HOLOGRES_DATABASE": "<YOUR_HOLOGRES_DATABASE>"
}
}
}
}Any MCP client — uv
ANY MCP CLIENT — UV · JSON
{
"mcpServers": {
"hologres-mcp-server": {
"command": "uv",
"args": [
"run",
"--with",
"hologres-mcp-server",
"hologres-mcp-server"
],
"env": {
"HOLOGRES_HOST": "<YOUR_HOLOGRES_HOST>",
"HOLOGRES_PORT": "<YOUR_HOLOGRES_PORT>",
"HOLOGRES_USER": "<YOUR_HOLOGRES_USER>",
"HOLOGRES_PASSWORD": "<YOUR_HOLOGRES_PASSWORD>",
"HOLOGRES_DATABASE": "<YOUR_HOLOGRES_DATABASE>"
}
}
}
}Any MCP client — uvx
ANY MCP CLIENT — UVX · JSON
{
"mcpServers": {
"hologres-mcp-server": {
"command": "uvx",
"args": [
"hologres-mcp-server"
],
"env": {
"HOLOGRES_HOST": "<YOUR_HOLOGRES_HOST>",
"HOLOGRES_PORT": "<YOUR_HOLOGRES_PORT>",
"HOLOGRES_USER": "<YOUR_HOLOGRES_USER>",
"HOLOGRES_PASSWORD": "<YOUR_HOLOGRES_PASSWORD>",
"HOLOGRES_DATABASE": "<YOUR_HOLOGRES_DATABASE>"
}
}
}
}Any MCP client — HTTP
Set the Hologres connection variables and start the server
ANY MCP CLIENT — HTTP · TERMINAL
export HOLOGRES_HOST="<YOUR_HOLOGRES_INSTANCE>.hologres.aliyuncs.com"
export HOLOGRES_PORT="80"
export HOLOGRES_USER="<YOUR_HOLOGRES_USER>"
export HOLOGRES_PASSWORD="<YOUR_HOLOGRES_PASSWORD>"
export HOLOGRES_DATABASE="<YOUR_HOLOGRES_DATABASE>"
uvx hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000Point your client at the endpoint: <host> and <port> are the --host and --port you started it with (127.0.0.1 and 8000 on the same machine)
ANY MCP CLIENT — HTTP · JSON
{
"mcpServers": {
"hologres-mcp-server": {
"url": "http://<YOUR_HOST>:<YOUR_PORT>/mcp"
}
}
}Claude Code
CLAUDE CODE · TERMINAL
claude mcp add hologres-mcp-server \
-e HOLOGRES_HOST=<YOUR_HOLOGRES_HOST> \
-e HOLOGRES_PORT=<YOUR_HOLOGRES_PORT> \
-e HOLOGRES_USER=<YOUR_HOLOGRES_USER> \
-e HOLOGRES_PASSWORD=<YOUR_HOLOGRES_PASSWORD> \
-e HOLOGRES_DATABASE=<YOUR_HOLOGRES_DATABASE> \
-- uvx hologres-mcp-server
