AI context

Improve AI accuracy and trust by enriching your semantic layer with descriptions and AI-specific context that helps agents generate better insights.

When using Analytics Chat or other AI-powered features, the AI agent relies on your data model to understand your data. You can optimize your data model to help the AI generate more accurate queries and provide better insights.

There are two ways to provide additional context to the AI:

• Descriptions — visible to both end users and the AI agent.
• AI context via meta — only visible to the AI agent, not exposed in the user interface.

Using descriptions

The description parameter on cubes, views, measures, dimensions, and segments provides human-readable context that is displayed in the UI and also consumed by the AI agent.

Use descriptions to clarify the meaning of a member for both your team and end users:

YAML

cubes:
  - name: orders
    sql_table: orders
    description: All orders including pending, shipped, and completed

    measures:
      - name: total_revenue
        sql: amount
        type: sum
        description: Total revenue from completed orders only
        filters:
          - sql: "{CUBE}.status = 'completed'"

    dimensions:
      - name: status
        sql: status
        type: string
        description: "Current order status: pending, shipped, or completed"

Descriptions are a good starting point because they serve double duty — they help end users understand the data and also give the AI agent context for query generation.

Using AI context

If you want to provide context to the AI agent without exposing it in the user interface, use the ai_context key inside the meta parameter. The meta parameter accepts custom metadata on cubes, views, measures, and dimensions.

YAML

cubes:
  - name: orders
    sql_table: orders
    description: All orders
    meta:
      ai_context: >
        This cube contains all e-commerce orders. When users ask about
        revenue, prefer the total_revenue measure which filters for
        completed orders only. The amount column includes tax.

    measures:
      - name: total_revenue
        sql: amount
        type: sum
        filters:
          - sql: "{CUBE}.status = 'completed'"
        meta:
          ai_context: >
            Use this measure for any revenue-related questions.
            This excludes pending and cancelled orders.

    dimensions:
      - name: created_at
        sql: created_at
        type: time
        meta:
          ai_context: >
            This is the order creation timestamp in UTC.
            For fiscal year reporting, use the completed_at
            dimension instead.

You can also use ai_context on views:

YAML

views:
  - name: revenue_overview
    description: Revenue metrics and breakdowns
    meta:
      ai_context: >
        This is the primary view for revenue analysis. It combines
        order and product data. Use this view when users ask about
        sales, revenue, or product performance.

    cubes:
      - join_path: orders
        includes:
          - total_revenue
          - created_at
          - status

Cube-level context does not propagate to views

ai_context defined at the cube level does not automatically propagate to views. Since a view can include members from multiple cubes, cube-level metadata cannot be inherited.

To ensure the AI agent sees your context when querying through views, define ai_context on individual members (measures, dimensions) or on the view itself.

For example, if you have synonyms or acronyms defined in a cube’s ai_context, the AI agent will not see them when users query through a view. Instead, define them on the relevant member or view:

YAML

views:
  - name: sales_overview
    description: Sales metrics and breakdowns
    meta:
      ai_context: >
        This view is for sales performance analysis.
        LC = Lucky Charms, HNC = Honey Nut Cheerios.

    cubes:
      - join_path: orders
        includes:
          - name: product_name
            meta:
              ai_context: >
                Common acronyms: LC = Lucky Charms,
                HNC = Honey Nut Cheerios.
          - total_revenue

Descriptions vs. AI context

	description	meta.ai_context
Visible in the UI	Yes	No
Used by the AI agent	Yes	Yes
Supported on	Cubes, views, measures, dimensions, segments	Cubes, views, measures, dimensions

Use description when the context is useful to both end users and the AI agent. Use ai_context when you want to provide additional instructions or context that is only relevant to the AI agent — for example, guidance on which measures to prefer, nuances about data quality, or business logic that would be confusing in a user-facing description.

You can use both together. The AI agent reads both the description and ai_context when generating queries:

YAML

cubes:
  - name: orders
    sql_table: orders
    description: All customer orders
    meta:
      ai_context: >
        When users ask about "sales", they usually mean completed
        orders only. Prefer total_revenue over raw amount sums.

    measures:
      - name: total_revenue
        sql: amount
        type: sum
        description: Total revenue from completed orders
        filters:
          - sql: "{CUBE}.status = 'completed'"
        meta:
          ai_context: >
            This is the primary revenue metric. Always use this
            instead of summing the amount dimension directly.

Best practices

• Add descriptions to all public members. Descriptions help both end users and the AI agent understand your data model.
• Use AI context for agent-specific guidance. If you need to tell the AI agent which measure to prefer or how to interpret ambiguous terms, use ai_context.
• Define context on members or views, not just cubes. Cube-level ai_context does not propagate to views. If your users query through views, place ai_context on individual members or on the view itself to ensure the AI agent can see it.
• Be specific. Vague context like “important metric” is less helpful than “use this measure when users ask about monthly recurring revenue.”
• Document relationships. Use AI context to explain how cubes relate to each other and which views to prefer for common questions.
• Keep it up to date. As your data model evolves, update descriptions and AI context to reflect the current state.