feat: Add multi-dimensional array support (fixes #49) (#90)

Implemented comprehensive support for PostgreSQL multi-dimensional arrays
with automatic dimension detection and backward compatibility.

Changes:
- Added Dimensions field to pg.FieldSchema to store array dimensionality
- Implemented detectArrayDimensions() to parse PostgreSQL type strings
  * Handles bracket notation: integer[], integer[][], integer[][][]
  * Handles underscore notation: _int4, _int4[], _int4[][]
  * Correctly combines both notations (e.g., _int4[] = 2D array)
- Updated LoadTableSchema() to detect dimensions from udt_name column
- Modified ARRAY_LENGTH SQL generation to use detected dimensions
- Updated getArrayDimension() to use CEL typeMap for accurate type lookup

Testing:
- Added comprehensive unit tests for dimension detection (22 test cases)
- Added integration tests for 1D, 2D, 3D, and 4D arrays
- Added backward compatibility tests
- All existing tests pass (72.2% coverage)

Backward Compatibility:
- Arrays without schema information default to dimension 1
- Explicit Dimensions=0 defaults to dimension 1
- Existing code continues to work without changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: richardwooding

cel2sql.go

@@ -486,6 +486,57 @@ func (con *converter) getFieldElementType(tableName, fieldName string) string {
 	return ""
 }
 
+// getArrayDimension returns the number of array dimensions for a field expression.
+// Returns 1 if no schema information is available (backward compatible default).
+// For multi-dimensional arrays, returns the detected dimension count (2 for int[][], 3 for int[][][], etc.)
+func (con *converter) getArrayDimension(expr *exprpb.Expr) int {
+	// Default to 1D arrays if we can't determine from schema
+	if con.schemas == nil {
+		return 1
+	}
+
+	// Try to extract field name from the select expression
+	selectExpr := expr.GetSelectExpr()
+	if selectExpr == nil {
+		return 1
+	}
+
+	fieldName := selectExpr.GetField()
+	operand := selectExpr.GetOperand()
+
+	// Get the type of the operand from the type map
+	operandType := con.typeMap[operand.GetId()]
+	if operandType == nil {
+		return 1
+	}
+
+	// Extract the type name (e.g., "TestTable" from the object type)
+	typeName := operandType.GetMessageType()
+	if typeName == "" {
+		return 1
+	}
+
+	// Look up the schema by type name
+	schema, ok := con.schemas[typeName]
+	if !ok {
+		return 1
+	}
+
+	// Find the field in the schema
+	field, found := schema.FindField(fieldName)
+	if !found || !field.Repeated {
+		return 1
+	}
+
+	// If dimensions is explicitly set and > 0, use it
+	if field.Dimensions > 0 {
+		return field.Dimensions
+	}
+
+	// Otherwise default to 1
+	return 1
+}
+
 func (con *converter) visitCall(expr *exprpb.Expr) error {
 	// Check for context cancellation before processing function calls
 	if err := con.checkContext(); err != nil {
@@ -1770,15 +1821,18 @@ func (con *converter) visitCallFunc(expr *exprpb.Expr) error {
 					con.str.WriteString("), 0)")
 					return nil
 				}
-				// For PostgreSQL, we need to specify the array dimension (1 for 1D arrays)
+				// For PostgreSQL, we need to specify the array dimension
+				// Detect the dimension from schema if available, otherwise default to 1
+				dimension := con.getArrayDimension(argExpr)
+
 				// Wrap in COALESCE to handle NULL arrays (ARRAY_LENGTH returns NULL for NULL input)
 				con.str.WriteString("COALESCE(ARRAY_LENGTH(")
 				nested := isBinaryOrTernaryOperator(argExpr)
 				err := con.visitMaybeNested(argExpr, nested)
 				if err != nil {
 					return err
 				}
-				con.str.WriteString(", 1), 0)")
+				con.str.WriteString(fmt.Sprintf(", %d), 0)", dimension))
 				return nil
 			default:
 				return newConversionErrorf(errMsgUnsupportedType, "size() argument type: %s", argType.String())

multidim_array_test.go

@@ -0,0 +1,203 @@
+package cel2sql
+
+import (
+	"testing"
+
+	"github.com/google/cel-go/cel"
+	"github.com/spandigital/cel2sql/v3/pg"
+)
+
+// TestMultiDimensionalArrays tests size() function with multi-dimensional arrays
+func TestMultiDimensionalArrays(t *testing.T) {
+	// Create schema with arrays of different dimensions
+	schema := pg.NewSchema([]pg.FieldSchema{
+		{Name: "tags", Type: "text", Repeated: true, Dimensions: 1},         // 1D array
+		{Name: "matrix", Type: "integer", Repeated: true, Dimensions: 2},    // 2D array
+		{Name: "cube", Type: "integer", Repeated: true, Dimensions: 3},      // 3D array
+		{Name: "hypercube", Type: "integer", Repeated: true, Dimensions: 4}, // 4D array
+		{Name: "simple_array", Type: "text", Repeated: true, Dimensions: 0}, // Dimension not set (defaults to 1)
+		{Name: "id", Type: "integer", Repeated: false, Dimensions: 0},       // Not an array
+	})
+
+	provider := pg.NewTypeProvider(map[string]pg.Schema{"TestTable": schema})
+
+	env, err := cel.NewEnv(
+		cel.CustomTypeProvider(provider),
+		cel.Variable("data", cel.ObjectType("TestTable")),
+	)
+	if err != nil {
+		t.Fatalf("failed to create CEL environment: %v", err)
+	}
+
+	tests := []struct {
+		name        string
+		cel         string
+		expectedSQL string
+		expectedDim int
+		description string
+	}{
+		{
+			name:        "1D array size",
+			cel:         "size(data.tags) > 0",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(data.tags, 1), 0) > 0",
+			expectedDim: 1,
+			description: "1D array should use dimension 1",
+		},
+		{
+			name:        "2D array size",
+			cel:         "size(data.matrix) > 0",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(data.matrix, 2), 0) > 0",
+			expectedDim: 2,
+			description: "2D array should use dimension 2",
+		},
+		{
+			name:        "3D array size",
+			cel:         "size(data.cube) == 5",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(data.cube, 3), 0) = 5",
+			expectedDim: 3,
+			description: "3D array should use dimension 3",
+		},
+		{
+			name:        "4D array size",
+			cel:         "size(data.hypercube) < 10",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(data.hypercube, 4), 0) < 10",
+			expectedDim: 4,
+			description: "4D array should use dimension 4",
+		},
+		{
+			name:        "array with no dimension set defaults to 1",
+			cel:         "size(data.simple_array) > 0",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(data.simple_array, 1), 0) > 0",
+			expectedDim: 1,
+			description: "Array with Dimensions=0 should default to dimension 1",
+		},
+		{
+			name:        "complex expression with 2D array",
+			cel:         "size(data.matrix) >= 3 && size(data.matrix) <= 10",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(data.matrix, 2), 0) >= 3 AND COALESCE(ARRAY_LENGTH(data.matrix, 2), 0) <= 10",
+			expectedDim: 2,
+			description: "Complex expressions should maintain correct dimension",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ast, issues := env.Compile(tt.cel)
+			if issues != nil && issues.Err() != nil {
+				t.Fatalf("failed to compile CEL: %v", issues.Err())
+			}
+
+			sql, err := Convert(ast, WithSchemas(map[string]pg.Schema{"TestTable": schema}))
+			if err != nil {
+				t.Fatalf("failed to convert to SQL: %v", err)
+			}
+
+			if sql != tt.expectedSQL {
+				t.Errorf("unexpected SQL for %s:\n  got:  %s\n  want: %s", tt.description, sql, tt.expectedSQL)
+			}
+
+			t.Logf("✓ %s: ARRAY_LENGTH(..., %d)", tt.description, tt.expectedDim)
+		})
+	}
+}
+
+// TestMultiDimensionalArrayBackwardCompatibility ensures that existing 1D array behavior is preserved
+func TestMultiDimensionalArrayBackwardCompatibility(t *testing.T) {
+	tests := []struct {
+		name        string
+		cel         string
+		expectedSQL string
+	}{
+		{
+			name:        "size without schema - defaults to 1D",
+			cel:         "size(string_list) > 0",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(string_list, 1), 0) > 0",
+		},
+		{
+			name:        "size in complex expression - defaults to 1D",
+			cel:         "size(items) >= 2 && size(items) <= 5",
+			expectedSQL: "COALESCE(ARRAY_LENGTH(items, 1), 0) >= 2 AND COALESCE(ARRAY_LENGTH(items, 1), 0) <= 5",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Create environment with variables declared but no schema
+			env, err := cel.NewEnv(
+				cel.Variable("string_list", cel.ListType(cel.StringType)),
+				cel.Variable("items", cel.ListType(cel.IntType)),
+			)
+			if err != nil {
+				t.Fatalf("failed to create CEL environment: %v", err)
+			}
+
+			ast, issues := env.Compile(tt.cel)
+			if issues != nil && issues.Err() != nil {
+				t.Fatalf("failed to compile CEL: %v", issues.Err())
+			}
+
+			// Convert WITHOUT providing schema - should default to dimension 1
+			sql, err := Convert(ast)
+			if err != nil {
+				t.Fatalf("failed to convert to SQL: %v", err)
+			}
+
+			if sql != tt.expectedSQL {
+				t.Errorf("backward compatibility failed:\n  got:  %s\n  want: %s", sql, tt.expectedSQL)
+			}
+
+			t.Logf("✓ Backward compatible: defaults to dimension 1 when no schema")
+		})
+	}
+}
+
+// TestExplicitDimensionOverridesDefault tests that explicitly setting Dimensions to 1 works correctly
+func TestExplicitDimensionOverridesDefault(t *testing.T) {
+	// Schema with explicitly set Dimensions=1
+	schemaExplicit := pg.NewSchema([]pg.FieldSchema{
+		{Name: "tags", Type: "text", Repeated: true, Dimensions: 1},
+	})
+
+	// Schema with Dimensions=0 (not set, should use 1 as default)
+	schemaImplicit := pg.NewSchema([]pg.FieldSchema{
+		{Name: "tags", Type: "text", Repeated: true, Dimensions: 0},
+	})
+
+	provider1 := pg.NewTypeProvider(map[string]pg.Schema{"TestTable": schemaExplicit})
+	provider2 := pg.NewTypeProvider(map[string]pg.Schema{"TestTable": schemaImplicit})
+
+	env1, _ := cel.NewEnv(
+		cel.CustomTypeProvider(provider1),
+		cel.Variable("data", cel.ObjectType("TestTable")),
+	)
+
+	env2, _ := cel.NewEnv(
+		cel.CustomTypeProvider(provider2),
+		cel.Variable("data", cel.ObjectType("TestTable")),
+	)
+
+	celExpr := "size(data.tags) > 0"
+	expectedSQL := "COALESCE(ARRAY_LENGTH(data.tags, 1), 0) > 0"
+
+	// Test with explicit Dimensions=1
+	ast1, _ := env1.Compile(celExpr)
+	sql1, err := Convert(ast1, WithSchemas(map[string]pg.Schema{"TestTable": schemaExplicit}))
+	if err != nil {
+		t.Fatalf("failed with explicit dimension: %v", err)
+	}
+	if sql1 != expectedSQL {
+		t.Errorf("explicit Dimensions=1 failed:\n  got:  %s\n  want: %s", sql1, expectedSQL)
+	}
+
+	// Test with implicit Dimensions=0 (should default to 1)
+	ast2, _ := env2.Compile(celExpr)
+	sql2, err := Convert(ast2, WithSchemas(map[string]pg.Schema{"TestTable": schemaImplicit}))
+	if err != nil {
+		t.Fatalf("failed with implicit dimension: %v", err)
+	}
+	if sql2 != expectedSQL {
+		t.Errorf("implicit Dimensions=0 (default) failed:\n  got:  %s\n  want: %s", sql2, expectedSQL)
+	}
+
+	t.Log("✓ Both explicit Dimensions=1 and implicit Dimensions=0 default to dimension 1")
+}