INSERT multi-dimensional arrays

Author: serprex

CHANGELOG.md

@@ -27,6 +27,12 @@ ALTER EXTENSION pg_clickhouse UPDATE TO '0.3';
 *   Added pushdown for [fuzzystrmatch] functions `soundex()` and
     `levenshtein()` (2-arg, mapped to `editDistance`).  Thanks to
     Philip Dubé for the PR ([#210]).
+*   Added multidimensional array support across SELECT and INSERT in both the
+    binary and http engines. Rectangular ClickHouse `Array(Array(...))` values
+    now map to PostgreSQL multidimensional arrays, jagged arrays not supported,
+    and PostgreSQL multidimensional arrays inserted into ClickHouse
+    `Array(Array(...))` columns preserve their nesting. Thanks to Philip Dubé
+    for the PR ([#233]).
 
 ### 🐞 Bug Fixes
 
@@ -89,10 +95,10 @@ ALTER EXTENSION pg_clickhouse UPDATE TO '0.3';
     "ClickHouse/pg_clickhouse#235 Detect TSV NULL marker before unescaping"
   [#231]: https://github.com/ClickHouse/pg_clickhouse/pull/231
     "ClickHouse/pg_clickhouse#231 Fix column_name option not being respected by inserts"
-  [#223]: https://github.com/ClickHouse/pg_clickhouse/pull/223
-    "pg_clickhouse#223 Fix EXPLAIN (VERBOSE) for window functions"
   [#228]: https://github.com/ClickHouse/pg_clickhouse/pull/228
-    "pg_clickhouse#228 Security: revoke PUBLIC execute on clickhouse_raw_query"
+    "ClickHouse/pg_clickhouse#228 Security: revoke PUBLIC execute on clickhouse_raw_query"
+  [#233]: https://github.com/ClickHouse/pg_clickhouse/pull/233
+    "ClickHouse/pg_clickhouse#233 Support multidimensional arrays"
 
 ## [v0.2.0] — 2026-04-13
 

src/binary.cpp

@@ -440,6 +440,57 @@ extern "C"
 		state->insert_block = (ch_insert_block_h *)block;
 	}
 
+	static void
+	column_append(clickhouse::ColumnRef col, Datum val, Oid valtype, bool isnull);
+
+	/*
+	 * Build a single ColumnArray row's worth of data from a (possibly nested)
+	 * ch_binary_array_t. items_type is the per-row element type of the parent
+	 * ColumnArray: scalar T for Array(T), Array(T) for Array(Array(T)), etc.
+	 *
+	 * For nested types, recurses to build child ColumnArrays and stitches them
+	 * via AppendAsColumn so the outer column's offsets describe the row shape.
+	 */
+	static clickhouse::ColumnRef
+	build_array_row_column(ch_binary_array_t *arr, clickhouse::TypeRef items_type)
+	{
+		using namespace clickhouse;
+
+		auto col = CreateColumnByType(items_type->GetName());
+
+		/* Empty postgres array fits any nesting depth: nothing to walk, so
+		 * skip the dim check and return an empty column at this level. */
+		if (arr->len == 0)
+			return col;
+
+		if (items_type->GetCode() == Type::Code::Array)
+		{
+			if (arr->ndim < 2)
+				throw std::runtime_error(
+				  "pg_clickhouse: insert array has fewer dimensions than column type");
+
+			auto inner_arr	   = col->AsStrict<ColumnArray>();
+			auto inner_items_t = items_type->As<clickhouse::ArrayType>()->GetItemType();
+
+			for (size_t i = 0; i < arr->len; i++)
+			{
+				auto child = (ch_binary_array_t *)DatumGetPointer(arr->datums[i]);
+				auto sub   = build_array_row_column(child, inner_items_t);
+
+				inner_arr->AppendAsColumn(sub);
+			}
+			return col;
+		}
+
+		if (arr->ndim != 1)
+			throw std::runtime_error(
+			  "pg_clickhouse: insert array has more dimensions than column type");
+
+		for (size_t i = 0; i < arr->len; i++)
+			column_append(col, arr->datums[i], arr->item_type, arr->nulls[i]);
+		return col;
+	}
+
 	static void
 	column_append(clickhouse::ColumnRef col, Datum val, Oid valtype, bool isnull)
 	{
@@ -667,13 +718,12 @@ extern "C"
 					case Type::Array:
 					{
 						auto arrcol = col->AsStrict<ColumnArray>();
-						auto items
-						= CreateColumnByType(arrcol->GetType().As<clickhouse::ArrayType>()->GetItemType()->GetName());
-						auto arr = (ch_binary_array_t *)DatumGetPointer(val);
-						for (size_t i = 0; i < arr->len; i++)
-							column_append(items, arr->datums[i], arr->item_type, arr->nulls[i]);
+						auto items_type
+						= arrcol->GetType().As<clickhouse::ArrayType>()->GetItemType();
+						auto arr	  = (ch_binary_array_t *)DatumGetPointer(val);
+						auto one_row = build_array_row_column(arr, items_type);
 
-						arrcol->AppendAsColumn(items);
+						arrcol->AppendAsColumn(one_row);
 						break;
 					}
 					default:

src/convert.c

@@ -219,7 +219,7 @@ convert_array(ch_convert_state * state, Datum val)
 
 	if (slot->len == 0)
 		val = PointerGetDatum(construct_empty_array(slot->item_type));
-	else if (slot->ndim == 1)
+	else if (slot->ndim <= 1)
 	{
 		void	   *arrout = construct_array(slot->datums, slot->len, slot->item_type,
 											 state->typlen, state->typbyval, state->typalign);
@@ -611,6 +611,49 @@ ch_binary_make_tuple_map(TupleDesc indesc, TupleDesc outdesc, Oid relid)
 	return states;
 }
 
+/*
+ * Chunk a flat postgres array (already extracted into `flat`/`flatnulls` in
+ * row-major order) into the nested ch_binary_array_t tree the binary engine
+ * expects for Array(Array(...)) columns. Each interior node carries
+ * ndim>1 with datums[i] = PointerGetDatum(child); leaves carry ndim==1 with
+ * scalar datums copied from the flat buffer.
+ */
+static ch_binary_array_t *
+build_nested_binary_array(int level, int ndim, int *dims, Oid item_type,
+						  Datum * flat, bool *flatnulls, size_t * idx)
+{
+	ch_binary_array_t *arr = palloc(sizeof(ch_binary_array_t));
+
+	arr->len = dims[level];
+	arr->ndim = ndim - level;
+	arr->item_type = item_type;
+	arr->array_type = InvalidOid;
+	arr->datums = palloc(sizeof(Datum) * arr->len);
+	arr->nulls = palloc0(sizeof(bool) * arr->len);
+
+	if (level + 1 == ndim)
+	{
+		for (size_t i = 0; i < arr->len; i++)
+		{
+			arr->datums[i] = flat[*idx];
+			arr->nulls[i] = flatnulls[*idx];
+			(*idx)++;
+		}
+	}
+	else
+	{
+		for (size_t i = 0; i < arr->len; i++)
+		{
+			ch_binary_array_t *child = build_nested_binary_array(level + 1, ndim, dims,
+																 item_type, flat,
+																 flatnulls, idx);
+
+			arr->datums[i] = PointerGetDatum(child);
+		}
+	}
+	return arr;
+}
+
 void
 ch_binary_do_output_conversion(ch_binary_insert_state * insert_state,
 							   TupleTableSlot * slot)
@@ -633,24 +676,51 @@ ch_binary_do_output_conversion(ch_binary_insert_state * insert_state,
 				AnyArrayType *v = DatumGetAnyArrayP(out_values[i]);
 				ch_binary_array_t *arr;
 				array_iter	iter;
+				int			ndim = AARR_NDIM(v);
+				int		   *dims = AARR_DIMS(v);
+				size_t		total = ArrayGetNItems(ndim, dims);
 
-				if (AARR_NDIM(v) > 1)
+				if (ndim > MAXDIM)
 					ereport(ERROR,
-							(errcode(ERRCODE_DATATYPE_MISMATCH),
-							 errmsg("pg_clickhouse: inserted array should have one dimension")));
-
-				arr = palloc(sizeof(ch_binary_array_t));
-				arr->len = ArrayGetNItems(AARR_NDIM(v), AARR_DIMS(v));
-				arr->ndim = 1;
-				arr->datums = palloc(sizeof(Datum) * arr->len);
-				arr->nulls = palloc(sizeof(bool) * arr->len);
-				arr->item_type = cstate->innertype;
-
-				array_iter_setup(&iter, v);
-				for (size_t j = 0; j < arr->len; j++)
+							(errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),
+							 errmsg("pg_clickhouse: inserted array depth %d exceeds maximum %d",
+									ndim, MAXDIM)));
+
+				if (ndim <= 1)
+				{
+					arr = palloc(sizeof(ch_binary_array_t));
+					arr->len = total;
+					arr->ndim = 1;
+					arr->item_type = cstate->innertype;
+					arr->array_type = InvalidOid;
+					arr->datums = total ? palloc(sizeof(Datum) * total) : NULL;
+					arr->nulls = total ? palloc(sizeof(bool) * total) : NULL;
+
+					array_iter_setup(&iter, v);
+					for (size_t j = 0; j < total; j++)
+					{
+						arr->datums[j] = array_iter_next(&iter, &arr->nulls[j], j,
+														 cstate->typlen, cstate->typbyval, cstate->typalign);
+					}
+				}
+				else
 				{
-					arr->datums[j] = array_iter_next(&iter, &arr->nulls[j], i,
-													 cstate->typlen, cstate->typbyval, cstate->typalign);
+					Datum	   *flat = palloc(sizeof(Datum) * total);
+					bool	   *flatnulls = palloc0(sizeof(bool) * total);
+					size_t		idx = 0;
+
+					array_iter_setup(&iter, v);
+					for (size_t j = 0; j < total; j++)
+					{
+						flat[j] = array_iter_next(&iter, &flatnulls[j], j,
+												  cstate->typlen, cstate->typbyval, cstate->typalign);
+					}
+
+					arr = build_nested_binary_array(0, ndim, dims, cstate->innertype,
+													flat, flatnulls, &idx);
+
+					pfree(flat);
+					pfree(flatnulls);
 				}
 				out_values[i] = PointerGetDatum(arr);