Auto-create BigQuery views when BQ Agent Analytics plugin creates a new table

[caohy1988]

Summary

When the BigQueryAgentAnalyticsPlugin creates a new agent_events table (via _ensure_schema_exists()), it should automatically create per-event-type BigQuery views that unnest the generic table into typed, queryable columns. Currently users must manually create these views or use the external BigQuery Agent Analytics SDK ViewManager.

Motivation

The agent_events table stores all event types in a single generic schema with JSON content and attributes columns. Querying specific event types (e.g., "show me all LLM latencies" or "find tool errors") requires users to write complex JSON extraction SQL every time. Per-event-type views solve this by providing pre-built, typed columns for each event category.

The BigQuery Agent Analytics SDK already implements this via a ViewManager class that:

• Creates 18 per-event-type views (one for each event type: USER_MESSAGE_RECEIVED, LLM_REQUEST, LLM_RESPONSE, TOOL_STARTING, TOOL_COMPLETED, AGENT_STARTING, AGENT_COMPLETED, HITL events, etc.)
• Each view filters by event_type and unnests JSON fields into typed columns while preserving standard identity headers (timestamp, agent, session_id, invocation_id, user_id, trace_id, etc.)
• Provides create_all_views() for bulk creation, create_view(event_type) for individual views, and get_view_sql(event_type) for SQL inspection
• Uses a SQL template pattern with per-event-type column definitions (_EVENT_VIEW_DEFS + _VIEW_SQL_TEMPLATE)

Proposed Implementation

Option A: Integrated into the plugin (recommended)

Add view creation as an optional step in BigQueryAgentAnalyticsPlugin._ensure_schema_exists():

1. After successfully creating the agent_events table, automatically create all per-event-type views in the same dataset
2. Add a config flag create_views: bool = True to BigQueryLoggerConfig to allow opting out
3. View creation should be idempotent — use CREATE OR REPLACE VIEW so it's safe to run multiple times
4. Views should be updated when schema upgrades occur (new columns added to existing event types)

Option B: Separate utility method

Add a create_analytics_views() method to the plugin that users can call explicitly, similar to the SDK's ViewManager.create_all_views().

Implementation Details

Reference the SDK's ViewManager pattern:

# Each event type maps to its view-specific column extractions
_EVENT_VIEW_DEFS = {
    "LLM_REQUEST": [
        ("model", "STRING", "JSON_VALUE(content, '$.model')"),
        ("prompt_tokens", "INT64", "CAST(JSON_VALUE(content, '$.usage.prompt_tokens') AS INT64)"),
        # ...
    ],
    # ... 18 event types total
}

# Template creates a filtered, typed view per event type
_VIEW_SQL_TEMPLATE = """
CREATE OR REPLACE VIEW `{project}.{dataset}.v_{event_type_lower}`
AS SELECT
  timestamp, agent, session_id, invocation_id, user_id,
  trace_id, span_id, parent_span_id, status, error_message,
  {extra_columns}
FROM `{project}.{dataset}.{table}`
WHERE event_type = '{event_type}'
"""

Views to create

One view per event type currently logged by the plugin:

View Name	Source Event Type
v_user_message_received	USER_MESSAGE_RECEIVED
v_llm_request	LLM_REQUEST
v_llm_response	LLM_RESPONSE
v_llm_error	LLM_ERROR
v_tool_starting	TOOL_STARTING
v_tool_completed	TOOL_COMPLETED
v_tool_error	TOOL_ERROR
v_agent_starting	AGENT_STARTING
v_agent_completed	AGENT_COMPLETED
v_invocation_starting	INVOCATION_STARTING
v_invocation_completed	INVOCATION_COMPLETED
v_state_delta	STATE_DELTA
v_hitl_credential_request	HITL_CREDENTIAL_REQUEST
v_hitl_confirmation_request	HITL_CONFIRMATION_REQUEST
v_hitl_input_request	HITL_INPUT_REQUEST

Affected Files

• src/google/adk/plugins/bigquery_agent_analytics_plugin.py — add view creation logic
• tests/unittests/plugins/test_bigquery_agent_analytics_plugin.py — add tests for view creation

References

• BigQuery Agent Analytics SDK — View Management
• Plugin source: src/google/adk/plugins/bigquery_agent_analytics_plugin.py

[klateefa]

@caohy1988 Thanks for reporting!
Thank you for bringing this to our attention. The request is under review, and I’ll keep you updated if any additional information is required. We appreciate your patience.

[caohy1988]

• Auto-create views (Auto-create BigQuery views when BQ Agent Analytics plugin creates a new table #4639): After ensuring the agent_events table exists, automatically creates 15 per-event-type BigQuery views (v_llm_request, v_tool_completed, etc.) that unnest JSON columns into typed, queryable columns. Controlled by BigQueryLoggerConfig.create_views (default True), idempotent via CREATE OR REPLACE VIEW.