chqce 0.1.0__py3-none-any.whl

chqce/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

chqce/cli.py

@@ -0,0 +1,163 @@
+import sys
+
+import click
+from rich.console import Console
+
+from . import __version__
+from .connection import create_client, test_connection
+from .estimator import QueryEstimator
+from .formatter import console, print_header, print_result
+from .suggestions import get_index_suggestions
+
+_err = Console(stderr=True)
+
+
+def _collect_interactive() -> str:
+    """Collect a multi-line SQL query from stdin.
+
+    Submit by ending a line with ';' or typing GO on its own line.
+    """
+    console.print(
+        "\n[dim]Paste or type your SQL query."
+        "  End with [bold];[/bold] or type [bold]GO[/bold] on its own line."
+        "  [bold]Ctrl+C[/bold] to exit.[/dim]\n"
+    )
+    lines: list[str] = []
+    try:
+        while True:
+            prefix = "[bold cyan]SQL>[/bold cyan] " if not lines else "     [dim]>[/dim] "
+            console.print(prefix, end="")
+            try:
+                line = input()
+            except EOFError:
+                break
+            stripped = line.strip()
+            if stripped.upper() == "GO" or stripped == ";":
+                if lines:
+                    break
+                continue
+            lines.append(line)
+            if stripped.endswith(";"):
+                break
+    except KeyboardInterrupt:
+        console.print("\n[dim]Bye![/dim]")
+        sys.exit(0)
+
+    return "\n".join(lines).strip()
+
+
+def _resolve_query(query: str | None, file: str | None) -> str | None:
+    """Determine the query source, in priority order.
+
+    1. --file FILE          read the query from a file (best for huge queries)
+    2. QUERY argument       passed directly on the command line
+    3. piped stdin          e.g.  `chqce < query.sql`  or  `cat q.sql | chqce`
+    4. None                 -> caller falls back to interactive mode
+    """
+    if file:
+        with open(file, "r", encoding="utf-8") as fh:
+            return fh.read().strip()
+    if query:
+        return query
+    # Query piped in on stdin (non-interactive).
+    if not sys.stdin.isatty():
+        data = sys.stdin.read().strip()
+        if data:
+            return data
+    return None
+
+
+def _run(query: str, estimator: QueryEstimator, client, database: str, execute: bool) -> None:
+    with console.status("[bold green]Analyzing…[/bold green]", spinner="dots"):
+        result = estimator.estimate(query, execute=execute)
+        suggestions = get_index_suggestions(query, client, current_database=database)
+    print_result(result, suggestions)
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("query", required=False)
+@click.option("--file", "-f", "file", type=click.Path(exists=True, dir_okay=False),
+              default=None, help="Read the query from a file (best for huge queries)")
+@click.option("--host", "-H", default="localhost", envvar="CLICKHOUSE_HOST",
+              show_default=True, help="ClickHouse host")
+@click.option("--port", "-p", default=8123, envvar="CLICKHOUSE_PORT", type=int,
+              show_default=True, help="HTTP(S) port")
+@click.option("--user", "-u", default="default", envvar="CLICKHOUSE_USER",
+              show_default=True, help="Username")
+@click.option("--password", "-P", default="", envvar="CLICKHOUSE_PASSWORD",
+              help="Password (or set CLICKHOUSE_PASSWORD)")
+@click.option("--database", "-d", default="default", envvar="CLICKHOUSE_DATABASE",
+              show_default=True, help="Default database")
+@click.option("--max-query-size", default=0, type=int, metavar="BYTES",
+              help="Raise ClickHouse max_query_size for very large queries "
+                   "(server default is 262144)")
+@click.option("--timeout", "-t", default=0, type=int, metavar="SECONDS",
+              help="Server-side max_execution_time; query is aborted after this "
+                   "many seconds (0 = unlimited)")
+@click.option("--max-ast-elements", default=0, type=int, metavar="N",
+              help="Raise ClickHouse max_ast_elements for queries that fail with "
+                   "'AST is too big' (server default is 50000)")
+@click.option("--no-execute", is_flag=True, default=False,
+              help="Estimate only — do not actually run the query")
+@click.version_option(__version__, "-V", "--version")
+def cli(query, file, host, port, user, password, database, max_query_size,
+        timeout, max_ast_elements, no_execute):
+    """ClickHouse Query Cost Estimator.
+
+    Estimates rows scanned, memory usage, and execution time for a ClickHouse
+    SQL query, and suggests indexes based on WHERE-clause columns.
+
+    \b
+    The query can come from (in priority order):
+      • --file query.sql      best for huge / multi-line queries
+      • a QUERY argument       chqce "SELECT ..."
+      • piped stdin            chqce < query.sql
+      • interactive prompt     run with no query at all
+
+    \b
+    Environment variables (override defaults):
+      CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER,
+      CLICKHOUSE_PASSWORD, CLICKHOUSE_DATABASE
+
+    \b
+    Examples:
+      chqce "SELECT count() FROM hits WHERE EventDate = today()"
+      chqce -f report.sql --no-execute
+      chqce -t 600 "SELECT ... a slow query ..."
+      cat report.sql | chqce --max-query-size 1048576 --max-ast-elements 500000
+    """
+    try:
+        resolved = _resolve_query(query, file)
+    except OSError as e:
+        _err.print(f"[red]Could not read query file:[/red] {e}")
+        sys.exit(1)
+
+    try:
+        client = create_client(host=host, port=port, user=user,
+                               password=password, database=database,
+                               max_query_size=max_query_size,
+                               max_execution_time=timeout,
+                               max_ast_elements=max_ast_elements)
+        ok, version_or_err = test_connection(client)
+    except Exception as e:
+        _err.print(f"[red]Connection error:[/red] {e}")
+        sys.exit(1)
+
+    if not ok:
+        _err.print(f"[red]Connection failed:[/red] {version_or_err}")
+        sys.exit(1)
+
+    print_header(version_or_err, host, port, database)
+
+    estimator = QueryEstimator(client)
+    execute = not no_execute
+
+    if resolved:
+        _run(resolved, estimator, client, database, execute)
+    else:
+        while True:
+            q = _collect_interactive()
+            if not q:
+                continue
+            _run(q, estimator, client, database, execute)
+            console.print("[dim]" + "─" * 60 + "[/dim]")

