Skip to main content

In Agents

Give an agent your semantic model by adding the view and topic files to the context: 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?”
The agent will use the semantic model to understand available dimensions and measures, then construct appropriate queries.

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 the semantic_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 format view_name.field_name:

Filtering Data

Apply filters to narrow down your results. Each filter names a field 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 limit to 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

Topics

Organize views into topics

Agents

Learn more about agents

Automations

Learn more about automations

Overview

Back to semantic model overview