feat(resolvespec): add 'contains' operator for array overlap

* Implemented 'contains' operator using BuildArrayOverlapCondition for real array containment.
* Updated documentation to clarify differences between text-cast ILIKE and array overlap.

pkg/common/sql_helpers.go

@@ -1040,3 +1040,21 @@ func BuildInCondition(column string, v interface{}) (query string, args []interf
 	}
 	return fmt.Sprintf("%s IN (%s)", column, strings.Join(placeholders, ",")), values
 }
+
+// BuildArrayOverlapCondition builds a parameterized condition testing whether an
+// array column has at least one element in common with the given value(s), using
+// PostgreSQL's array overlap operator (&&). Unlike a text-cast ILIKE, this performs
+// real element-wise containment (no substring false positives) and can use a GIN
+// index on the column. A single value is treated as a one-element array.
+// Returns ("", nil) if the value is empty.
+func BuildArrayOverlapCondition(column string, v interface{}) (query string, args []interface{}) {
+	values := FilterValueToSlice(v)
+	if len(values) == 0 {
+		return "", nil
+	}
+	placeholders := make([]string, len(values))
+	for i := range values {
+		placeholders[i] = "?"
+	}
+	return fmt.Sprintf("%s && ARRAY[%s]", column, strings.Join(placeholders, ",")), values
+}

pkg/common/sql_helpers_test.go

@@ -979,3 +979,61 @@ t.Errorf("AddTablePrefixToColumns(%q, %q) = %q; want %q", tt.where, tt.tableName
 		})
 	}
 }
+
+func TestBuildArrayOverlapCondition(t *testing.T) {
+	tests := []struct {
+		name         string
+		column       string
+		value        interface{}
+		expectedCond string
+		expectedArgs int
+	}{
+		{
+			name:         "single scalar value",
+			column:       "tags",
+			value:        "urgent",
+			expectedCond: "tags && ARRAY[?]",
+			expectedArgs: 1,
+		},
+		{
+			name:         "multiple values",
+			column:       "tags",
+			value:        []string{"urgent", "billing", "vip"},
+			expectedCond: "tags && ARRAY[?,?,?]",
+			expectedArgs: 3,
+		},
+		{
+			name:         "JSON-decoded []interface{} value",
+			column:       "tags",
+			value:        []interface{}{"urgent", "billing"},
+			expectedCond: "tags && ARRAY[?,?]",
+			expectedArgs: 2,
+		},
+		{
+			name:         "nil value",
+			column:       "tags",
+			value:        nil,
+			expectedCond: "",
+			expectedArgs: 0,
+		},
+		{
+			name:         "empty slice value",
+			column:       "tags",
+			value:        []string{},
+			expectedCond: "",
+			expectedArgs: 0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cond, args := BuildArrayOverlapCondition(tt.column, tt.value)
+			if cond != tt.expectedCond {
+				t.Errorf("BuildArrayOverlapCondition(%q, %v) condition = %q; want %q", tt.column, tt.value, cond, tt.expectedCond)
+			}
+			if len(args) != tt.expectedArgs {
+				t.Errorf("BuildArrayOverlapCondition(%q, %v) args = %d; want %d", tt.column, tt.value, len(args), tt.expectedArgs)
+			}
+		})
+	}
+}

pkg/resolvespec/filter_test.go

@@ -57,6 +57,36 @@ func TestBuildFilterCondition(t *testing.T) {
 			expectedCondition: "CAST(email AS TEXT) LIKE ?",
 			expectedArgsCount: 1,
 		},
+		{
+			name: "CONTAINS operator with single value",
+			filter: common.FilterOption{
+				Column:   "tags",
+				Operator: "contains",
+				Value:    "urgent",
+			},
+			expectedCondition: "tags && ARRAY[?]",
+			expectedArgsCount: 1,
+		},
+		{
+			name: "CONTAINS operator with multiple values",
+			filter: common.FilterOption{
+				Column:   "tags",
+				Operator: "contains",
+				Value:    []string{"urgent", "billing"},
+			},
+			expectedCondition: "tags && ARRAY[?,?]",
+			expectedArgsCount: 2,
+		},
+		{
+			name: "CONTAINS operator with empty value",
+			filter: common.FilterOption{
+				Column:   "tags",
+				Operator: "contains",
+				Value:    nil,
+			},
+			expectedCondition: "",
+			expectedArgsCount: 0,
+		},
 	}
 
 	for _, tt := range tests {

pkg/resolvespec/handler.go

@@ -1895,6 +1895,11 @@ func (h *Handler) buildFilterCondition(filter common.FilterOption) (conditionStr
 		if condition == "" {
 			return "", nil
 		}
+	case "contains":
+		condition, args = common.BuildArrayOverlapCondition(filter.Column, filter.Value)
+		if condition == "" {
+			return "", nil
+		}
 	default:
 		return "", nil
 	}
@@ -1939,6 +1944,11 @@ func (h *Handler) applyFilter(query common.SelectQuery, filter common.FilterOpti
 		if condition == "" {
 			return query
 		}
+	case "contains":
+		condition, args = common.BuildArrayOverlapCondition(filter.Column, filter.Value)
+		if condition == "" {
+			return query
+		}
 	default:
 		return query
 	}

pkg/restheadspec/HEADERS.md

@@ -88,7 +88,7 @@ This will match any records where the column contains the search term (case-inse
 Search with specific operators (AND logic).
 
 **Supported Operators:**
-- `contains` - Contains substring (case-insensitive)
+- `contains` - Contains substring (case-insensitive). Implemented as `CAST(col AS TEXT) ILIKE '%value%'` for every column type, including arrays (stringifies the array, then substring-matches). **Not** array containment — no GIN index use, and can false-positive on partial matches within array elements. resolvespec (a different spec package in this repo) defines `contains` differently: real PostgreSQL array-overlap (`&&`). Don't assume the two behave the same.
 - `beginswith` / `startswith` - Starts with (case-insensitive)
 - `endswith` - Ends with (case-insensitive)
 - `equals` / `eq` - Exact match

pkg/restheadspec/README.md

@@ -96,6 +96,8 @@ X-Limit: 50
 
 **Available Operators**: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `startswith`, `endswith`, `between`, `betweeninclusive`, `in`, `empty`, `notempty`
 
+> Note: `contains` here is a text-cast ILIKE substring match (works on any column type, including arrays, by stringifying first) — not array containment. resolvespec's `contains` operator has different semantics (real array overlap). See [HEADERS.md](HEADERS.md) for details.
+
 For complete header documentation, see [HEADERS.md](HEADERS.md).
 
 ## Lifecycle Hooks