Proposal: Unify ClickHouse Execution over HTTP API (Remove executeCHQuery)

Background & Problem

Currently, the API maintains two disparate paths for interacting with ClickHouse:

1. HTTP Proxy: Used by internal/api/query.go to forward raw SQL directly to ClickHouse.
2. Native Driver (clickhouse-go): Used by programmatic endpoints (internal/api/structured_query.go and internal/api/pipes.go), which rely on the executeCHQuery wrapper found in internal/api/clickhouse_exec.go.

The native driver path introduces significant complexity. To determine whether to use .Query() or .Exec(), clickhouse_exec.go relies on an isMutation heuristic, CTE parsing, and comment-stripping logic. As noted in internal/api/query.go, this logic is fragile, error-prone, and requires ongoing maintenance as ClickHouse introduces new keywords and syntax.

Proposed Solution

We should eliminate executeCHQuery entirely and standardize all ClickHouse interactions on the HTTP interface used in internal/api/query.go. This simplifies the architecture, reduces our bug surface, and potentially improves performance by reducing serialization steps.

Affected Files

• internal/api/clickhouse_exec.go (Targeted for removal)
• internal/api/query.go (Reference for HTTP proxy implementation)
• internal/api/structured_query.go (Needs refactoring)
• internal/api/pipes.go (Needs refactoring)

Implementation Options & Side Effects

1. Parameter Binding

• Concern: Switching to the HTTP API means we lose clickhouse-go's standard ? parameter binding used in structured_query.go and pipes.go.
• Option/Action: We must rewrite the parameter generation logic in query.Build and pipes.BindParams. Instead of standard placeholders, we need to implement ClickHouse's HTTP parameterization scheme (e.g., using {name: DataType} syntax in the query and appending param_my_var=... to the HTTP request query string).

2. Caching Mechanism Updates

• Side Effect (Positive): Currently, the cached paths unmarshal the driver results into []map[string]any and then call json.Marshal to store the data in the TieredCache.
• Option/Action: Moving to HTTP allows us to skip JSON marshaling/unmarshaling entirely. We can extract the raw data byte array straight from the ClickHouse HTTP JSON response and write those bytes directly into the cache and the http.ResponseWriter.

3. Standardizing Type Formatting

• Concern: transformRow in clickhouse_exec.go currently intercepts and manually formats uuid.UUID and time.Time (to RFC3339Nano) for JSON safety.
• Option/Action: When proxying via HTTP, we rely on ClickHouse to output the JSON directly. To ensure we don't break our API contract for Dates and UUIDs, we need to enforce formatting via URL query parameters, such as passing date_time_output_format=iso to the proxy client (similar to how it is currently handled in query.go).