altinity-expert-clickhouse-connection

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Connection mode

连接模式

Decide connection mode first and verify connectivity then:

sql

select
    hostName() as hostname,
    version() as version,
    getMacro('cluster') as cluster_name,
    formatReadableTimeDelta(uptime()) as uptime_human,
    getSetting('max_memory_usage') as max_memory_usage,
    (select value from system.asynchronous_metrics where metric = 'OSMemoryTotal') as os_memory_total

请先确定连接模式，然后验证连通性：

sql

select
    hostName() as hostname,
    version() as version,
    getMacro('cluster') as cluster_name,
    formatReadableTimeDelta(uptime()) as uptime_human,
    getSetting('max_memory_usage') as max_memory_usage,
    (select value from system.asynchronous_metrics where metric = 'OSMemoryTotal') as os_memory_total

MCP mode

MCP模式

Try to use MCP server with clickhouse in the name. If multiple ClickHouse MCP servers are available, ask the user which one to use. When executing queries by the MCP server, push a single SQL statement to the MCP server (no multy query!)

优先使用名称中包含clickhouse的MCP服务器。如果有多个ClickHouse MCP服务器可用，请询问用户使用哪一个。通过MCP服务器执行查询时，仅向其推送单条SQL语句（禁止多查询！）

Exec mode (clickhouse-client)

执行模式（clickhouse-client）

if MCP is unavailable, try to run
```
clickhouse-client
```
. Don't rely on env vars. On failure, ask how to run it properly.
Prefer running queries from a
```
.sql
```
file with
```
--queries-file
```
and forcing JSON output (
```
-f JSON
```
) when capturing results to files.

如果MCP不可用，尝试运行
```
clickhouse-client
```
。不要依赖环境变量。如果运行失败，请询问正确的运行方式。
当需要将结果保存到文件时，优先使用
```
--queries-file
```
参数从
```
.sql
```
文件运行查询，并强制使用JSON格式输出（
```
-f JSON
```
）。

Cluster selection for

clusterAllReplicas('{cluster}', ...)

针对

clusterAllReplicas('{cluster}', ...)

的集群选择

Verify from the query results above if a cluster_name (cluster macro var) is not empty. If defined - leave macro as-is.
if not, ask the user to choose from:
```
SELECT DISTINCT cluster FROM system.clusters where not is_local
```
and replace
```
'{cluster}'
```
placeholders in the queries in all
```
.sql
```
files.
if the query above returns nothing, consider single-server mode and automatically rewrite
```
clusterAllReplicas('{cluster}', system.<table>)
```
→
```
system.<table>
```
before execution.

从上述查询结果中验证cluster_name（集群宏变量）是否非空。如果已定义，则保持宏不变。
如果未定义，请让用户从
```
SELECT DISTINCT cluster FROM system.clusters where not is_local
```
的结果中选择，并替换所有
```
.sql
```
文件查询中的
```
'{cluster}'
```
占位符。
如果上述查询无结果，则视为单服务器模式，在执行前自动将
```
clusterAllReplicas('{cluster}', system.<table>)
```
重写为
```
system.<table>
```
。

Timeframe default for logs/errors

日志/错误的默认时间范围

If the user explicitly provides a timeframe in the initial prompt, use it exactly.
Otherwise always default to last 24 hours:

sql

-- Use this pattern for system.*_log tables and system.errors time filters:
-- WHERE event_time >= now() - INTERVAL 24 HOUR

never expend time window without an explicit user prompt. If needed, ask user to extend time window

如果用户在初始提示中明确提供了时间范围，请严格使用该范围。
否则默认使用最近24小时：

sql

-- 对system.*_log表和system.errors使用以下时间过滤模式：
-- WHERE event_time >= now() - INTERVAL 24 HOUR

未经用户明确提示，不得扩大时间范围。如果需要，请询问用户是否扩展时间范围。

Schema-safe rule

Schema安全规则

If a query fails with
```
UNKNOWN_IDENTIFIER
```
, run
```
DESCRIBE TABLE system.<table>
```
and drop/adjust only the missing columns.
If a query fails with
```
UNKNOWN_TABLE
```
, skip that query and note the table is disabled or unavailable (e.g.,
```
system.part_log
```
,
```
system.detached_parts
```
).

如果查询因
```
UNKNOWN_IDENTIFIER
```
失败，请运行
```
DESCRIBE TABLE system.<table>
```
，仅删除或调整缺失的列。
如果查询因
```
UNKNOWN_TABLE
```
失败，请跳过该查询，并记录该表已禁用或不可用（例如：
```
system.part_log
```
、
```
system.detached_parts
```
）。

Report Output

报告输出

In all reports, always provide a header with information:

Connection mode used: MCP or clickhouse-client
cluster name (or “no cluster / single node”)
clickhouse version
time window used for analysis

在所有报告中，必须包含以下信息作为表头：

使用的连接模式：MCP或clickhouse-client
集群名称（或“无集群/单节点”）
ClickHouse版本
分析使用的时间范围

altinity-expert-clickhouse-connection

Original

Translation

Connection mode

连接模式

MCP mode

MCP模式

Exec mode (clickhouse-client)

执行模式（clickhouse-client）

Cluster selection for
`clusterAllReplicas('{cluster}', ...)`

针对
`clusterAllReplicas('{cluster}', ...)`
的集群选择

Timeframe default for logs/errors

日志/错误的默认时间范围

Schema-safe rule

Schema安全规则

Report Output

报告输出

altinity-expert-clickhouse-connection

Original

Translation

Connection mode

连接模式

MCP mode

MCP模式

Exec mode (clickhouse-client)

执行模式（clickhouse-client）

Cluster selection for clusterAllReplicas('{cluster}', ...)

针对clusterAllReplicas('{cluster}', ...)的集群选择

Timeframe default for logs/errors

日志/错误的默认时间范围

Schema-safe rule

Schema安全规则

Report Output

报告输出

Cluster selection for
`clusterAllReplicas('{cluster}', ...)`

针对
`clusterAllReplicas('{cluster}', ...)`
的集群选择