Semantic and Reporting Layers

In Holistics, your entire analytics stack is defined as code — fields, data models, datasets, visualizations, and dashboards. This is what makes Holistics AI particularly effective: it can read the full context of your semantic and reporting layers, directly from code.

What AI reads from your semantic layer

Object	What AI uses
Datasets	name, label, description, tags, relationships, drill-down and breakdown configurations
Data models	name, label, description, tags, dbt descriptions
Fields (dimensions, measures, metrics)	name, label, type, description, definition (formula), dbt descriptions

What AI reads from your reporting layer

Object	What AI uses
Dashboards	name, label, tags, visualization blocks, text blocks, controls and filters
Visualizations	label, fields and filters used, result data (if shared with AI)

Best practices for enriching context

Investing in well-documented analytics assets pays off for everyone — not just AI. Better documentation means business users find the right data faster, and AI gives more accurate answers with less hand-holding.

Write clear, descriptive names

Use unambiguous names for datasets, models, metrics, dimensions, dashboards, and widgets. If a business user wouldn't know what rev_adj_net_v2 means, neither will AI.

Use tags to signal trust

AI prioritizes endorsed datasets and deprioritizes archived ones. Tag your data consistently so AI steers users toward reliable sources. See Tags.

Encode business logic in formulas

Ambiguous terms are a leading cause of wrong AI answers. If "active user" means something specific in your business, define it in a metric formula — that formula becomes the ground truth AI uses for every related query.

metric active_user_count {
  label: 'Active user count'
  description: '''
    Active users are those who placed at least one order in the previous month.
  '''
  definition: @aql
    ecommerce_orders
    | where(ecommerce_orders.created_at is @(last month))
    | count_distinct(ecommerce_orders.user_id)
}

Add context in descriptions

Use descriptions to document synonyms, caveats, and rules that can't be expressed in a formula alone.

metric return_ratio {
  label: "Return Ratio"
  description: '''
    If the return ratio of a particular product_id exceeds 30%,
    it indicates a product quality issue.
  '''
  definition: @aql safe_divide(return_amount, gross_sales)
}

Configure drill-down and breakdown groups

When you define underlying tables and common breakdowns for a metric, AI uses these as a guide for follow-up analysis. For example, if Revenue has predefined underlying tables — Orders, Users, Products — AI can suggest targeted investigations during a revenue drop. See View Underlying Data and Drill Down & Break Down.

Use AI to speed up documentation

You don't have to document everything manually. Holistics AI can help you enrich your semantic layer faster — for example, generating field descriptions in bulk, generating tag descriptions, or creating metrics and dimensions from natural language. See What you can do with Holistics AI for the full list of capabilities.