docs: Add multi-dimensional array support documentation

Updated documentation across README, CHANGELOG, and CLAUDE.md:
- Added multi-dimensional arrays section to README with usage examples
- Updated Supported Features table to include multi-dim arrays
- Added comprehensive CHANGELOG entry for issue #49
- Enhanced CLAUDE.md with implementation details and type system info

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

Co-Authored-By: Claude <[email protected]>

Author: richardwooding

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+### Added
+- **Multi-Dimensional Array Support** (fixes #49)
+  - Added `Dimensions` field to `pg.FieldSchema` to store array dimensionality (1D, 2D, 3D, 4D+)
+  - Implemented `detectArrayDimensions()` to automatically detect dimensions from PostgreSQL type strings
+    * Supports bracket notation: `integer[]` (1D), `integer[][]` (2D), `integer[][][]` (3D)
+    * Supports underscore notation: `_int4` (1D), `_int4[]` (2D), `_int4[][]` (3D)
+    * Correctly combines both notations (e.g., `_int4[]` = 2D array)
+  - Updated `LoadTableSchema()` to query `udt_name` column and detect dimensions automatically
+  - Modified `getArrayDimension()` to use CEL typeMap for accurate type resolution
+  - Enhanced ARRAY_LENGTH SQL generation to use detected dimensions: `ARRAY_LENGTH(field, N)`
+  - Full backward compatibility: defaults to dimension 1 when no schema provided
+  - Comprehensive test coverage: 22 unit tests + integration tests for 1D-4D arrays
+  - Example: `size(matrix)` where `matrix integer[][]` → `COALESCE(ARRAY_LENGTH(matrix, 2), 0)`
+
 ## [3.4.0] - 2025-10-31
 
 ### Added

CLAUDE.md

@@ -104,11 +104,46 @@ The library uses CEL's protobuf-based type system (`exprpb.Type`, `exprpb.Expr`)
 **Structured Types:**
 - `json`, `jsonb` → `decls.Dyn` (with automatic JSON path support)
 - Arrays: Set `Repeated: true` in schema
+- Multi-dimensional arrays: Set `Repeated: true` and `Dimensions: N` in schema
 - Composite types: Use nested `Schema` fields
 
 **Unsupported Types:**
 Unknown PostgreSQL types (e.g., `point`, `polygon`, `box`, custom enums) will cause `FindStructFieldType()` to return `found=false`. This prevents silent type mismatches. Add explicit support for custom types or use composite type definitions.
 
+### Multi-Dimensional Array Support
+
+cel2sql supports PostgreSQL multi-dimensional arrays (1D, 2D, 3D, 4D+) with automatic dimension detection.
+
+**Dimension Detection:**
+- Automatically detects dimensions from PostgreSQL type strings via `detectArrayDimensions()`
+- Supports bracket notation: `integer[]` (1D), `integer[][]` (2D), `integer[][][]` (3D)
+- Supports underscore notation: `_int4` (1D), `_int4[]` (2D), `_int4[][]` (3D)
+- Correctly combines both notations (e.g., `_int4[]` = 2D: 1 from underscore + 1 from bracket)
+
+**Schema Definition:**
+```go
+schema := pg.NewSchema([]pg.FieldSchema{
+    {Name: "tags", Type: "text", Repeated: true, Dimensions: 1},      // 1D: text[]
+    {Name: "matrix", Type: "integer", Repeated: true, Dimensions: 2},  // 2D: integer[][]
+    {Name: "cube", Type: "float", Repeated: true, Dimensions: 3},      // 3D: float[][][]
+})
+```
+
+**SQL Generation:**
+- `size()` function automatically uses correct dimension in `ARRAY_LENGTH(field, dimension)`
+- Example: `size(matrix)` where `matrix integer[][]` → `COALESCE(ARRAY_LENGTH(matrix, 2), 0)`
+- Dimension lookup uses CEL typeMap for accurate type resolution in `getArrayDimension()`
+
+**Backward Compatibility:**
+- Arrays without schema information default to dimension 1
+- Explicit `Dimensions: 0` defaults to dimension 1
+- Existing code continues to work without changes
+
+**Implementation Details:**
+- `pg/provider.go`: Contains `detectArrayDimensions()` and dimension detection logic
+- `cel2sql.go`: Contains `getArrayDimension()` that uses CEL typeMap for lookup
+- `LoadTableSchema()`: Queries `udt_name` column to detect dimensions from database
+
 ### JSON/JSONB Support
 
 CEL field access on JSON/JSONB columns automatically converts to PostgreSQL JSON path operations:

README.md

@@ -315,6 +315,32 @@ user.scores.all(s, s >= 60)
 // SQL: NOT EXISTS (SELECT 1 FROM UNNEST(user.scores) AS s WHERE NOT (s >= 60))
 ```
 
+### 6. Multi-Dimensional Arrays
+
+cel2sql supports PostgreSQL multi-dimensional arrays (1D, 2D, 3D, 4D+) with automatic dimension detection:
+
+```go
+// Define schema with multi-dimensional arrays
+schema := pg.NewSchema([]pg.FieldSchema{
+    {Name: "tags", Type: "text", Repeated: true, Dimensions: 1},      // 1D: text[]
+    {Name: "matrix", Type: "integer", Repeated: true, Dimensions: 2},  // 2D: integer[][]
+    {Name: "cube", Type: "float", Repeated: true, Dimensions: 3},      // 3D: float[][][]
+})
+
+// CEL: size() automatically uses correct dimension
+ast, _ := env.Compile("size(data.matrix) > 0")
+// SQL: COALESCE(ARRAY_LENGTH(data.matrix, 2), 0) > 0
+
+// Or load dimensions automatically from database
+provider, _ := pg.NewTypeProviderWithConnection(ctx, connString)
+provider.LoadTableSchema(ctx, "products")  // Dimensions detected from schema
+```
+
+**Dimension Detection:**
+- Detects dimensions from PostgreSQL type strings (`integer[][]`, `_int4[]`)
+- Works with both bracket notation and underscore notation
+- Defaults to 1D for backward compatibility when no schema is provided
+
 ## Documentation
 
 - 📖 **[Getting Started Guide](docs/getting-started.md)** - Step-by-step tutorial
@@ -333,6 +359,7 @@ user.scores.all(s, s >= 60)
 | Logic | `active && verified` | `active IS TRUE AND verified IS TRUE` |
 | Strings | `name.startsWith("A")` | `name LIKE 'A%'` |
 | Lists | `"admin" in roles` | `'admin' IN UNNEST(roles)` |
+| Multi-Dim Arrays | `size(matrix) > 0` | `COALESCE(ARRAY_LENGTH(matrix, 2), 0) > 0` |
 | JSON | `data.key == "value"` | `data->>'key' = 'value'` |
 | Regex | `email.matches(r".*@test\.com")` | `email ~ '.*@test\.com'` |
 | Dates | `created_at.getFullYear() == 2024` | `EXTRACT(YEAR FROM created_at) = 2024` |