fix(sql_helpers): strip empty RHS conditions from SQL strings

* Add regex patterns to identify and remove empty comparisons
* Implement tests for stripping empty RHS conditions
fix(handler): prevent duplicate JOIN aliases from preload
* Skip custom SQL JOINs if alias already provided by preload
* Split multiple JOIN clauses for individual alias handling

pkg/common/adapters/database/bun.go

@@ -487,6 +487,14 @@ func normalizeTableAlias(query, expectedAlias, tableName string) string {
 	return modified
 }
 
+func isJoinKeyword(word string) bool {
+	switch strings.ToUpper(word) {
+	case "JOIN", "INNER", "LEFT", "RIGHT", "FULL", "OUTER", "CROSS":
+		return true
+	}
+	return false
+}
+
 func (b *BunSelectQuery) WhereOr(query string, args ...interface{}) common.SelectQuery {
 	b.query = b.query.WhereOr(query, args...)
 	return b
@@ -517,7 +525,7 @@ func (b *BunSelectQuery) Join(query string, args ...interface{}) common.SelectQu
 	if prefix != "" && !strings.Contains(strings.ToUpper(query), " AS ") {
 		// If query doesn't already have AS, check if it's a simple table name
 		parts := strings.Fields(query)
-		if len(parts) > 0 && !strings.HasPrefix(strings.ToUpper(parts[0]), "JOIN") {
+		if len(parts) > 0 && !isJoinKeyword(parts[0]) {
 			// Simple table name, add prefix: "table AS prefix"
 			joinClause = fmt.Sprintf("%s AS %s", parts[0], prefix)
 			if len(parts) > 1 {
@@ -552,7 +560,7 @@ func (b *BunSelectQuery) LeftJoin(query string, args ...interface{}) common.Sele
 	joinClause := query
 	if prefix != "" && !strings.Contains(strings.ToUpper(query), " AS ") {
 		parts := strings.Fields(query)
-		if len(parts) > 0 && !strings.HasPrefix(strings.ToUpper(parts[0]), "LEFT") && !strings.HasPrefix(strings.ToUpper(parts[0]), "JOIN") {
+		if len(parts) > 0 && !isJoinKeyword(parts[0]) {
 			joinClause = fmt.Sprintf("%s AS %s", parts[0], prefix)
 			if len(parts) > 1 {
 				joinClause += " " + strings.Join(parts[1:], " ")

pkg/common/sql_helpers.go

@@ -59,6 +59,38 @@ func IsSQLExpression(cond string) bool {
 	return false
 }
 
+// reEmptyCompMid matches a simple column comparison with an empty RHS that is immediately
+// followed by AND/OR (only whitespace between the operator and the next keyword).
+// Removing the match leaves the preceding AND/OR connector intact.
+// Example: "cond1 and col = \n    and cond2" → "cond1 and cond2"
+var reEmptyCompMid = regexp.MustCompile(`(?i)[\w.]+\s*(?:=|<>|!=|>=|<=|>|<)\s+(?:and|or)\s+`)
+
+// reEmptyCompEnd matches AND/OR + a simple column comparison with an empty RHS at the end
+// of the string (or sub-clause).
+// Example: "cond1 and col = " → "cond1"
+var reEmptyCompEnd = regexp.MustCompile(`(?i)\s+(?:and|or)\s+[\w.]+\s*(?:=|<>|!=|>=|<=|>|<)\s*$`)
+
+// stripEmptyComparisonClauses removes comparison conditions that have no right-hand side
+// value from a raw SQL string. Operates on the whole string so it also cleans up conditions
+// inside subqueries, not just top-level AND splits.
+func stripEmptyComparisonClauses(sql string) string {
+	sql = reEmptyCompMid.ReplaceAllLiteralString(sql, "")
+	sql = reEmptyCompEnd.ReplaceAllLiteralString(sql, "")
+	return sql
+}
+
+// hasEmptyRHS returns true when a condition ends with a comparison operator and has no
+// right-hand side value — e.g., "col = ", "com.rid_parent = ", "col >= ".
+func hasEmptyRHS(cond string) bool {
+	cond = strings.TrimSpace(cond)
+	for _, op := range []string{"<>", "!=", ">=", "<=", "=", ">", "<"} {
+		if strings.HasSuffix(cond, op) {
+			return true
+		}
+	}
+	return false
+}
+
 // IsTrivialCondition checks if a condition is trivial and always evaluates to true
 // These conditions should be removed from WHERE clauses as they have no filtering effect
 func IsTrivialCondition(cond string) bool {
@@ -147,6 +179,14 @@ func SanitizeWhereClause(where string, tableName string, options ...*RequestOpti
 		return ""
 	}
 
+	// Strip comparison conditions with empty RHS throughout the SQL string (including
+	// inside subqueries), before condition splitting.
+	where = stripEmptyComparisonClauses(where)
+	if where == "" {
+		return ""
+	}
+	where = strings.TrimSpace(where)
+
 	// Check if the original clause has outer parentheses and contains OR operators
 	// If so, we need to preserve the outer parentheses to prevent OR logic from escaping
 	hasOuterParens := false
@@ -212,6 +252,12 @@ func SanitizeWhereClause(where string, tableName string, options ...*RequestOpti
 			continue
 		}
 
+		// Skip conditions with no right-hand side value (e.g. "col = " with empty value)
+		if hasEmptyRHS(condToCheck) {
+			logger.Debug("Removing condition with empty value: '%s'", cond)
+			continue
+		}
+
 		// If tableName is provided and the condition HAS a table prefix, check if it's correct
 		if tableName != "" && hasTablePrefix(condToCheck) {
 			// Extract the current prefix and column name

pkg/common/sql_helpers_test.go

@@ -134,6 +134,30 @@ func TestSanitizeWhereClause(t *testing.T) {
 			tableName: "apiprovider",
 			expected:  "apiprovider.type in ('softphone') AND (apiprovider.rid_apiprovider in (select l.rid_apiprovider from core.apiproviderlink l where l.rid_hub = 2576))",
 		},
+		{
+			name:      "empty RHS stripped mid-clause",
+			where:     "com.tableprefix = 'tcli' and com.rid_parent = \n    and com.status = 'Active'",
+			tableName: "",
+			expected:  "com.tableprefix = 'tcli' AND com.status = 'Active'",
+		},
+		{
+			name:      "empty RHS stripped at end of clause",
+			where:     "com.tableprefix = 'tcli' and com.rid_parent =",
+			tableName: "",
+			expected:  "com.tableprefix = 'tcli'",
+		},
+		{
+			name:      "non-empty value not stripped",
+			where:     "com.tableprefix = 'tcli' and com.rid_parent = 123 and com.status = 'Active'",
+			tableName: "",
+			expected:  "com.tableprefix = 'tcli' AND com.rid_parent = 123 AND com.status = 'Active'",
+		},
+		{
+			name:      "empty RHS inside subquery stripped",
+			where:     "a = 1 and b in (select x from t where c.rid = \n    and d = 2)",
+			tableName: "",
+			expected:  "a = 1 AND b in (select x from t where d = 2)",
+		},
 	}
 
 	for _, tt := range tests {

pkg/funcspec/function_api.go

@@ -168,9 +168,16 @@ func (h *Handler) SqlQueryList(sqlquery string, options SqlQueryOptions) HTTPFun
 		// Replace meta variables in SQL
 		sqlquery = h.replaceMetaVariables(sqlquery, r, userCtx, metainfo, variables)
 
-		// Remove unused input variables
+		// Replace variables from provided values, then blank any remaining unused ones
-		if options.BlankParams {
+		for _, kw := range inputvars {
-			for _, kw := range inputvars {
+			varName := kw[1 : len(kw)-1] // strip [ and ]
+			if val, ok := variables[varName]; ok {
+				if strVal := fmt.Sprintf("%v", val); strVal != "" {
+					sqlquery = strings.ReplaceAll(sqlquery, kw, ValidSQL(strVal, "colvalue"))
+					continue
+				}
+			}
+			if options.BlankParams {
 				replacement := getReplacementForBlankParam(sqlquery, kw)
 				sqlquery = strings.ReplaceAll(sqlquery, kw, replacement)
 				logger.Debug("Replaced unused variable %s with: %s", kw, replacement)
@@ -520,9 +527,16 @@ func (h *Handler) SqlQuery(sqlquery string, options SqlQueryOptions) HTTPFuncTyp
 			}
 		}
 
-		// Remove unused input variables
+		// Replace variables from provided values, then blank any remaining unused ones
-		if options.BlankParams {
+		for _, kw := range inputvars {
-			for _, kw := range inputvars {
+			varName := kw[1 : len(kw)-1] // strip [ and ]
+			if val, ok := variables[varName]; ok {
+				if strVal := fmt.Sprintf("%v", val); strVal != "" {
+					sqlquery = strings.ReplaceAll(sqlquery, kw, ValidSQL(strVal, "colvalue"))
+					continue
+				}
+			}
+			if options.BlankParams {
 				replacement := getReplacementForBlankParam(sqlquery, kw)
 				sqlquery = strings.ReplaceAll(sqlquery, kw, replacement)
 				logger.Debug("Replaced unused variable %s with: %s", kw, replacement)
@@ -715,8 +729,9 @@ func (h *Handler) mergeQueryParams(r *http.Request, sqlquery string, variables m
 			propQry[parmk] = val
 		}
 
-		// Apply filters if allowed
+		// Apply filters if allowed — check against string-literal-stripped SQL to avoid
-		if allowFilter && len(parmk) > 1 && strings.Contains(strings.ToLower(sqlquery), strings.ToLower(parmk)) {
+		// matching column names that only appear inside quoted arguments (e.g. JSON strings)
+		if allowFilter && len(parmk) > 1 && strings.Contains(strings.ToLower(sqlStripStringLiterals(sqlquery)), strings.ToLower(parmk)) {
 			if len(parmv) > 1 {
 				// Sanitize each value in the IN clause with appropriate quoting
 				sanitizedValues := make([]string, len(parmv))
@@ -824,6 +839,14 @@ func (h *Handler) mergeHeaderParams(r *http.Request, sqlquery string, variables
 	return sqlquery
 }
 
+// sqlStripStringLiterals removes the contents of single-quoted string literals from SQL,
+// leaving the structural identifiers (column names, table names) intact.
+// Used to check column presence without matching inside string arguments.
+func sqlStripStringLiterals(sql string) string {
+	re := regexp.MustCompile(`'(?:[^']|'')*'`)
+	return re.ReplaceAllString(sql, "''")
+}
+
 // replaceMetaVariables replaces meta variables like [rid_user], [user], etc. in the SQL query
 func (h *Handler) replaceMetaVariables(sqlquery string, r *http.Request, userCtx *security.UserContext, metainfo map[string]interface{}, variables map[string]interface{}) string {
 	if strings.Contains(sqlquery, "[p_meta_default]") {
@@ -991,8 +1014,8 @@ func getReplacementForBlankParam(sqlquery, param string) string {
 		charAfter = sqlquery[endIdx]
 	}
 
-	// Check if parameter is surrounded by quotes (single quote or dollar sign for PostgreSQL dollar-quoted strings)
+	// Check if parameter is surrounded by quotes (single quote, dollar sign for PostgreSQL dollar-quoted strings, or double quote for JSON string values)
-	if (charBefore == '\'' || charBefore == '$') && (charAfter == '\'' || charAfter == '$') {
+	if (charBefore == '\'' || charBefore == '$' || charBefore == '"') && (charAfter == '\'' || charAfter == '$' || charAfter == '"') {
 		// Parameter is in quotes, return empty string
 		return ""
 	}

pkg/funcspec/function_api_test.go

@@ -851,6 +851,231 @@ func TestReplaceMetaVariables(t *testing.T) {
 	}
 }
 
+// TestSqlStripStringLiterals tests that single-quoted string literals are removed
+func TestSqlStripStringLiterals(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "No string literals",
+			input:    "SELECT rid, rid_parent FROM users",
+			expected: "SELECT rid, rid_parent FROM users",
+		},
+		{
+			name:     "Simple string literal",
+			input:    "SELECT * FROM users WHERE mode = 'admin'",
+			expected: "SELECT * FROM users WHERE mode = ''",
+		},
+		{
+			name:     "JSON argument containing column names",
+			input:    `SELECT rid, rid_parent FROM crm_get_menu(1,'mode', '{"rid_parent":"[rid_parent]","CF:STARTDATE":"[cf_startdate]"}')`,
+			expected: `SELECT rid, rid_parent FROM crm_get_menu(1,'', '')`,
+		},
+		{
+			name:     "Escaped single quotes inside literal",
+			input:    "SELECT * FROM t WHERE name = 'O''Brien'",
+			expected: "SELECT * FROM t WHERE name = ''",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := sqlStripStringLiterals(tt.input)
+			if result != tt.expected {
+				t.Errorf("sqlStripStringLiterals() =\n  %q\nwant\n  %q", result, tt.expected)
+			}
+		})
+	}
+}
+
+// TestAllowFilterDoesNotMatchInsideJsonArgument verifies that AllowFilter will add WHERE
+// clauses for real output columns (rid, rid_parent) but not for names that only appear
+// inside a JSON string argument (cf_startdate, cf_rid_branch).
+func TestAllowFilterDoesNotMatchInsideJsonArgument(t *testing.T) {
+	handler := NewHandler(&MockDatabase{})
+
+	sqlQuery := `select rid, rid_parent, description
+      from crm_get_menu([rid_user],'[p_mode]', 0, '', '{"rid_parent":"[rid_parent]", "CF:STARTDATE": "[cf_startdate]", "CF:RID_BRANCH": "[cf_rid_branch]"}')`
+
+	tests := []struct {
+		name        string
+		queryParams map[string]string
+		checkResult func(t *testing.T, result string)
+	}{
+		{
+			name:        "rid_parent=0 is a real column — filter applied",
+			queryParams: map[string]string{"rid_parent": "0"},
+			checkResult: func(t *testing.T, result string) {
+				if !strings.Contains(strings.ToLower(result), "where") {
+					t.Error("Expected WHERE clause to be added for rid_parent")
+				}
+				if !strings.Contains(result, "rid_parent = 0 OR") && !strings.Contains(result, "rid_parent IS NULL") {
+					t.Errorf("Expected null-safe filter for rid_parent=0, got:\n%s", result)
+				}
+			},
+		},
+		{
+			name:        "cf_startdate only appears in JSON string — no filter applied",
+			queryParams: map[string]string{"cf_startdate": "2024-01-01"},
+			checkResult: func(t *testing.T, result string) {
+				if strings.Contains(strings.ToLower(result), "where") {
+					t.Errorf("Expected no WHERE clause for cf_startdate (only in JSON arg), got:\n%s", result)
+				}
+			},
+		},
+		{
+			name:        "cf_rid_branch only appears in JSON string — no filter applied",
+			queryParams: map[string]string{"cf_rid_branch": "5"},
+			checkResult: func(t *testing.T, result string) {
+				if strings.Contains(strings.ToLower(result), "where") {
+					t.Errorf("Expected no WHERE clause for cf_rid_branch (only in JSON arg), got:\n%s", result)
+				}
+			},
+		},
+		{
+			name:        "description is a real column — filter applied",
+			queryParams: map[string]string{"description": "test"},
+			checkResult: func(t *testing.T, result string) {
+				if !strings.Contains(strings.ToLower(result), "where") {
+					t.Error("Expected WHERE clause for description")
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			req := createTestRequest("GET", "/test", tt.queryParams, nil, nil)
+			variables := make(map[string]interface{})
+			propQry := make(map[string]string)
+
+			result := handler.mergeQueryParams(req, sqlQuery, variables, true, propQry)
+			tt.checkResult(t, result)
+		})
+	}
+}
+
+// TestGetReplacementForBlankParamDoubleQuote verifies that placeholders surrounded by
+// double quotes (as in JSON string values) are blanked to "" not NULL.
+func TestGetReplacementForBlankParamDoubleQuote(t *testing.T) {
+	tests := []struct {
+		name     string
+		sqlQuery string
+		param    string
+		expected string
+	}{
+		{
+			name:     "Parameter in double quotes (JSON value)",
+			sqlQuery: `SELECT * FROM f(1, '{"key":"[myparam]"}')`,
+			param:    "[myparam]",
+			expected: "",
+		},
+		{
+			name:     "Parameter not in any quotes",
+			sqlQuery: `SELECT * FROM f([myparam])`,
+			param:    "[myparam]",
+			expected: "NULL",
+		},
+		{
+			name:     "Parameter in single quotes",
+			sqlQuery: `SELECT * FROM f('[myparam]')`,
+			param:    "[myparam]",
+			expected: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := getReplacementForBlankParam(tt.sqlQuery, tt.param)
+			if result != tt.expected {
+				t.Errorf("getReplacementForBlankParam() = %q, want %q\nquery: %s", result, tt.expected, tt.sqlQuery)
+			}
+		})
+	}
+}
+
+// TestVariableReplacementFromQueryParams verifies that query params matching [placeholder]
+// tokens are substituted even when they don't have the p- prefix.
+func TestVariableReplacementFromQueryParams(t *testing.T) {
+	handler := NewHandler(&MockDatabase{})
+
+	sqlQuery := `select rid, rid_parent from crm_get_menu([rid_user],'[p_mode]', 0, '', '{"rid_parent":"[rid_parent]","CF:STARTDATE":"[cf_startdate]"}')`
+
+	tests := []struct {
+		name        string
+		queryParams map[string]string
+		checkResult func(t *testing.T, result string)
+	}{
+		{
+			name:        "rid_parent replaced from query param",
+			queryParams: map[string]string{"rid_parent": "42"},
+			checkResult: func(t *testing.T, result string) {
+				if strings.Contains(result, "[rid_parent]") {
+					t.Errorf("Expected [rid_parent] to be replaced, still present in:\n%s", result)
+				}
+				if !strings.Contains(result, "42") {
+					t.Errorf("Expected value 42 in query, got:\n%s", result)
+				}
+			},
+		},
+		{
+			name:        "cf_startdate replaced from query param",
+			queryParams: map[string]string{"cf_startdate": "2024-01-01"},
+			checkResult: func(t *testing.T, result string) {
+				if strings.Contains(result, "[cf_startdate]") {
+					t.Errorf("Expected [cf_startdate] to be replaced, still present in:\n%s", result)
+				}
+				if !strings.Contains(result, "2024-01-01") {
+					t.Errorf("Expected date value in query, got:\n%s", result)
+				}
+			},
+		},
+		{
+			name:        "missing param blanked to empty string inside JSON (double-quoted)",
+			queryParams: map[string]string{},
+			checkResult: func(t *testing.T, result string) {
+				// [cf_startdate] is surrounded by " in the JSON — should blank to ""
+				if strings.Contains(result, "[cf_startdate]") {
+					t.Errorf("Expected [cf_startdate] to be blanked, still present in:\n%s", result)
+				}
+				if strings.Contains(result, "NULL") && strings.Contains(result, "cf_startdate") {
+					t.Errorf("Expected empty string (not NULL) for double-quoted placeholder, got:\n%s", result)
+				}
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			inputvars := make([]string, 0)
+			q := handler.extractInputVariables(sqlQuery, &inputvars)
+
+			req := createTestRequest("GET", "/test", tt.queryParams, nil, nil)
+			variables := make(map[string]interface{})
+			propQry := make(map[string]string)
+
+			q = handler.mergeQueryParams(req, q, variables, false, propQry)
+
+			// Simulate the variable replacement + blank-param loop (mirrors function_api.go)
+			for _, kw := range inputvars {
+				varName := kw[1 : len(kw)-1]
+				if val, ok := variables[varName]; ok {
+					if strVal := strings.TrimSpace(val.(string)); strVal != "" {
+						q = strings.ReplaceAll(q, kw, ValidSQL(strVal, "colvalue"))
+						continue
+					}
+				}
+				replacement := getReplacementForBlankParam(q, kw)
+				q = strings.ReplaceAll(q, kw, replacement)
+			}
+
+			tt.checkResult(t, q)
+		})
+	}
+}
+
 // TestGetReplacementForBlankParam tests the blank parameter replacement logic
 func TestGetReplacementForBlankParam(t *testing.T) {
 	tests := []struct {

pkg/reflection/helpers.go

@@ -76,9 +76,14 @@ func GetJSONNameForField(modelType reflect.Type, fieldName string) string {
 		return ""
 	}
 
-	// Handle pointer types
+	// Unwrap pointer and slice indirections to reach the struct type
-	if modelType.Kind() == reflect.Ptr {
+	for {
-		modelType = modelType.Elem()
+		switch modelType.Kind() {
+		case reflect.Ptr, reflect.Slice:
+			modelType = modelType.Elem()
+			continue
+		}
+		break
 	}
 
 	if modelType.Kind() != reflect.Struct {

pkg/reflection/model_utils.go

@@ -541,9 +541,14 @@ func collectSQLColumnsFromType(typ reflect.Type, columns *[]string, scanOnlyEmbe
 func IsColumnWritable(model any, columnName string) bool {
 	modelType := reflect.TypeOf(model)
 
-	// Unwrap pointers to get to the base struct type
+	// Unwrap pointers and slices to get to the base struct type
-	for modelType != nil && modelType.Kind() == reflect.Pointer {
+	for modelType != nil {
-		modelType = modelType.Elem()
+		switch modelType.Kind() {
+		case reflect.Ptr, reflect.Slice:
+			modelType = modelType.Elem()
+			continue
+		}
+		break
 	}
 
 	// Validate that we have a struct type
@@ -878,8 +883,14 @@ func GetRelationType(model interface{}, fieldName string) RelationType {
 		return RelationUnknown
 	}
 
-	if modelType.Kind() == reflect.Ptr {
+	// Unwrap pointer → slice → pointer chains to reach the underlying struct
-		modelType = modelType.Elem()
+	for {
+		switch modelType.Kind() {
+		case reflect.Ptr, reflect.Slice:
+			modelType = modelType.Elem()
+			continue
+		}
+		break
 	}
 
 	if modelType == nil || modelType.Kind() != reflect.Struct {
@@ -1472,9 +1483,14 @@ func convertToFloat64(value interface{}) (float64, bool) {
 func GetValidJSONFieldNames(modelType reflect.Type) map[string]bool {
 	validFields := make(map[string]bool)
 
-	// Unwrap pointers to get to the base struct type
+	// Unwrap pointers and slices to get to the base struct type
-	for modelType != nil && modelType.Kind() == reflect.Pointer {
+	for modelType != nil {
-		modelType = modelType.Elem()
+		switch modelType.Kind() {
+		case reflect.Ptr, reflect.Slice:
+			modelType = modelType.Elem()
+			continue
+		}
+		break
 	}
 
 	if modelType == nil || modelType.Kind() != reflect.Struct {
@@ -1535,8 +1551,13 @@ func getRelationModelSingleLevel(model interface{}, fieldName string) interface{
 		return nil
 	}
 
-	if modelType.Kind() == reflect.Ptr {
+	for {
-		modelType = modelType.Elem()
+		switch modelType.Kind() {
+		case reflect.Ptr, reflect.Slice:
+			modelType = modelType.Elem()
+			continue
+		}
+		break
 	}
 
 	if modelType == nil || modelType.Kind() != reflect.Struct {
@@ -1599,17 +1620,16 @@ func getRelationModelSingleLevel(model interface{}, fieldName string) interface{
 		return nil
 	}
 
-	if targetType.Kind() == reflect.Slice {
+	for {
-		targetType = targetType.Elem()
+		switch targetType.Kind() {
-		if targetType == nil {
+		case reflect.Ptr, reflect.Slice:
-			return nil
+			targetType = targetType.Elem()
-		}
+			if targetType == nil {
-	}
+				return nil
-	if targetType.Kind() == reflect.Ptr {
+			}
-		targetType = targetType.Elem()
+			continue
-		if targetType == nil {
-			return nil
 		}
+		break
 	}
 
 	if targetType.Kind() != reflect.Struct {

pkg/restheadspec/handler.go

@@ -575,11 +575,25 @@ func (h *Handler) handleRead(ctx context.Context, w common.ResponseWriter, id st
 		}
 	}
 
-	// Apply custom SQL JOIN clauses
+	// Apply custom SQL JOIN clauses, skipping any whose alias is already provided by a
+	// preload LEFT JOIN (to prevent "table name specified more than once" errors).
 	if len(options.CustomSQLJoin) > 0 {
-		for _, joinClause := range options.CustomSQLJoin {
+		preloadAliasSet := make(map[string]bool, len(options.Preload))
+		for _, p := range options.Preload {
+			if alias := common.RelationPathToBunAlias(p.Relation); alias != "" {
+				preloadAliasSet[alias] = true
+			}
+		}
+
+		for i, joinClause := range options.CustomSQLJoin {
+			if i < len(options.JoinAliases) && options.JoinAliases[i] != "" {
+				alias := strings.ToLower(options.JoinAliases[i])
+				if preloadAliasSet[alias] {
+					logger.Debug("Skipping custom SQL JOIN (alias '%s' already joined by preload): %s", alias, joinClause)
+					continue
+				}
+			}
 			logger.Debug("Applying custom SQL JOIN: %s", joinClause)
-			// Joins are already sanitized during parsing, so we can apply them directly
 			query = query.Join(joinClause)
 		}
 	}

pkg/restheadspec/headers.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"reflect"
+	"regexp"
 	"strconv"
 	"strings"
 
@@ -501,6 +502,31 @@ func (h *Handler) parseExpand(options *ExtendedRequestOptions, value string) {
 	}
 }
 
+// reMultiJoinBoundary finds the start of each individual JOIN clause within a string that
+// may contain multiple consecutive JOIN clauses (e.g., "INNER JOIN ... LEFT OUTER JOIN ...").
+var reMultiJoinBoundary = regexp.MustCompile(`(?i)(?:inner|left(?:\s+outer)?|right(?:\s+outer)?|full(?:\s+outer)?|cross)\s+join\b`)
+
+// splitJoinClauses splits a SQL string that may contain multiple JOIN clauses into
+// individual clauses. A plain pipe-separated segment may itself contain several JOINs;
+// this function splits them so each gets its own alias entry.
+func splitJoinClauses(joinStr string) []string {
+	indices := reMultiJoinBoundary.FindAllStringIndex(joinStr, -1)
+	if len(indices) <= 1 {
+		return []string{strings.TrimSpace(joinStr)}
+	}
+	parts := make([]string, 0, len(indices))
+	for i, idx := range indices {
+		end := len(joinStr)
+		if i+1 < len(indices) {
+			end = indices[i+1][0]
+		}
+		if part := strings.TrimSpace(joinStr[idx[0]:end]); part != "" {
+			parts = append(parts, part)
+		}
+	}
+	return parts
+}
+
 // parseCustomSQLJoin parses x-custom-sql-join header
 // Format: Single JOIN clause or multiple JOIN clauses separated by |
 // Example: "LEFT JOIN departments d ON d.id = employees.department_id"
@@ -533,17 +559,19 @@ func (h *Handler) parseCustomSQLJoin(options *ExtendedRequestOptions, value stri
 			continue
 		}
 
-		// Extract table alias from the JOIN clause
+		// Split into individual JOIN clauses so each clause gets its own alias entry.
-		alias := extractJoinAlias(sanitizedJoin)
+		// CustomSQLJoin and JoinAliases are kept parallel (one entry per individual clause).
-		if alias != "" {
+		for _, clause := range splitJoinClauses(sanitizedJoin) {
+			alias := extractJoinAlias(clause)
+			// Keep arrays parallel; use empty string when alias cannot be extracted.
 			options.JoinAliases = append(options.JoinAliases, alias)
-			// Also add to the embedded RequestOptions for validation
 			options.RequestOptions.JoinAliases = append(options.RequestOptions.JoinAliases, alias)
-			logger.Debug("Extracted join alias: %s", alias)
+			if alias != "" {
+				logger.Debug("Extracted join alias: %s", alias)
+			}
+			logger.Debug("Adding custom SQL join: %s", clause)
+			options.CustomSQLJoin = append(options.CustomSQLJoin, clause)
 		}
-
-		logger.Debug("Adding custom SQL join: %s", sanitizedJoin)
-		options.CustomSQLJoin = append(options.CustomSQLJoin, sanitizedJoin)
 	}
 }