# Semantic and Reporting Layers

> How your semantic layer powers Holistics AI and how to enrich it

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](/docs/find-organize/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.

```aml
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.

```aml
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](/docs/interactions/view-underlying-data) and [Drill Down & Break Down](/docs/interactions/drill-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](/docs/ai/capabilities) for the full list of capabilities.