altinity-expert-clickhouse-schema

Table schema and design analysis

Answers "is this table designed the way ClickHouse wants it" from system.parts, system.tables, system.columns, system.parts_columns, system.data_skipping_indices and system.merge_tree_settings. Run altinity-expert-clickhouse-connection first if the connection mode, cluster and time window are not yet established.

Query packs

• checks.sql — 10 checks: partition health audit, oversized partitions on collapsing engines, primary key analysis, column count, Nullable column audit, over-long table and column names, materialized view design issues, materialized view dependency chains, a table overview and the table-level MergeTree settings that shape all of the above.
• reference.md — background (settings, sizing, anti-patterns); read only when you need to explain a recommendation.

How to run the query packs

1. Read each pack file from this skill's directory (the skill loader prints the directory path).
2. Run statements one at a time, never a whole file. Statements end with ; and start with a -- @check <id> <title> header; keep the id with its result.
3. Honor -- @requires: skip the statement when the named table is missing, when keeper is required and the server has no Keeper/ZooKeeper, or when the version condition is not met. List skipped ids with the reason.
4. Keep {cluster} as written when a cluster macro exists; otherwise apply the connection skill's rewrite rule. Any other {placeholder} is a template variable: substitute a real value first or skip the statement.
5. On an error, record the check id and the first line of the error, then continue. Only for UNKNOWN_IDENTIFIER, run DESCRIBE TABLE system.<table> and drop the missing column.
6. A severity column is the verdict for that row. Copy it; do not re-grade.

Deep-dive statements

Partition distribution for one table, to judge whether the partition key is too granular.

SELECT
    partition,
    count() AS parts,
    sum(rows) AS total_rows,
    formatReadableSize(sum(bytes_on_disk)) AS partition_size
FROM clusterAllReplicas('{cluster}', system.parts)
WHERE active AND database = '{database}' AND table = '{table}'
GROUP BY partition
ORDER BY partition DESC
LIMIT 100;