Add Tuple support

Author: evertlammerts

_duckdb-stubs/_typing.pyi

@@ -133,7 +133,7 @@ Note:
     We use lowercase here to be able to reuse this `Literal` in the `DTypeIdentifiers` `Literal`.
 """
 
-NestedIds: TypeAlias = Literal["list", "struct", "array", "enum", "map", "decimal", "union"]
+NestedIds: TypeAlias = Literal["list", "struct", "tuple", "array", "enum", "map", "decimal", "union"]
 """Identifiers for nested types in `DuckDBPyType.id`."""
 
 PyTypeIds: TypeAlias = Builtins | NestedIds

duckdb/experimental/spark/sql/type_utils.py

@@ -94,7 +94,7 @@ def convert_nested_type(dtype: DuckDBPyType) -> DataType:  # noqa: D103
             "DuckDB union types cannot be directly mapped to PySpark types."
         )
         raise ContributionsAcceptedError(msg)
-    if id == "struct":
+    if id == "struct" or id == "tuple":
         children: list[tuple[str, DuckDBPyType]] = dtype.children
         fields = [StructField(x[0], convert_type(x[1])) for x in children]
         return StructType(fields)
@@ -105,7 +105,7 @@ def convert_nested_type(dtype: DuckDBPyType) -> DataType:  # noqa: D103
 
 def convert_type(dtype: DuckDBPyType) -> DataType:  # noqa: D103
     id = dtype.id
-    if id in ["list", "struct", "map", "array"]:
+    if id in ["list", "struct", "tuple", "map", "array"]:
         return convert_nested_type(dtype)
     if id == "decimal":
         children: list[tuple[str, DuckDBPyType]] = dtype.children

external/duckdb

@@ -117,7 +117,7 @@ Value TransformDictionaryToStruct(optional_ptr<ClientContext> context, const PyD
                                   const LogicalType &target_type = LogicalType::UNKNOWN) {
 	auto struct_keys = TransformStructKeys(dict.keys, dict.len, target_type);
 
-	bool struct_target = target_type.id() == LogicalTypeId::STRUCT;
+	bool struct_target = target_type.id() == LogicalTypeId::STRUCT || target_type.id() == LogicalTypeId::TUPLE;
 	if (struct_target && dict.len != StructType::GetChildCount(target_type)) {
 		throw InvalidInputException("We could not convert the object %s to the desired target type (%s)",
 		                            dict.ToString(), target_type.ToString());
@@ -252,7 +252,7 @@ Value TransformTupleToStruct(optional_ptr<ClientContext> context, py::handle ele
 	auto tuple = py::cast<py::tuple>(ele);
 	auto size = py::len(tuple);
 
-	D_ASSERT(target_type.id() == LogicalTypeId::STRUCT);
+	D_ASSERT(target_type.id() == LogicalTypeId::STRUCT || target_type.id() == LogicalTypeId::TUPLE);
 	auto child_types = StructType::GetChildTypes(target_type);
 	auto child_count = child_types.size();
 	if (size != child_count) {
@@ -558,7 +558,7 @@ struct PythonValueConversion {
 
 	static void HandleTuple(optional_ptr<ClientContext> context, Value &result, const LogicalType &target_type,
 	                        py::handle ele, idx_t list_size) {
-		if (target_type.id() == LogicalTypeId::STRUCT) {
+		if (target_type.id() == LogicalTypeId::STRUCT || target_type.id() == LogicalTypeId::TUPLE) {
 			result = TransformTupleToStruct(context, ele, target_type);
 			return;
 		}
@@ -584,6 +584,7 @@ struct PythonValueConversion {
 			PyDictionary dict = PyDictionary(py::reinterpret_borrow<py::object>(ele));
 			switch (target_type.id()) {
 			case LogicalTypeId::STRUCT:
+			case LogicalTypeId::TUPLE:
 				return TransformDictionaryToStruct(context, dict, target_type);
 			case LogicalTypeId::MAP:
 				return TransformDictionaryToMap(context, dict, target_type);
@@ -886,6 +887,7 @@ struct PythonVectorConversion {
 		auto &result_type = result.GetType();
 		switch (result_type.id()) {
 		case LogicalTypeId::STRUCT:
+		case LogicalTypeId::TUPLE:
 			ConvertTupleToStruct(context, result, result_offset, ele, tuple_size);
 			break;
 		case LogicalTypeId::ARRAY:
@@ -981,6 +983,7 @@ void TransformPythonObjectInternal(optional_ptr<ClientContext> context, py::hand
 		auto &conversion_target = OP::ConversionTarget(result, param);
 		switch (conversion_target.id()) {
 		case LogicalTypeId::STRUCT:
+		case LogicalTypeId::TUPLE:
 		case LogicalTypeId::UNKNOWN:
 		case LogicalTypeId::LIST:
 		case LogicalTypeId::ARRAY:

src/duckdb_py/native/python_conversion.cpp

@@ -461,6 +461,7 @@ static bool KeyIsHashable(const LogicalType &type) {
 		return true;
 	}
 	case LogicalTypeId::STRUCT:
+	case LogicalTypeId::TUPLE:
 		return false;
 	case LogicalTypeId::SQLNULL:
 		// A SQLNULL key is always NULL, and Python's None is hashable.
@@ -692,7 +693,8 @@ py::object PythonObject::FromValue(const Value &val, const LogicalType &type,
 		}
 		return std::move(py_struct);
 	}
-	case LogicalTypeId::STRUCT: {
+	case LogicalTypeId::STRUCT:
+	case LogicalTypeId::TUPLE: {
 		return FromStruct(val, type, client_properties);
 	}
 	case LogicalTypeId::UUID: {

src/duckdb_py/native/python_objects.cpp

@@ -295,21 +295,10 @@ struct ArrayConvert {
 };
 
 struct StructConvert {
-	static py::dict ConvertValue(Vector &input, idx_t chunk_offset, NumpyAppendData &append_data) {
-		auto &client_properties = append_data.client_properties;
-
-		py::dict py_struct;
+	// Delegate to FromStruct so unnamed structs / TUPLE values become Python tuples (named ones stay dicts).
+	static py::object ConvertValue(Vector &input, idx_t chunk_offset, NumpyAppendData &append_data) {
 		auto val = input.GetValue(chunk_offset);
-		auto &child_types = StructType::GetChildTypes(input.GetType());
-		auto &struct_children = StructValue::GetChildren(val);
-
-		for (idx_t i = 0; i < struct_children.size(); i++) {
-			auto &child_entry = child_types[i];
-			auto &child_name = child_entry.first;
-			auto &child_type = child_entry.second;
-			py_struct[child_name.c_str()] = PythonObject::FromValue(struct_children[i], child_type, client_properties);
-		}
-		return py_struct;
+		return PythonObject::FromStruct(val, input.GetType(), append_data.client_properties);
 	}
 };
 
@@ -714,6 +703,7 @@ void ArrayWrapper::Append(idx_t current_offset, Vector &input, idx_t source_size
 		may_have_null = ConvertNested<py::object, duckdb_py_convert::UnionConvert>(append_data);
 		break;
 	case LogicalTypeId::STRUCT:
+	case LogicalTypeId::TUPLE:
 		may_have_null = ConvertNested<py::object, duckdb_py_convert::StructConvert>(append_data);
 		break;
 	case LogicalTypeId::VARIANT:

src/duckdb_py/numpy/array_wrapper.cpp

@@ -58,6 +58,7 @@ static idx_t GetNumpyTypeWidth(const LogicalType &type) {
 	case LogicalTypeId::LIST:
 	case LogicalTypeId::MAP:
 	case LogicalTypeId::STRUCT:
+	case LogicalTypeId::TUPLE:
 	case LogicalTypeId::UNION:
 	case LogicalTypeId::UUID:
 	case LogicalTypeId::ARRAY:
@@ -124,6 +125,7 @@ string RawArrayWrapper::DuckDBToNumpyDtype(const LogicalType &type) {
 	case LogicalTypeId::LIST:
 	case LogicalTypeId::MAP:
 	case LogicalTypeId::STRUCT:
+	case LogicalTypeId::TUPLE:
 	case LogicalTypeId::UNION:
 	case LogicalTypeId::UUID:
 	case LogicalTypeId::ARRAY:

src/duckdb_py/numpy/raw_array_wrapper.cpp

@@ -51,7 +51,7 @@ bool DuckDBPyType::EqualsString(const string &type_str) const {
 
 std::shared_ptr<DuckDBPyType> DuckDBPyType::GetAttribute(const string &name) const {
 	auto name_identifier = Identifier(name);
-	if (type.id() == LogicalTypeId::STRUCT || type.id() == LogicalTypeId::UNION) {
+	if (type.id() == LogicalTypeId::STRUCT || type.id() == LogicalTypeId::TUPLE || type.id() == LogicalTypeId::UNION) {
 		auto &children = StructType::GetChildTypes(type);
 		for (idx_t i = 0; i < children.size(); i++) {
 			auto &child = children[i];
@@ -372,6 +372,7 @@ py::list DuckDBPyType::Children() const {
 	switch (type.id()) {
 	case LogicalTypeId::LIST:
 	case LogicalTypeId::STRUCT:
+	case LogicalTypeId::TUPLE:
 	case LogicalTypeId::UNION:
 	case LogicalTypeId::MAP:
 	case LogicalTypeId::ARRAY:
@@ -403,7 +404,7 @@ py::list DuckDBPyType::Children() const {
 		children.append(py::make_tuple("values", strings_list));
 		return children;
 	}
-	if (id == LogicalTypeId::STRUCT || id == LogicalTypeId::UNION) {
+	if (id == LogicalTypeId::STRUCT || id == LogicalTypeId::TUPLE || id == LogicalTypeId::UNION) {
 		auto &struct_children = StructType::GetChildTypes(type);
 		for (idx_t i = 0; i < struct_children.size(); i++) {
 			auto &child = struct_children[i];

src/duckdb_py/typing/pytype.cpp

@@ -57,7 +57,7 @@ def test_parametrized_explain(self, duckdb_cursor):
         duckdb_cursor.execute(query, params)
 
         results = duckdb_cursor.fetchall()
-        assert "EXPLAIN_ANALYZE" in results[0][1]
+        assert "Total Time" in results[0][1]
 
     def test_named_param(self):
         con = duckdb.connect()

tests/fast/api/test_duckdb_query.py

@@ -135,5 +135,10 @@ def test_all_types_schema(self, spark):
                 ),
                 StructField("map", MapType(StringType(), StringType(), True), True),
                 StructField("time_ns", TimeNSType(), True),
+                StructField(
+                    "tuple",
+                    StructType([StructField("", IntegerType(), True), StructField("", StringType(), True)]),
+                    True,
+                ),
             ]
         )