Optimize models for Omni AI

Requirements

To follow this guide, you’ll need:

An understanding of Omni modeling concepts
Familiarity with Omni’s model IDE
Familiarity with basic AI terminology such as tokens, agents, etc.

Common questions

What is AI context?

Context is information such as:

Descriptions of topics and fields
Possible field values
How a field might be used

In Omni, this is provided to the AI using a context window. A context window is the amount of text an AI can read and consider at one time when answering a question or completing a task.

Why provide context to AI?

Using context windows allows AI models to understand and incorporate relevant information. Specifically, providing context to the LLM makes it more effective, enabling it to interpret your request accurately and generate meaningful responses.

What does Omni AI use for context?

Omni uses the following for context, in priority order:

Context and tuning pre-built by the Omni Engineering team

The ai_context parameters in the model, topics and views, if provided

Topic's description, if provided

Topic's name and base_view

Prioritized field properties

fully_qualified_name (view_name.field_name) - For example, order_items.total_sale_price
name - For example, total_sale_price
aliases
ai_context
all_values - Used to specify the possible values for the field

Pruned field properties

These properties will be pruned in the following order, but note that fields may be truncated entirely if required.

description
group_label - The categorization of the field
label - If defined, the value will be used. If not provided, a title-cased field name with underscores removed will be used. For example, Total Sale Price
semantic_type - The dimension or aggregate type, such as dimension, sum, count, etc. This value is evaluated based on the field definition and can’t be directly modified.
data_type - The field’s data type, such as number, string, etc.
sample_values - Example values for the field
synonyms - Other terms used to refer to the field

Where does context apply?

Context applies to:

Omni Agent / Embedded chat instances
Workbook Agent in the workbook
AI summary visualizations
AI filter generator

What limitations does context have?

Omni’s model can handle ~200K characters of context:

~15-25K is reserved for Omni app context, which is used to ensure queries are generated properly
The remaining ~175K characters are allocated for context from the semantic layer before truncation, starting with field metadata

To prevent field truncation, we recommend limiting the number of fields included in the context window to 550. Let’s look at an example to demonstrate why.

Topic metadata & prioritized field properties

You have a topic that you want to use for AI querying. Including the topic’s description, name, base_view, ai_context, and the included fields’ prioritized properties (ex: name), let’s say the total characters used is around 10,000.

  175,000 characters   // total allocated for semantic layer context
-  10,000 characters   // topic metadata & prioritized field properties
  ------------------
  165,000 characters   // total remaining for additional context

Topic field metadata

In the topic, the included fields generally look like this:

active_camp_active_campaign_id_c:
  sql: '"ACTIVE_CAMP_ACTIVE_CAMPAIGN_ID_C"'
  label: Active Campaign Active Campaign ID
  group_label: Active Campaign

The total characters used for this field’s basic metadata equals 160 characters.

Field-level context

You’ll likely want to add field-level context, such as description, sample_values, and ai_context. Let’s add 140 characters to account for the AI-specific metadata, which brings the total characters per field to 300 characters:

  160 characters      // basic field metadata
+ 140 characters      // field-level context for AI
  --------------
  300 characters      // total field metadata

Remaining fields for inclusion

To get the total number of fields, divide the remaining characters available (165,000) by the total metadata characters per field:

  165,000 characters      // total remaining for additional context
/     300 characters      // total field metadata
  -------------------
    550(ish) fields       // total fields for inclusion

This gives you roughly 550 fields to include in the context window before Omni begins truncating fields.

How is context to the AI processed?

Context provided to Omni’s AI is shared with AWS Bedrock. Refer to the AI data security guide for more information.

Context and agent behavior

As the previous section explained, Omni assembles ai_context from multiple levels — model, topic, view, and field — and passes it to the Omni Agent as part of the query generation prompt. The LLM that powers the Omni Agent makes its own decisions about which context to follow, how to weight it, and how to resolve apparent contradictions. This means:

