01
Recognize the client-side inference failure
Read where the exception occurs. If constructing ArrayQueryParameter raises ValueError before a query is submitted, the immediate problem is parameter construction. A dataset location change or broader data access role does not supply missing field types.
In the reproduction, passing the generic string STRUCT with an empty list produced a message requesting a detailed StructQueryParameterType. With no element values, the client had no struct fields from which to infer that description.
02
Declare the element schema explicitly
Define the fields and their types according to the business input. The following example describes items with a string SKU and integer quantity, even when the current items list is empty.
The explicit schema belongs to the parameter contract. Do not add a dummy row to make inference work: that changes the input and can affect query results or writes.
from google.cloud import bigquery
item_type = bigquery.StructQueryParameterType(
bigquery.ScalarQueryParameterType("STRING", name="sku"),
bigquery.ScalarQueryParameterType("INT64", name="quantity"),
)
empty_items = bigquery.ArrayQueryParameter("items", item_type, [])03
Inspect the serialized parameter locally
Use the public to_api_repr method to check the type and empty array value without executing SQL. This is a useful contract test for request construction and does not prove a query has run successfully.
Our serialized value contained an ARRAY with a STRUCT element whose named fields were STRING and INT64, and arrayValues was empty. Record types and counts rather than sensitive populated parameter values in production diagnostics.
representation = empty_items.to_api_repr()
assert representation["parameterType"]["type"] == "ARRAY"
assert representation["parameterType"]["arrayType"]["type"] == "STRUCT"
assert representation["parameterValue"]["arrayValues"] == []04
Keep populated values on the same schema
Test at least one populated case as well. The example below constructs an item using the same field names and types. Our checks confirmed that its serialized parameter type matched the empty case.
If application validation allows nullable fields or nested arrays and structs, describe and test those explicitly. A parameter type can be stable while the business input remains invalid.
one_item = bigquery.StructQueryParameter(
None,
bigquery.ScalarQueryParameter("sku", "STRING", "sku-1"),
bigquery.ScalarQueryParameter("quantity", "INT64", 2),
)
filled_items = bigquery.ArrayQueryParameter("items", item_type, [one_item])
assert filled_items.to_api_repr()["parameterType"] == representation["parameterType"]05
Choose empty-input behavior before running SQL
Decide whether an empty list should yield no matches, skip a job, or represent another explicitly designed operation. Query parameters substitute values and expressions; they do not turn arbitrary table identifiers into safe dynamic parameters.
For a real query, inspect its SQL, intended project, location, cost controls, and result using an authorized test. Correct parameter serialization only resolves the local inference error. It does not establish query semantics or prove that an empty list is appropriate for a production mutation.
Know the limits
Reproduced with google-cloud-bigquery 3.46.2. ArrayQueryParameter("items", "STRUCT", []) raised ValueError; explicit field types produced a typed empty array and a matching populated representation. No SQL engine, query job, table access, or billing was exercised.
Sources & further reading
A technical publication by CoreTrailKit.
Browse all articles