BigQuery’s AI.AGG can now return typed records—but a schema is not a reliability guarantee

What changed

Google Cloud’s October 14 release note says the generally available AI.AGG function now supports an output_schema argument. Instead of receiving only a free-form string, a query can ask the model-backed aggregate to return a typed STRUCT whose fields are declared as a comma-separated schema. Supported field types include STRING, INT64, FLOAT64, BOOL, ARRAY and nested STRUCT; fields can also carry descriptions and NOT NULL constraints. Google Cloud release notes AI.AGG reference

That is a useful integration change for analytics pipelines. A semantic aggregation over reviews, logs or agent traces can now produce named fields that downstream SQL can address directly, rather than forcing every consumer to parse prose. Grouped queries still return one result per input group, so the structured result can sit beside ordinary dimensions in a table. AI.AGG reference

The boundary the schema does not remove

The declared type governs the shape of the result; it does not make the underlying inference deterministic or complete. Google recommends marking most fields NOT NULL, warning that otherwise the model might return null fields. Calls can also return partial results when Vertex AI requests fail. The max_error_ratio parameter controls how many row-level failures a query will tolerate and defaults to 1.0, although a run still fails if every row fails. AI.AGG reference

There are scale limits to design around as well. Output is capped at 10,000 tokens per group. Google recommends no more than 1,000 distinct groups, with workload-specific input guidance ranging from 20 million rows for text and single-image records down to 1,000 rows for video. Queries above those recommendations might fail or return only partial results. AI.AGG reference

Multimodal access has a security wrinkle: inside a VPC Service Controls perimeter, delegated ObjectRef access is blocked because it creates signed HTTP URLs. Google directs users to pass a direct Cloud Storage reference instead. AI.AGG reference

What practitioners should do

Treat output_schema as a contract for downstream processing, not as proof of semantic correctness. Use required fields where absence is unacceptable, set an explicit failure threshold rather than inheriting the permissive default, and validate business-critical values after inference. For agent-operations analysis—the documentation names agent performance as a use case—the strongest pattern is to keep raw traces and status data beside the generated structure so an attractive typed row never hides missing inputs or a partially completed run. AI.AGG reference