In Agents
Give an agent your semantic model by adding the view and topic files to thecontext: block of its .agentic.yml file. The agent then resolves questions
against your defined measures and dimensions, and the semantic engine compiles
the SQL — see Context & affordances for
how each kind of context is used.
analytics.agentic.yml
When querying a topic with default_filters, those filters are
automatically applied to all queries. User-provided filters are combined with
default filters using AND logic. For example, if a topic has a default filter
for
tenant_id = 'abc123', every query will be scoped to that tenant
regardless of additional filters specified by the user.Example Queries
Once configured, your agent can handle queries like:- “What’s the total revenue by customer segment?”
- “Show me the top 5 products by sales this month”
- “What’s the average order value for each acquisition channel?”
Multiple Domains
Glob patterns decide which parts of the semantic model an agent sees. Point one agent at everything, or give each agent only the topics for its domain:sales.agentic.yml
In Automations
Use thesemantic_query task type in automations to execute structured queries against your semantic model. This is ideal for automated reporting, data pipelines, and scheduled analytics.
Basic Automation Task
automations/sales_report.automation.yml
Semantic Query Task Properties
Field Referencing
Reference dimensions and measures using the formatview_name.field_name:
Filtering Data
Apply filters to narrow down your results. Each filter names afield and an
op:
These filters are combined with any default_filters defined in the topic using AND logic:
If the topic
ecommerce_analytics has default filters (e.g., tenant_id = 'xyz'), they are automatically applied along with the filters specified
above. All default filters and user filters must be satisfied.Ordering Results
Control the sort order of your results:Advanced Example
automations/customer_analysis.automation.yml
Best Practices
Agent Usage
- Scope each agent’s
context:to the views and topics its domain needs - Let the agent decide which dimensions and measures to use based on the question
Automation Usage
- Use semantic queries for repeatable analysis patterns
- Leverage variables for dynamic filtering
- Chain semantic queries with agent tasks for insights generation
Performance
- Use
limitto constrain result set size when appropriate - Be selective with dimensions—only include what you need
- Consider adding indexes on frequently filtered columns
- Use default_filters in topics for common business rules
Error Handling
- Test your semantic queries before deploying to production
- Handle cases where queries return no results
- Provide meaningful error messages to users
- Monitor query performance and optimize as needed
Related Documentation
Topics
Organize views into topics
Agents
Learn more about agents
Automations
Learn more about automations
Overview
Back to semantic model overview