Phase 2: unified query language spanning ClickHouse and Tantivy

Replaces the separate SQL-only /query and text-only /search endpoints
with one pipe-syntax query language (plus raw SQL escape hatch) that
compiles to a single IR and execution plan across both backends, so a
query like `message:"connection refused" | stats count by host` runs
as one request instead of two disjoint tools.

- api/internal/querylang: lexer -> ast -> parser -> ir -> planner ->
  executor, each layer independently tested.
- Execution generalizes Phase 1's proven Tantivy-prefilter pattern
  into a 4-way routing table (pure ClickHouse / text-only / text +
  aggregation / raw SQL passthrough).
- Unified web query page and `sentryctl query`, both hitting the same
  POST /query endpoint.
- Benchmarked against a real 1,022,000-row dataset
  (hack/benchmark-fixture); caught and fixed a real bug where the
  Tantivy prefilter cap (10,000) produced an IN-clause exceeding
  ClickHouse's default max_query_size -- lowered to 5,000, documented
  in docs/query-language-design.md and docs/phase-2-runbook.md.
- docs/query-language-reference.md: customer-facing syntax reference.

api/internal/queryapi/handler.go

@@ -1,13 +1,14 @@
-// Package queryapi is Sentry's query API: POST /query (Phase 0, a crude
-// raw-SQL passthrough allowlisted to SELECT) and POST /search (Phase 1,
-// free-text search via the search service, joined back against
-// ClickHouse). This is a deliberate simplification of the pinned "gRPC +
-// REST gateway" control-plane pattern (see CLAUDE.md's tech stack table):
-// plain net/http REST handlers, not a gRPC service transcoded through
-// grpc-gateway. That machinery (proto definitions, googleapis
-// annotations, gateway codegen) doesn't buy much for two crude endpoints
-// that Phase 2's real SPL-like query layer replaces outright. Revisit
-// gRPC+gateway once /api's endpoint count and lifespan justify it.
+// Package queryapi is Sentry's query API: a single POST /query endpoint
+// accepting either the pipe syntax or raw SQL, compiled by
+// querylang/planner and executed by querylang/executor. Replaces Phase
+// 0/1's two separate placeholder endpoints (raw-SQL-only /query,
+// free-text-only /search) -- see /docs/query-language-design.md.
+//
+// Still plain net/http, not the pinned gRPC+REST-gateway pattern, for
+// the same reason as Phase 0/1: this is one endpoint, and the
+// proto/annotations/codegen machinery doesn't buy much at that size.
+// `/api` does speak gRPC internally (to /search) — this simplification
+// is about the public-facing surface only.
 package queryapi
 
 import (
@@ -15,38 +16,34 @@ import (
 	"encoding/json"
 	"log/slog"
 	"net/http"
+	"strings"
 	"time"
-)
 
-// queryExecutor is the narrow interface handleQuery depends on, so tests
-// can substitute a fake without a real ClickHouse connection. *Executor
-// satisfies it.
-type queryExecutor interface {
-	Execute(ctx context.Context, sql string) (*QueryResult, error)
-}
+	"github.com/sentry/sentry/api/internal/querylang/executor"
+	"github.com/sentry/sentry/api/internal/querylang/planner"
+)
 
 type Handler struct {
 	logger        *slog.Logger
-	exec          queryExecutor
-	search        searchClient
+	sqlRunner     executor.SQLRunner
+	search        executor.SearchClient
 	queryTimeout  time.Duration
 	allowedOrigin string
 }
 
-func NewHandler(logger *slog.Logger, exec queryExecutor, search searchClient, queryTimeout time.Duration, allowedOrigin string) *Handler {
-	return &Handler{logger: logger, exec: exec, search: search, queryTimeout: queryTimeout, allowedOrigin: allowedOrigin}
+func NewHandler(logger *slog.Logger, sqlRunner executor.SQLRunner, search executor.SearchClient, queryTimeout time.Duration, allowedOrigin string) *Handler {
+	return &Handler{logger: logger, sqlRunner: sqlRunner, search: search, queryTimeout: queryTimeout, allowedOrigin: allowedOrigin}
 }
 
 func (h *Handler) Routes() http.Handler {
 	mux := http.NewServeMux()
 	mux.HandleFunc("POST /query", h.handleQuery)
-	mux.HandleFunc("POST /search", h.handleSearch)
 	mux.HandleFunc("GET /healthz", h.handleHealthz)
 	return h.withCORS(mux)
 }
 
 // withCORS is deliberately permissive by default (see CORSAllowedOrigin in
-// internal/config) since Phase 0 has no auth and the SvelteKit dev server
+// internal/config) since there's no auth yet and the SvelteKit dev server
 // runs on a different origin. Tighten alongside adding real auth.
 func (h *Handler) withCORS(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -66,14 +63,24 @@ func (h *Handler) handleHealthz(w http.ResponseWriter, _ *http.Request) {
 }
 
 type queryRequest struct {
-	SQL string `json:"sql"`
+	Query string `json:"query"`
+	// Language overrides auto-detection ("" / omitted). "sql" or "spl" --
+	// see planner.Language and /docs/query-language-design.md's
+	// "Detection" section for why this exists: the rare case a pipe
+	// query legitimately starts with the literal word "select".
+	Language string `json:"language"`
+}
+
+type queryResponse struct {
+	Columns []string `json:"columns"`
+	Rows    [][]any  `json:"rows"`
 }
 
 type errorResponse struct {
 	Error string `json:"error"`
 }
 
-// maxBodyBytes caps the request body: a raw SQL string has no legitimate
+// maxBodyBytes caps the request body: a query string has no legitimate
 // reason to be larger than this.
 const maxBodyBytes = 1 << 20 // 1 MiB
 
@@ -85,8 +92,19 @@ func (h *Handler) handleQuery(w http.ResponseWriter, r *http.Request) {
 		writeError(w, http.StatusBadRequest, "invalid JSON body: "+err.Error())
 		return
 	}
+	if strings.TrimSpace(req.Query) == "" {
+		writeError(w, http.StatusBadRequest, "query must not be empty")
+		return
+	}
 
-	if err := validateSelectOnly(req.SQL); err != nil {
+	lang := planner.Language(req.Language)
+	if lang != planner.Auto && lang != planner.SQL && lang != planner.SPL {
+		writeError(w, http.StatusBadRequest, `language must be "sql", "spl", or omitted`)
+		return
+	}
+
+	plan, err := planner.Compile(req.Query, lang, time.Now())
+	if err != nil {
 		writeError(w, http.StatusBadRequest, err.Error())
 		return
 	}
@@ -94,14 +112,19 @@ func (h *Handler) handleQuery(w http.ResponseWriter, r *http.Request) {
 	ctx, cancel := context.WithTimeout(r.Context(), h.queryTimeout)
 	defer cancel()
 
-	result, err := h.exec.Execute(ctx, req.SQL)
+	result, err := executor.Execute(ctx, plan, h.sqlRunner, h.search)
 	if err != nil {
-		h.logger.Error("query execution failed", "error", err)
+		h.logger.Error("query execution failed", "query", req.Query, "error", err)
 		writeError(w, http.StatusBadGateway, "query failed: "+err.Error())
 		return
 	}
 
-	writeJSON(w, result)
+	writeJSON(w, queryResponse{Columns: result.Columns, Rows: result.Rows})
+}
+
+func writeJSON(w http.ResponseWriter, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(v)
 }
 
 func writeError(w http.ResponseWriter, status int, msg string) {