[BigQuery Data Agents](/about/bigquery-data-agents) November 3, 2026

# BigQuery agent instructions, glossary, and verified queries

Make a BigQuery data agent accurate on GA4 data: precise instructions, a business glossary, and eight verified queries with parameters to start from.

![](/images/65d75b0ae8d69ef95785a5d6_david-pombar.webp)

**[David Pombar](/authors-guides/david-pombar)** Swiss army knife at Trackingplan

8 min read · 1804 words

The agent from [guide 5](/guides/create-a-bigquery-data-agent) answers, and [guide 6](/guides/check-bigquery-agent-answers) taught you to catch it when it’s wrong. This guide is about making it wrong less often. A data agent has three tools for that, and each one fixes a different kind of error: instructions for defaults, a glossary for words, and verified queries for the questions that matter most.

By the end you will have all three on your agent, including eight verified queries for ecommerce questions on GA4 data that you can adapt to your own tables.

![An open handwritten manuscript recipe book with a paper slip marking a page](/images/bigquery-agent-verified-queries-recipe-book.jpg)

A recipe that worked, written down so nobody has to improvise it again. Image: Unoquha, Wikimedia Commons, CC0

**Goal of this guide:** an agent with precise instructions, a glossary of your business terms, and eight parameterized verified queries. ** You need:** the agent from guide 5 and the list of wrong answers you kept in guide 6.

## Three tools, three kinds of error

![Diagram of the three tools that shape a data agent’s answers, in order of priority: verified queries give exact SQL for common questions, the glossary defines business terms, and instructions set defaults and behavior.](/images/bigquery-agent-verified-queries-three-tools.webp)

When they disagree, the verified query wins, then the glossary, then the instructions.

| Tool | Fixes | Example |
| --- | --- | --- |
| Instructions | Defaults and behavior | “If no period is given, use the last 30 days and say so.” |
| Glossary | Words that mean something specific in your business | “Channel: the session’s medium.” |
| Verified queries | Exact SQL for the questions asked most | “Revenue by channel for a period” |

