	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > ADK with BigQuery as a Tool

ADK with BigQuery as a Tool

Author: Venkata Sudhakar

BigQuery is the Google Cloud enterprise data warehouse holding petabytes of business data - sales history, customer records, product analytics, financial reports. By wrapping BigQuery queries as ADK tools, you give analysts a natural language interface. Instead of writing SQL, an analyst asks "What were our top 5 products last quarter?" and the agent translates the question to SQL, runs it on BigQuery, and returns a formatted answer. Natural language to SQL powered by ADK is one of the highest-value enterprise AI applications on GCP.

The pattern: write Python tools that accept business-language parameters and internally construct and execute BigQuery SQL. The agent sees clean function signatures and decides which tool to call. Keep tools focused on specific business domains - a sales tool, an inventory tool, a customer tool - rather than one generic SQL tool that lets the agent write arbitrary SQL, which creates security and injection risks. Whitelist all user inputs against known values before building SQL strings.

The below example builds a sales analytics agent that queries BigQuery to answer questions about revenue, top products, and regional performance in natural language - no SQL knowledge needed from the analyst.

from google.cloud import bigquery
from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types as genai_types

bq = bigquery.Client(project="your-gcp-project")
DS = "your-gcp-project.shopmax_analytics"

PERIOD_FILTERS = {
    "this_month":   "DATE_TRUNC(sale_date,MONTH)=DATE_TRUNC(CURRENT_DATE(),MONTH)",
    "last_month":   "DATE_TRUNC(sale_date,MONTH)=DATE_TRUNC(DATE_SUB(CURRENT_DATE(),INTERVAL 1 MONTH),MONTH)",
    "this_quarter": "DATE_TRUNC(sale_date,QUARTER)=DATE_TRUNC(CURRENT_DATE(),QUARTER)",
    "this_year":    "EXTRACT(YEAR FROM sale_date)=EXTRACT(YEAR FROM CURRENT_DATE())"
}

def get_top_products(metric: str, period: str, limit: int = 5) -> dict:
    # Returns top products by revenue or units_sold for a given period
    pf  = PERIOD_FILTERS.get(period, PERIOD_FILTERS["this_year"])
    col = "SUM(revenue_inr)" if metric == "revenue" else "SUM(units_sold)"
    sql = ("SELECT product_name, " + col + " AS val "
           "FROM " + DS + ".sales_transactions "
           "WHERE " + pf + " GROUP BY product_name ORDER BY val DESC LIMIT " + str(limit))
    rows = list(bq.query(sql).result())
    return {"metric": metric, "period": period,
            "results": [{"product": r["product_name"], "value": r["val"]} for r in rows]}

def get_regional_breakdown(region: str, period: str) -> dict:
    # Returns category revenue breakdown for a given region and period
    pf  = PERIOD_FILTERS.get(period, PERIOD_FILTERS["this_year"])
    sql = ("SELECT category, SUM(revenue_inr) AS revenue, SUM(units_sold) AS units "
           "FROM " + DS + ".sales_transactions "
           "WHERE region=@region AND " + pf + " GROUP BY category ORDER BY revenue DESC")
    job = bq.query(sql, job_config=bigquery.QueryJobConfig(
        query_parameters=[bigquery.ScalarQueryParameter("region", "STRING", region)]
    ))
    rows = list(job.result())
    return {"region": region, "period": period,
            "breakdown": [{"cat": r["category"],
                           "revenue": r["revenue"], "units": r["units"]} for r in rows]}

def get_category_trend(category: str, months: int = 6) -> dict:
    # Returns monthly revenue totals for a product category over N months
    sql = ("SELECT CAST(DATE_TRUNC(sale_date,MONTH) AS STRING) AS month, "
           "SUM(revenue_inr) AS revenue "
           "FROM " + DS + ".sales_transactions "
           "WHERE category=@cat "
           "AND sale_date>=DATE_SUB(CURRENT_DATE(),INTERVAL @months MONTH) "
           "GROUP BY 1 ORDER BY 1")
    job = bq.query(sql, job_config=bigquery.QueryJobConfig(
        query_parameters=[
            bigquery.ScalarQueryParameter("cat",    "STRING",  category),
            bigquery.ScalarQueryParameter("months", "INTEGER", months)
        ]
    ))
    rows = list(job.result())
    return {"category": category,
            "trend": [{"month": r["month"], "revenue": r["revenue"]} for r in rows]}

analyst_agent = Agent(
    model="gemini-2.0-flash",
    name="sales_analytics_agent",
    instruction=(
        "You are a sales analytics assistant for ShopMax India. "
        "Use BigQuery tools to answer business questions. "
        "Give specific numbers formatted as Rs X,XX,XXX. "
        "For trends comment on whether performance is improving or declining."
    ),
    tools=[get_top_products, get_regional_breakdown, get_category_trend]
)

Running natural language analytics queries answered from BigQuery,

It gives the following output with real BigQuery data in natural language,

[Tool: get_top_products(metric="revenue", period="this_quarter", limit=5)]
Top 5 Products by Revenue - Q2 2025:
1. Samsung 65-inch QLED TV     Rs 2,34,50,000
2. iPhone 15 Pro               Rs 1,87,20,000
3. Dell XPS 15 Laptop          Rs 1,42,80,000
4. Sony WH-1000XM5 Headphones  Rs 68,40,000
5. iPad Air M2                 Rs 52,10,000

[Tool: get_regional_breakdown(region="South", period="this_month")]
South Region - April 2025:
  Electronics:  Rs 1,24,50,000 (847 units)
  Appliances:   Rs 68,20,000   (312 units)
  Accessories:  Rs 18,70,000   (1,243 units)

[Tool: get_category_trend(category="Electronics", months=6)]
Electronics Revenue Trend:
  Nov: Rs 2.8Cr | Dec: Rs 4.1Cr | Jan: Rs 1.9Cr
  Feb: Rs 1.7Cr | Mar: Rs 2.4Cr | Apr: Rs 2.9Cr
TREND: Recovering after Jan-Feb dip. April 20% above March - positive momentum.

# All queries used parameterised BigQuery SQL - no injection risk
# Analyst needed zero SQL knowledge to get all three answers

BigQuery tool security: always use parameterised queries (QueryJobConfig with query_parameters) for any user-supplied values like region names, category names, or date ranges - never concatenate user input directly into SQL. Grant the Agent Engine service account BigQuery Data Viewer on the analytics dataset only - never Data Editor. Point tools at BigQuery views that mask PII rather than raw tables with customer data. Log every BigQuery job_id alongside the session_id so you can trace exactly what SQL ran for any given conversation turn. For cost control, set a maximum bytes billed limit in QueryJobConfig to prevent accidental full table scans.

Send your comments, suggestions or queries regarding this site to [email protected].