refactor(filterquery): collapse the builder into the visitor

One Visitor struct now carries sb, fmter and errors like the old
per-feature visitors did; FieldResolver stays the only new concept.

pkg/modules/dashboard/impldashboard/listfilter.go

@@ -4,41 +4,17 @@ import (
 	"strings"
 
 	"github.com/SigNoz/signoz/pkg/errors"
+	"github.com/SigNoz/signoz/pkg/parser/filterquery/sqlcompiler"
 	"github.com/SigNoz/signoz/pkg/sqlstore"
 	"github.com/SigNoz/signoz/pkg/types/dashboardtypes"
 )
 
-type Compiled struct {
-	SQL  string
-	Args []any
-}
-
-func (c Compiled) IsEmpty() bool {
-	return c.SQL == ""
-}
-
-// Compile always returns a non-nil *Compiled. An empty query (or one that
-// produces no SQL) yields a Compiled with an empty SQL — callers gate on
-// SQL != "" rather than a nil check.
-//
-// A `key OP value` term compiles to a DSL predicate; a bare word is a
-// case-insensitive substring search over the dashboard name, description, and tag
-// keys/values. They compose through AND/OR/NOT, so `prod payment` matches both
-// words (implicit AND) and `prod OR name = 'x'` mixes free text with a filter. A
-// quoted token matches literally, e.g. `"prod payment"`.
-func Compile(query string, formatter sqlstore.SQLFormatter) (*Compiled, error) {
-	if len(strings.TrimSpace(query)) == 0 {
-		return &Compiled{}, nil
-	}
-
-	sql, args, errs := newVisitor(formatter).compile(query)
+// Compile wraps compiler errors in the dashboard list filter error code.
+func Compile(query string, formatter sqlstore.SQLFormatter) (*sqlcompiler.Compiled, error) {
+	compiled, errs := sqlcompiler.Compile(query, formatter, dashboardFieldResolver{})
 	if len(errs) > 0 {
 		return nil, errors.NewInvalidInputf(dashboardtypes.ErrCodeDashboardListFilterInvalid,
 			"invalid filter query: %s", strings.Join(errs, "; "))
 	}
-
-	return &Compiled{
-		SQL:  sql,
-		Args: args,
-	}, nil
+	return compiled, nil
 }

pkg/modules/dashboard/impldashboard/listfilter_resolver.go

@@ -0,0 +1,125 @@
+package impldashboard
+
+import (
+	"strings"
+
+	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
+	"github.com/SigNoz/signoz/pkg/parser/filterquery/sqlcompiler"
+	"github.com/SigNoz/signoz/pkg/types/dashboardtypes"
+	qbtypesv5 "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	sqlbuilder "github.com/huandu/go-sqlbuilder"
+)
+
+// dashboardFieldResolver maps dashboard list DSL keys; a non-reserved key is a tag key matched case-insensitively.
+type dashboardFieldResolver struct{}
+
+func (r dashboardFieldResolver) ResolveComparison(v *sqlcompiler.Visitor, rawKey string, operation qbtypesv5.FilterOperator, ctx *grammar.ComparisonContext) string {
+	key := strings.ToLower(rawKey)
+
+	if allowedOperations, isReserved := dashboardtypes.ReservedOps[dashboardtypes.DSLKey(key)]; isReserved {
+		return r.resolveReservedKey(v, ctx, operation, dashboardtypes.DSLKey(key), allowedOperations)
+	}
+
+	if _, allowed := dashboardtypes.TagKeyOps[operation]; !allowed {
+		v.AddError("operator %s is not allowed on a tag-key filter", sqlcompiler.OperationName(operation))
+		return ""
+	}
+	return r.tagComparison(v, ctx, operation, key)
+}
+
+func (r dashboardFieldResolver) resolveReservedKey(v *sqlcompiler.Visitor, ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, key dashboardtypes.DSLKey, allowedOperations map[qbtypesv5.FilterOperator]struct{}) string {
+	if _, allowed := allowedOperations[operation]; !allowed {
+		v.AddError("operator %s is not allowed for key %q", sqlcompiler.OperationName(operation), key)
+		return ""
+	}
+	switch key {
+	case dashboardtypes.DSLKeyName:
+		columnExpression := string(v.Formatter().JSONExtractString("dashboard.data", "$.spec.display.name"))
+		return v.StringOperation(v.SelectBuilder(), ctx, operation, columnExpression, string(key))
+	case dashboardtypes.DSLKeyDescription:
+		columnExpression := string(v.Formatter().JSONExtractString("dashboard.data", "$.spec.display.description"))
+		return v.StringOperation(v.SelectBuilder(), ctx, operation, columnExpression, string(key))
+	case dashboardtypes.DSLKeyCreatedAt:
+		return v.TimestampComparison(ctx, operation, "dashboard.created_at")
+	case dashboardtypes.DSLKeyUpdatedAt:
+		return v.TimestampComparison(ctx, operation, "dashboard.updated_at")
+	case dashboardtypes.DSLKeyCreatedBy:
+		return v.StringOperation(v.SelectBuilder(), ctx, operation, "dashboard.created_by", string(key))
+	case dashboardtypes.DSLKeyLocked:
+		return v.BoolComparison(ctx, operation, "dashboard.locked")
+	}
+	v.AddError("no handler for reserved key %q", key)
+	return ""
+}
+
+func (dashboardFieldResolver) tagComparison(v *sqlcompiler.Visitor, ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, tagKey string) string {
+	subqueryBuilder := sqlbuilder.NewSelectBuilder()
+
+	if operation == qbtypesv5.FilterOperatorExists || operation == qbtypesv5.FilterOperatorNotExists {
+		buildSubqueryForTagKey(subqueryBuilder, tagKey)
+	} else {
+		// Value predicates take the positive operator; negation toggles the EXISTS wrapper.
+		positiveOperation := operation
+		if operation.IsNegativeOperator() {
+			positiveOperation = operation.Inverse()
+		}
+		valuePredicate := v.StringOperation(subqueryBuilder, ctx, positiveOperation, "t.value", tagKey)
+		if valuePredicate == "" {
+			return ""
+		}
+		buildSubqueryForTagKeyAndValue(subqueryBuilder, tagKey, valuePredicate)
+	}
+
+	if operation.IsNegativeOperator() {
+		return v.SelectBuilder().NotExists(subqueryBuilder)
+	}
+	return v.SelectBuilder().Exists(subqueryBuilder)
+}
+
+func buildSubqueryForTagKey(subqueryBuilder *sqlbuilder.SelectBuilder, tagKey string) *sqlbuilder.SelectBuilder {
+	const dashboardTagKind = `"dashboard"`
+
+	return subqueryBuilder.
+		Select("1").
+		From("tag_relation tr").
+		Join("tag t", "t.id = tr.tag_id").
+		Where(
+			subqueryBuilder.Equal("tr.kind", dashboardTagKind),
+			"tr.resource_id = dashboard.id",
+			"LOWER(t.key) = LOWER("+subqueryBuilder.Var(tagKey)+")",
+		)
+}
+
+func buildSubqueryForTagKeyAndValue(subqueryBuilder *sqlbuilder.SelectBuilder, tagKey, valuePredicate string) *sqlbuilder.SelectBuilder {
+	return buildSubqueryForTagKey(subqueryBuilder, tagKey).Where(valuePredicate)
+}
+
+// FreeText searches name, description and tag keys/values.
+func (dashboardFieldResolver) FreeText(v *sqlcompiler.Visitor, value string) string {
+	nameColumn := string(v.Formatter().JSONExtractString("dashboard.data", "$.spec.display.name"))
+	descriptionColumn := string(v.Formatter().JSONExtractString("dashboard.data", "$.spec.display.description"))
+	namePredicate := v.FreeTextContains(v.SelectBuilder(), nameColumn, value)
+	descriptionPredicate := v.FreeTextContains(v.SelectBuilder(), descriptionColumn, value)
+
+	subqueryBuilder := sqlbuilder.NewSelectBuilder()
+	keyPredicate := v.FreeTextContains(subqueryBuilder, "t.key", value)
+	valuePredicate := v.FreeTextContains(subqueryBuilder, "t.value", value)
+	buildSubqueryForFreeTextTag(subqueryBuilder, keyPredicate, valuePredicate)
+	tagPredicate := v.SelectBuilder().Exists(subqueryBuilder)
+
+	return v.SelectBuilder().Or(namePredicate, descriptionPredicate, tagPredicate)
+}
+
+func buildSubqueryForFreeTextTag(subqueryBuilder *sqlbuilder.SelectBuilder, keyPredicate, valuePredicate string) *sqlbuilder.SelectBuilder {
+	const dashboardTagKind = `"dashboard"`
+
+	return subqueryBuilder.
+		Select("1").
+		From("tag_relation tr").
+		Join("tag t", "t.id = tr.tag_id").
+		Where(
+			subqueryBuilder.Equal("tr.kind", dashboardTagKind),
+			"tr.resource_id = dashboard.id",
+			subqueryBuilder.Or(keyPredicate, valuePredicate),
+		)
+}

pkg/modules/dashboard/impldashboard/listfilter_test.go

@@ -559,6 +559,11 @@ func TestCompile_Rejections(t *testing.T) {
 			dslQueryToCompile:        `created_at >= 'not-a-date'`,
 			expectedErrShouldContain: "RFC3339",
 		},
+		{
+			subtestName:              "rejects LIKE pattern ending in an unescaped backslash",
+			dslQueryToCompile:        `name LIKE 'prod\\'`,
+			expectedErrShouldContain: "must not end with an unescaped backslash",
+		},
 		{
 			subtestName:              "rejects REGEXP — not yet supported",
 			dslQueryToCompile:        `name REGEXP '.*'`,
@@ -573,7 +578,7 @@ func TestCompile_Rejections(t *testing.T) {
 }
 
 // Every key in dashboardtypes.ReservedOps must have a matching case in
-// visitComparisonForReservedKeys; a key that's reserved but unhandled falls
+// resolveReservedKey; a key that's reserved but unhandled falls
 // through to the "no handler for reserved key" error. Equal is accepted by all
 // reserved keys, so `key = 'x'` always reaches the dispatch switch — a missing
 // handler surfaces as that error regardless of whether the value type-checks.
@@ -583,7 +588,7 @@ func TestCompileReservedKeysAllHandled(t *testing.T) {
 			_, err := Compile(string(key)+` = 'x'`, formatter(t))
 			if err != nil {
 				assert.NotContains(t, err.Error(), "no handler for reserved key",
-					"reserved key %q has no handler in visitComparisonForReservedKeys", key)
+					"reserved key %q has no handler in resolveReservedKey", key)
 			}
 		})
 	}