Google’s [data agent page](https://docs.cloud.google.com/bigquery/docs/create-data-agents) sets the priority when they conflict: verified queries first, then the glossary, then the instructions. It also recommends structured context, meaning descriptions, examples, and the glossary, before you reach for more instructions.

## Instructions: defaults, not essays

Instructions apply to every question, so every line costs attention on questions it doesn’t concern. Keep them to what changes behavior. Google groups useful instructions into six kinds, and each one has a GA4 version:

-   **Key fields.** “The most important tables are sessions and purchases.”
-   **Filtering and grouping.** “For questions over time, group by session\_date or purchase\_date.”
-   **Default filters.** “Unless the question says otherwise, use data up to yesterday. Today’s data is incomplete.”
-   **Synonyms and business terms.** Short ones here; the full list goes in the glossary.
-   **Excluded fields.** “Never use the user’s first source for channel questions.”
-   **Joins.** “purchases.session\_key joins to sessions.session\_key. Never join purchase\_items to sessions directly.”

Add three behavior rules that guide 6 showed you need:

```text
- Report NULL, empty and "(not set)" values as their own row, with their share.
- When a question is ambiguous, ask one clarifying question before answering.
- State the period and the definition of each metric in the first line of the answer.
```

Write instructions like a short briefing for a new analyst, one rule per line. A paragraph of good intentions is harder for the model to follow than ten plain rules.

## The glossary: your words, defined once

The glossary holds business terms, each with a **definition** and ** synonyms**. Add it under ** Glossary > Add term**. Terms you create stay in BigQuery; if your company keeps a business glossary in Knowledge Catalog (Dataplex), you can import those terms too, and they apply to every agent.

Start with the terms that caused wrong answers in guide 6:

| Term | Definition | Synonyms |
| --- | --- | --- |
| Session | A row in agent\_layer.sessions: one user’s visit, identified by session\_key | visit |
| Channel | The session’s medium (agent\_layer.sessions.medium), not the user’s first source | medium, traffic type |
| Revenue | SUM(revenue) in agent\_layer.purchases, in the store currency | sales, turnover |
| Conversion rate | Converted sessions divided by all sessions, as a percentage | CR, conversion |
| Users | COUNT(DISTINCT user\_pseudo\_id) | visitors, customers |
| Order | A row in agent\_layer.purchases | transaction, purchase |
| AOV | Revenue divided by orders | average order value, basket size |

If you keep a tracking plan, it already defines most of these: what each event means and which properties it carries. Copy the definitions from there rather than writing new ones that drift from what the site actually sends.

> **How a production agent does it.** Trackingplan’s agent keeps the same kind of knowledge per site: facts and standing rules your team teaches it in conversation, such as “the Meta pixel was retired” or “exclude staging hostnames”. They are shared by everyone working on that site, reviewable in settings under Plan context, and applied in every chat and audit ([how it works](/blog/same-models-different-answers)). The lesson for your BigQuery agent: give glossary terms and instructions an owner, and review them like code, because they change answers for everyone.

## Verified queries: exact answers for common questions

A verified query is a question and the SQL that answers it, approved by you. When a question matches one, the agent runs the SQL exactly as written. When none matches, it uses them as examples of how to query your tables. They were called golden queries until recently, and you will still see the old name in older tutorials.

To add one, open **Verified Queries** in the agent, click ** Add query**, type the question, click ** Generate SQL**, correct the SQL if needed, then ** Run** and ** Add**. Gemini also proposes candidates under ** Review suggestions**; review them as carefully as you would a colleague’s query.

### Parameters make one query answer many questions

Write `@name` placeholders in the SQL and declare each one under **Manage query parameters** with a name, a type, a default value, and a description. The agent reads the values from the question. “Revenue by channel in January” and “revenue by channel last December” become the same query with different dates.

## Eight verified queries for GA4 ecommerce

![List of eight verified queries for GA4 ecommerce data with their parameters: revenue by channel, conversion rate by device, top products, average order value by month, landing pages, revenue by day, sessions by country, and one channel over time.](/images/bigquery-agent-verified-queries-eight.webp)

Eight questions most marketing teams ask every week, each one parameterized.

All eight run on the `agent_layer` tables from [guide 4](/guides/ga4-views-for-bigquery-agents). Declare `@start_date` and `@end_date` as `DATE`, with defaults inside the sample’s range, such as `2021-01-01` and `2021-01-31`.

**1\. Revenue by channel for a period**

```sql
SELECT s.medium AS channel, COUNT(*) AS orders, SUM(p.revenue) AS revenue
FROM agent_layer.purchases p
JOIN agent_layer.sessions s USING (session_key)
WHERE p.purchase_date BETWEEN @start_date AND @end_date
GROUP BY channel
ORDER BY revenue DESC;
```

**2\. Sessions and conversion rate by device**

```sql
SELECT device_category,
  COUNT(*) AS sessions,
  ROUND(100 * COUNTIF(converted) / COUNT(*), 2) AS conversion_rate_pct
FROM agent_layer.sessions
WHERE session_date BETWEEN @start_date AND @end_date
GROUP BY device_category
ORDER BY sessions DESC;
```

**3\. Top products by units sold**

```sql
SELECT item_name, SUM(quantity) AS units, SUM(item_revenue) AS revenue
FROM agent_layer.purchase_items
WHERE purchase_date BETWEEN @start_date AND @end_date
GROUP BY item_name
ORDER BY units DESC
LIMIT @top_n;
```

Declare `@top_n` as `INT64` with a default of 10.

**4\. Average order value by month**

```sql
SELECT DATE_TRUNC(purchase_date, MONTH) AS month,
  COUNT(*) AS orders,
  ROUND(SUM(revenue) / COUNT(*), 2) AS average_order_value
FROM agent_layer.purchases
WHERE purchase_date BETWEEN @start_date AND @end_date
GROUP BY month
ORDER BY month;
```

**5\. Landing pages by sessions and conversion**

```sql
SELECT landing_page,
  COUNT(*) AS sessions,
  ROUND(100 * COUNTIF(converted) / COUNT(*), 2) AS conversion_rate_pct
FROM agent_layer.sessions
WHERE session_date BETWEEN @start_date AND @end_date
GROUP BY landing_page
HAVING sessions >= 50
ORDER BY sessions DESC
LIMIT 20;
```

The `HAVING` line keeps pages with a handful of sessions from topping the conversion ranking by chance.

**6\. Revenue and orders by day**

```sql
SELECT purchase_date, COUNT(*) AS orders, SUM(revenue) AS revenue
FROM agent_layer.purchases
WHERE purchase_date BETWEEN @start_date AND @end_date
GROUP BY purchase_date
ORDER BY purchase_date;
```

**7\. Sessions and users by country**

```sql
SELECT IFNULL(country, '(missing)') AS country,
  COUNT(*) AS sessions,
  COUNT(DISTINCT user_pseudo_id) AS users
FROM agent_layer.sessions
WHERE session_date BETWEEN @start_date AND @end_date
GROUP BY country
ORDER BY sessions DESC;
```

The `IFNULL` puts missing values on their own visible line, as the instructions ask.

**8\. One channel over time**

```sql
SELECT DATE_TRUNC(s.session_date, WEEK(MONDAY)) AS week,
  COUNT(*) AS sessions,
  COUNTIF(s.converted) AS converted_sessions,
  IFNULL(SUM(p.revenue), 0) AS revenue
FROM agent_layer.sessions s
LEFT JOIN agent_layer.purchases p USING (session_key)
WHERE s.session_date BETWEEN @start_date AND @end_date
  AND s.medium = @medium
GROUP BY week
ORDER BY week;
```

Declare `@medium` as `STRING`, with a description that lists the values it takes (`organic`, `cpc`, `referral`, `(none)`). Weeks start on Monday, and the query says so; an agent left to choose might start them on Sunday. If a session can hold more than one purchase in your data, the `LEFT JOIN` repeats that session’s row, so count sessions with `COUNT(DISTINCT s.session_key)` there.

## How to grow the set

Don’t write fifty verified queries on day one. Write the eight above, adapted to your questions, and then add one each time two things are true: the agent got a question wrong, and that question will be asked again. Your list from guide 6 is the first batch.

For every verified query you add, write down the question you asked and the right answer. That pair becomes a test case in the next guide.

## Exercise

Add the instructions, the seven glossary terms, and the eight verified queries to your agent. Then ask the five questions from guide 5 again and compare the SQL with the SQL you got before. For each question, write which of the three tools changed the answer.

## How to know you got it right

-   Your instructions fit on one screen, one rule per line.
-   Every term that caused a wrong answer in guide 6 is in the glossary.
-   Your eight verified queries use parameters, not hard-coded dates.
-   Asking “revenue by channel in December 2020” runs verified query 1 with the right dates.

## Resources

-   [Create data agents](https://docs.cloud.google.com/bigquery/docs/create-data-agents), Google Cloud docs: instructions, glossary, verified queries, and parameters, with Google’s own examples.
-   [Authored context for BigQuery data sources](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/data-agent-authored-context-bq), Google Cloud docs: the same context as written through the API, useful once you manage agents as code in guide 11.
-   [Ask effective questions](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/ask-effective-questions), Google Cloud docs: Google’s advice on scope, dates, and multi-part questions.
-   [Manage glossaries](https://docs.cloud.google.com/knowledge-catalog/docs/manage-glossaries), Google Cloud docs: the Knowledge Catalog business glossary you can import from.

## FAQ

**What are verified queries in a BigQuery data agent?** Verified queries, formerly called golden queries, are pairs of a question and the SQL that answers it, which you approve. When a question matches one, the agent runs that query exactly as written; when it doesn’t, the agent uses the verified queries as examples. They can take parameters such as dates or a channel.

**How do parameters work in BigQuery verified queries?** Write @name placeholders in the SQL, such as WHERE purchase\_date BETWEEN @start\_date AND @end\_date, and declare each parameter with a name, a type, a default value, and a description. The agent reads the values from the question, so one verified query answers every period or channel.

**What is the difference between instructions, the glossary, and verified queries?** Instructions set the agent’s defaults and behavior. The glossary defines business terms and their synonyms. Verified queries give exact SQL for common questions. When they conflict, Google’s documentation gives verified queries priority, then the glossary, then the instructions.

**How many verified queries should a data agent have?** Google’s BigQuery documentation states no limit. Start with the eight to fifteen questions people ask most, each written as a parameterized query, and add one every time an answer goes wrong on a question that will be asked again.

**Next:** [Test your agent before you share it](/guides/evaluate-a-bigquery-data-agent).

Part of[BigQuery data agents: a guide series from zero to expert](/guides/bigquery-data-agents)

On this page

1.  [*01*Three tools, three kinds of error](#three-tools-three-kinds-of-error)
2.  [*02*Instructions: defaults, not essays](#instructions-defaults-not-essays)
3.  [*03*The glossary: your words, defined once](#the-glossary-your-words-defined-once)
4.  [*04*Verified queries: exact answers for common questions](#verified-queries-exact-answers-for-common-questions)
5.  [*05*Eight verified queries for GA4 ecommerce](#eight-verified-queries-for-ga4-ecommerce)
6.  [*06*How to grow the set](#how-to-grow-the-set)
7.  [*07*Exercise](#exercise)
8.  [*08*How to know you got it right](#how-to-know-you-got-it-right)
9.  [*09*Resources](#resources)
10.  [*10*FAQ](#faq)

**Stop babysitting tags**

Trackingplan audits your real user data around the clock and flags issues before they cost you.

[Start free trial →](https://app.trackingplan.com/signup)

![](/images/65d75b0ae8d69ef95785a5d6_david-pombar.webp)

**David Pombar** Swiss army knife at Trackingplan

Read more from David, a Senior Product Strategist with 18+ years in digital product development and an atypical error detection knack.

Share Copy link [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fwww.trackingplan.com%2Fguides%2Fbigquery-agent-verified-queries) [X](https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.trackingplan.com%2Fguides%2Fbigquery-agent-verified-queries&text=BigQuery%20agent%20instructions%2C%20glossary%2C%20and%20verified%20queries)

Read next

[All Guides →](/guides)

-   [
    
    6 minBigQuery Data AgentsNovember 3, 2026
    
    ### Test a BigQuery data agent before you share it
    
    Build a set of questions with known answers, rerun it after every change to your data agent, and use conversation logs to find the questions you missed.
    
    by **David Pombar**](/guides/evaluate-a-bigquery-data-agent)
-   [
    
    7 minBigQuery Data AgentsNovember 3, 2026
    
    ### Check a BigQuery agent’s answer: six errors on GA4 data
    
    How to ask a BigQuery data agent better questions, read its answer critically, and spot the six errors agents make most often on GA4 data.
    
    by **David Pombar**](/guides/check-bigquery-agent-answers)
-   [
    
    8 minBigQuery Data AgentsNovember 3, 2026
    
    ### GA4 views for BigQuery agents: build the readable layer
    
    Turn the raw GA4 export into narrow tables a data agent can read: sessions, purchases, items, and pages, with descriptions written for the agent.
    
    by **David Pombar**](/guides/ga4-views-for-bigquery-agents)

Trackingplan

## See everything. Miss nothing.

Your implementations audited around the clock with real-time, real-user data. Real-time alerts about errors or changes in your data, campaigns, pixels, privacy and consent. Let AI flag issues before they cost you.

[Start free trial →](https://app.trackingplan.com/signup) [Book a demo](/demo)