From 9bbd802a91371b427fb198a3d2e11cfb75b9b5e9 Mon Sep 17 00:00:00 2001 From: John Coffey Date: Fri, 4 Sep 2026 17:44:54 -0700 Subject: [PATCH] Catch the runbooks up with the query API they describe Phase 2 unified the two query languages behind one endpoint and renamed the request field, and the runbooks were never updated. Following them today does not work: {"sql": ...} -> 400 query must not be empty POST /api :8080/search -> 404, the route no longer exists Both appear in the Phase 0 and Phase 1 runbooks and in the windows-fixture README. That matters more than a normal doc typo, because status.md cites the Phase 0 runbook as the record of how Phase 0 was verified -- so the documented verification procedure is one nobody can re-run as written. The Phase 1 step is rewritten rather than search-and-replaced: it checked the SQL and full-text paths against two different endpoints, and its exit criterion (the same record_id from both) now has to be expressed against /query twice, once with SQL and once with a bare word. Phase 0's expected output for SELECT 1 also gained a warnings field since it was written. Every command here was run against a live stack before being written down, including confirming both paths return the same record_id. Signed-off-by: John Coffey --- docs/phase-0-runbook.md | 9 ++++++--- docs/phase-1-runbook.md | 9 +++++++-- hack/windows-fixture/README.md | 4 ++-- 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/phase-0-runbook.md b/docs/phase-0-runbook.md index ae68f24..c52e0a8 100644 --- a/docs/phase-0-runbook.md +++ b/docs/phase-0-runbook.md @@ -75,8 +75,11 @@ curl http://localhost:8080/healthz curl -X POST http://localhost:8080/query \ -H 'Content-Type: application/json' \ - -d '{"sql": "SELECT 1"}' -# -> {"columns":["1"],"rows":[[1]]} (exact column name may vary by ClickHouse version) + -d '{"query": "SELECT 1"}' +# -> {"columns":["1"],"rows":[[1]],"warnings":[...]} +# (exact column name may vary by ClickHouse version; `warnings` carries +# costguard's assessment and is present on every response that has +# something to say about the query's cost) ``` This confirms `api` can reach `clickhouse` before you go looking for bugs @@ -157,7 +160,7 @@ ORDER BY timestamp DESC LIMIT 100`), and look for a row with ```sh curl -X POST http://localhost:8080/query \ -H 'Content-Type: application/json' \ - -d '{"sql": "SELECT * FROM logs ORDER BY timestamp DESC LIMIT 10"}' + -d '{"query": "SELECT * FROM logs ORDER BY timestamp DESC LIMIT 10"}' ``` **Or via cairnobsctl, just to confirm api is up (doesn't check the data diff --git a/docs/phase-1-runbook.md b/docs/phase-1-runbook.md index 238f524..ab5b42a 100644 --- a/docs/phase-1-runbook.md +++ b/docs/phase-1-runbook.md @@ -64,10 +64,15 @@ line (steps 4–6 there — mTLS certs, build, run, `logger`). Then, instead of just checking `/query`, check both: ```sh +# The SQL path (ClickHouse). curl -X POST http://localhost:8080/query -H 'Content-Type: application/json' \ - -d '{"sql": "SELECT record_id, message FROM logs ORDER BY timestamp DESC LIMIT 1"}' + -d '{"query": "SELECT record_id, message FROM logs ORDER BY timestamp DESC LIMIT 1"}' -curl -X POST http://localhost:8080/search -H 'Content-Type: application/json' \ +# The full-text path (Tantivy). A bare word is a free-text search -- see +# /docs/query-language-reference.md. Both go to /query: Phase 2 unified +# the two languages behind one endpoint, and the separate POST /search +# this step used to call no longer exists. +curl -X POST http://localhost:8080/query -H 'Content-Type: application/json' \ -d '{"query": ""}' ``` diff --git a/hack/windows-fixture/README.md b/hack/windows-fixture/README.md index 8ff7434..9f02ec3 100644 --- a/hack/windows-fixture/README.md +++ b/hack/windows-fixture/README.md @@ -41,9 +41,9 @@ Then confirm both query paths see it: ```sh curl -s -X POST http://localhost:8080/query -H 'Content-Type: application/json' \ - -d '{"sql": "SELECT host, severity, message, attributes['"'"'winevt.event_id'"'"'] AS event_id FROM logs WHERE host = '"'"'WIN-FIXTURE-01'"'"' ORDER BY timestamp DESC"}' + -d '{"query": "SELECT host, severity, message, attributes['"'"'winevt.event_id'"'"'] AS event_id FROM logs WHERE host = '"'"'WIN-FIXTURE-01'"'"' ORDER BY timestamp DESC"}' -curl -s -X POST http://localhost:8080/search -H 'Content-Type: application/json' \ +curl -s -X POST http://localhost:8080/query -H 'Content-Type: application/json' \ -d '{"query": "notepad"}' ```