pkg/modules/dashboard/impldashboard/listfilter_visitor.go

@@ -1,631 +0,0 @@
-package impldashboard
-
-import (
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/SigNoz/signoz/pkg/parser/filterquery"
-	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
-	"github.com/SigNoz/signoz/pkg/sqlstore"
-	"github.com/SigNoz/signoz/pkg/types/dashboardtypes"
-	qbtypesv5 "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
-	"github.com/antlr4-go/antlr/v4"
-	sqlbuilder "github.com/huandu/go-sqlbuilder"
-)
-
-// bunPlaceholderFlavor is any flavor that renders `?` placeholders, which bun
-// re-binds to the actual backend (e.g. `$1` for Postgres) at query time.
-const bunPlaceholderFlavor = sqlbuilder.SQLite
-
-type visitor struct {
-	grammar.BaseFilterQueryVisitor
-	selectBuilder *sqlbuilder.SelectBuilder
-	formatter     sqlstore.SQLFormatter
-	errors        []string
-}
-
-func newVisitor(formatter sqlstore.SQLFormatter) *visitor {
-	return &visitor{
-		selectBuilder: sqlbuilder.NewSelectBuilder(),
-		formatter:     formatter,
-	}
-}
-
-// compile builds `?`-placeholder WHERE SQL + args for bun. Each term is either a
-// `key OP value` comparison or a bare token that becomes a free-text search; the
-// two compose through the boolean grammar (AND/OR/NOT). Malformed input is
-// returned as errors.
-func (v *visitor) compile(query string) (string, []any, []string) {
-	tree, _, collector := filterquery.Parse(query)
-	if len(collector.Errors) > 0 {
-		return "", nil, collector.Errors
-	}
-	condition, _ := v.visit(tree).(string)
-	if len(v.errors) > 0 {
-		return "", nil, v.errors
-	}
-	if condition == "" {
-		return "", nil, nil
-	}
-	sql, arguments := v.selectBuilder.Args.CompileWithFlavor(condition, bunPlaceholderFlavor)
-	return sql, arguments, nil
-}
-
-func (v *visitor) visit(tree antlr.ParseTree) any {
-	if tree == nil {
-		return nil
-	}
-	return tree.Accept(v)
-}
-
-// ════════════════════════════════════════════════════════════════════════
-// methods from grammar.BaseFilterQueryVisitor that are overridden
-// ════════════════════════════════════════════════════════════════════════
-
-func (v *visitor) VisitQuery(ctx *grammar.QueryContext) any {
-	return v.visit(ctx.Expression())
-}
-
-func (v *visitor) VisitExpression(ctx *grammar.ExpressionContext) any {
-	return v.visit(ctx.OrExpression())
-}
-
-func (v *visitor) VisitOrExpression(ctx *grammar.OrExpressionContext) any {
-	parts := ctx.AllAndExpression()
-	conditions := make([]string, 0, len(parts))
-	for _, part := range parts {
-		if condition, ok := v.visit(part).(string); ok && condition != "" {
-			conditions = append(conditions, condition)
-		}
-	}
-	switch len(conditions) {
-	case 0:
-		return ""
-	case 1:
-		return conditions[0]
-	default:
-		return v.selectBuilder.Or(conditions...)
-	}
-}
-
-func (v *visitor) VisitAndExpression(ctx *grammar.AndExpressionContext) any {
-	parts := ctx.AllUnaryExpression()
-	conditions := make([]string, 0, len(parts))
-	for _, part := range parts {
-		if condition, ok := v.visit(part).(string); ok && condition != "" {
-			conditions = append(conditions, condition)
-		}
-	}
-	switch len(conditions) {
-	case 0:
-		return ""
-	case 1:
-		return conditions[0]
-	default:
-		return v.selectBuilder.And(conditions...)
-	}
-}
-
-func (v *visitor) VisitUnaryExpression(ctx *grammar.UnaryExpressionContext) any {
-	condition, _ := v.visit(ctx.Primary()).(string)
-	if condition == "" {
-		return ""
-	}
-	if ctx.NOT() != nil {
-		return fmt.Sprintf("NOT (%s)", condition)
-	}
-	return condition
-}
-
-func (v *visitor) VisitPrimary(ctx *grammar.PrimaryContext) any {
-	if ctx.OrExpression() != nil {
-		return v.visit(ctx.OrExpression())
-	}
-	if ctx.Comparison() != nil {
-		return v.visit(ctx.Comparison())
-	}
-	// A lone key/value/full-text token is a free-text term, composed with any
-	// comparisons through the boolean grammar. A quoted token matches its contents
-	// literally — the escape hatch for a phrase or a term that looks like DSL.
-	return v.buildFreeTextTerm(trimQuotes(ctx.GetText()))
-}
-
-// VisitComparison dispatches a single `key OP value` term. A key that matches
-// a reserved DSL key (name, description, etc.) becomes a column-level
-// predicate; any other identifier is treated as a tag key — the operator
-// applies to the tag's value, with a case-insensitive match on the tag's key.
-func (v *visitor) VisitComparison(ctx *grammar.ComparisonContext) any {
-	key := strings.ToLower(strings.TrimSpace(ctx.Key().GetText()))
-
-	operation, ok := v.extractOperation(ctx)
-	if !ok {
-		return ""
-	}
-
-	if allowedOperations, isReserved := dashboardtypes.ReservedOps[dashboardtypes.DSLKey(key)]; isReserved {
-		return v.visitComparisonForReservedKeys(ctx, operation, dashboardtypes.DSLKey(key), allowedOperations)
-	}
-	return v.visitComparisonForTags(ctx, operation, key)
-}
-
-func (v *visitor) visitComparisonForReservedKeys(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, key dashboardtypes.DSLKey, allowedOperations map[qbtypesv5.FilterOperator]struct{}) string {
-	if _, allowed := allowedOperations[operation]; !allowed {
-		v.addError("operator %s is not allowed for key %q", operationName(operation), key)
-		return ""
-	}
-	switch key {
-	case dashboardtypes.DSLKeyName:
-		return v.buildJSONStringComparison(ctx, operation, dashboardtypes.DSLKeyName, "$.spec.display.name")
-	case dashboardtypes.DSLKeyDescription:
-		return v.buildJSONStringComparison(ctx, operation, dashboardtypes.DSLKeyDescription, "$.spec.display.description")
-	case dashboardtypes.DSLKeyCreatedAt:
-		return v.buildTimestampComparison(ctx, operation, "dashboard.created_at")
-	case dashboardtypes.DSLKeyUpdatedAt:
-		return v.buildTimestampComparison(ctx, operation, "dashboard.updated_at")
-	case dashboardtypes.DSLKeyCreatedBy:
-		return v.buildStringComparison(ctx, operation, dashboardtypes.DSLKeyCreatedBy, "dashboard.created_by")
-	case dashboardtypes.DSLKeyLocked:
-		return v.buildBoolComparison(ctx, operation, "dashboard.locked")
-	}
-	// Unreachable for real input: every dashboardtypes.ReservedOps key has a case above, and
-	// TestCompileReservedKeysAllHandled guards that the two stay in sync.
-	v.addError("no handler for reserved key %q", key)
-	return ""
-}
-
-func (v *visitor) visitComparisonForTags(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, tagKey string) string {
-	if _, allowed := dashboardtypes.TagKeyOps[operation]; !allowed {
-		v.addError("operator %s is not allowed on a tag-key filter", operationName(operation))
-		return ""
-	}
-	return v.buildTagComparison(ctx, operation, tagKey)
-}
-
-func (v *visitor) extractOperation(ctx *grammar.ComparisonContext) (qbtypesv5.FilterOperator, bool) {
-	// For operators that take an optional leading NOT, Inverse() maps each to
-	// its Not<X> counterpart.
-	maybeNot := func(operation qbtypesv5.FilterOperator) qbtypesv5.FilterOperator {
-		if ctx.NOT() != nil {
-			return operation.Inverse()
-		}
-		return operation
-	}
-	switch {
-	case ctx.EQUALS() != nil:
-		return qbtypesv5.FilterOperatorEqual, true
-	case ctx.NOT_EQUALS() != nil, ctx.NEQ() != nil:
-		return qbtypesv5.FilterOperatorNotEqual, true
-	case ctx.LT() != nil:
-		return qbtypesv5.FilterOperatorLessThan, true
-	case ctx.LE() != nil:
-		return qbtypesv5.FilterOperatorLessThanOrEq, true
-	case ctx.GT() != nil:
-		return qbtypesv5.FilterOperatorGreaterThan, true
-	case ctx.GE() != nil:
-		return qbtypesv5.FilterOperatorGreaterThanOrEq, true
-	case ctx.BETWEEN() != nil:
-		return maybeNot(qbtypesv5.FilterOperatorBetween), true
-	case ctx.LIKE() != nil:
-		return maybeNot(qbtypesv5.FilterOperatorLike), true
-	case ctx.ILIKE() != nil:
-		return maybeNot(qbtypesv5.FilterOperatorILike), true
-	case ctx.CONTAINS() != nil:
-		return maybeNot(qbtypesv5.FilterOperatorContains), true
-	case ctx.REGEXP() != nil:
-		return maybeNot(qbtypesv5.FilterOperatorRegexp), true
-	case ctx.InClause() != nil:
-		return qbtypesv5.FilterOperatorIn, true
-	case ctx.NotInClause() != nil:
-		return qbtypesv5.FilterOperatorNotIn, true
-	case ctx.EXISTS() != nil:
-		return maybeNot(qbtypesv5.FilterOperatorExists), true
-	}
-	v.addError("could not determine operator in expression %q", ctx.GetText())
-	return qbtypesv5.FilterOperatorUnknown, false
-}
-
-// ─── per-key emitters ────────────────────────────────────────────────────────
-
-func (v *visitor) buildJSONStringComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, key dashboardtypes.DSLKey, jsonPath string) string {
-	columnExpression := string(v.formatter.JSONExtractString("dashboard.data", jsonPath))
-	return v.buildStringOperation(v.selectBuilder, ctx, operation, columnExpression, string(key))
-}
-
-func (v *visitor) buildStringComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, key dashboardtypes.DSLKey, columnExpression string) string {
-	return v.buildStringOperation(v.selectBuilder, ctx, operation, columnExpression, string(key))
-}
-
-// buildStringOperation covers all the operators the spec allows on text-shaped keys
-// (name, description, created_by, and a tag's value). Placeholders are interned
-// into builder — the outer builder for column predicates, the subquery builder for
-// tag-value predicates — so nested EXISTS arguments thread correctly.
-func (v *visitor) buildStringOperation(builder *sqlbuilder.SelectBuilder, ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, columnExpression, keyForError string) string {
-	switch operation {
-	case qbtypesv5.FilterOperatorEqual:
-		val, ok := v.extractSingleStringValue(ctx, keyForError)
-		if !ok {
-			return ""
-		}
-		return builder.Equal(columnExpression, val)
-	case qbtypesv5.FilterOperatorNotEqual:
-		val, ok := v.extractSingleStringValue(ctx, keyForError)
-		if !ok {
-			return ""
-		}
-		return builder.NotEqual(columnExpression, val)
-	case qbtypesv5.FilterOperatorLike, qbtypesv5.FilterOperatorNotLike:
-		val, ok := v.extractSingleStringValue(ctx, keyForError)
-		if !ok {
-			return ""
-		}
-		like := "LIKE"
-		if operation == qbtypesv5.FilterOperatorNotLike {
-			like = "NOT LIKE"
-		}
-		// The user's % and _ stay as wildcards; ESCAPE pins backslash as the escape
-		// char so a literal `\` in the pattern is read the same on both dialects —
-		// Postgres defaults to `\`, SQLite has no default escape.
-		return fmt.Sprintf("%s %s %s ESCAPE '\\'", columnExpression, like, builder.Var(val))
-	case qbtypesv5.FilterOperatorILike, qbtypesv5.FilterOperatorNotILike:
-		val, ok := v.extractSingleStringValue(ctx, keyForError)
-		if !ok {
-			return ""
-		}
-		// SQLite has no ILIKE keyword and Postgres LIKE is case-sensitive — emit
-		// LOWER(col) LIKE LOWER(?) so behavior is identical on both dialects. ESCAPE
-		// pins backslash as the escape char (Postgres default; SQLite has none).
-		lowerColumn := string(v.formatter.LowerExpression(columnExpression))
-		like := "LIKE"
-		if operation == qbtypesv5.FilterOperatorNotILike {
-			like = "NOT LIKE"
-		}
-		return fmt.Sprintf("%s %s LOWER(%s) ESCAPE '\\'", lowerColumn, like, builder.Var(val))
-	case qbtypesv5.FilterOperatorContains, qbtypesv5.FilterOperatorNotContains:
-		val, ok := v.extractSingleStringValue(ctx, keyForError)
-		if !ok {
-			return ""
-		}
-		like := "LIKE"
-		if operation == qbtypesv5.FilterOperatorNotContains {
-			like = "NOT LIKE"
-		}
-		// Escape the user's % and _ so they match literally, then wrap in wildcards.
-		// ESCAPE declares the backslash the escaper injected as the escape char —
-		// needed on SQLite (no default) and a harmless restatement of the Postgres default.
-		escaped := v.formatter.EscapeLikePattern(val)
-		return fmt.Sprintf("%s %s %s ESCAPE '\\'", columnExpression, like, builder.Var("%"+escaped+"%"))
-	case qbtypesv5.FilterOperatorRegexp, qbtypesv5.FilterOperatorNotRegexp:
-		v.addError("REGEXP filtering on %q is not yet supported", keyForError)
-		return ""
-	case qbtypesv5.FilterOperatorIn, qbtypesv5.FilterOperatorNotIn:
-		values, ok := v.extractStringValueList(ctx, keyForError)
-		if !ok {
-			return ""
-		}
-		arguments := make([]any, len(values))
-		for i, s := range values {
-			arguments[i] = s
-		}
-		if operation == qbtypesv5.FilterOperatorNotIn {
-			return builder.NotIn(columnExpression, arguments...)
-		}
-		return builder.In(columnExpression, arguments...)
-	}
-	v.addError("operator %s on %q is not implemented", operationName(operation), keyForError)
-	return ""
-}
-
-func (v *visitor) buildTimestampComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, columnExpression string) string {
-	switch operation {
-	case qbtypesv5.FilterOperatorEqual, qbtypesv5.FilterOperatorNotEqual,
-		qbtypesv5.FilterOperatorLessThan, qbtypesv5.FilterOperatorLessThanOrEq,
-		qbtypesv5.FilterOperatorGreaterThan, qbtypesv5.FilterOperatorGreaterThanOrEq:
-		t, ok := v.extractSingleTimestampValue(ctx)
-		if !ok {
-			return ""
-		}
-		switch operation {
-		case qbtypesv5.FilterOperatorEqual:
-			return v.selectBuilder.Equal(columnExpression, t)
-		case qbtypesv5.FilterOperatorNotEqual:
-			return v.selectBuilder.NotEqual(columnExpression, t)
-		case qbtypesv5.FilterOperatorLessThan:
-			return v.selectBuilder.LessThan(columnExpression, t)
-		case qbtypesv5.FilterOperatorLessThanOrEq:
-			return v.selectBuilder.LessEqualThan(columnExpression, t)
-		case qbtypesv5.FilterOperatorGreaterThan:
-			return v.selectBuilder.GreaterThan(columnExpression, t)
-		case qbtypesv5.FilterOperatorGreaterThanOrEq:
-			return v.selectBuilder.GreaterEqualThan(columnExpression, t)
-		}
-	case qbtypesv5.FilterOperatorBetween, qbtypesv5.FilterOperatorNotBetween:
-		timestamps, ok := v.extractTwoTimestampValues(ctx)
-		if !ok {
-			return ""
-		}
-		if operation == qbtypesv5.FilterOperatorNotBetween {
-			return v.selectBuilder.NotBetween(columnExpression, timestamps[0], timestamps[1])
-		}
-		return v.selectBuilder.Between(columnExpression, timestamps[0], timestamps[1])
-	}
-	v.addError("operator %s on timestamp is not implemented", operationName(operation))
-	return ""
-}
-
-func (v *visitor) buildBoolComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, columnExpression string) string {
-	b, ok := v.extractSingleBoolValue(ctx)
-	if !ok {
-		return ""
-	}
-	if operation == qbtypesv5.FilterOperatorNotEqual {
-		return v.selectBuilder.NotEqual(columnExpression, b)
-	}
-	return v.selectBuilder.Equal(columnExpression, b)
-}
-
-func (v *visitor) buildTagComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, tagKey string) string {
-	subqueryBuilder := sqlbuilder.NewSelectBuilder()
-
-	if operation == qbtypesv5.FilterOperatorExists || operation == qbtypesv5.FilterOperatorNotExists {
-		buildSubqueryForTagKey(subqueryBuilder, tagKey)
-	} else {
-		// All other tag operators take the positive form of the value predicate
-		// and toggle the EXISTS wrapper for negation. Inverse() flips Not<X> → <X>.
-		positiveOperation := operation
-		if operation.IsNegativeOperator() {
-			positiveOperation = operation.Inverse()
-		}
-		valuePredicate := v.buildStringOperation(subqueryBuilder, ctx, positiveOperation, "t.value", tagKey)
-		if valuePredicate == "" {
-			return ""
-		}
-		buildSubqueryForTagKeyAndValue(subqueryBuilder, tagKey, valuePredicate)
-	}
-
-	if operation.IsNegativeOperator() {
-		return v.selectBuilder.NotExists(subqueryBuilder)
-	}
-	return v.selectBuilder.Exists(subqueryBuilder)
-}
-
-func buildSubqueryForTagKey(subqueryBuilder *sqlbuilder.SelectBuilder, tagKey string) *sqlbuilder.SelectBuilder {
-	const dashboardTagKind = `"dashboard"`
-
-	return subqueryBuilder.
-		Select("1").
-		From("tag_relation tr").
-		Join("tag t", "t.id = tr.tag_id").
-		Where(
-			subqueryBuilder.Equal("tr.kind", dashboardTagKind),
-			"tr.resource_id = dashboard.id",
-			"LOWER(t.key) = LOWER("+subqueryBuilder.Var(tagKey)+")",
-		)
-}
-
-func buildSubqueryForTagKeyAndValue(subqueryBuilder *sqlbuilder.SelectBuilder, tagKey, valuePredicate string) *sqlbuilder.SelectBuilder {
-	return buildSubqueryForTagKey(subqueryBuilder, tagKey).Where(valuePredicate)
-}
-
-// ─── free-text search ────────────────────────────────────────────────────────
-
-// buildFreeTextTerm matches value as a case-insensitive substring of the
-// dashboard name, description, or any tag key/value.
-func (v *visitor) buildFreeTextTerm(value string) string {
-	nameColumn := string(v.formatter.JSONExtractString("dashboard.data", "$.spec.display.name"))
-	descriptionColumn := string(v.formatter.JSONExtractString("dashboard.data", "$.spec.display.description"))
-	namePredicate := v.buildFreeTextContains(v.selectBuilder, nameColumn, value)
-	descriptionPredicate := v.buildFreeTextContains(v.selectBuilder, descriptionColumn, value)
-
-	subqueryBuilder := sqlbuilder.NewSelectBuilder()
-	keyPredicate := v.buildFreeTextContains(subqueryBuilder, "t.key", value)
-	valuePredicate := v.buildFreeTextContains(subqueryBuilder, "t.value", value)
-	buildSubqueryForFreeTextTag(subqueryBuilder, keyPredicate, valuePredicate)
-	tagPredicate := v.selectBuilder.Exists(subqueryBuilder)
-
-	return v.selectBuilder.Or(namePredicate, descriptionPredicate, tagPredicate)
-}
-
-// buildFreeTextContains emits a case-insensitive contains as
-// LOWER(COALESCE(col, '')) LIKE LOWER(?), identical on SQLite and Postgres.
-// COALESCE keeps a NULL column (an absent description) false rather than NULL —
-// otherwise `NOT (…)` goes NULL and drops every description-less dashboard. The
-// value's % and _ are escaped, and ESCAPE pins backslash as the escape char.
-func (v *visitor) buildFreeTextContains(builder *sqlbuilder.SelectBuilder, columnExpression, value string) string {
-	lowerColumn := string(v.formatter.LowerExpression("COALESCE(" + columnExpression + ", '')"))
-	pattern := "%" + v.formatter.EscapeLikePattern(value) + "%"
-	return fmt.Sprintf("%s LIKE LOWER(%s) ESCAPE '\\'", lowerColumn, builder.Var(pattern))
-}
-
-func buildSubqueryForFreeTextTag(subqueryBuilder *sqlbuilder.SelectBuilder, keyPredicate, valuePredicate string) *sqlbuilder.SelectBuilder {
-	const dashboardTagKind = `"dashboard"`
-
-	return subqueryBuilder.
-		Select("1").
-		From("tag_relation tr").
-		Join("tag t", "t.id = tr.tag_id").
-		Where(
-			subqueryBuilder.Equal("tr.kind", dashboardTagKind),
-			"tr.resource_id = dashboard.id",
-			subqueryBuilder.Or(keyPredicate, valuePredicate),
-		)
-}
-
-// ─── value extraction helpers ───────────────────────────────────────────────
-
-func (v *visitor) addError(format string, arguments ...any) {
-	v.errors = append(v.errors, fmt.Sprintf(format, arguments...))
-}
-
-func (v *visitor) extractSingleStringValue(ctx *grammar.ComparisonContext, keyForError string) (string, bool) {
-	values := ctx.AllValue()
-	if len(values) != 1 {
-		v.addError("expected exactly one value for %q", keyForError)
-		return "", false
-	}
-	return v.extractStringValue(values[0], keyForError)
-}
-
-func (v *visitor) extractSingleBoolValue(ctx *grammar.ComparisonContext) (bool, bool) {
-	values := ctx.AllValue()
-	if len(values) != 1 {
-		v.addError("expected a single boolean (true/false)")
-		return false, false
-	}
-	return v.extractBoolValue(values[0])
-}
-
-func (v *visitor) extractSingleTimestampValue(ctx *grammar.ComparisonContext) (time.Time, bool) {
-	values := ctx.AllValue()
-	if len(values) != 1 {
-		v.addError("expected a single RFC3339 timestamp")
-		return time.Time{}, false
-	}
-	return v.extractTimestampValue(values[0])
-}
-
-func (v *visitor) extractTwoTimestampValues(ctx *grammar.ComparisonContext) ([2]time.Time, bool) {
-	values := ctx.AllValue()
-	if len(values) != 2 {
-		v.addError("BETWEEN expects two RFC3339 timestamps")
-		return [2]time.Time{}, false
-	}
-	a, ok1 := v.extractTimestampValue(values[0])
-	b, ok2 := v.extractTimestampValue(values[1])
-	if !ok1 || !ok2 {
-		return [2]time.Time{}, false
-	}
-	return [2]time.Time{a, b}, true
-}
-
-func (v *visitor) extractStringValueList(ctx *grammar.ComparisonContext, keyForError string) ([]string, bool) {
-	var valuesCtx []grammar.IValueContext
-	switch {
-	case ctx.InClause() != nil:
-		inClause := ctx.InClause()
-		if inClause.ValueList() != nil {
-			valuesCtx = inClause.ValueList().AllValue()
-		} else {
-			valuesCtx = []grammar.IValueContext{inClause.Value()}
-		}
-	case ctx.NotInClause() != nil:
-		notInClause := ctx.NotInClause()
-		if notInClause.ValueList() != nil {
-			valuesCtx = notInClause.ValueList().AllValue()
-		} else {
-			valuesCtx = []grammar.IValueContext{notInClause.Value()}
-		}
-	default:
-		v.addError("IN clause is missing for %q", keyForError)
-		return nil, false
-	}
-	if len(valuesCtx) == 0 {
-		v.addError("IN list for %q is empty", keyForError)
-		return nil, false
-	}
-	out := make([]string, 0, len(valuesCtx))
-	for _, valueContext := range valuesCtx {
-		s, ok := v.extractStringValue(valueContext, keyForError)
-		if !ok {
-			return nil, false
-		}
-		out = append(out, s)
-	}
-	return out, true
-}
-
-func (v *visitor) extractStringValue(ctx grammar.IValueContext, keyForError string) (string, bool) {
-	if ctx.QUOTED_TEXT() != nil {
-		return trimQuotes(ctx.QUOTED_TEXT().GetText()), true
-	}
-	if ctx.KEY() != nil {
-		// Bare tokens are accepted as strings, mirroring the FilterQuery lexer's
-		// treatment of unquoted identifiers on the value side.
-		return ctx.KEY().GetText(), true
-	}
-	v.addError("expected a string value for %q, got %q", keyForError, ctx.GetText())
-	return "", false
-}
-
-func (v *visitor) extractBoolValue(ctx grammar.IValueContext) (bool, bool) {
-	if ctx.BOOL() == nil {
-		v.addError("expected a boolean (true/false), got %q", ctx.GetText())
-		return false, false
-	}
-	return strings.EqualFold(ctx.BOOL().GetText(), "true"), true
-}
-
-func (v *visitor) extractTimestampValue(ctx grammar.IValueContext) (time.Time, bool) {
-	if ctx.QUOTED_TEXT() == nil {
-		v.addError("expected an RFC3339 timestamp string, got %q", ctx.GetText())
-		return time.Time{}, false
-	}
-	raw := trimQuotes(ctx.QUOTED_TEXT().GetText())
-	t, err := time.Parse(time.RFC3339, raw)
-	if err != nil {
-		v.addError("invalid RFC3339 timestamp %q: %s", raw, err.Error())
-		return time.Time{}, false
-	}
-	return t, true
-}
-
-// ─── operator spelling ───────────────────────────────────────────────────────
-
-// operationName returns the user-facing spelling of a FilterOperator, used only in
-// error messages — go-sqlbuilder's Cond helpers emit the SQL keywords.
-func operationName(operation qbtypesv5.FilterOperator) string {
-	switch operation {
-	case qbtypesv5.FilterOperatorEqual:
-		return "="
-	case qbtypesv5.FilterOperatorNotEqual:
-		return "!="
-	case qbtypesv5.FilterOperatorLessThan:
-		return "<"
-	case qbtypesv5.FilterOperatorLessThanOrEq:
-		return "<="
-	case qbtypesv5.FilterOperatorGreaterThan:
-		return ">"
-	case qbtypesv5.FilterOperatorGreaterThanOrEq:
-		return ">="
-	case qbtypesv5.FilterOperatorBetween:
-		return "BETWEEN"
-	case qbtypesv5.FilterOperatorNotBetween:
-		return "NOT BETWEEN"
-	case qbtypesv5.FilterOperatorLike:
-		return "LIKE"
-	case qbtypesv5.FilterOperatorNotLike:
-		return "NOT LIKE"
-	case qbtypesv5.FilterOperatorILike:
-		return "ILIKE"
-	case qbtypesv5.FilterOperatorNotILike:
-		return "NOT ILIKE"
-	case qbtypesv5.FilterOperatorContains:
-		return "CONTAINS"
-	case qbtypesv5.FilterOperatorNotContains:
-		return "NOT CONTAINS"
-	case qbtypesv5.FilterOperatorRegexp:
-		return "REGEXP"
-	case qbtypesv5.FilterOperatorNotRegexp:
-		return "NOT REGEXP"
-	case qbtypesv5.FilterOperatorIn:
-		return "IN"
-	case qbtypesv5.FilterOperatorNotIn:
-		return "NOT IN"
-	case qbtypesv5.FilterOperatorExists:
-		return "EXISTS"
-	case qbtypesv5.FilterOperatorNotExists:
-		return "NOT EXISTS"
-	}
-	return "?"
-}
-
-func trimQuotes(s string) string {
-	if len(s) >= 2 {
-		if (s[0] == '"' && s[len(s)-1] == '"') || (s[0] == '\'' && s[len(s)-1] == '\'') {
-			s = s[1 : len(s)-1]
-		}
-	}
-	s = strings.ReplaceAll(s, `\\`, `\`)
-	s = strings.ReplaceAll(s, `\'`, `'`)
-	return s
-}

pkg/parser/filterquery/sqlcompiler/compiler.go

@@ -0,0 +1,516 @@
+// Package sqlcompiler compiles list-page filter queries to relational-store WHERE clauses; telemetry queries stay on querybuilder's ClickHouse visitor.
+package sqlcompiler
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/SigNoz/signoz/pkg/parser/filterquery"
+	grammar "github.com/SigNoz/signoz/pkg/parser/filterquery/grammar"
+	"github.com/SigNoz/signoz/pkg/sqlstore"
+	qbtypesv5 "github.com/SigNoz/signoz/pkg/types/querybuildertypes/querybuildertypesv5"
+	"github.com/antlr4-go/antlr/v4"
+	sqlbuilder "github.com/huandu/go-sqlbuilder"
+)
+
+// bunPlaceholderFlavor is any flavor that renders the `?` placeholders bun expects.
+const bunPlaceholderFlavor = sqlbuilder.SQLite
+
+// FieldResolver is the per-feature policy: which keys exist and what each maps to.
+type FieldResolver interface {
+	// ResolveComparison builds the predicate for one `key OP value` term; key keeps the user's casing.
+	ResolveComparison(v *Visitor, key string, operation qbtypesv5.FilterOperator, ctx *grammar.ComparisonContext) string
+	// FreeText builds the predicate for a bare token.
+	FreeText(v *Visitor, value string) string
+}
+
+// Compiled is a `?`-placeholder WHERE clause with its bun bind args.
+type Compiled struct {
+	SQL  string
+	Args []any
+}
+
+func (c Compiled) IsEmpty() bool {
+	return c.SQL == ""
+}
+
+// Compile on success returns a non-nil *Compiled, empty for an empty query; callers gate on IsEmpty, not nil.
+func Compile(query string, formatter sqlstore.SQLFormatter, resolver FieldResolver) (*Compiled, []string) {
+	if len(strings.TrimSpace(query)) == 0 {
+		return &Compiled{}, nil
+	}
+
+	v := &Visitor{
+		sb:       sqlbuilder.NewSelectBuilder(),
+		fmter:    formatter,
+		resolver: resolver,
+	}
+
+	tree, _, collector := filterquery.Parse(query)
+	if len(collector.Errors) > 0 {
+		return nil, collector.Errors
+	}
+	condition, _ := v.visit(tree).(string)
+	if len(v.errors) > 0 {
+		return nil, v.errors
+	}
+	if condition == "" {
+		return &Compiled{}, nil
+	}
+	sql, arguments := v.sb.Args.CompileWithFlavor(condition, bunPlaceholderFlavor)
+	return &Compiled{SQL: sql, Args: arguments}, nil
+}
+
+// Visitor walks the parse tree and carries the per-compile SQL state; the
+// FieldResolver calls its helpers back to build each predicate.
+type Visitor struct {
+	grammar.BaseFilterQueryVisitor
+	sb       *sqlbuilder.SelectBuilder
+	fmter    sqlstore.SQLFormatter
+	errors   []string
+	resolver FieldResolver
+}
+
+func (v *Visitor) SelectBuilder() *sqlbuilder.SelectBuilder {
+	return v.sb
+}
+
+func (v *Visitor) Formatter() sqlstore.SQLFormatter {
+	return v.fmter
+}
+
+func (v *Visitor) AddError(format string, arguments ...any) {
+	v.errors = append(v.errors, fmt.Sprintf(format, arguments...))
+}
+
+// StringOperation interns placeholders into sb so nested subquery arguments thread correctly.
+func (v *Visitor) StringOperation(sb *sqlbuilder.SelectBuilder, ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, columnExpression, keyForError string) string {
+	switch operation {
+	case qbtypesv5.FilterOperatorEqual:
+		val, ok := v.ExtractSingleStringValue(ctx, keyForError)
+		if !ok {
+			return ""
+		}
+		return sb.Equal(columnExpression, val)
+	case qbtypesv5.FilterOperatorNotEqual:
+		val, ok := v.ExtractSingleStringValue(ctx, keyForError)
+		if !ok {
+			return ""
+		}
+		return sb.NotEqual(columnExpression, val)
+	case qbtypesv5.FilterOperatorLike, qbtypesv5.FilterOperatorNotLike:
+		val, ok := v.ExtractSingleStringValue(ctx, keyForError)
+		if !ok {
+			return ""
+		}
+		if endsWithDanglingEscape(val) {
+			v.AddError("LIKE pattern for %q must not end with an unescaped backslash, use \\\\ to match a literal backslash", keyForError)
+			return ""
+		}
+		like := "LIKE"
+		if operation == qbtypesv5.FilterOperatorNotLike {
+			like = "NOT LIKE"
+		}
+		// ESCAPE pins backslash as the escape char (the Postgres default, SQLite has none).
+		return fmt.Sprintf("%s %s %s ESCAPE '\\'", columnExpression, like, sb.Var(val))
+	case qbtypesv5.FilterOperatorILike, qbtypesv5.FilterOperatorNotILike:
+		val, ok := v.ExtractSingleStringValue(ctx, keyForError)
+		if !ok {
+			return ""
+		}
+		if endsWithDanglingEscape(val) {
+			v.AddError("ILIKE pattern for %q must not end with an unescaped backslash, use \\\\ to match a literal backslash", keyForError)
+			return ""
+		}
+		// SQLite has no ILIKE and Postgres LIKE is case-sensitive, so LOWER both sides.
+		lowerColumn := string(v.fmter.LowerExpression(columnExpression))
+		like := "LIKE"
+		if operation == qbtypesv5.FilterOperatorNotILike {
+			like = "NOT LIKE"
+		}
+		return fmt.Sprintf("%s %s LOWER(%s) ESCAPE '\\'", lowerColumn, like, sb.Var(val))
+	case qbtypesv5.FilterOperatorContains, qbtypesv5.FilterOperatorNotContains:
+		val, ok := v.ExtractSingleStringValue(ctx, keyForError)
+		if !ok {
+			return ""
+		}
+		like := "LIKE"
+		if operation == qbtypesv5.FilterOperatorNotContains {
+			like = "NOT LIKE"
+		}
+		// Escape the user's % and _ so they match literally, then wrap in wildcards.
+		escaped := v.fmter.EscapeLikePattern(val)
+		return fmt.Sprintf("%s %s %s ESCAPE '\\'", columnExpression, like, sb.Var(fmt.Sprintf("%%%s%%", escaped)))
+	case qbtypesv5.FilterOperatorRegexp, qbtypesv5.FilterOperatorNotRegexp:
+		v.AddError("REGEXP filtering on %q is not supported", keyForError)
+		return ""
+	case qbtypesv5.FilterOperatorIn, qbtypesv5.FilterOperatorNotIn:
+		values, ok := v.ExtractStringValueList(ctx, keyForError)
+		if !ok {
+			return ""
+		}
+		arguments := make([]any, len(values))
+		for i, s := range values {
+			arguments[i] = s
+		}
+		if operation == qbtypesv5.FilterOperatorNotIn {
+			return sb.NotIn(columnExpression, arguments...)
+		}
+		return sb.In(columnExpression, arguments...)
+	}
+	v.AddError("operator %s on %q is not implemented", OperationName(operation), keyForError)
+	return ""
+}
+
+func (v *Visitor) TimestampComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, columnExpression string) string {
+	switch operation {
+	case qbtypesv5.FilterOperatorEqual, qbtypesv5.FilterOperatorNotEqual,
+		qbtypesv5.FilterOperatorLessThan, qbtypesv5.FilterOperatorLessThanOrEq,
+		qbtypesv5.FilterOperatorGreaterThan, qbtypesv5.FilterOperatorGreaterThanOrEq:
+		t, ok := v.extractSingleTimestampValue(ctx)
+		if !ok {
+			return ""
+		}
+		switch operation {
+		case qbtypesv5.FilterOperatorEqual:
+			return v.sb.Equal(columnExpression, t)
+		case qbtypesv5.FilterOperatorNotEqual:
+			return v.sb.NotEqual(columnExpression, t)
+		case qbtypesv5.FilterOperatorLessThan:
+			return v.sb.LessThan(columnExpression, t)
+		case qbtypesv5.FilterOperatorLessThanOrEq:
+			return v.sb.LessEqualThan(columnExpression, t)
+		case qbtypesv5.FilterOperatorGreaterThan:
+			return v.sb.GreaterThan(columnExpression, t)
+		case qbtypesv5.FilterOperatorGreaterThanOrEq:
+			return v.sb.GreaterEqualThan(columnExpression, t)
+		}
+	case qbtypesv5.FilterOperatorBetween, qbtypesv5.FilterOperatorNotBetween:
+		timestamps, ok := v.extractTwoTimestampValues(ctx)
+		if !ok {
+			return ""
+		}
+		if operation == qbtypesv5.FilterOperatorNotBetween {
+			return v.sb.NotBetween(columnExpression, timestamps[0], timestamps[1])
+		}
+		return v.sb.Between(columnExpression, timestamps[0], timestamps[1])
+	}
+	v.AddError("operator %s on timestamp is not implemented", OperationName(operation))
+	return ""
+}
+
+func (v *Visitor) BoolComparison(ctx *grammar.ComparisonContext, operation qbtypesv5.FilterOperator, columnExpression string) string {
+	value, ok := v.extractSingleBoolValue(ctx)
+	if !ok {
+		return ""
+	}
+	if operation == qbtypesv5.FilterOperatorNotEqual {
+		return v.sb.NotEqual(columnExpression, value)
+	}
+	return v.sb.Equal(columnExpression, value)
+}
+
+// A pattern ending in an unescaped backslash never matches on sqlite and errors on Postgres.
+func endsWithDanglingEscape(value string) bool {
+	trailing := len(value) - len(strings.TrimRight(value, `\`))
+	return trailing%2 == 1
+}
+
+// FreeTextContains COALESCEs the column so NOT (...) does not go NULL and drop rows where it is absent.
+func (v *Visitor) FreeTextContains(sb *sqlbuilder.SelectBuilder, columnExpression, value string) string {
+	lowerColumn := string(v.fmter.LowerExpression(fmt.Sprintf("COALESCE(%s, '')", columnExpression)))
+	pattern := fmt.Sprintf("%%%s%%", v.fmter.EscapeLikePattern(value))
+	return fmt.Sprintf("%s LIKE LOWER(%s) ESCAPE '\\'", lowerColumn, sb.Var(pattern))
+}
+
+func (v *Visitor) ExtractSingleStringValue(ctx *grammar.ComparisonContext, keyForError string) (string, bool) {
+	values := ctx.AllValue()
+	if len(values) != 1 {
+		v.AddError("expected exactly one value for %q", keyForError)
+		return "", false
+	}
+	return v.extractStringValue(values[0], keyForError)
+}
+
+func (v *Visitor) ExtractStringValueList(ctx *grammar.ComparisonContext, keyForError string) ([]string, bool) {
+	var valuesCtx []grammar.IValueContext
+	switch {
+	case ctx.InClause() != nil:
+		inClause := ctx.InClause()
+		if inClause.ValueList() != nil {
+			valuesCtx = inClause.ValueList().AllValue()
+		} else {
+			valuesCtx = []grammar.IValueContext{inClause.Value()}
+		}
+	case ctx.NotInClause() != nil:
+		notInClause := ctx.NotInClause()
+		if notInClause.ValueList() != nil {
+			valuesCtx = notInClause.ValueList().AllValue()
+		} else {
+			valuesCtx = []grammar.IValueContext{notInClause.Value()}
+		}
+	default:
+		v.AddError("IN clause is missing for %q", keyForError)
+		return nil, false
+	}
+	if len(valuesCtx) == 0 {
+		v.AddError("IN list for %q is empty", keyForError)
+		return nil, false
+	}
+	out := make([]string, 0, len(valuesCtx))
+	for _, valueContext := range valuesCtx {
+		s, ok := v.extractStringValue(valueContext, keyForError)
+		if !ok {
+			return nil, false
+		}
+		out = append(out, s)
+	}
+	return out, true
+}
+
+func (v *Visitor) extractSingleBoolValue(ctx *grammar.ComparisonContext) (bool, bool) {
+	values := ctx.AllValue()
+	if len(values) != 1 {
+		v.AddError("expected a single boolean (true/false)")
+		return false, false
+	}
+	return v.extractBoolValue(values[0])
+}
+
+func (v *Visitor) extractSingleTimestampValue(ctx *grammar.ComparisonContext) (time.Time, bool) {
+	values := ctx.AllValue()
+	if len(values) != 1 {
+		v.AddError("expected a single RFC3339 timestamp")
+		return time.Time{}, false
+	}
+	return v.extractTimestampValue(values[0])
+}
+
+func (v *Visitor) extractTwoTimestampValues(ctx *grammar.ComparisonContext) ([2]time.Time, bool) {
+	values := ctx.AllValue()
+	if len(values) != 2 {
+		v.AddError("BETWEEN expects two RFC3339 timestamps")
+		return [2]time.Time{}, false
+	}
+	first, ok1 := v.extractTimestampValue(values[0])
+	second, ok2 := v.extractTimestampValue(values[1])
+	if !ok1 || !ok2 {
+		return [2]time.Time{}, false
+	}
+	return [2]time.Time{first, second}, true
+}
+
+func (v *Visitor) extractStringValue(ctx grammar.IValueContext, keyForError string) (string, bool) {
+	if ctx.QUOTED_TEXT() != nil {
+		return trimQuotes(ctx.QUOTED_TEXT().GetText()), true
+	}
+	if ctx.KEY() != nil {
+		return ctx.KEY().GetText(), true
+	}
+	v.AddError("expected a string value for %q, got %q", keyForError, ctx.GetText())
+	return "", false
+}
+
+func (v *Visitor) extractBoolValue(ctx grammar.IValueContext) (bool, bool) {
+	if ctx.BOOL() == nil {
+		v.AddError("expected a boolean (true/false), got %q", ctx.GetText())
+		return false, false
+	}
+	return strings.EqualFold(ctx.BOOL().GetText(), "true"), true
+}
+
+func (v *Visitor) extractTimestampValue(ctx grammar.IValueContext) (time.Time, bool) {
+	if ctx.QUOTED_TEXT() == nil {
+		v.AddError("expected an RFC3339 timestamp string, got %q", ctx.GetText())
+		return time.Time{}, false
+	}
+	raw := trimQuotes(ctx.QUOTED_TEXT().GetText())
+	t, err := time.Parse(time.RFC3339, raw)
+	if err != nil {
+		v.AddError("invalid RFC3339 timestamp %q: %s", raw, err.Error())
+		return time.Time{}, false
+	}
+	return t, true
+}
+
+func (v *Visitor) visit(tree antlr.ParseTree) any {
+	if tree == nil {
+		return nil
+	}
+	return tree.Accept(v)
+}
+
+func (v *Visitor) VisitQuery(ctx *grammar.QueryContext) any {
+	return v.visit(ctx.Expression())
+}
+
+func (v *Visitor) VisitExpression(ctx *grammar.ExpressionContext) any {
+	return v.visit(ctx.OrExpression())
+}
+
+func (v *Visitor) VisitOrExpression(ctx *grammar.OrExpressionContext) any {
+	parts := ctx.AllAndExpression()
+	conditions := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if condition, ok := v.visit(part).(string); ok && condition != "" {
+			conditions = append(conditions, condition)
+		}
+	}
+	switch len(conditions) {
+	case 0:
+		return ""
+	case 1:
+		return conditions[0]
+	default:
+		return v.sb.Or(conditions...)
+	}
+}
+
+func (v *Visitor) VisitAndExpression(ctx *grammar.AndExpressionContext) any {
+	parts := ctx.AllUnaryExpression()
+	conditions := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if condition, ok := v.visit(part).(string); ok && condition != "" {
+			conditions = append(conditions, condition)
+		}
+	}
+	switch len(conditions) {
+	case 0:
+		return ""
+	case 1:
+		return conditions[0]
+	default:
+		return v.sb.And(conditions...)
+	}
+}
+
+func (v *Visitor) VisitUnaryExpression(ctx *grammar.UnaryExpressionContext) any {
+	condition, _ := v.visit(ctx.Primary()).(string)
+	if condition == "" {
+		return ""
+	}
+	if ctx.NOT() != nil {
+		return fmt.Sprintf("NOT (%s)", condition)
+	}
+	return condition
+}
+
+func (v *Visitor) VisitPrimary(ctx *grammar.PrimaryContext) any {
+	if ctx.OrExpression() != nil {
+		return v.visit(ctx.OrExpression())
+	}
+	if ctx.Comparison() != nil {
+		return v.visit(ctx.Comparison())
+	}
+	// A quoted lone token matches its contents literally, the escape hatch for a phrase that looks like DSL.
+	return v.resolver.FreeText(v, trimQuotes(ctx.GetText()))
+}
+
+func (v *Visitor) VisitComparison(ctx *grammar.ComparisonContext) any {
+	key := strings.TrimSpace(ctx.Key().GetText())
+	operation, ok := v.extractOperation(ctx)
+	if !ok {
+		return ""
+	}
+	return v.resolver.ResolveComparison(v, key, operation, ctx)
+}
+
+func (v *Visitor) extractOperation(ctx *grammar.ComparisonContext) (qbtypesv5.FilterOperator, bool) {
+	maybeNot := func(operation qbtypesv5.FilterOperator) qbtypesv5.FilterOperator {
+		if ctx.NOT() != nil {
+			return operation.Inverse()
+		}
+		return operation
+	}
+	switch {
+	case ctx.EQUALS() != nil:
+		return qbtypesv5.FilterOperatorEqual, true
+	case ctx.NOT_EQUALS() != nil, ctx.NEQ() != nil:
+		return qbtypesv5.FilterOperatorNotEqual, true
+	case ctx.LT() != nil:
+		return qbtypesv5.FilterOperatorLessThan, true
+	case ctx.LE() != nil:
+		return qbtypesv5.FilterOperatorLessThanOrEq, true
+	case ctx.GT() != nil:
+		return qbtypesv5.FilterOperatorGreaterThan, true
+	case ctx.GE() != nil:
+		return qbtypesv5.FilterOperatorGreaterThanOrEq, true
+	case ctx.BETWEEN() != nil:
+		return maybeNot(qbtypesv5.FilterOperatorBetween), true
+	case ctx.LIKE() != nil:
+		return maybeNot(qbtypesv5.FilterOperatorLike), true
+	case ctx.ILIKE() != nil:
+		return maybeNot(qbtypesv5.FilterOperatorILike), true
+	case ctx.CONTAINS() != nil:
+		return maybeNot(qbtypesv5.FilterOperatorContains), true
+	case ctx.REGEXP() != nil:
+		return maybeNot(qbtypesv5.FilterOperatorRegexp), true
+	case ctx.InClause() != nil:
+		return qbtypesv5.FilterOperatorIn, true
+	case ctx.NotInClause() != nil:
+		return qbtypesv5.FilterOperatorNotIn, true
+	case ctx.EXISTS() != nil:
+		return maybeNot(qbtypesv5.FilterOperatorExists), true
+	}
+	v.AddError("could not determine operator in expression %q", ctx.GetText())
+	return qbtypesv5.FilterOperatorUnknown, false
+}
+
+// OperationName is the user-facing spelling, used only in error messages.
+func OperationName(operation qbtypesv5.FilterOperator) string {
+	switch operation {
+	case qbtypesv5.FilterOperatorEqual:
+		return "="
+	case qbtypesv5.FilterOperatorNotEqual:
+		return "!="
+	case qbtypesv5.FilterOperatorLessThan:
+		return "<"
+	case qbtypesv5.FilterOperatorLessThanOrEq:
+		return "<="
+	case qbtypesv5.FilterOperatorGreaterThan:
+		return ">"
+	case qbtypesv5.FilterOperatorGreaterThanOrEq:
+		return ">="
+	case qbtypesv5.FilterOperatorBetween:
+		return "BETWEEN"
+	case qbtypesv5.FilterOperatorNotBetween:
+		return "NOT BETWEEN"
+	case qbtypesv5.FilterOperatorLike:
+		return "LIKE"
+	case qbtypesv5.FilterOperatorNotLike:
+		return "NOT LIKE"
+	case qbtypesv5.FilterOperatorILike:
+		return "ILIKE"
+	case qbtypesv5.FilterOperatorNotILike:
+		return "NOT ILIKE"
+	case qbtypesv5.FilterOperatorContains:
+		return "CONTAINS"
+	case qbtypesv5.FilterOperatorNotContains:
+		return "NOT CONTAINS"
+	case qbtypesv5.FilterOperatorRegexp:
+		return "REGEXP"
+	case qbtypesv5.FilterOperatorNotRegexp:
+		return "NOT REGEXP"
+	case qbtypesv5.FilterOperatorIn:
+		return "IN"
+	case qbtypesv5.FilterOperatorNotIn:
+		return "NOT IN"
+	case qbtypesv5.FilterOperatorExists:
+		return "EXISTS"
+	case qbtypesv5.FilterOperatorNotExists:
+		return "NOT EXISTS"
+	}
+	return "?"
+}
+
+func trimQuotes(s string) string {
+	if len(s) >= 2 {
+		if (s[0] == '"' && s[len(s)-1] == '"') || (s[0] == '\'' && s[len(s)-1] == '\'') {
+			s = s[1 : len(s)-1]
+		}
+	}
+	s = strings.ReplaceAll(s, `\\`, `\`)
+	s = strings.ReplaceAll(s, `\'`, `'`)
+	return s
+}