Repository navigation
feat(api): bypass cache for raw admin SQL queries #93
Description
Problem
Currently, raw SQL queries submitted via the /v1/query endpoint are routed through the TieredCache and singleflight mechanism. This is an anti-pattern for administrative tools because:
- Consistency: Admins and CI/CD E2E tests require real-time data to verify ingestion correctness (read-your-writes).
- Cache Pollution: Ad-hoc raw SQL queries are highly unique and rarely re-executed, causing unnecessary memory/Redis churn in the
TieredCache.
Proposed Solution
- Modify
api/query.go: Update theQueryHandler.Handlemethod to bypass theh.Cache(Get/Set) andsingleflight(if applicable) logic when processing raw SQL. - Header Management: Ensure the response is served with
Cache-Control: no-cacheto discourage intermediate or client-side caching. - Separation of Concerns: This change must strictly apply to raw SQL (
/v1/query). Structured queries and pipes must remain cached to maintain system performance.
Acceptance Criteria
- Direct execution against ClickHouse for all
POST /v1/queryrequests. - No
h.Cache.Getorh.Cache.Setlogic triggered for the raw SQL path. - Raw SQL responses include
Cache-Control: no-cacheheader. - E2E/Admin tests that perform inserts followed by counts/reads now pass reliably without stale data collisions.
-
/pipes(Named Queries) and Structured Queries retain current caching/singleflight behavior.
This issue is part of the "Query Cache" improvement initiative discussed in the recent standup (#73 . It serves as the primary "escape hatch" for administrative data verification while we implement more complex invalidation logic for structured queries.
Alternatives Considered
None
Additional Context
None
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
EricAndrechek commentedon May 19, 2026
Closing as done by PR #164.
Two commits cover this:
45bc840— moves raw SQL from/v1/queryto/v1/admin/queryunder the admin gate.421c3ce— strips theTieredCache+singleflightfromQueryHandlerentirely. BothCache.GetandCache.Setare gone, no cache key is computed, noX-Cache: HIT/MISSheader is emitted, and the mutation cache-bypass branch is removed (no cache to bypass). The structured query and pipes endpoints retain their caching unchanged.Acceptance criteria status:
h.Cache.Get/h.Cache.Settriggered —QueryHandlerno longer holds aCachefield./pipes+ structured queries retain caching — unchanged.Cache-Control: no-cacheresponse header — not yet shipped; will land in the upcoming HTTP-proxy refactor (next commit on the same branch, replacingclickhouse-goQuery/Exec with a thin proxy to ClickHouse's HTTP interface). Tracking that change in PR refactor(ingest)!: insert-only pipeline; mutations via /v1/query #164 too.EricAndrechek commentedon May 19, 2026
Reopening — jumped the gun. The work is in PR #164 but the issue should auto-close on merge, not before. I've updated the PR description to include `Closes #93` so GitHub closes it when (and only when) the PR lands.
refactor(ingest)!: insert-only pipeline; mutations via /v1/query (#164)