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.
2026-08-13 12:21:42 -07:00
parent cd8aa290ca
commit fb5049a747
36 changed files with 4119 additions and 613 deletions
@@ -11,111 +11,179 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/sentry/sentry/api/internal/querylang/executor"
 )

-type fakeExecutor struct {
-	result *QueryResult
+type fakeSQLRunner struct {
+	result *executor.Result
 	err    error
 	gotSQL string
 }

-func (f *fakeExecutor) Execute(_ context.Context, sql string) (*QueryResult, error) {
+func (f *fakeSQLRunner) RunSQL(_ context.Context, sql string) (*executor.Result, error) {
 	f.gotSQL = sql
 	if f.err != nil {
 		return nil, f.err
 	}
-	return f.result, nil
+	if f.result != nil {
+		return f.result, nil
+	}
+	return &executor.Result{Columns: []string{}, Rows: [][]any{}}, nil
 }

 type fakeSearchClient struct {
 	recordIDs []string
 	err       error
+	gotQuery  string
 }

-func (f *fakeSearchClient) Search(_ context.Context, _ string, _ uint32) ([]string, error) {
+func (f *fakeSearchClient) Search(_ context.Context, query string, _ uint32) ([]string, error) {
+	f.gotQuery = query
 	if f.err != nil {
 		return nil, f.err
 	}
 	return f.recordIDs, nil
 }

-func newTestHandler(exec queryExecutor) *Handler {
-	return newTestHandlerWithSearch(exec, &fakeSearchClient{})
+func newTestHandler(sqlRunner *fakeSQLRunner, search *fakeSearchClient) *Handler {
+	if search == nil {
+		search = &fakeSearchClient{}
+	}
+	return NewHandler(slog.New(slog.NewTextHandler(io.Discard, nil)), sqlRunner, search, time.Second, "*")
 }

-func newTestHandlerWithSearch(exec queryExecutor, search searchClient) *Handler {
-	return NewHandler(slog.New(slog.NewTextHandler(io.Discard, nil)), exec, search, time.Second, "*")
+func postQuery(t *testing.T, h *Handler, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPost, "/query", strings.NewReader(body))
+	rec := httptest.NewRecorder()
+	h.Routes().ServeHTTP(rec, req)
+	return rec
 }

-func TestHandleQuerySuccess(t *testing.T) {
-	fe := &fakeExecutor{result: &QueryResult{
+func TestHandleQuerySQLSuccess(t *testing.T) {
+	sr := &fakeSQLRunner{result: &executor.Result{
 		Columns: []string{"host", "count"},
 		Rows:    [][]any{{"h1", 3}},
 	}}
-	h := newTestHandler(fe)
+	h := newTestHandler(sr, nil)

-	body := strings.NewReader(`{"sql": "SELECT host, count(*) FROM logs GROUP BY host"}`)
-	req := httptest.NewRequest(http.MethodPost, "/query", body)
-	rec := httptest.NewRecorder()
-
-	h.Routes().ServeHTTP(rec, req)
+	rec := postQuery(t, h, `{"query": "SELECT host, count(*) FROM logs GROUP BY host"}`)

 	if rec.Code != http.StatusOK {
 		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
 	}
-	var got QueryResult
+	var got queryResponse
 	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
 		t.Fatalf("decoding response: %v", err)
 	}
 	if len(got.Columns) != 2 || len(got.Rows) != 1 {
 		t.Fatalf("unexpected result: %+v", got)
 	}
-	if fe.gotSQL != "SELECT host, count(*) FROM logs GROUP BY host" {
-		t.Fatalf("executor received unexpected SQL: %q", fe.gotSQL)
+	if sr.gotSQL != "SELECT host, count(*) FROM logs GROUP BY host" {
+		t.Fatalf("unexpected SQL passed through: %q", sr.gotSQL)
 	}
 }

-func TestHandleQueryRejectsNonSelect(t *testing.T) {
-	fe := &fakeExecutor{}
-	h := newTestHandler(fe)
+func TestHandleQueryPipeSyntaxSuccess(t *testing.T) {
+	sr := &fakeSQLRunner{result: &executor.Result{
+		Columns: []string{"host"},
+		Rows:    [][]any{{"api"}},
+	}}
+	h := newTestHandler(sr, nil)

-	body := strings.NewReader(`{"sql": "DELETE FROM logs"}`)
-	req := httptest.NewRequest(http.MethodPost, "/query", body)
-	rec := httptest.NewRecorder()
+	rec := postQuery(t, h, `{"query": "service=api"}`)

-	h.Routes().ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	if !strings.Contains(sr.gotSQL, "`service` = 'api'") {
+		t.Fatalf("expected compiled SQL to filter on service, got: %s", sr.gotSQL)
+	}
+}

+func TestHandleQueryTextSearchRoutesThroughSearchClient(t *testing.T) {
+	sr := &fakeSQLRunner{}
+	fs := &fakeSearchClient{recordIDs: []string{"id-1"}}
+	h := newTestHandler(sr, fs)
+
+	rec := postQuery(t, h, `{"query": "message:\"connection refused\""}`)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	if fs.gotQuery != `"connection refused"` {
+		t.Fatalf("search query = %q", fs.gotQuery)
+	}
+	if !strings.Contains(sr.gotSQL, "record_id IN ('id-1')") {
+		t.Fatalf("expected the search prefilter in the generated SQL, got: %s", sr.gotSQL)
+	}
+}
+
+func TestHandleQueryRejectsEmptyQuery(t *testing.T) {
+	h := newTestHandler(&fakeSQLRunner{}, nil)
+	rec := postQuery(t, h, `{"query": "   "}`)
 	if rec.Code != http.StatusBadRequest {
 		t.Fatalf("status = %d, want 400", rec.Code)
 	}
-	if fe.gotSQL != "" {
-		t.Fatal("executor should not have been called for a rejected query")
-	}
 }

 func TestHandleQueryRejectsInvalidJSON(t *testing.T) {
-	h := newTestHandler(&fakeExecutor{})
-
-	body := strings.NewReader(`not json`)
-	req := httptest.NewRequest(http.MethodPost, "/query", body)
-	rec := httptest.NewRecorder()
-
-	h.Routes().ServeHTTP(rec, req)
-
+	h := newTestHandler(&fakeSQLRunner{}, nil)
+	rec := postQuery(t, h, `not json`)
 	if rec.Code != http.StatusBadRequest {
 		t.Fatalf("status = %d, want 400", rec.Code)
 	}
 }

+func TestHandleQueryRejectsCompileError(t *testing.T) {
+	h := newTestHandler(&fakeSQLRunner{}, nil)
+	rec := postQuery(t, h, `{"query": "service=api | bogus"}`)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400; body=%s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestHandleQueryRejectsNonSelectSQL(t *testing.T) {
+	h := newTestHandler(&fakeSQLRunner{}, nil)
+	rec := postQuery(t, h, `{"query": "DELETE FROM logs", "language": "sql"}`)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400", rec.Code)
+	}
+}
+
+func TestHandleQueryRejectsInvalidLanguage(t *testing.T) {
+	h := newTestHandler(&fakeSQLRunner{}, nil)
+	rec := postQuery(t, h, `{"query": "service=api", "language": "cobol"}`)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want 400", rec.Code)
+	}
+}
+
+func TestHandleQueryExplicitLanguageOverridesAutoDetect(t *testing.T) {
+	sr := &fakeSQLRunner{}
+	fs := &fakeSearchClient{recordIDs: []string{"id-1"}}
+	h := newTestHandler(sr, fs)
+
+	// "select" alone would auto-detect as (nonsensical but
+	// syntactically-valid-looking) SQL without the override -- the
+	// override forces pipe-syntax parsing instead, where a bare word
+	// with no comparator is a free-text search term.
+	rec := postQuery(t, h, `{"query": "select", "language": "spl"}`)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200; body=%s", rec.Code, rec.Body.String())
+	}
+	if fs.gotQuery != "select" {
+		t.Fatalf("expected 'select' to be treated as a free-text search term, got query=%q", fs.gotQuery)
+	}
+}
+
 func TestHandleQueryExecutorErrorReturnsBadGateway(t *testing.T) {
-	fe := &fakeExecutor{err: errors.New("boom")}
-	h := newTestHandler(fe)
+	sr := &fakeSQLRunner{err: errors.New("boom")}
+	h := newTestHandler(sr, nil)

-	body := strings.NewReader(`{"sql": "SELECT 1"}`)
-	req := httptest.NewRequest(http.MethodPost, "/query", body)
-	rec := httptest.NewRecorder()
-
-	h.Routes().ServeHTTP(rec, req)
+	rec := postQuery(t, h, `{"query": "SELECT 1"}`)

 	if rec.Code != http.StatusBadGateway {
 		t.Fatalf("status = %d, want 502", rec.Code)
@@ -123,7 +191,7 @@ func TestHandleQueryExecutorErrorReturnsBadGateway(t *testing.T) {
 }

 func TestHandleHealthz(t *testing.T) {
-	h := newTestHandler(&fakeExecutor{})
+	h := newTestHandler(&fakeSQLRunner{}, nil)
 	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
 	rec := httptest.NewRecorder()

@@ -135,7 +203,7 @@ func TestHandleHealthz(t *testing.T) {
 }

 func TestCORSPreflight(t *testing.T) {
-	h := newTestHandler(&fakeExecutor{})
+	h := newTestHandler(&fakeSQLRunner{}, nil)
 	req := httptest.NewRequest(http.MethodOptions, "/query", nil)
 	rec := httptest.NewRecorder()