Merge pull request #16 from Coffey-Labs/docs/query-api-request-shape

Catch the runbooks up with the query API they describe

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

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": "<a distinctive word from your test log line>"}'
 ```
 

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"}'
 ```