chqce/connection.py

@@ -0,0 +1,55 @@
+import clickhouse_connect
+from clickhouse_connect.driver import Client
+
+
+DEFAULT_SOCKET_TIMEOUT = 300
+
+
+def create_client(
+    host: str = "localhost",
+    port: int = 8123,
+    user: str = "default",
+    password: str = "",
+    database: str = "default",
+    max_query_size: int = 0,
+    max_execution_time: int = 0,
+    max_ast_elements: int = 0,
+) -> Client:
+    # Per-session ClickHouse settings, only sent when the caller overrides them.
+    settings = {}
+    if max_query_size > 0:
+        # ClickHouse rejects queries larger than max_query_size (256 KiB default).
+        settings["max_query_size"] = max_query_size
+    if max_execution_time > 0:
+        # Server aborts the query after this many seconds (0 = unlimited).
+        settings["max_execution_time"] = max_execution_time
+    if max_ast_elements > 0:
+        # Raises the limit on parsed-query size (huge IN-lists, deep nesting).
+        settings["max_ast_elements"] = max_ast_elements
+        settings["max_expanded_ast_elements"] = max_ast_elements
+
+    # Keep the client socket alive a bit longer than the server-side limit so
+    # ClickHouse returns a clean timeout error instead of the socket dropping.
+    socket_timeout = DEFAULT_SOCKET_TIMEOUT
+    if max_execution_time > 0:
+        socket_timeout = max_execution_time + 30
+
+    return clickhouse_connect.get_client(
+        host=host,
+        port=port,
+        username=user,
+        password=password,
+        database=database,
+        connect_timeout=10,
+        send_receive_timeout=socket_timeout,
+        settings=settings,
+    )
+
+
+def test_connection(client: Client) -> tuple[bool, str]:
+    try:
+        result = client.query("SELECT version()")
+        version = result.result_rows[0][0]
+        return True, version
+    except Exception as e:
+        return False, str(e)

chqce/errors.py

