feat: EXPOSED-359 Add support for multidimensional arrays

[obabichevjb]

Description

Summary of the change: Added support for multi-dimensional array types in Exposed for PostgreSQL database.

Detailed description:

• What: This PR introduces new functions and types for supporting multi-dimensional arrays. Specifically, it includes the multi2Array, multi3Array, and multiArray functions for defining multi-dimensional array columns. It also adds corresponding literal functions multi2ArrayLiteral, multi3ArrayLiteral, and multiArrayLiteral.

---

Type of Change

Please mark the relevant options with an "X":

• New feature
• Documentation update

Updates/remove existing public API methods:

• Is breaking change

Affected databases:

• Postgres

---

Related Issues

EXPOSED-359 Add support for multidimensional arrays

[obabichevjb]

I called new column type MultiArrayColumnType, column creator functions multiArray, multi2Array, multi3Array, and literals multi2ArrayLiteral, multi3ArrayLiteral, multiArrayLiteral, but it's discussible, I'm open for other options.

[bog-walk]

Left comments about documentation and examples with breaking changes. Please also update title with feat!:.

It'd probably also be best to get other opinions about the naming of these new columns.

Current proposal is:

// existing 1D type
val col1 = array<Int>("col1")
// new types
val col2 = array2<Int>("col2") // 2D
val col3 = array3<Int>("col3") // 3D
val col4 = arrayN<Int, List<List<List<List<Int>>>>>("col4", 4) // 4D

To me, the hanging numbers at the end look incomplete. Also most other ORMs have a single array() that can take 1+ dimensions, so I'm proposing something like:

// overload existing type to default to 1, unless arg passed to 'dimensions'
val col1 = array<Int>("col1")
val col4 = array<Int, List<List<List<List<Int>>>>>("col4", 4)

val col2 = array2d<Int>("col2")
val col3 = array3d<Int>("col3") 

Other options could maybe be array2D(), array2Multi(), array2Dim().

@e5l @joc-a Could you please let us know if you have suggestions/thoughts?

[bog-walk]

Small type in second line.

[bog-walk]

Please review these blocks through the Writerside plugin, as there are many errors and column types are not appearing. For example, 'code-block's do not accept nested < or >, since they will be confused for html tags. You need to use <, >, and " or wrap the entire code in <![CDATA[]]>. Please see previous blocks in file.

Also please fix indentation.

[bog-walk]

I personally think this would be better placed directly as a sub-chapter under 'How to use Array Types', before sub-chapter on functions. That way you could then add an example of using a function with nD arrays in the function section after.

[bog-walk]

Imo it looks cleaner if both of them are called arrayLiteral() (same for arrayParam(). Allows easy switch if user wants to for some reason use multi- instead and didn't cause any issues with the overload.
Could you also consider moving dimensions to before the default delegateType, so it doesn't always have to be named when invoked without delegate?

[bog-walk]

Is there a reason that dimensions can't be given a default value of 1?
If there is, then at minimum this needs to be included in the breaking changes doc.
Anybody that uses ArrayColumnType in custom function will now need to add a value for dimensions, for example:

class ArrayAggFunction<T>(
    expression: ExpressionWithColumnType<T>,
    delegate: ColumnType<T & Any>
) : CustomFunction<List<T>>(
    functionName = "ARRAY_AGG",
    columnType = ArrayColumnType(delegate), // won't compile anymore unless dimensions value passed
    expr = arrayOf(expression)
)

[bog-walk]

I'm a bit confused by changes to maximumCardinality. I guess I see why the type had to change, even though it isn't used by PostgreSQL and PostgreSQL is the only db that supports multiple-dimensions (but I can see that may change).

From the line above, it sounds like Exposed is going to do some validation. Did you mean to maybe override validateValueBeforeUpdate() here?

If not, then maybe the line should say: "Any validation should be implemented on the client side."

[bog-walk]

If type must change, this is another breaking change that should be mentioned in docs.
If ArrayColumnType instance was being used with original value, it will now be mistaken as dimensions or cause type does not conform error:

class ArrayAggFunction<T>(
    expression: ExpressionWithColumnType<T>,
    delegate: ColumnType<T & Any>
) : CustomFunction<List<T>>(
    functionName = "ARRAY_AGG",
    columnType = ArrayColumnType(delegate, 5), // will compile but argument will be now wrongly for dimensions
    expr = arrayOf(expression)
)

class ArrayAggFunction<T>(
    expression: ExpressionWithColumnType<T>,
    delegate: ColumnType<T & Any>
) : CustomFunction<List<T>>(
    functionName = "ARRAY_AGG",
    columnType = ArrayColumnType(delegate, maximumCardinality = 5), // won't compile
    expr = arrayOf(expression)
)

[bog-walk]

Same comment about validation as in previous file.

[bog-walk]

I'd suggest discussing naming options with the rest of the team too.
To me, there's something odd about a hanging number at the end array2<Int>(). I'd still vote for array2d() or maybe even array2Multi() or array2Dim().

[bog-walk]

Same comment as for arrayLiteral() and arrayParam(). I think it would be cleaner to have single-named array() that has multiple overloads with/without dimensions.