Add Array and List datatypes

[elbakramer]

Summary

Adds two composite types, Array and List, for DuckDB's fixed-size and variable-length array types, based on sqlalchemy.types.ARRAY.

Motivation

The standard sqlalchemy.types.ARRAY always compiles to variable-length arrays in DuckDB (e.g., FLOAT[]). This made it impossible to create fixed-size array columns when using SQLModel ORM, which is important for use cases like embedding vectors where the dimension must be fixed.

Before this PR:

from uuid import UUID, uuid4
from sqlmodel import ARRAY, FLOAT, Column, Field, SQLModel

class Element(SQLModel, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    text: str
    embedding: list[float] = Field(
        min_items=EMBEDDING_SIZE,
        max_items=EMBEDDING_SIZE,
        sa_column=Column(ARRAY(FLOAT)),  # Creates FLOAT[] (variable-length)
    )

With this PR:

from uuid import UUID, uuid4
from sqlmodel import FLOAT, Column, Field, SQLModel
from duckdb_engine.datatypes import Array

class Element(SQLModel, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    text: str
    embedding: list[float] = Field(
        min_items=EMBEDDING_SIZE,
        max_items=EMBEDDING_SIZE,
        sa_column=Column(Array(FLOAT, EMBEDDING_SIZE)),  # Creates FLOAT[EMBEDDING_SIZE] (fixed-size)
    )

Implementation

• Array: Fixed-size arrays, compiles to TYPE[size] (e.g., FLOAT[384])

  • Supports multi-dimensional arrays: Array(String, [2, 3]) → VARCHAR[2][3]
  • Validates that size dimensions match

• List: Variable-length lists, compiles to TYPE[] (e.g., VARCHAR[])

  • Equivalent to standard SQLAlchemy ARRAY behavior, but explicit for DuckDB

Both follow the same pattern as existing composite types (Struct, Map, Union).

Changes

• duckdb_engine/datatypes.py: Add Array and List classes with DuckDB-specific compilers
• duckdb_engine/tests/test_datatypes.py: Add test coverage for both types
• Minor cleanup: Fix missing closing parentheses in Struct, Map, and Union docstrings

Related

DuckDB documentation:

• https://duckdb.org/docs/stable/sql/data_types/overview#nested--composite-types
• https://duckdb.org/docs/stable/core_extensions/vss