Skip to main content
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: 
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. 
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: 
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

​
Descriptions vs. AI context

descriptionmeta.ai_context
Visible in the UIYesNo
Used by the AI agentYesYes
Supported onCubes, views, measures, dimensions, segmentsCubes, 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: 
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.
  • 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.