Model-level ai_context is not guaranteed to override topic-level ai_context. All context is passed together; the LLM decides what to prioritize.
Context is guidance, not strict instruction. The LLM may partially follow, fully follow, or in some cases not follow a given instruction, especially when instructions are complex or contradictory.
Behavior can be non-deterministic. Running the same query twice may result in different context being applied, particularly when context is large or contains conflicting signals.

Use the workbook inspector to view and debug the context for a given AI session.

Curate AI outputs across the model

You can use the model parameter ai_context to pass context shared across topics. This parameter may also be useful for topic selection in the Omni Agent.

Personalize context with user attributes

The ai_context parameter at the model, topic, and view levels supports user attributes through {{omni_attributes.<attribute_name>}} syntax. At query time, Omni substitutes each placeholder with the current user’s attribute value, allowing you to tailor AI behavior per user or group.

Topic ai_context using user attributes

ai_context: |
  You are a sales analyst. When someone asks about their team or pipeline, always filter by account.segment = {{omni_attributes.segment}} and account.region = {{omni_attributes.region}}.

User attribute references are supported in ai_context at the model, topic, and view levels only. Dimension and measure ai_context does not support this syntax — the value is used as-is. Field references and filter conditions are also not supported and will produce a validation warning.

Optimize context for different AI models

The ai_context parameter at the model, topic, and view levels supports model-specific customization through the omni_llm namespace. This ensures optimal performance across AI model options by allowing you to tailor AI instructions to the capabilities of different AI model tiers:

smartest - Most capable models suited for complex reasoning
standard - Balanced models for typical queries
fastest - Optimized for speed and simple requests

