As business intelligence is reimagined in the AI era, the focus has expanded from data delivery to verifiable accuracy. The Conversational Analytics API for Looker Embedded environments transforms static dashboards into natural-language interfaces.
Introducing Golden Queries
Golden Queries offer deterministic precision for your apps, and act as verified question and SQL pairs, ensuring that customers always receive the gold standard of truth for their most critical business questions. By providing these as structured context, you teach your AI agent to handle complex business requests accurately rather than guessing.
Think about the BI dashboards you use. They aren’t just random collections of charts, they’re built to answer specific questions. For example, A dashboard for a sales leader is set up to answer things like, “What are our top-selling products?” or “Which sales region is growing fastest?” Golden Queries work the same way, but for Conversational AI. For every important question a dashboard answers, a BI developer has already figured out the best query to get that information. Golden Queries are just like that!
They are the pre-approved queries written by the data experts that can be provided to the AI. This means when you ask the Agent a key question, it doesn’t have to guess or try to build a query on the fly. It just uses the “golden” one that’s already been created and tested. It’s the same reason you trust the numbers in your dashboard. It ensures you get a reliable, consistent answer to your most important questions, every single time.
Golden Query Format:
looker_golden_queries = [
{
"natural_language_questions": [
"{{primary_question}}",
"{{alternative_phrasing_1}}",
"{{alternative_phrasing_2}}"
],
"looker_query": {
"model": "{{looker_model_name}}",
"explore": "{{explore_name}}",
"fields": ["{{view_name}}.{{dimension_1}}", "{{view_name}}.{{dimension_2}}"],
"filters": [
{
"field": "{{view_name}}.{{filter_field}}",
"value": "{{filter_value}}"
}
],
"sorts": ["{{view_name}}.{{sort_field}} {{direction}}"],
"limit": "{{limit_count}}"
}
}
]
Using Golden Queries for your apps
If you’re building apps with the Looker SDK, adding Golden Queries makes users trust your tool much more. Here’s how to do it:
Step 1: Identify the questions
First, think of the natural language questions a user might ask about a specific Explore. You will use these for the natural_language_questions field.
Step 2: Retrieve the Looker query metadata
In your Explore, open the actions menu and click Share to copy the share URL. Grab the “share slug” at the end of the URL, and make a GET /queries/slug/Explore_slug request to the Looker API to retrieve the query metadata.
Step 3: Build the Golden Query objects
For each golden query, create an object that contains:
natural_language_questions: The questions you identified in Step 1.
looker_query: The metadata you retrieved in Step 2. You must include the model and explore fields. You can optionally include fields[ ], filters[ ], sorts[ ], and limit to make the query more precise
Step 4: Provide the golden queries to the data agent
Compile your list of golden query objects under the looker_golden_queries key.
You can then pass this list to the Conversational Analytics API using either direct HTTP requests or the Python SDK. You can find example of Golden Queries here.
Best Practices
- Provide a diverse variety of 30 to 50 question-and-query pairs that feature different types of questions, filters, and filter values so the agent has a robust set of patterns to learn from.
- Analysts should proactively monitor ad-hoc queries received outside the platform to pinpoint critical gaps in the API layer, ensuring high-value insights are captured in the curated context.
- Look for queries/insights that are generated repeatedly and use these as golden queries:
- Queries from cache: these are retrieved at least twice - good indicator for importance and accuracy.
- Queries with dashboard source - these are on a dashboard and are consumed regularly, indicator for importance.
For more details, take a look at the documentation here.