@@ -0,0 +1,87 @@
+"""Classify ClickHouse / client errors into actionable hints.
+
+ClickHouse surfaces resource limits as server errors (timeout, AST too big,
+memory, query size). We map the raw message to a short category and a hint
+that tells the user which flag or setting can get them unstuck.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ClassifiedError:
+    category: str            # machine-readable bucket
+    title: str               # short human label
+    hint: Optional[str]      # actionable suggestion, or None
+
+
+# Each rule: (category, title, list-of-substrings-to-match, hint)
+# Substring match is case-insensitive. Order matters — first match wins.
+_RULES = [
+    (
+        "timeout",
+        "Query timed out",
+        ["timeout_exceeded", "timeout exceeded", "max_execution_time",
+         "timed out", "read timed out", "readtimeout"],
+        "The query exceeded its time budget. Try:\n"
+        "  • raise the limit:  --timeout 600  (seconds, 0 = unlimited)\n"
+        "  • estimate without running:  --no-execute\n"
+        "  • narrow the query with a WHERE filter or LIMIT",
+    ),
+    (
+        "ast_too_big",
+        "Query AST is too big",
+        ["too_big_ast", "ast is too big", "max_ast_elements",
+         "max_expanded_ast_elements"],
+        "The parsed query has too many elements (often huge IN-lists or "
+        "deeply nested expressions). Try:\n"
+        "  • raise the limit:  --max-ast-elements 500000\n"
+        "  • replace a long  IN (1, 2, 3, …)  with a subquery or a "
+        "temporary table / JOIN",
+    ),
+    (
+        "parser_depth",
+        "Query nesting is too deep",
+        ["too_deep_recursion", "maximum parse depth", "max_parser_depth"],
+        "The query nests deeper than the parser allows. Try:\n"
+        "  • flatten deeply nested subqueries or boolean expressions\n"
+        "  • raise the server setting  max_parser_depth",
+    ),
+    (
+        "query_size",
+        "Query text is too large",
+        ["max query size exceeded", "max_query_size"],
+        "The raw query exceeds ClickHouse's max_query_size (256 KiB default). "
+        "Try:\n"
+        "  • raise the limit:  --max-query-size 1048576  (bytes)",
+    ),
+    (
+        "memory",
+        "Query ran out of memory",
+        ["memory_limit_exceeded", "memory limit", "max_memory_usage"],
+        "The query exceeded the memory budget. Try:\n"
+        "  • add a WHERE filter or LIMIT to scan less data\n"
+        "  • pre-aggregate, or raise the server setting  max_memory_usage",
+    ),
+    (
+        "read_limit",
+        "Query scans too much data",
+        ["too_many_rows", "max_rows_to_read", "too_many_bytes",
+         "max_bytes_to_read"],
+        "The query would read more rows/bytes than allowed. Try:\n"
+        "  • add a WHERE filter on the table's ORDER BY columns\n"
+        "  • check the Index Suggestions below",
+    ),
+]
+
+
+def classify_error(message: Optional[str]) -> Optional[ClassifiedError]:
+    """Return a ClassifiedError for a known failure, or None if unrecognized."""
+    if not message:
+        return None
+    low = message.lower()
+    for category, title, needles, hint in _RULES:
+        if any(n in low for n in needles):
+            return ClassifiedError(category=category, title=title, hint=hint)
+    return None

chqce/estimator.py

@@ -0,0 +1,125 @@
+import time
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+
+@dataclass
+class TableEstimate:
+    database: str
+    table: str
+    parts: int
+    rows: int
+    marks: int
+
+
+@dataclass
+class EstimateResult:
+    query: str
+
+    # EXPLAIN ESTIMATE results
+    table_estimates: List[TableEstimate] = field(default_factory=list)
+    total_rows: int = 0
+    total_parts: int = 0
+    total_marks: int = 0
+
+    # EXPLAIN PLAN
+    query_plan: str = ""
+
+    # Timing (milliseconds)
+    explain_time_ms: float = 0.0      # time to run EXPLAIN (analysis + planning)
+    execution_time_ms: float = 0.0    # wall-clock time for full execution
+    server_time_ms: float = 0.0       # server-side time reported by ClickHouse
+
+    # Execution stats
+    read_rows: int = 0
+    read_bytes: int = 0
+    result_rows: int = 0
+    result_bytes: int = 0
+    memory_usage_bytes: int = 0
+
+    was_executed: bool = False
+
+    # Errors (non-fatal — other steps still run)
+    explain_error: Optional[str] = None
+    execution_error: Optional[str] = None
+
+
+class QueryEstimator:
+    def __init__(self, client):
+        self.client = client
+
+    @staticmethod
+    def _is_select(query: str) -> bool:
+        first = query.strip().split()[0].upper() if query.strip() else ""
+        return first in ("SELECT", "WITH")
+
+    def estimate(self, query: str, execute: bool = True) -> EstimateResult:
+        result = EstimateResult(query=query)
+        is_select = self._is_select(query)
+
+        # Step 1: EXPLAIN ESTIMATE — rows/parts/marks per table
+        if is_select:
+            try:
+                t0 = time.perf_counter()
+                er = self.client.query(f"EXPLAIN ESTIMATE {query}")
+                result.explain_time_ms = (time.perf_counter() - t0) * 1000
+
+                for row in er.result_rows:
+                    te = TableEstimate(
+                        database=str(row[0]),
+                        table=str(row[1]),
+                        parts=int(row[2]),
+                        rows=int(row[3]),
+                        marks=int(row[4]),
+                    )
+                    result.table_estimates.append(te)
+                    result.total_rows += te.rows
+                    result.total_parts += te.parts
+                    result.total_marks += te.marks
+            except Exception as e:
+                result.explain_error = str(e)
+
+        # Step 2: EXPLAIN PLAN — human-readable execution plan
+        if is_select:
+            try:
+                pr = self.client.query(f"EXPLAIN PLAN {query}")
+                result.query_plan = "\n".join(str(row[0]) for row in pr.result_rows)
+            except Exception:
+                pass
+
+        # Step 3: Execute and collect real stats
+        if execute:
+            try:
+                t0 = time.perf_counter()
+                xr = self.client.query(query)
+                result.execution_time_ms = (time.perf_counter() - t0) * 1000
+                result.was_executed = True
+                result.result_rows = len(xr.result_rows)
+
+                summary = xr.summary or {}
+                result.read_rows = int(summary.get("read_rows", 0))
+                result.read_bytes = int(summary.get("read_bytes", 0))
+                result.result_bytes = int(summary.get("result_bytes", 0))
+                elapsed_ns = int(summary.get("elapsed_ns", 0))
+                if elapsed_ns:
+                    result.server_time_ms = elapsed_ns / 1_000_000
+
+                # Memory usage lives in query_log; give the flush a moment
+                query_id = getattr(xr, "query_id", None)
+                if query_id:
+                    time.sleep(0.05)
+                    try:
+                        mem_res = self.client.query(
+                            "SELECT memory_usage FROM system.query_log "
+                            "WHERE type = 'QueryFinish' AND query_id = {qid:String} LIMIT 1",
+                            parameters={"qid": query_id},
+                        )
+                        if mem_res.result_rows:
+                            result.memory_usage_bytes = int(mem_res.result_rows[0][0])
+                    except Exception:
+                        pass
+
+            except Exception as e:
+                result.execution_error = str(e)
+
+        return result

chqce/formatter.py

@@ -0,0 +1,227 @@
+from typing import List
+
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+
+from .errors import classify_error
+from .estimator import EstimateResult
+from .suggestions import IndexSuggestion
+
+console = Console()
+
+
+# ── helpers ─────────────────────────────────────────────────────────────────
+
+def _fmt_bytes(n: int) -> str:
+    if n <= 0:
+        return "—"
+    for unit, threshold in (("GB", 1 << 30), ("MB", 1 << 20), ("KB", 1 << 10)):
+        if n >= threshold:
+            return f"{n / threshold:.1f} {unit}"
+    return f"{n} B"
+
+
+def _fmt_rows(n: int) -> str:
+    if n >= 1_000_000_000:
+        return f"{n / 1_000_000_000:.1f}B"
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f}K"
+    return str(n)
+
+
+def _fmt_ms(ms: float) -> str:
+    if ms <= 0:
+        return "—"
+    if ms >= 1_000:
+        return f"{ms / 1_000:.2f} s"
+    if ms >= 1:
+        return f"{ms:.1f} ms"
+    return f"{ms * 1_000:.0f} µs"
+
+
+# ── public API ───────────────────────────────────────────────────────────────
+
+def print_header(version: str, host: str, port: int, database: str) -> None:
+    console.print()
+    console.print(
+        Panel(
+            f"[bold cyan]ClickHouse Query Cost Estimator[/bold cyan]  [dim]v0.1.0[/dim]\n"
+            f"[dim]Connected to [green]{host}:{port}[/green]"
+            f"  ·  database: [green]{database}[/green]"
+            f"  ·  ClickHouse [green]{version}[/green][/dim]",
+            box=box.ROUNDED,
+            border_style="cyan",
+        )
+    )
+
+
+def print_result(result: EstimateResult, suggestions: List[IndexSuggestion]) -> None:
+    console.print()
+
+    # ── Query display ────────────────────────────────────────────────────────
+    # Truncate the echo for huge queries so results stay visible.
+    QUERY_ECHO_LINES = 30
+    q = result.query.strip()
+    q_lines = q.split("\n")
+    if len(q_lines) > QUERY_ECHO_LINES:
+        head = "\n".join(q_lines[:QUERY_ECHO_LINES])
+        body = Syntax(head, "sql", theme="monokai")
+        title = (
+            f"[bold]Query[/bold]  "
+            f"[dim](showing {QUERY_ECHO_LINES} of {len(q_lines)} lines, "
+            f"{len(q):,} chars)[/dim]"
+        )
+    else:
+        body = Syntax(q, "sql", theme="monokai")
+        title = "[bold]Query[/bold]"
+    console.print(Panel(body, title=title, border_style="blue"))
+    console.print()
+
+    # ── Errors ───────────────────────────────────────────────────────────────
+    if result.explain_error:
+        _print_error("⚠  Estimate unavailable", result.explain_error,
+                     style="yellow", border="yellow")
+    if result.execution_error:
+        _print_error("✗  Execution error", result.execution_error,
+                     style="red", border="red")
+        _print_index_suggestions(suggestions)
+        return
+
+    # ── Cost estimate ────────────────────────────────────────────────────────
+    if result.table_estimates:
+        t = Table(
+            title="[bold]Cost Estimate  [dim](from EXPLAIN ESTIMATE)[/dim][/bold]",
+            box=box.SIMPLE_HEAD,
+            header_style="bold magenta",
+        )
+        t.add_column("Database", style="cyan")
+        t.add_column("Table", style="cyan")
+        t.add_column("Parts", justify="right")
+        t.add_column("Est. Rows", justify="right", style="yellow")
+        t.add_column("Marks", justify="right")
+
+        for te in result.table_estimates:
+            t.add_row(te.database, te.table, str(te.parts), _fmt_rows(te.rows), str(te.marks))
+
+        if len(result.table_estimates) > 1:
+            t.add_section()
+            t.add_row(
+                "[bold]Total[/bold]",
+                "",
+                f"[bold]{result.total_parts}[/bold]",
+                f"[bold yellow]{_fmt_rows(result.total_rows)}[/bold yellow]",
+                f"[bold]{result.total_marks}[/bold]",
+            )
+        console.print(t)
+        console.print()
+
+    # ── Timing ───────────────────────────────────────────────────────────────
+    t = Table(
+        title="[bold]Timing[/bold]",
+        box=box.SIMPLE_HEAD,
+        header_style="bold magenta",
+    )
+    t.add_column("Phase", style="cyan")
+    t.add_column("Time", justify="right", style="green")
+    t.add_column("Notes", style="dim")
+
+    if result.explain_time_ms > 0:
+        t.add_row(
+            "SQL Analyzer  (EXPLAIN)",
+            _fmt_ms(result.explain_time_ms),
+            "parsing + plan generation",
+        )
+    if result.was_executed:
+        t.add_row(
+            "Execution  (client)",
+            _fmt_ms(result.execution_time_ms),
+            "wall-clock including network",
+        )
+        if result.server_time_ms > 0:
+            t.add_row(
+                "Execution  (server)",
+                _fmt_ms(result.server_time_ms),
+                "server-side only",
+            )
+
+    console.print(t)
+    console.print()
+
+    # ── Execution stats ───────────────────────────────────────────────────────
+    if result.was_executed:
+        t = Table(
+            title="[bold]Execution Stats[/bold]",
+            box=box.SIMPLE_HEAD,
+            header_style="bold magenta",
+        )
+        t.add_column("Metric", style="cyan")
+        t.add_column("Value", justify="right", style="green")
+
+        t.add_row("Rows read", _fmt_rows(result.read_rows))
+        t.add_row("Bytes read", _fmt_bytes(result.read_bytes))
+        t.add_row("Result rows", _fmt_rows(result.result_rows))
+        t.add_row("Result size", _fmt_bytes(result.result_bytes))
+        t.add_row("Peak memory", _fmt_bytes(result.memory_usage_bytes))
+
+        console.print(t)
+        console.print()
+
+    # ── Query plan ────────────────────────────────────────────────────────────
+    if result.query_plan:
+        lines = result.query_plan.split("\n")
+        body = "\n".join(lines[:40])
+        if len(lines) > 40:
+            body += f"\n[dim]… {len(lines) - 40} more lines[/dim]"
+        console.print(
+            Panel(body, title="[bold]Query Plan[/bold]", border_style="dim", expand=False)
+        )
+        console.print()
+
+    # ── Index suggestions ─────────────────────────────────────────────────────
+    _print_index_suggestions(suggestions)
+
+
+def _print_error(label: str, message: str, style: str, border: str) -> None:
+    """Render an error with a classified, actionable hint when we recognize it."""
+    classified = classify_error(message)
+    msg = message.strip()
+    body = f"[{style}]{label}[/{style}]"
+    if classified:
+        body += f"  [bold]{classified.title}[/bold]"
+    body += f"\n[dim]{msg}[/dim]"
+    if classified and classified.hint:
+        body += f"\n\n[bold]Suggestions[/bold]\n{classified.hint}"
+    console.print(Panel(body, border_style=border, expand=False))
+    console.print()
+
+
+def _print_index_suggestions(suggestions: List[IndexSuggestion]) -> None:
+    if not suggestions:
+        console.print("[dim]No index suggestions — add a WHERE clause to get recommendations.[/dim]")
+        console.print()
+        return
+
+    console.rule("[bold]Index Suggestions[/bold]", style="magenta")
+    console.print()
+
+    for s in suggestions:
+        if s.in_primary_key:
+            console.print(
+                f"  [green]✓[/green]  [bold]{s.column}[/bold]"
+                f"  [dim]on {s.table}[/dim]  —  {s.reason}"
+            )
+        else:
+            console.print(
+                f"  [yellow]⚠[/yellow]  [bold]{s.column}[/bold]"
+                f"  [dim]on {s.table}[/dim]  —  {s.reason}"
+            )
+            if s.suggestion:
+                console.print(
+                    Syntax(s.suggestion, "sql", theme="monokai", padding=(0, 4))
+                )
+        console.print()

chqce/suggestions.py

@@ -0,0 +1,156 @@
+from dataclasses import dataclass
+from typing import List, Set
+
+import sqlglot
+import sqlglot.expressions as exp
+
+
+@dataclass
+class IndexSuggestion:
+    table: str
+    column: str
+    reason: str
+    suggestion: str
+    in_primary_key: bool = False
+
+
+def _parse_query(query: str):
+    """Return (tables, where_cols) — tolerates parse failures."""
+    try:
+        tree = sqlglot.parse_one(query, read="clickhouse")
+    except Exception:
+        try:
+            tree = sqlglot.parse_one(query)
+        except Exception:
+            return {}, {}
+
+    # alias/name -> (database, table_name)
+    tables: dict[str, tuple[str, str]] = {}
+    for node in tree.find_all(exp.Table):
+        if not node.name:
+            continue
+        alias = (node.alias or node.name).lower()
+        tables[alias] = (node.db or "", node.name)
+
+    # column_name -> set of condition kinds
+    where_cols: dict[str, set] = {}
+
+    def _add(col_node: exp.Column, kind: str):
+        if col_node.name:
+            where_cols.setdefault(col_node.name.lower(), set()).add(kind)
+
+    where = tree.find(exp.Where)
+    if where:
+        for node in where.find_all(exp.EQ):
+            for c in node.find_all(exp.Column):
+                _add(c, "equality")
+        for node in where.find_all(exp.Between):
+            for c in node.find_all(exp.Column):
+                _add(c, "range")
+        for node in where.find_all(exp.LT, exp.LTE, exp.GT, exp.GTE):
+            for c in node.find_all(exp.Column):
+                _add(c, "range")
+        for node in where.find_all(exp.Like, exp.ILike):
+            for c in node.find_all(exp.Column):
+                _add(c, "like")
+        for node in where.find_all(exp.In):
+            for c in node.find_all(exp.Column):
+                _add(c, "in")
+
+    return tables, where_cols
+
+
+def _get_order_by_cols(client, database: str, table: str) -> List[str]:
+    try:
+        res = client.query(
+            "SELECT sorting_key, primary_key FROM system.tables "
+            "WHERE database = {db:String} AND name = {t:String}",
+            parameters={"db": database, "t": table},
+        )
+        if not res.result_rows:
+            return []
+        sorting_key, primary_key = res.result_rows[0]
+        key = sorting_key or primary_key
+        if key:
+            return [c.strip() for c in key.split(",") if c.strip()]
+    except Exception:
+        pass
+    return []
+
+
+def _get_col_type(client, database: str, table: str, column: str) -> str:
+    try:
+        res = client.query(
+            "SELECT type FROM system.columns "
+            "WHERE database={db:String} AND table={t:String} AND name={c:String}",
+            parameters={"db": database, "t": table, "c": column},
+        )
+        if res.result_rows:
+            return res.result_rows[0][0]
+    except Exception:
+        pass
+    return ""
+
+
+def _best_index_type(col_type: str, conditions: Set[str]) -> str:
+    ct = col_type.lower()
+    if "like" in conditions:
+        return "tokenbf_v1(32768, 3, 0)"
+    if "range" in conditions:
+        return "minmax"
+    if "string" in ct or "fixedstring" in ct:
+        return "bloom_filter(0.01)"
+    if any(x in ct for x in ("int", "uint", "float", "decimal", "date", "datetime")):
+        return "set(100)" if "in" in conditions or "equality" in conditions else "minmax"
+    return "bloom_filter(0.01)"
+
+
+def get_index_suggestions(
+    query: str, client, current_database: str = "default"
+) -> List[IndexSuggestion]:
+    tables, where_cols = _parse_query(query)
+    if not where_cols or not tables:
+        return []
+
+    suggestions: List[IndexSuggestion] = []
+
+    for _alias, (db, table_name) in tables.items():
+        effective_db = db or current_database
+        pk_cols = _get_order_by_cols(client, effective_db, table_name)
+        pk_lower = {c.lower() for c in pk_cols}
+        full_table = f"{effective_db}.{table_name}" if effective_db else table_name
+
+        for col_name, conditions in where_cols.items():
+            in_pk = col_name in pk_lower
+
+            if in_pk:
+                suggestions.append(
+                    IndexSuggestion(
+                        table=full_table,
+                        column=col_name,
+                        reason=f"already in ORDER BY {pk_cols}",
+                        suggestion="",
+                        in_primary_key=True,
+                    )
+                )
+            else:
+                col_type = _get_col_type(client, effective_db, table_name, col_name)
+                idx_type = _best_index_type(col_type, conditions)
+                idx_name = f"idx_{table_name}_{col_name}"
+                alter_sql = (
+                    f"ALTER TABLE {full_table}\n"
+                    f"    ADD INDEX {idx_name} {col_name}\n"
+                    f"    TYPE {idx_type} GRANULARITY 4;"
+                )
+                pk_label = pk_cols if pk_cols else ["(unknown)"]
+                suggestions.append(
+                    IndexSuggestion(
+                        table=full_table,
+                        column=col_name,
+                        reason=f"not in ORDER BY {pk_label}",
+                        suggestion=alter_sql,
+                        in_primary_key=False,
+                    )
+                )
+
+    return suggestions

chqce-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: chqce
+Version: 0.1.0
+Summary: ClickHouse Query Cost Estimator CLI
+Author-email: Ahmad Darwich <darw.ahmad@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AhmadDarwich/clickhouse-query-cost-estimator
+Project-URL: Repository, https://github.com/AhmadDarwich/clickhouse-query-cost-estimator
+Project-URL: Issues, https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/issues
+Keywords: clickhouse,sql,cli,query,cost,performance,explain
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clickhouse-connect>=0.7.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: sqlglot>=20.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# clickhouse-query-cost-estimator
+
+[![CI](https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/actions/workflows/ci.yml/badge.svg)](https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chqce.svg)](https://pypi.org/project/chqce/)
+[![Python versions](https://img.shields.io/pypi/pyversions/chqce.svg)](https://pypi.org/project/chqce/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A terminal CLI that estimates the cost of a ClickHouse SQL query **before you regret running it**, and helps you tune indexes afterwards.
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ClickHouse Query Cost Estimator  v0.1.0                      │
+│ Connected to localhost:8123  ·  database: default  ·  23.8  │
+╰──────────────────────────────────────────────────────────────╯
+
+Cost Estimate  (from EXPLAIN ESTIMATE)
+ Database  Table   Parts  Est. Rows  Marks
+ default   orders     12    4.5M     550
+
+Timing
+ Phase                       Time        Notes
+ SQL Analyzer (EXPLAIN)      2.1 ms      parsing + plan generation
+ Execution (client)        234.5 ms      wall-clock including network
+ Execution (server)        228.3 ms      server-side only
+
+Execution Stats
+ Rows read      4.5M      Bytes read   1.2 GB
+ Result rows    18.2K     Peak memory  45.6 MB
+
+── Index Suggestions ──────────────────────────────────────────
+  ✓  created_at  —  already in ORDER BY
+  ⚠  user_id    —  not in ORDER BY
+     ALTER TABLE default.orders
+         ADD INDEX idx_orders_user_id user_id
+         TYPE bloom_filter(0.01) GRANULARITY 4;
+```
+
+## What it tells you
+
+| Metric | Source |
+|---|---|
+| **Estimated rows / parts / marks** | `EXPLAIN ESTIMATE` |
+| **SQL analyzer time** | time to run `EXPLAIN PLAN` (parsing + planning) |
+| **Execution time (client)** | wall-clock including network round-trip |
+| **Execution time (server)** | `elapsed_ns` from `X-ClickHouse-Summary` header |
+| **Rows / bytes read, peak memory** | `system.query_log` after execution |
+| **Index suggestions** | `system.tables` ORDER BY vs WHERE columns |
+
+## Installation
+
+```bash
+pip install chqce
+```
+
+Or, for local development:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Analyze a single query
+chqce "SELECT count() FROM hits WHERE EventDate = today()"
+
+# Interactive mode — paste any query, then type ; or GO to submit
+chqce
+
+# Custom connection
+chqce --host my.ch.host --port 9123 --user admin --database analytics \
+      "SELECT count() FROM events WHERE user_id = 42"
+
+# Estimate only — skip execution (safe for expensive/destructive queries)
+chqce --no-execute "SELECT * FROM huge_table WHERE x > 0"
+```
+
+### Large queries
+
+For big, multi-line queries (hundreds or thousands of lines) you don't want to
+wrestle with shell quoting. Read the query from a file or pipe it in instead:
+
+```bash
+# From a file — the cleanest option for huge queries
+chqce -f report.sql
+
+# Piped via stdin
+cat report.sql | chqce
+chqce < report.sql
+
+# If ClickHouse rejects it with a max_query_size error, raise the limit
+chqce -f report.sql --max-query-size 1048576   # 1 MiB
+```
+
+The query source is resolved in this priority order:
+
+1. `--file` / `-f` — read from a file
+2. `QUERY` argument — passed on the command line
+3. piped **stdin** — when input isn't a terminal
+4. interactive prompt — when nothing else is provided
+
+The echoed query is truncated to the first 30 lines in the output, so a large
+query never buries the results.
+
+### Timeouts and resource limits
+
+Heavy queries can hit server-side limits. The tool catches these, reports them
+clearly, and tells you which flag gets you unstuck:
+
+```bash
+# Abort the query after 5 minutes instead of waiting indefinitely
+chqce -t 300 "SELECT ... a slow aggregation ..."
+
+# Fix "AST is too big" (e.g. a giant IN (...) list)
+chqce -f report.sql --max-ast-elements 500000
+
+# Fix "Max query size exceeded"
+chqce -f report.sql --max-query-size 1048576   # 1 MiB
+```
+
+When a query fails, the error is classified and shown with suggestions. For
+example, a timeout renders as:
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ✗  Execution error  Query timed out                          │
+│ Code: 159. DB::Exception: Timeout exceeded: elapsed 30 ...   │
+│                                                              │
+│ Suggestions                                                  │
+│ The query exceeded its time budget. Try:                     │
+│   • raise the limit:  --timeout 600  (seconds, 0 = unlimited)│
+│   • estimate without running:  --no-execute                  │
+│   • narrow the query with a WHERE filter or LIMIT            │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+Recognized failures: **timeout**, **AST too big**, **parser depth**,
+**query size**, **memory limit**, and **read-row/byte limits**.
+
+## Options
+
+| Flag | Env var | Default | Description |
+|---|---|---|---|
+| `--file` / `-f` | — | — | Read the query from a file (best for huge queries) |
+| `--host` / `-H` | `CLICKHOUSE_HOST` | `localhost` | ClickHouse host |
+| `--port` / `-p` | `CLICKHOUSE_PORT` | `8123` | HTTP port |
+| `--user` / `-u` | `CLICKHOUSE_USER` | `default` | Username |
+| `--password` / `-P` | `CLICKHOUSE_PASSWORD` | _(empty)_ | Password |
+| `--database` / `-d` | `CLICKHOUSE_DATABASE` | `default` | Default database |
+| `--timeout` / `-t` | — | `0` _(unlimited)_ | Server-side `max_execution_time` in seconds |
+| `--max-query-size` | — | _(server default 262144)_ | Raise ClickHouse `max_query_size` for very large queries |
+| `--max-ast-elements` | — | _(server default 50000)_ | Raise ClickHouse `max_ast_elements` for queries with huge ASTs |
+| `--no-execute` | — | `false` | Skip actual execution; estimate only |
+
+## Interactive mode
+
+Type or paste a multi-line query, then submit by:
+- Ending the last line with `;`
+- Typing `GO` on its own line
+
+Press **Ctrl+C** to exit.
+
+## How index suggestions work
+
+1. The query is parsed with [sqlglot](https://github.com/tobymao/sqlglot) to extract WHERE-clause columns and condition types (equality, range, LIKE, IN).
+2. Each referenced table's `sorting_key` is fetched from `system.tables`.
+3. Columns not covered by the sort key get a skip-index `ALTER TABLE` suggestion, with the type chosen by condition and column type:
+
+| Condition | Column type | Suggested index |
+|---|---|---|
+| `LIKE` / `ILIKE` | any | `tokenbf_v1(32768, 3, 0)` |
+| `>` / `<` / `BETWEEN` | any | `minmax` |
+| `=` / `IN` | String | `bloom_filter(0.01)` |
+| `=` / `IN` | numeric / date | `set(100)` |
+
+## Requirements
+
+- Python ≥ 3.10
+- ClickHouse with HTTP interface enabled (default port 8123)
+
+## Development
+
+Run the test suite (no ClickHouse server required — tests use a fake client):
+
+```bash
+pip install -e ".[test]"   # or: pip install -r requirements-dev.txt
+pytest
+```
+
+The tests live in `tests/` and cover error classification, the estimator,
+index suggestions, output formatting, connection settings, and the CLI.

chqce-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+chqce/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+chqce/cli.py,sha256=s3PjZsVvpIEXslKxH6rCLEsYImrkwO7ndZgFzvKGZVs,6435
+chqce/connection.py,sha256=qMYLLV3HReHvBkcNgMDA8MzE4yQp9okFWOZveWYK_-g,1810
+chqce/errors.py,sha256=SDw4NPGYRyk58iyaIy6ARN0Zoh2i0zpWcyinJqOjADY,3332
+chqce/estimator.py,sha256=cB3yHXJ8uqDVQOgh_sFnMeAGp0aPYQLe1W6i6I9AOTI,4290
+chqce/formatter.py,sha256=LChQHR2atkawtGqDwiH4dicAasV_zQRN-yD2L9tf5x8,8872
+chqce/suggestions.py,sha256=lb6yhjXUAHSUDqMYPeemqEDInnrxzrn2UThBT46gx14,5246
+chqce-0.1.0.dist-info/licenses/LICENSE,sha256=WzwMceuO8oWaxTqWZNRJFRIcXS4AJIInPqiba2XtI_Y,1070
+chqce-0.1.0.dist-info/METADATA,sha256=Xj__fCoc3mQJXuCgPrse00vGCMNRO1PxjlFam8UlyTk,9014
+chqce-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+chqce-0.1.0.dist-info/entry_points.txt,sha256=0RJ1jIhBZ9T0YTXHkKQP9mPowWEo9aD7SbwYEDdUf2Y,40
+chqce-0.1.0.dist-info/top_level.txt,sha256=BMw-L4xkLh5Frcmnczp6pMbuhzlhoPL7L8rB0BfQXWs,6
+chqce-0.1.0.dist-info/RECORD,,

chqce-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

chqce-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chqce = chqce.cli:cli

chqce-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmad Darwich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chqce-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+chqce