Skip to content

README.md

Latest commit

 

History

History
97 lines (67 loc) · 3.64 KB

README.md

File metadata and controls

97 lines (67 loc) · 3.64 KB
Raw

Python UDF Deployment

Register SDK analytical kernels as BigQuery Python UDFs for direct in-engine execution with no Cloud Function required.

Prerequisites

  • BigQuery Python UDF support enabled (Preview)
  • A BigQuery dataset to host the UDFs

Quick Start

Option 1: Run the static SQL

Replace PROJECT and UDF_DATASET in register.sql, then execute:

bq query --use_legacy_sql=false < register.sql

Option 2: Generate SQL programmatically

from bigquery_agent_analytics.udf_sql_templates import generate_all_udfs

sql = generate_all_udfs("my-project", "analytics")
print(sql)

Or generate a single UDF:

from bigquery_agent_analytics.udf_sql_templates import generate_udf

sql = generate_udf("bqaa_score_latency", "my-project", "analytics")

Available UDFs

Tier 1: Event Semantics

Function Params Returns Description
bqaa_is_error_event event_type, error_message, status BOOL Error detection
bqaa_tool_outcome event_type, status STRING Tool outcome classification
bqaa_extract_response_text content_json STRING Response text extraction
bqaa_normalize_event_label event_type STRING Event type normalization

Tier 2: Score Kernels

Function Params Returns Description
bqaa_score_latency avg_latency_ms, threshold_ms FLOAT64 Latency scoring
bqaa_score_error_rate tool_calls, tool_errors, max_error_rate FLOAT64 Error rate scoring
bqaa_score_turn_count turn_count, max_turns FLOAT64 Turn count scoring
bqaa_score_token_efficiency total_tokens, max_tokens FLOAT64 Token efficiency scoring
bqaa_score_ttft avg_ttft_ms, threshold_ms FLOAT64 Time-to-first-token scoring
bqaa_score_cost input_tokens, output_tokens, max_cost_usd, input_cost_per_1k, output_cost_per_1k FLOAT64 Cost scoring

All score kernels return a value in [0.0, 1.0] where 1.0 is best.

Tier 3: Vectorized UDFs (Deferred)

Vectorized Python UDFs (OPTIONS(vectorized = true)) are deferred until BigQuery adds vectorized option support for Python UDFs. The option is currently only supported for JavaScript UDFs. When support lands, batch-oriented scoring UDFs using numpy/pandas will be added.

Tier 4: STRING Envelope UDFs

UDFs that return a JSON STRING for richer structured output.

Function Params Returns Description
bqaa_eval_summary_json avg_latency_ms, tool_calls, tool_errors, turn_count, total_tokens, avg_ttft_ms, input_tokens, output_tokens, threshold_ms, max_error_rate, max_turns, max_tokens, ttft_threshold_ms, max_cost_usd, input_cost_per_1k, output_cost_per_1k STRING All six scores + pass/fail in one JSON object

Use JSON_VALUE() to extract individual scores from the result:

JSON_VALUE(summary, '$.latency')   -- individual score
JSON_VALUE(summary, '$.passed')    -- overall pass/fail

Region Guidance

BigQuery UDFs are region-scoped. If your data lives in multiple regions, register UDFs in each region or use dataset replication for a shared utility dataset.

Examples