feat: Support passing struct data to the DB API

google/cloud/bigquery/dbapi/_helpers.py

@@ -302,6 +302,24 @@ def complex_query_parameter(
     return param
 
 
+def _dispatch_parameter(type_, value, name=None):
+    if type_ is not None and "<" in type_:
+        param = complex_query_parameter(name, value, type_)
+    elif isinstance(value, collections_abc.Mapping):
+        raise NotImplementedError(
+            f"STRUCT-like parameter values are not supported"
+            f"{' (parameter ' + name + ')' if name else ''},"
+            f" unless an explicit type is give in the parameter placeholder"
+            f" (e.g. '%({name if name else ''}:struct<...>)s')."
+            )
+    elif array_like(value):
+        param = array_to_query_parameter(value, name, type_)
+    else:
+        param = scalar_to_query_parameter(value, name, type_)
+
+    return param
+
+
 def to_query_parameters_list(parameters, parameter_types):
     """Converts a sequence of parameter values into query parameters.
 
@@ -315,21 +333,9 @@ def to_query_parameters_list(parameters, parameter_types):
         List[google.cloud.bigquery.query._AbstractQueryParameter]:
             A list of query parameters.
     """
-    result = []
-
-    for value, type_ in zip(parameters, parameter_types):
-        if type_ is not None and "<" in type_:
-            param = complex_query_parameter(None, value, type_)
-        elif isinstance(value, collections_abc.Mapping):
-            raise NotImplementedError("STRUCT-like parameter values are not supported.")
-        elif array_like(value):
-            param = array_to_query_parameter(value, None, type_)
-        else:
-            param = scalar_to_query_parameter(value, None, type_)
-
-        result.append(param)
-
-    return result
+    return [_dispatch_parameter(type_, value)
+            for value, type_ in zip(parameters, parameter_types)
+            ]
 
 
 def to_query_parameters_dict(parameters, query_parameter_types):
@@ -345,29 +351,9 @@ def to_query_parameters_dict(parameters, query_parameter_types):
         List[google.cloud.bigquery.query._AbstractQueryParameter]:
             A list of named query parameters.
     """
-    result = []
-
-    for name, value in parameters.items():
-        query_parameter_type = query_parameter_types.get(name)
-        if query_parameter_type is not None and "<" in query_parameter_type:
-            param = complex_query_parameter(name, value, query_parameter_type)
-        elif isinstance(value, collections_abc.Mapping):
-            raise NotImplementedError(
-                "STRUCT-like parameter values are not supported "
-                "(parameter {}).".format(name)
-            )
-        elif array_like(value):
-            param = array_to_query_parameter(
-                value, name=name, query_parameter_type=query_parameter_type
-            )
-        else:
-            param = scalar_to_query_parameter(
-                value, name=name, query_parameter_type=query_parameter_type,
-            )
-
-        result.append(param)
-
-    return result
+    return [_dispatch_parameter(query_parameter_types.get(name), value, name)
+            for name, value in parameters.items()
+            ]
 
 
 def to_query_parameters(parameters, parameter_types):

tests/unit/test_dbapi__helpers.py

@@ -563,6 +563,10 @@ def test_complex_query_parameter_type(type_, value, expect):
     assert param == expect
 
 
+def _expected_error_match(expect):
+    return "^" + re.escape(expect) + "$"
+
+
 @pytest.mark.parametrize(
     "value,type_,expect",
     [
@@ -599,11 +603,10 @@ def test_complex_query_parameter_type_errors(type_, value, expect):
     from google.cloud.bigquery.dbapi import exceptions
 
     with pytest.raises(
-        exceptions.ProgrammingError, match="^" + re.escape(expect) + "$",
+        exceptions.ProgrammingError, match=_expected_error_match(expect),
     ):
         complex_query_parameter("test", value, type_)
 
-
 @pytest.mark.parametrize(
     "parameters,parameter_types,expect",
     [
@@ -666,3 +669,25 @@ def test_to_query_parameters_complex_types(parameters, parameter_types, expect):
 
     result = [p.to_api_repr() for p in to_query_parameters(parameters, parameter_types)]
     assert result == expect
+
+def test_to_query_parameters_struct_error():
+    from google.cloud.bigquery.dbapi._helpers import to_query_parameters
+
+    with pytest.raises(
+        NotImplementedError,
+        match=_expected_error_match(
+            "STRUCT-like parameter values are not supported, "
+            "unless an explicit type is give in the parameter placeholder "
+            "(e.g. '%(:struct<...>)s').")
+        ):
+        to_query_parameters([dict(x=1)], [None])
+
+    with pytest.raises(
+        NotImplementedError,
+        match=_expected_error_match(
+            "STRUCT-like parameter values are not supported (parameter foo), "
+            "unless an explicit type is give in the parameter placeholder "
+            "(e.g. '%(foo:struct<...>)s').")
+        ):
+        to_query_parameters(dict(foo=dict(x=1)), {})
+