For example, you can provide different chain-of-thought instructions based on model tier. In the following example, the first block ({{# omni_llm.smartest }}) would apply when the model tier is smartest, and the second ({{^ omni_llm.smartest }}) would apply when the model tier is standard or fastest:

Model-level ai_context with omni_llm

ai_context: |
  {{# omni_llm.smartest }}
  Before calling 'GenerateQuery', explain your reasoning for field selection in detail (9-10 sentences) under "Reasoning for field selection", then provide 3-4 sentences on alternative approaches under "Alternative approaches considered".
  {{/ omni_llm.smartest }}

  {{^ omni_llm.smartest }}
  Proceed directly to generating the query without intermediate explanation steps.
  {{/ omni_llm.smartest }}

You can also adjust analysis depth based on model capabilities:

Topic-level ai_context with omni_llm

ai_context: |
  This topic focuses on financial transactions.

  {{# omni_llm.smartest }}
  For complex multi-table queries, consider indirect relationships and provide rationale for join path selection.
  {{/ omni_llm.smartest }}

  {{# omni_llm.standard }}
  Use straightforward joins between related tables.
  {{/ omni_llm.standard }}

  {{# omni_llm.fastest }}
  Prefer single-table queries when possible.
  {{/ omni_llm.fastest }}

See the ai_context references for models, topics, and views for more information and examples.

Optimize context for different AI agents

The ai_context parameter at the model, topic, and view levels also supports agent-specific customization through the omni_agent namespace. This lets you scope portions of your context to the AI agent that will read it, preventing bulky agent-specific content from inflating context windows for other agents. The three agent types correspond to existing AI settings configuration categories:

analyze - Used for search-model tool and query generation
build - Used for topic metadata generation and learn-from-conversation
simple_summarize - Used for tile/visualization summaries and query metadata

For example, you might want to provide detailed modeling conventions to the build agent while keeping the analyze agent’s context concise:

Model-level ai_context with omni_agent

ai_context: |
  {{# omni_agent.build }}
  Modeling conventions: Always define primary keys. Use snake_case for field names. Prefer measures over dimensions for aggregations.
  {{/ omni_agent.build }}

  {{^ omni_agent.build }}
  Keep queries focused and efficient.
  {{/ omni_agent.build }}

  This context is read by the {{ omni_agent.name }} agent.

You can also provide agent-specific query optimization tips at the topic level:

Topic-level ai_context with omni_agent

ai_context: |
  This topic focuses on user activity data.

  {{# omni_agent.analyze }}
  For performance, prefer filtering by date ranges before joining to user details.
  {{/ omni_agent.analyze }}

  {{# omni_agent.build }}
  When generating field relationships, consider that user_id is the primary key linking activity to users.
  {{/ omni_agent.build }}

See the ai_context references for models, topics, and views for more information and examples.

Use constants for reusable AI context

You can define reusable AI instruction blocks as constants and reference them across multiple ai_context fields using @{constant_name} syntax. This approach helps you maintain shared context (tone, privacy guidance, domain context) in a single location instead of duplicating it across models, topics, views, and sample queries.

Model file with reusable AI context constants

constants:
  tone:
    value: "Keep responses concise and professional."
  privacy_high:
    value: "Never show individual customer names or emails."
  domain_finance:
    value: "This is a financial analytics model. Use monetary values with precision."

ai_context: |
  @{tone} @{privacy_high}
  @{domain_finance}

You can then reference these same constants in topic-level, view-level, and sample query ai_context fields, ensuring consistent instruction blocks across your model while keeping maintenance centralized. See the constants reference for more details and examples.

Implement chain-of-thought reasoning

If you want the Omni Agent to give a more thorough explanation of what is being generated (topic selection, field selection, etc.), you can include the following context within the model’s ai_context. This can be altered and tweaked if needed, but the reference to GenerateQuery is required for proper behavior.

ai_context: |
  Before calling the 'GenerateQuery' tool, please do the following steps:
  
  1. Explain your reasoning of how you picked the fields in detail (9-10 sentences), under the header "Reasoning for field selection"
  2. Another 3-4 sentences on alternative queries or fields you could have chosen under the header "Alternative approaches considered"
  3. Finally add 4 markdown links as follow up questions under the header "Follow-up questions"

If you don’t want to implement chain-of-thought reasoning for all model tiers, you can provide model tier-specific instructions instead.

Output summaries in multiple languages

If you’d like the Omni Agent to summarize outputs in multiple languages, you can include the following context:

ai_context: |
  When generating a summary, always output the summary in both English and Spanish.

Curate topics

Topics have an ai_context parameter, which is useful for providing behavioral prompts and guidance for handling certain questions specific to the topic. For example:

ai_context for e-commerce orders topic

ai_context: |-
  This topic focuses on e-commerce orders. The main concepts are orders
  at the line item level in the order items table, users in our user table,
  inventory in our inventory items table, and products in the products table.

  Only respond with accurate answers based on the data that you're aware of.
  Don't pivot unless there is more than one dimension included in the query.

  Typical questions will be focused on order performance over time, breakdowns across users, and more. 
  - if asked about sales or performance, always use the order_items.total_sale_price field
  - if asked about which users or who, use the users.full_name and users.email fields. Never return an ID unless explicitly asked.
  - if asked about top n without a specific metric or dimension, assume it involves the order_items.total_sale_price and products.name fields

You can use the ai_chat_topics model parameter to curate the list of topics that the Omni Agent or embedded chat instances have access to.

Limit fields included in the context window

The Omni Agent only uses fields within the context of a topic. Fields with hidden: true are excluded from the context window. To control which fields are included, use the ai_fields parameter in a topic. For included fields, you can also provide additional context at the field level. We recommend periodically checking the Analytics > AI usage dashboard to see what questions your users are asking. This helps you identify opportunities to promote commonly used calculations and aggregations to the shared model, improving the self-serve experience over time.

Reuse logic and limit the context window with topic extensions

Topics that you’re already leveraging in Omni can be extended to further curate them for AI. Using the extends parameter, you can reuse the definition of an existing topic without needing to repeat the code. Consider the following Order Transactions topic, which you want to extend to create a curated version dedicated to AI usage:

Order Transactions topic

label: Order Transactions

default_filters:
  order_items.status:
    not: [ Returned, Cancelled ]

joins:
  users: {}
  user_order_facts: {}
  inventory_items:
    products:
      distribution_centers: {}

In a new topic, use extends: [ order_items ] to extend the Order Transactions topic. You can then specify what to include in the AI-specific topic, such as limiting fields, filtering the data for specific use cases, adding more AI context, and so on:

Orders for AI querying topic, extended from Order Transactions

extends: [ order_items ]

base_view_label: Order Items
label: Orders for AI Querying

# limit fields included in the context window
ai_fields: [ tag:use_for_ai ]

Add example queries as context

Along with providing context about the topic itself, you can use the topic’s sample_queries to provide example questions. This approach is useful if you anticipate specific, recurring questions or you find that the Omni Agent struggles with date filters. To do this, you’ll want to:

Create a query in a workbook that contains the correct answer to the question.
In the workbook, click Model > Save as sample query to topic.
When prompted, fill in the following:
- Label - A user-friendly name for the query
- Description - An optional description
- Display on topic overview - If checked, the query will display as a sample query when the topic is selected in a new query tab
- Include in AI context - If checked, the query will be included in the AI context for the topic
  - Prompt - An optional example prompt that could be used to generate this query
  - AI context - Optional, additional context for the AI
When finished, click Save.

You can also use the model-level sample_queries parameter to define example queries that could be performed using the topics contained in the model.

Curate views and fields

Views also have an ai_context parameter which can be useful for passing context to AI that is specific to the view. Keeping fields organized and labeled can not only help you create a top-notch self-service experience, it can also make Omni’s AI more efficient. The following parameters can be used to add metadata to fields for the purposes of AI:

ai_context - Adds context useful for AI responses
all_values - All possible values for the field
- Note: when the dbt integration is enabled, accepted_values tests will be ingested as all_values
sample_values - Example values for the field
synonyms - Other terms used to refer to the field

You can use the workbook or the IDE to add the parameters.

In the workbook

In the field browser, click the (three dots icon) next to the field.
Click Modeling > Edit to open the Edit field side panel.

In the IDE

In the IDE, navigate to the view containing the field to add the parameters. For example:

products.view

dimensions:
  brand:
    sql: '"BRAND"'
    description: Brand name of product
    sample_values:
      [
        Calvin Klein,
        Carhartt,
        Hanes,
        Volcom,
        Levi's,
        Diesel,
        Lucky Brand,
        Quicksilver,
        Nautica,
        American Apparel,
        Columbia,
        Hurley,
        Dockers,
        Arc'teryx,
        C-IN2,
        DKNY,
        HOBO,
        NOM,
        ANS
      ]
    synonyms: [ logo ]
    ai_context: To filter this field, use contains with the brand name.

Getting started

Manage content

Analyze & build

Visualize & present

Deliver content

Model data

Manage integrations

Optimize models for Omni AI

Requirements

Common questions

Context and agent behavior

Curate AI outputs across the model

Personalize context with user attributes

Optimize context for different AI models

Optimize context for different AI agents

Use constants for reusable AI context

Implement chain-of-thought reasoning

Output summaries in multiple languages

Curate topics

Limit fields included in the context window

Reuse logic and limit the context window with topic extensions

Add example queries as context

Curate views and fields

​Requirements

​Common questions

​Context and agent behavior

​Curate AI outputs across the model

​Personalize context with user attributes

​Optimize context for different AI models

​Optimize context for different AI agents

​Use constants for reusable AI context

​Implement chain-of-thought reasoning

​Output summaries in multiple languages

​Curate topics

​Limit fields included in the context window

​Reuse logic and limit the context window with topic extensions

​Add example queries as context

​Curate views and fields

Requirements

Common questions

Context and agent behavior

Curate AI outputs across the model

Personalize context with user attributes

Optimize context for different AI models

Optimize context for different AI agents

Use constants for reusable AI context

Implement chain-of-thought reasoning

Output summaries in multiple languages

Curate topics

Limit fields included in the context window

Reuse logic and limit the context window with topic extensions

Add example queries as context

Curate views and fields